nadzoring.dns_lookup.reverse module

Reverse DNS lookup: IP address → hostname (PTR record).

Typical usage:

from nadzoring.dns_lookup.reverse import reverse_dns
from nadzoring.utils.result import unwrap

result = reverse_dns("8.8.8.8")
if result["error"]:
    print("Lookup failed:", result["error"])
else:
    print("Hostname:", result["hostname"])
    print("RTT:", result["response_time"], "ms")

# Or raise on error:
safe_result = unwrap(result)
print(safe_result["hostname"])
nadzoring.dns_lookup.reverse._make_result(ip_address: str) → ReverseDNSResult[source]

Return a zeroed reverse-lookup result dict.

nadzoring.dns_lookup.reverse.reverse_dns(ip_address: str, nameserver: str | None = None, timeout_config: TimeoutConfig | None = None) → ReverseDNSResult[source]

Perform a reverse DNS lookup to resolve an IP address to a hostname.

Queries the PTR record for ip_address using dns.reversename.from_address() for automatic in-addr.arpa / ip6.arpa name construction. Both IPv4 and IPv6 are supported.

The function never raises; all failures are returned in the "error" field so that callers can handle them uniformly. Error strings are defined in nadzoring.dns_lookup.errors.DNSReverseError.

Parameters:

  • ip_address – IPv4 or IPv6 address to look up (e.g. "8.8.8.8").

  • nameserver – Optional nameserver IP address. None uses the system default resolvers.

  • timeout_config – Unified timeout configuration. If None, uses default.

Returns:

  • ip_address: The original address queried (always present).

  • hostname: Resolved hostname with trailing dot stripped, or None when the lookup failed.

  • error: Error message string on failure; None on success.

  • response_time: Query round-trip time in milliseconds (2 d.p.), or None when the query timed out.

Return type:

ReverseDNSResult dict with the following keys

Examples

Successful lookup:

result = reverse_dns("8.8.8.8")
assert result["hostname"] == "dns.google"
assert result["error"] is None

Missing PTR record:

result = reverse_dns("192.168.1.1")
assert result["hostname"] is None
assert result["error"] == "No PTR record"

IPv6 address:

result = reverse_dns("2001:4860:4860::8888")
print(result["hostname"])  # dns.google

Using a custom nameserver:

result = reverse_dns("8.8.8.8", nameserver="1.1.1.1")

Type-safe error handling:

from nadzoring.dns_lookup.errors import DNSReverseError

result = reverse_dns("10.0.0.1")
if result["error"] == "No PTR record":
    print("No reverse DNS configured")
elif result["error"] == "Query timeout":
    print("Nameserver did not respond")