Hyperlink

Hyperlink is a featureful, pure-Python implementation of the URL, with an emphasis on correctness. Based on RFC 3986 and RFC 3987, it models URLs and IRIs as immutable objects that are safe to share, hash, and compare, while offering a rich API for parsing, manipulating, and rendering web addresses.

Extracted from the Twisted networking library, Hyperlink has been production-grade for well over a decade. It handles the many subtle corners of URL encoding, normalization, and relative resolution so applications can work with links reliably instead of resorting to fragile string manipulation.

What You Get

• An immutable URL object that is safe to hash, compare, and share across code
• Standards-compliant parsing and rendering based on RFC 3986 and RFC 3987
• Distinct EncodedURL and DecodedURL views for precise control over percent-encoding
• Relative URL resolution via the click() method and query manipulation helpers
• Full type hints (py.typed) and broad Python version compatibility

Common Use Cases

• Parsing and validating user- or API-supplied URLs before use
• Safely adding, removing, or reading query parameters and path segments
• Resolving relative links against a base URL when crawling or scraping
• Normalizing and comparing URLs for deduplication or routing

Under The Hood

Architecture - The library’s public surface is defined in src/hyperlink/init.py, which re-exports parse, register_scheme, URL, EncodedURL, DecodedURL, and URLParseError from the single core module src/hyperlink/_url.py (~2,470 lines). URL is the central immutable value type; EncodedURL and DecodedURL are thin views that control percent-encoding semantics, and all mutation-style methods return new instances rather than modifying state.

Tech Stack - Pure Python with a single runtime dependency, idna (>=2.5), for internationalized domain handling. It ships a bundled idna-tables-properties.csv.gz data file, py.typed for type distribution, and supports a wide range of Python versions. Packaging uses setuptools with a src layout; formatting is handled by Black with an 80-column line length.

Code Quality - The repository has a dedicated test package (src/hyperlink/test) with focused suites for parsing, decoded URLs, scheme registration, sockets, and property-based tests via Hypothesis. Naming is explicit, encoding edge cases are covered, and the code is fully type-annotated, reflecting its origin as a hardened extract from Twisted.

API Design - The API is compact and discoverable: URL.from_text() parses, replace() produces modified copies, click() resolves relative links, and get()/set() manage query parameters. Immutability makes the objects predictable and safe to share, and the small exported surface keeps the learning curve low for common URL tasks.