idna

idna is a pure-Python library implementing Internationalized Domain Names in Applications (IDNA 2008, RFC 5891) together with Unicode IDNA Compatibility Processing (UTS #46). It converts domain names between their Unicode representation (U-labels) and ASCII-compatible xn— encoding (A-labels), superseding the standard library’s older encodings.idna module.

With broader script coverage than the 2003 specification and built-in validation that rejects domains with known security issues, idna is a foundational dependency across the Python ecosystem, used by HTTP clients such as Requests, urllib3, and httpx to correctly handle non-ASCII domain names.

What You Get

• encode() and decode() functions that convert whole domains between Unicode and ASCII-compatible xn— form
• IDNA 2008 (RFC 5891) validation with bidirectional, contextual-joiner, and codepoint checks
• Optional UTS #46 compatibility mapping (uts46=True) that normalizes user input before conversion
• Per-label alabel/ulabel helpers and a registered idna2008 codec for str.encode('idna2008')
• A command-line idna tool for converting domains from the shell or standard input

Common Use Cases

• Normalizing and encoding non-ASCII hostnames before making network requests
• Validating that a user-supplied domain conforms to IDNA 2008 rules
• Displaying Unicode domain names decoded from their xn— Punycode form in user interfaces

Under The Hood

Architecture The public surface lives in idna/core.py, where encode() splits a domain on the four Unicode label separators via _unicode_dots_re, optionally applies UTS #46 remapping through uts46_remap() (backed by the generated tables in uts46data.py), then Punycode-encodes each label with alabel(); alabel() runs the full validation stack — check_label() enforces bidirectional rules (RFC 5893), hyphen and initial-combiner constraints, and contextual joiners (CONTEXTJ/CONTEXTO) — before prepending the xn-- prefix. decode() reverses the process, and codec.py registers a stateless idna2008 codec plus incremental encoder/decoder classes. Tech Stack It is pure Python targeting 3.9+ with zero runtime dependencies, leaning only on the standard library (unicodedata, bisect, re, codecs); it builds with the flit_core backend, ships a py.typed marker, and generates its large idnadata.py/uts46data.py lookup tables offline via the scripts in tools/. Development tooling is ruff (with bugbear, simplify, pyupgrade, and perflint rule sets), mypy, and pytest. Code Quality Codepoint membership is answered in O(log n) by intranges.py, which packs sorted ranges into single integers (start << 32 | end) and binary-searches them, and hot bidi category sets are hoisted to module-level frozensets to stay out of the per-codepoint loop. The code is fully type-annotated, exposes a clean exception hierarchy (IDNAError with IDNABidiError, InvalidCodepoint, InvalidCodepointContext), and is exercised by a tests/ suite covering core, UTS #46, the codec, the CLI, compat, and the intranges helper. API Design The surface is deliberately small and mirrors familiar codec naming: encode/decode for whole domains, alabel/ulabel per label, an uts46=True flag for compatibility mapping, and a display=True option for leaving undecodable labels intact in UIs. Registering the idna2008 codec lets callers use str.encode('idna2008'), and a bundled CLI plus a concise, example-driven README keep the getting-started boilerplate near zero.