aiodns

aiodns provides a simple way to perform asynchronous DNS resolutions in Python using asyncio. It wraps the pycares bindings to the c-ares C library, exposing a DNSResolver class whose methods return awaitable futures, so DNS lookups integrate cleanly into async applications without blocking the event loop.

It supports a broad set of query types including A, AAAA, ANY, CAA, CNAME, MX, NAPTR, NS, PTR, SOA, SRV, and TXT, along with reverse lookups, getaddrinfo, and getnameinfo helpers. Part of the aio-libs organization, aiodns is a foundational dependency for asyncio networking stacks such as aiohttp.

What You Get

• A DNSResolver class with awaitable, non-blocking resolution methods
• Support for A, AAAA, ANY, CAA, CNAME, MX, NAPTR, NS, PTR, SOA, SRV, and TXT queries
• Reverse lookups plus getaddrinfo and getnameinfo helpers
• Cancellation and explicit resolver close for clean shutdown
• Optional async context-manager usage for short-lived resolvers

Common Use Cases

• Resolving hostnames without blocking an asyncio event loop
• Performing custom DNS record lookups (MX, TXT, SRV) in async services
• Backing async HTTP clients like aiohttp with non-blocking DNS
• Doing reverse DNS or address-info resolution in network tooling

Under The Hood

Architecture - aiodns is a thin async wrapper: its init.py defines DNSResolver, which owns a pycares Channel and integrates it with the running asyncio loop by driving c-ares socket readiness through add_reader/add_writer callbacks, translating c-ares completion callbacks into resolved asyncio futures. A compat module preserves the legacy 3.x result format while the new query_dns API returns native pycares 5.x types. Tech Stack - Pure Python targeting modern asyncio, with the heavy lifting delegated to pycares and the underlying c-ares C library; packaging uses pyproject/setup.cfg and ships a py.typed marker for type checkers. Code Quality - The project includes a pytest test suite (test_aiodns.py, test_compat.py), CI workflows, a maintained ChangeLog with a long release history, typed public API, and clear migration documentation between major versions, reflecting careful stewardship under aio-libs. API Design - The API is intentionally small and predictable, mirroring familiar socket resolution names (gethostbyaddr, getaddrinfo, getnameinfo) plus a typed query_dns, and it documents best practices such as reusing long-lived resolvers and closing them from the creating loop.