Async DNS Lookup Helper

A lightweight async DNS helper that issues concurrent lookups while allowing callers to choose the event-loop backend (asyncio or trio).

Capabilities

Selectable async backend

• Creating the client with backend set to "asyncio" or "trio" uses that backend and rejects unsupported names with a ValueError. @test

Resolve single record

• Resolving an A record for example.com against 1.1.1.1 returns at least one IPv4 address string via the configured backend. @test

Resolve dual stack concurrently

• Dual-stack resolution issues A and AAAA queries concurrently; the result contains an "A" list with at least one IPv4 address for example.com, and an "AAAA" list that may be empty but is always present. @test

Nameserver override per call

• Supplying a nameserver override for a single lookup uses only that nameserver without mutating the client's configured nameservers. @test

Implementation

@generates

API

from typing import Iterable, Literal, Sequence

BackendName = Literal["asyncio", "trio"]

class AsyncDnsClient:
    def __init__(self, nameservers: Sequence[str] | None = None, backend: BackendName = "asyncio", timeout: float | None = 2.0):
        """Configure the resolver with optional nameservers, backend, and timeout seconds."""

    def set_backend(self, backend: BackendName) -> None:
        """Switch the active async backend; raise ValueError for unsupported names."""

    async def lookup(self, name: str, record_type: str = "A", *, nameservers: Iterable[str] | None = None) -> list[str]:
        """Resolve a single record type asynchronously using the active backend; optional nameserver override."""

    async def lookup_dual_stack(self, name: str) -> dict[str, list[str]]:
        """Resolve both A and AAAA concurrently using the active backend; returns {"A": [...], "AAAA": [...]} with lists possibly empty."""

Dependencies { .dependencies }

dnspython { .dependency }

Provides asynchronous DNS querying and resolver abstractions with backend selection.