uritools

Uritools is a Python library providing RFC 3986 compliant functions for splitting, joining, classifying, and composing URIs and URI references. It largely replaces the standard library’s urllib.parse module, which retains legacy parsing quirks and is not fully compliant with the current URI standard.

With a small, focused API, uritools lets you decompose a URI into its five standard components, rebuild URIs from parts, resolve relative references, and distinguish between absolute URIs, relative references, and same-document references, all backed by a well-tested, fully typed implementation.

What You Get

• urisplit and uriunsplit for decomposing and reassembling URIs into their five RFC 3986 components
• uricompose for building URIs from scheme, host, port, path, query, and fragment parts with proper encoding
• urijoin for resolving relative references against a base URI per the standard’s algorithm
• SplitResult helpers like getport, getquerydict, isuri, and isabsuri for inspecting and classifying URIs
• A fully typed (py.typed) implementation with type stubs and high test coverage

Common Use Cases

• Parsing URIs correctly where urllib.parse’s legacy quirks cause bugs
• Composing well-formed URIs from user-supplied components with proper percent-encoding
• Resolving relative links against a base URI in crawlers or clients
• Classifying whether a string is an absolute URI, relative reference, or same-document reference

Under The Hood

Architecture - The library is implemented as a single focused module under src/uritools/__init__.py, exposing top-level functions (urisplit, uriunsplit, uricompose, urijoin, uridefrag) plus a SplitResult named-tuple subclass that carries the parsed components and convenience accessors. Parsing is driven by RFC 3986’s grammar via compiled regular expressions rather than ad-hoc string splitting, which is what keeps it standards-compliant.

Tech Stack - Pure Python with zero runtime dependencies, packaged with a modern pyproject.toml build and distributed with inline type stubs (__init__.pyi) and a py.typed marker. Testing runs under tox with coverage reported to Codecov, and documentation is built on Read the Docs.

Code Quality - The repo maintains a dedicated tests/ suite with high coverage (badged via Codecov), ships type stubs for static analysis, and keeps a detailed CHANGELOG.rst. The small surface area and regex-driven grammar make behavior easy to audit against the RFC.

API Design - The function names mirror urllib.parse (urisplit vs urlsplit) so migration is intuitive, while uricompose adds an ergonomic keyword-argument builder that handles encoding for you. Classification helpers on the result object read declaratively (parts.isuri()), giving the library excellent developer ergonomics for a niche standard.