mdurl

mdurl is a small Python library providing URL parsing, normalization, encoding, decoding, and formatting utilities, ported line-for-line from the JavaScript mdurl package that underpins the markdown-it ecosystem. It exists primarily as a dependency of markdown-it-py, giving the Python CommonMark implementation the same URL-handling behavior as its JavaScript counterpart.

The library exposes focused functions for parsing a URL into its components, percent-encoding/decoding parts of a URL safely, and re-serializing a parsed URL back into a string, matching the exact edge-case behavior markdown-it relies on for link and autolink handling.

What You Get

• A parse() function that decomposes a URL string into its constituent parts
• encode()/decode() functions for safe percent-encoding and decoding of URL components
• A format() function to re-serialize a parsed URL structure back into a string
• Behavior ported directly from the JavaScript mdurl package for cross-implementation consistency
• A minimal, dependency-free implementation suitable as a lightweight sub-dependency

Common Use Cases

• Powering link and autolink URL handling inside markdown-it-py’s CommonMark parser
• Normalizing or safely encoding URLs extracted from user-supplied Markdown content
• Any Python project that needs JavaScript-mdurl-compatible URL parsing behavior for interoperability

Under The Hood

Architecture - The package is organized as small, single-purpose modules under src/mdurl: _parse.py handles URL decomposition, _encode.py/_decode.py handle percent-encoding, _format.py re-serializes parsed URLs, and _url.py defines the shared URL data structure, with init.py exposing the public parse/encode/decode/format functions. Tech Stack - Pure Python with no runtime dependencies, packaged via a standard pyproject.toml, and mirrors the reference JavaScript mdurl implementation’s function signatures and edge-case behavior closely enough to be a drop-in behavioral match. Code Quality - The tests/ directory includes dedicated test modules for each function (test_parse.py, test_encode.py, test_decode.py, test_format.py) plus shared fixtures under tests/fixtures/, and CI runs tests with coverage reporting via Codecov, indicating disciplined parity testing against the upstream JS behavior. API Design - The API surface is intentionally tiny — four top-level functions matching the original JS package’s naming — which keeps integration nearly zero-effort for any project (like markdown-it-py) that already expects mdurl’s specific parsing semantics.