aiohttp-asyncmdnsresolver: mDNS Resolver for aiohttp

0.1.1 · active · verified Thu Apr 16

aiohttp-asyncmdnsresolver is an asynchronous resolver for aiohttp that extends its capabilities to include mDNS (multicast DNS) resolution. It leverages the zeroconf library to resolve '.local' domain names. The library is actively maintained by the aio-libs organization, with its current version being 0.1.1, and typically sees releases aligned with updates to aiohttp or zeroconf, or as new features and fixes are introduced.

Common errors

```
aiohttp.client_exceptions.ClientConnectorDNSError: Cannot connect to host some_mdns_hostname.local:80 ssl:default [Domain name not found]
```
cause aiohttp's default DNS resolver does not support mDNS resolution for '.local' domains, leading to an inability to connect to such hosts.

fix Configure `aiohttp.TCPConnector` to use a resolver from `aiohttp-asyncmdnsresolver`, such as `AsyncDualMDNSResolver`, when creating your `aiohttp.ClientSession`.
```
mDNS hostnames do not resolve when aiodns is installed.
```
cause When the optional `aiodns` library is installed, `aiohttp` may use it as the default resolver. `aiodns` (based on `c-ares`) lacks native mDNS support, causing resolution failures for '.local' names.

fix Explicitly override the `aiohttp.TCPConnector`'s resolver with `aiohttp_asyncmdnsresolver.api.AsyncMDNSResolver` or `AsyncDualMDNSResolver` to ensure mDNS capabilities.
```
Expected both '.local' and regular hostnames to resolve, but only mDNS names work (or only regular DNS names work).
```
cause Using `AsyncMDNSResolver` which prioritizes mDNS for '.local' names but does not fallback to regular DNS for all other names, or conversely, not using any custom resolver for mDNS names.

fix For environments where you need to resolve both mDNS (`.local`) and standard DNS hostnames reliably, use `aiohttp_asyncmdnsresolver.api.AsyncDualMDNSResolver`.

Warnings

gotcha aiohttp's default resolver (and optionally aiodns) does not support mDNS names. Attempting to resolve '.local' domains without this library will result in resolution failures.
Fix: Use `aiohttp_asyncmdnsresolver.api.AsyncMDNSResolver` or `AsyncDualMDNSResolver` with `aiohttp.TCPConnector`.
gotcha The `AsyncMDNSResolver` class only resolves mDNS names for '.local' domains and does not automatically fall back to standard DNS for other hostnames. For environments requiring both, `AsyncDualMDNSResolver` is recommended.
Fix: For comprehensive resolution, import and use `aiohttp_asyncmdnsresolver.api.AsyncDualMDNSResolver`.
breaking Future versions (starting from `v0.1.2`, currently unreleased draft) will increase the minimum required `setuptools` version to `v77` or higher due to packaging metadata changes (PEP 639).
Fix: Ensure your environment's `setuptools` is updated to version 77+ before upgrading to `aiohttp-asyncmdnsresolver` v0.1.2 or later.

Install

pip install aiohttp-asyncmdnsresolver Install stable version

Imports

AsyncDualMDNSResolver

from aiohttp_asyncmdnsresolver.api import AsyncDualMDNSResolver

AsyncMDNSResolver
```
from aiohttp_asyncmdnsresolver.api import AsyncMDNSResolver
```
Use AsyncDualMDNSResolver if you need both mDNS and regular DNS fallback.

Quickstart

This quickstart demonstrates how to integrate `aiohttp-asyncmdnsresolver` with `aiohttp.ClientSession` to enable both mDNS (`.local` hostnames) and standard DNS resolution. It uses `AsyncDualMDNSResolver` which attempts mDNS first and falls back to regular DNS, providing comprehensive hostname resolution. Remember to replace `mydevice.local.` with an actual mDNS-resolvable host on your network for testing mDNS.

import asyncio
import aiohttp
from aiohttp_asyncmdnsresolver.api import AsyncDualMDNSResolver

async def main():
    # Use AsyncDualMDNSResolver for both mDNS (.local) and standard DNS resolution
    resolver = AsyncDualMDNSResolver()
    # Create a TCPConnector with the custom resolver
    connector = aiohttp.TCPConnector(resolver=resolver, ssl=False)

    async with aiohttp.ClientSession(connector=connector) as session:
        # Example: Resolving a standard domain
        try:
            async with session.get('http://example.com') as response:
                print(f"Example.com Status: {response.status}")
        except Exception as e:
            print(f"Could not connect to example.com: {e}")

        # Example: Resolving an mDNS (.local) domain (replace with a real mDNS host if available)
        try:
            async with session.get('http://mydevice.local.') as response:
                print(f"Mydevice.local Status: {response.status}")
        except Exception as e:
            print(f"Could not connect to mydevice.local: {e}")

    await resolver.close()

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →