aiohappyeyeballs

aiohappyeyeballs implements the Happy Eyeballs algorithm (RFC 8305) for Python’s asyncio, letting you race TCP connection attempts across a pre-resolved list of addrinfo tuples instead of a DNS name. This matters for applications that already resolve names themselves — through DNS caching, custom resolvers, or service discovery like zeroconf — where the stdlib’s loop.create_connection() only accepts an unresolved hostname and can’t take advantage of dual-stack racing.

It is a small, dependency-free utility extracted from aiohttp’s internals so any asyncio-based client can reuse the same battle-tested connection racing logic without depending on aiohttp itself.

What You Get

• A start_connection() coroutine that races connection attempts across a list of addrinfo tuples and returns the first successful socket
• A staggered_race()-based interleaving implementation (_staggered.py) that starts connection attempts to alternating address families with a configurable delay
• Helper functions (addr_to_addr_infos, remove_addr_infos, pop_addr_infos_interleave) for building and filtering addrinfo lists
• Fully typed, dependency-free package (ships a py.typed marker) that works alongside loop.create_connection()

Common Use Cases

• HTTP clients (aiohttp itself, and others) that resolve DNS themselves and want dual-stack connection racing
• Applications using service discovery (e.g. zeroconf) that hand asyncio a list of addresses instead of a hostname
• Custom asyncio clients that cache DNS results and need to retry/interleave among multiple resolved addresses efficiently

Under The Hood

Architecture: The package is a thin, focused layer over asyncio’s low-level socket APIs. impl.py exposes start_connection(), the public entry point, which normalizes the addrinfo list, opens a socket per candidate, and delegates interleaved racing to _staggered.staggered_race() in _staggered.py. That module runs each connection attempt as a task, starting the next candidate after happy_eyeballs_delay seconds if the previous one hasn’t completed, and cancels the losers once a winner connects — implementing RFC 8305 section 5’s staggered connection attempts. utils.py provides pure helper functions for reshaping addrinfo tuples (family/type/proto/canonname/sockaddr) between formats. types.py defines the shared AddrInfoType/SocketFactoryType type aliases used across the package.

Tech Stack: Pure Python 3.10+ with zero runtime dependencies, built with Poetry (poetry-core backend). Dev tooling is Ruff (lint, including flake8-bandit/bugbear/docstrings rule sets), mypy in strict mode (disallow_untyped_defs, disallow_any_generics), pytest with pytest-asyncio and pytest-cov, and pytest-codspeed for benchmarking. Docs are built with Sphinx/MyST/Furo and published to Read the Docs; releases are cut via python-semantic-release from Conventional Commits.

Code Quality: The tests/ directory has one test module per source file (test_impl.py, test_staggered.py, test_staggered_cpython.py, test_utils.py, test_init.py) plus a CPython-parity test (test_staggered_cpython_eager_task_factory.py) that checks behavior against the upstream asyncio implementation under eager task factories — a strong signal of deliberate compatibility testing. Coverage is enforced via --cov=aiohappyeyeballs --cov-report=term-missing:skip-covered in pytest config, and mypy strict mode plus Ruff’s bandit ruleset catch type and security issues before merge.

API Design: The public surface is intentionally minimal — one coroutine (start_connection) plus three small helpers, all re-exported from the package __init__.py. Docstrings on start_connection spell out every parameter and show the exact loop.create_connection() composition pattern, so adopting it requires no more than swapping a DNS-name argument for a pre-fetched addrinfo list.