nadzoring.dns_lookup.utils module

Utility functions for DNS lookup module.

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

Create and configure a DNS resolver instance.

Initializes a DNS resolver with specified timeout parameters and optional custom nameserver.

Parameters:

  • nameserver – Optional specific nameserver IP address to use for queries. If None, uses system default nameservers.

  • timeout – Query timeout in seconds for each individual nameserver. Defaults to 5.0 seconds.

  • lifetime – Total lifetime in seconds for the entire query operation. This includes retries across multiple nameservers. Defaults to 10.0 seconds.

Returns:

Configured dns.resolver.Resolver instance ready for queries.

Return type:

Resolver

Example

>>> resolver = create_resolver("8.8.8.8", timeout=3.0, lifetime=8.0)
>>> answers = resolver.resolve("example.com", "A")
nadzoring.dns_lookup.utils.extract_records(answers: Answer, record_type: str) → list[str][source]

Extract and format DNS records from a resolution answer.

Processes DNS answers based on record type, handling special formatting for complex record types like MX, TXT, and SOA.

Parameters:

  • answers – DNS answer object from resolver.resolve() containing the resolved records.

  • record_type – Type of DNS record being processed (e.g., ‘A’, ‘MX’, ‘TXT’). Used to determine special formatting rules.

Returns:

List of formatted record strings. Format varies by record type:

  • MX: “priority mailserver” (e.g., “10 mail.example.com”)

  • TXT: Concatenated string parts (e.g., “v=spf1 include:…”)

  • SOA: fields: “mname rname serial refresh retry expire minimum”

  • Others: Simple string representation with trailing dots removed

Return type:

List[str]

Example

>>> 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][source]

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

Returns a curated list of reliable public DNS resolvers from various providers suitable for testing or fallback scenarios.

Returns:

List of DNS server IP addresses including:

  • Google Public DNS (8.8.8.8, 8.8.4.4)

  • Cloudflare DNS (1.1.1.1, 1.0.0.1)

  • OpenDNS (208.67.222.222, 208.67.220.220)

  • Quad9 (9.9.9.9, 149.112.112.112)

  • Verisign Public DNS (64.6.64.6, 64.6.65.6)

Return type:

List[str]

Example

>>> servers = get_public_dns_servers()
>>> for server in servers[:3]:
...     print(f"Testing DNS server: {server}")
nadzoring.dns_lookup.utils.resolve_with_timer(domain: str, record_type: Literal['A', 'AAAA', 'CNAME', 'MX', 'NS', 'TXT', 'PTR', 'SOA', 'DNSKEY'] = 'A', nameserver: str | None = None, *, include_ttl: bool = False, timeout: float = 5.0, lifetime: float = 10.0) → DNSResult[source]

Perform DNS resolution with timing information and error handling.

Resolves a domain name for a specific record type, measuring response time and optionally capturing TTL information. Handles common DNS errors gracefully.

Parameters:

  • domain – Domain name to resolve (e.g., “example.com”).

  • record_type – DNS record type to query (e.g., “A”, “MX”, “TXT”). Defaults to “A”.

  • nameserver – Optional specific nameserver IP to use for resolution. If None, uses system default.

  • include_ttl – Whether to include TTL (Time To Live) value in result. Defaults to False.

  • timeout – Query timeout in seconds for each nameserver. Defaults to 5.0.

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

Returns:

Dictionary containing resolution results with structure:

  • domain: The queried domain name

  • record_type: The queried record type

  • records: List of resolved records (empty if resolution failed)

  • ttl: TTL in seconds if include_ttl=True and available, else None

  • error: Error message string if resolution failed, else None

  • response_time: Query response time in milliseconds, rounded to 2 decimals

Return type:

DNSResult

Example

>>> result = resolve_with_timer("example.com", "MX", include_ttl=True)
>>> if not result["error"]:
...     print(f"Records: {result['records']}, TTL: {result['ttl']}")