urlpattern-py 0.1.0

Pure Python implementation of the WHATWG URL Pattern Standard

urlpattern-py

Pure Python implementation of the WHATWG URL Pattern Standard (as of 3 December 2025).

Docs include two folders: docs/urlpattern for the official WPT suite and docs/urlpattern-polyfill for the official polyfill.

Quick Start

Installation

pip install urlpattern-py

Installation (Development)

# Clone repository
cd urlpattern-py

# Install dev dependencies
python -m pip install -e ".[dev]"

Usage

from urlpattern import URLPattern

pattern = URLPattern("https://example.com/books/:id")
assert pattern.test("https://example.com/books/123") is True
assert pattern.exec("https://example.com/books/123")["pathname"]["groups"]["id"] == "123"

Development Guidelines

Code Formatting & Linting

We use Ruff for formatting and linting. To ensure consistency, please set up pre-commit to run automatically before each commit.

# Install the git hooks (pre-commit is installed via dev dependencies)
pre-commit install

Once installed, Ruff will run automatically on git commit. You can also run it manually on all files:

pre-commit run --all-files

Configuration for Ruff (line length, import sorting, etc.) can be found in pyproject.toml.

Architecture

URLPattern string → Tokenizer → Normalizer → Compiler → Python regex

Running Tests

# Run the full suite
python -m pytest

# Run a single module
python -m pytest tests/test_compliance.py

808 passed, 7 skipped in 0.56s

The pytest suite mirrors all WPT URLPattern cases under docs/urlpattern, including compare, generate, hasRegExpGroups, and constructor coverage; the WPT data options (expected_obj, expected_match, exactly_empty_components, and input/baseURL/ignoreCase variants) are all exercised in tests/. Polyfill-specific test data under docs/urlpattern-polyfill/test is also mirrored in tests/resources/polyfill, with dedicated pytest coverage for the additional cases and compare/hasRegExpGroups behavior; any polyfill expectations that conflict with WPT are skipped. The suite also includes tests generated from the examples in MDN and the WHATWG spec (docs/index.md and docs/spec.bs) to keep documentation examples aligned with implementation behavior.

License

MIT