nadzoring.dns_lookup.utils module

Utility functions for the DNS lookup module.

This module provides the low-level building blocks used by the rest of nadzoring.dns_lookup:

• create_resolver() — build a configured dnspython resolver

• extract_records() — format raw resolver answers into strings

• resolve_with_timer() — single-query entry point with timing and structured error handling

• get_public_dns_servers() — return the built-in list of well-known public resolvers

None of the functions in this module raise on DNS errors; all failures are surfaced through the "error" field of the returned DNSResult dict. Callers that prefer exceptions should wrap the result themselves or use nadzoring.utils.errors.

nadzoring.dns_lookup.utils._extract_default_records(answers: Answer) → list[str]

Extract generic DNS records, stripping trailing dots.

nadzoring.dns_lookup.utils._extract_mx_records(answers: Answer) → list[str]

Extract and format MX records from a resolver answer.

nadzoring.dns_lookup.utils._extract_soa_records(answers: Answer) → list[str]

Extract and format SOA records into a single space-joined string.

nadzoring.dns_lookup.utils._extract_txt_records(answers: Answer) → list[str]

Extract and format TXT records, joining multi-part strings.

nadzoring.dns_lookup.utils._make_empty_result(domain: str, record_type: RecordType) → DNSResult

Return a zeroed DNSResult dict.

nadzoring.dns_lookup.utils.create_resolver(nameserver: str | None = None, timeout: float = 5.0, lifetime: float = 10.0) → Resolver

Create and configure a dnspython resolver instance.

Parameters:

• nameserver – Optional nameserver IP address. When None the system default resolvers are used.

• timeout – Per-nameserver query timeout in seconds. Defaults to 5.0.

• lifetime – Total query lifetime in seconds, including retries across nameservers. Defaults to 10.0.

Returns:

Configured dns.resolver.Resolver ready for queries.

Examples

>>> resolver = create_resolver("8.8.8.8", timeout=3.0)
>>> answers = resolver.resolve("example.com", "A")

nadzoring.dns_lookup.utils.extract_records(answers: Answer, record_type: str) → list[str]

Extract and format DNS records from a resolver answer.

Applies record-type-specific formatting:

• MX — "priority mailserver"

• TXT — all string parts joined into one string

• SOA — space-joined SOA fields

• other — plain str() with trailing dot stripped

Parameters:

• answers – dns.resolver.Answer returned by Resolver.resolve().

• record_type – DNS record type string (e.g. "A", "MX").

Returns:

List of formatted record strings.

Examples

>>> answers = resolver.resolve("example.com", "MX")
>>> extract_records(answers, "MX")
['10 mail.example.com', '20 backup.example.com']

nadzoring.dns_lookup.utils.get_public_dns_servers() → list[str]

Return a list of well-known public DNS server IP addresses.

Includes resolvers from Google, Cloudflare, OpenDNS, Quad9, and Verisign.

Returns:

A new list of DNS server IP address strings (copy of internal constant, safe to mutate).

Examples

>>> servers = get_public_dns_servers()
>>> "8.8.8.8" in servers
True
>>> "1.1.1.1" in servers
True

nadzoring.dns_lookup.utils.resolve_with_timer(domain: str, record_type: RecordType = 'A', nameserver: str | None = None, *, include_ttl: bool = False, timeout: float = 5.0, lifetime: float = 10.0) → DNSResult

Perform DNS resolution with timing and structured error handling.

Resolves domain for record_type, measuring response time and optionally capturing TTL. All DNS errors are surfaced through the "error" field rather than raised as exceptions, making this safe to call in automated scripts without try/except.

Parameters:

• domain – Domain name to resolve (e.g. "example.com").

• record_type – DNS record type to query. Defaults to "A".

• nameserver – Optional nameserver IP; None uses the system default.

• include_ttl – Include TTL value in result. Defaults to False.

• timeout – Per-nameserver query timeout in seconds. Defaults to 5.0.

• lifetime – Total query lifetime in seconds. Defaults to 10.0.

Returns:

DNSResult dict. Always check result["error"] before using result["records"]:

result = resolve_with_timer("example.com", "A")
if result["error"]:
    # Possible values:
    # "Domain does not exist"  — NXDOMAIN
    # "No A records"           — NoAnswer
    # "Query timeout"          — Timeout
    # <arbitrary string>       — unexpected error
    print("DNS error:", result["error"])
else:
    print(result["records"])  # ['93.184.216.34']
    print(result["response_time"])  # e.g. 42.5

Examples

Basic A record lookup:

result = resolve_with_timer("example.com")
if not result["error"]:
    print(result["records"])

MX lookup with TTL:

result = resolve_with_timer("example.com", "MX", include_ttl=True)
if not result["error"]:
    print(result["records"], result["ttl"])

Using a custom nameserver:

result = resolve_with_timer("example.com", nameserver="1.1.1.1")