Thread-Safe DNS Helper

Build a helper that performs DNS lookups safely across multiple threads by sharing a package-provided cache and returning immutable results. The helper should make it easy to warm the cache up front, perform single and batch lookups, and keep per-call timeout overrides isolated to the calling thread.

Capabilities

Shared caching across threads

• Concurrent lookup calls for the same hostname reuse a single cache entry so both return identical address tuples, and later calls serve from the cache instead of triggering another query. @test

Immutable results

• Results from lookup and lookup_many are immutable snapshots; mutating a returned collection does not affect subsequent calls or cached data. @test

Negative caching

• When a hostname does not exist, the helper caches the negative response so a second request before expiry returns the same cached failure quickly without performing another wire query. @test

Per-call timeout override

• Passing a shorter timeout to lookup_many enforces that limit for each query without altering the default timeout used for later calls. @test

Implementation

@generates

API

from typing import Iterable, Mapping, Tuple, Optional

class ThreadSafeDnsHelper:
    def __init__(self, nameservers: Iterable[str], default_timeout: float = 2.0) -> None: ...

    def warm_cache(self, hostnames: Iterable[str], record_type: str = "A", timeout: Optional[float] = None) -> None: ...

    def lookup(self, hostname: str, record_type: str = "A", timeout: Optional[float] = None) -> Tuple[str, ...]: ...

    def lookup_many(self, hostnames: Iterable[str], record_type: str = "A", timeout: Optional[float] = None) -> Mapping[str, Tuple[str, ...]]: ...

Dependencies { .dependencies }

dnspython { .dependency }

Provides DNS resolution, immutable-friendly record objects, and resolver caches suitable for multi-threaded use.