pyproject.toml

[build-system]
requires = ["hatchling", "hatch-fancy-pypi-readme>=24.1.0"]
build-backend = "hatchling.build"

[project]
name = "yarlpattern"
description = "WHATWG URLPattern for Python. 100% specification strict, pure Python, optimized and yarl-compatible."
dynamic = ["version", "readme"]
license = "Apache-2.0"
license-files = ["LICENSE", "NOTICE"]
requires-python = ">=3.12"
authors = [
    { name = "yarlpattern contributors" },
]
keywords = [
    "urlpattern",
    "whatwg",
    "url",
    "yarl",
    "routing",
]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: Apache Software License",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Topic :: Internet :: WWW/HTTP",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Typing :: Typed",
]
dependencies = [
    "yarl>=1.20",
]

[project.urls]
Homepage = "https://github.com/chad-loder/yarlpattern"
Documentation = "https://chad-loder.github.io/yarlpattern/"
Issues = "https://github.com/chad-loder/yarlpattern/issues"
Source = "https://github.com/chad-loder/yarlpattern"
Changelog = "https://github.com/chad-loder/yarlpattern/blob/main/CHANGELOG.md"

[project.optional-dependencies]
# Bring-your-own regex engine via :mod:`yarlpattern._regex_engine`. Installing
# ``yarlpattern[regex]`` pulls in Matthew Barnett's third-party ``regex``
# package; URLPattern's engine auto-probe will then prefer it over stdlib
# ``re`` (closes the JS ``v``-flag set-operation conformance gap in the
# WPT corpus — ``[a&&b]`` / ``[a--b]`` patterns).
regex = [
    "regex>=2026.4.4",
]

[tool.hatch.version]
path = "src/yarlpattern/_version.py"

[tool.hatch.metadata.hooks.fancy-pypi-readme]
content-type = "text/markdown"

[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
path = "README.md"
end-before = "<!-- pypi-end -->"

[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
pattern = '\[([^\]]+)\]\((?!https?://)([^)]+)\)'
replacement = '[\1](https://github.com/chad-loder/yarlpattern/blob/main/\2)'

[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
pattern = '\]\(LICENSE\)'
replacement = '](https://github.com/chad-loder/yarlpattern/blob/main/LICENSE)'

[tool.hatch.build.targets.wheel]
packages = ["src/yarlpattern"]

[tool.hatch.build.targets.sdist]
include = ["/src", "/tests", "/docs", "/CHANGELOG.md", "pyproject.toml", "LICENSE", "README.md"]

[dependency-groups]
# PEP 735 — not published as installable extras; for contributors / CI only.
# Mirror the ``[regex]`` extra so contributors get the full-conformance
# engine by default when running the test suite (the corpus's two set-op
# cases would otherwise xfail).
engines-all = [
    "regex>=2026.4.4",
]
test = [
    { include-group = "engines-all" },
    "pytest>=9.0.3",
    "pytest-cov>=7.1.0",
    "hypothesis>=6.152.1",
]
lint = [
    "ruff>=0.15.11",
    "mypy>=1.19.1,<1.20",
    "pyright>=1.1.408",
    "ty>=0.0.31",
    "codespell>=2.4.2",
    "validate-pyproject[all]>=0.25",
    "semgrep>=1.160.0",
    "interrogate>=1.7.0",
]
# Documentation site (chad-loder.github.io/yarlpattern). Pinned mkdocs-material
# theme + mkdocstrings for API surface auto-extraction; built by
# ``.github/workflows/docs.yml`` and locally with ``just docs``.
docs = [
    "properdocs>=1.6.5",
    "mkdocs-material>=9.6",
    "mkdocstrings[python]>=0.29",
    "mkdocs-code-validator>=0.2.1",
]
# Extra tooling (not needed for the library at runtime) — pyclean for cache cleaning.
dev = [
    "pyclean>=3.6.0",
]
# Self-benchmark suite under ``benchmarks/``. Pinned via dependency-group (not
# a published extra) because the suite is for contributors / maintainers; end
# users have no need for ``pytest-benchmark``.
bench = [
    "pytest>=9.0.3",
    "pytest-benchmark>=5.1.0",
]
maintainer = [
    { include-group = "dev" },
    "python-semantic-release>=10.5.3",
    "rumdl>=0.1.76",
    "check-jsonschema>=0.37.1",
    "zizmor>=1.24.1",
]

[tool.uv]
default-groups = ["test", "lint", "maintainer"]
# Resolver cutoff: ignore PyPI uploads newer than this (relative to lock/sync resolve time).
# 72h balances fast incident response on PyPI with a buffer past typical detection and
# weekend-drop windows. For an urgent CVE fix: `uv lock --exclude-newer=0h --upgrade-package <name>`.
exclude-newer = "72h"

# ---------------------------------------------------------------------------
# Tool configuration
# ---------------------------------------------------------------------------

[tool.rumdl]
respect-gitignore = true
exclude = [
    ".git", "node_modules", "dist", "build", ".scratch", "reference", "plan",
    # Generated by ``scripts/generate_compliance_report.py``; long table
    # rows and badge URLs are intentional, not subject to prose-style
    # line-length limits.
    "docs/wpt-compliance.md",
    # GitHub template / metadata files have their own conventions
    # (HTML-comment intros, raw advisory URLs); not project prose.
    ".github/PULL_REQUEST_TEMPLATE.md",
    "SECURITY.md",
]

# --- Headings ---
[tool.rumdl.MD003]
style = "atx"

[tool.rumdl.MD024]
siblings-only = true

[tool.rumdl.MD026]
punctuation = ".,;:!"

[tool.rumdl.MD041]
front-matter-title = "title"

# --- Lists ---
[tool.rumdl.MD004]
style = "dash"

# --- Whitespace / line layout ---
[tool.rumdl.MD013]
line-length = 150
code-blocks = false
tables = false
headings = false

# --- Formatting ---
# ``<kbd>`` is the spec-defined way to show keystrokes / inline status
# tags. We use it pervasively in README tables for an accessible status
# indicator that doesn't depend on color. Allow it (and other common
# HTML elements GitHub renders).
[tool.rumdl.MD033]
allowed = ["kbd", "br", "sub", "sup", "details", "summary", "strong"]

[tool.rumdl.MD044]
names = ["yarlpattern", "GitHub"]
code-blocks = false
# Shields.io badge URLs encode the *display label*, which often differs in
# case from the proper-name spelling. The badge text is rendered as an
# image; rumdl's URL scan is a false positive there.
html-elements = false

[tool.rumdl.MD049]
style = "asterisk"

[tool.rumdl.MD050]
style = "asterisk"

# --- Code blocks ---
[tool.rumdl.MD040]
style = "consistent"
unknown-language-action = "warn"

[tool.rumdl.MD046]
style = "fenced"

[tool.rumdl.MD048]
style = "backtick"

# --- Links ---
[tool.rumdl.MD057]
compact-paths = true

# --- Forbidden terms (catch stale TODOs in published docs) ---
[tool.rumdl.MD061]
terms = ["TODO", "FIXME", "XXX", "HACK"]

# --- Per-file overrides ---
[tool.rumdl.per-file-flavor]
# Site pages use mkdocs / pymdownx extensions (admonitions, tabbed code blocks)
# that rumdl's default ("commonmark") flags as raw HTML noise.
"docs/**/*.md" = "mkdocs"

[tool.rumdl.per-file-ignores]
".github/PULL_REQUEST_TEMPLATE.md" = ["MD041"]
"SECURITY.md" = ["MD036"]
# About-section wrappers are single-line ``--8<-- "FILE"`` snippet
# directives; the included file supplies the H1. rumdl can't follow
# the inclusion at lint time.
"docs/about/contributing.md" = ["MD041"]
"docs/about/changelog.md" = ["MD041"]
"docs/about/security.md" = ["MD041"]
"docs/about/code-of-conduct.md" = ["MD041"]
"README.md" = ["MD044", "MD061"]
# PSR changelog output: list style / blank lines differ from repo-wide markdown rules
"CHANGELOG.md" = ["MD004", "MD012"]

[tool.ruff]
line-length = 120
target-version = "py312"
# reference/ holds verbatim excerpts from upstream projects — not
# meant to compile in-tree; never lint or format.
extend-exclude = ["reference"]

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    "D",       # pydocstyle handled below per-file
    "ANN401",  # Any allowed in interior helpers; protocol surfaces enforce types
    "COM812",  # trailing-comma conflicts with ruff format
    "FIX",     # TODO/FIXME tracking is for issue tracker, not lint
    "TD002",   # don't require author on TODOs
    "TD003",   # don't require issue link on TODOs
    # --- Stylistic noise on spec-driven code; reasonable defaults for this project.
    "TRY003",  # raise TypeError(f"...") is the idiomatic exception pattern in this codebase
    "EM101",   # raw-string-in-exception — pairs with TRY003
    "EM102",   # f-string-in-exception — pairs with TRY003
    "PLR2004", # magic-value-comparison — spec tables / port numbers / encode-set bytes are inherently "magic"
    "S101",    # `assert` — used as defensive spec-invariant checks in non-test code; not security-sensitive
    "C901",    # complex-structure — spec-faithful algorithms (FSM, parser) naturally exceed default complexity limits
    "PLR0911", # too-many-return-statements — same rationale as C901
    "PLR0912", # too-many-branches — same rationale
    "PLR0915", # too-many-statements — same rationale
    "ERA001",  # commented-out-code — we keep short spec references in comments
    "RUF002",  # ambiguous-unicode-character-docstring — em-dash etc. is fine in docstrings
    "RUF003",  # ambiguous-unicode-character-comment — same
    "SIM108",  # ternary instead of if/else — sometimes the long form reads better
    "PERF403", # manual-dict-comprehension — long-form loop is fine when the body is non-trivial
    "TRY301",  # raise-within-try — appropriate when the try block has multiple failure modes
]

[tool.ruff.lint.mccabe]
max-complexity = 12

[tool.ruff.lint.pylint]
max-args = 10
max-branches = 16
max-statements = 60

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.isort]
known-first-party = ["yarlpattern"]
force-single-line = false

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = [
    "S101",    # assert is the entire point of tests
    "PLR2004", # magic numbers in tests are fine
    "ANN",     # tests don't require full annotations
    "D",       # tests don't require docstrings
    "INP001",  # tests dir is not a package
    "PT018",   # composite asserts in tests are readable for "match + group" patterns
    "N802",    # `test_*_baseURL_*` names mirror the spec component name
    "S105",    # `password = ...` is dict-key naming, not a hardcoded credential
    "SLF001",  # tests legitimately reach into ``_private`` attributes to
               # assert internal wiring (e.g. ``pat._engine is X``).
]
"benchmarks/**/*.py" = [
    "S101",    # ``assert`` validates fixture invariants inside benchmark bodies
    "PLR2004", # magic literals are unavoidable in benchmark payloads
    "ANN",     # benchmarks don't require full annotations
    "D",       # benchmarks document at module level, not per-function
    "S105",    # ``password = ...`` is dict-key naming, not a hardcoded credential
    "S106",    # same — ``password="bar"`` in kitchen-sink benchmark payloads
]
"scripts/**/*.py" = [
    "T201",    # print is fine in CLI scripts
    "INP001",
    "S105",    # ``SYM_PASS`` / ``COLOR_PASS`` constant names trip the
               # hardcoded-password detector. They're status symbols.
    "FBT001",  # local helper functions in scripts use boolean positional
               # args (``expect(idx, name, pattern, expected=True)``);
               # not worth a keyword-only constraint for a single-file
               # one-shot script.
]
"src/yarlpattern/_constructor.py" = [
    "SLF001",  # FSM helper methods are internal to this module; the parser
               # class and its driver function live in the same file by
               # design, so ``parser._foo()`` access is intra-module.
]
"src/yarlpattern/_regex_engine/__init__.py" = [
    "PLC0415", # Engine adapters are lazily imported on demand so installing
               # the package without the ``[regex]`` extra doesn't pay an
               # import cost for code it can't use. The top-of-file
               # placement requirement doesn't fit this dispatch pattern.
]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
docstring-code-format = true

[tool.mypy]
python_version = "3.12"
strict = true
explicit_package_bases = true
mypy_path = ["src"]
cache_dir = ".mypy_cache"
sqlite_cache = true
incremental = true
enable_error_code = [
    "exhaustive-match",
    "possibly-undefined",
    "truthy-bool",
    "ignore-without-code",
]
exclude = '''(?x)(
    ^\.venv/
    | ^build/
    | ^dist/
    | \.egg-info/
    | ^reference/
)'''

[[tool.mypy.overrides]]
module = ["tests.*"]
disallow_untyped_defs = false
disallow_incomplete_defs = false
disallow_untyped_calls = false
# Tests freely index into ``Optional`` after explicit ``assert is not None``
# guards and consume JSON via ``json.loads`` (returns ``Any``). Strict mode
# doesn't honor the narrowing or the ``Any`` round-trip in a way that
# matches how the test bodies actually read.
disable_error_code = ["index", "union-attr", "no-any-return"]

[[tool.mypy.overrides]]
module = ["scripts.*"]
# Compliance-report CLI consumes JSON via ``json.loads`` (returns ``Any``)
# and indexes into spec result dicts after explicit guards.
disable_error_code = ["index", "union-attr", "no-any-return", "no-untyped-call"]

[tool.pyright]
pythonVersion = "3.12"
pythonPlatform = "All"
typeCheckingMode = "strict"
include = ["src", "tests", "scripts"]
exclude = [".venv", "build", "dist", "**/__pycache__", "reference"]
# Cross-module access to ``_private`` names is intentional inside a package:
# helpers in ``_url.py`` are consumed by ``_pattern.py`` etc. Pyright's
# strict mode flags this as cross-file leakage, but the boundary that
# matters is the public ``yarlpattern.*`` re-exports in ``__init__.py``.
reportPrivateUsage = "none"
# ``field(default_factory=list)`` infers as partially-unknown under strict
# mode even when the surrounding dataclass field is fully typed; the field
# annotation is authoritative. Engine-cache helpers are intentionally only
# used from tests and at lazy-import time.
reportUnknownVariableType = "warning"
reportUnknownArgumentType = "warning"
reportUnusedFunction = "warning"

[[tool.pyright.executionEnvironments]]
root = "src"
extraPaths = ["src"]

[[tool.pyright.executionEnvironments]]
root = "tests"
extraPaths = ["src", "."]
reportPrivateUsage = "none"
reportUnknownMemberType = "none"
reportUnknownVariableType = "none"
reportUnknownLambdaType = "none"
reportUnknownArgumentType = "none"
reportAttributeAccessIssue = "none"
reportOptionalSubscript = "none"
reportOptionalMemberAccess = "none"
reportUnusedFunction = "none"

[[tool.pyright.executionEnvironments]]
root = "scripts"
extraPaths = ["src", "."]
reportPrivateUsage = "none"
reportOptionalMemberAccess = "none"
reportUnknownVariableType = "none"
reportUnknownMemberType = "none"
reportUnknownArgumentType = "none"


[tool.ty.src]
include = ["src"]

[tool.ty.rules]
# Dynamic TypedDict subscript is intentional in ``_url.py::components_with_base``:
# the spec iterates the chain of inherited components, looking each one up by
# its component name. mypy/pyright accept ``# type: ignore[literal-required]``;
# ty needs its own knob.
invalid-key = "warn"

[tool.pytest.ini_options]
minversion = "8.0"
addopts = ["--tb=short", "--strict-markers", "--strict-config", "--import-mode=importlib"]
xfail_strict = true
filterwarnings = ["once::Warning"]
testpaths = ["tests"]
markers = [
    "wpt: marks tests parametrized from the upstream WPT urlpattern corpus",
    "polyfill: marks tests parametrized from the WICG urlpattern-polyfill corpus",
]

# ---------------------------------------------------------------------------
# Coverage
# ---------------------------------------------------------------------------
#
# Opt-in, machine-readable coverage. Invoke with:
#
#     uv run pytest --cov --cov-report=json --cov-report=term-missing
#
# The JSON report lands at ``.coverage.json`` (format documented at
# https://coverage.readthedocs.io/en/latest/cmd.html#json-reporting).
# Both humans and tools can consume it:
#
#     jq '.totals | {percent_covered, num_statements, missing_lines}' .coverage.json
#     jq '.files | to_entries | map({k: .key, pct: .value.summary.percent_covered}) | sort_by(.pct)' .coverage.json
#
# Branch coverage is on by default — catches "if cond: return" where the
# false branch is never exercised.

[tool.coverage.run]
# Package name (not ``src/...``) so coverage matches imports from a wheel
# in CI (see structlog: extract sdist, ``rm -rf src``, test against wheel only).
# Run tests with ``coverage run -m pytest`` (as structlog does via tox), not
# ``pytest --cov`` — aligns with their workflow and with ``parallel`` data files.
source = ["yarlpattern"]
branch = true
parallel = true
data_file = ".coverage"
omit = [
    "*/yarlpattern/__init__.py",
]

# Map checkout tree and installed wheel paths so ``coverage combine`` can merge
# Linux/Windows and matrix data (structlog: ``src`` + site-packages)
[tool.coverage.paths]
source = ["src/yarlpattern", "*/site-packages/yarlpattern"]

[tool.coverage.report]
# Do not set fail_under here: matrix jobs only collect .coverage.*; the CI
# ``coverage`` job runs ``coverage report --fail-under`` on combined data.
show_missing = true
skip_covered = false
skip_empty = true
precision = 1
sort = "-Cover"
exclude_also = [
    "raise NotImplementedError",
    "if TYPE_CHECKING:",
    "^\\s*\\.\\.\\.$",
    "@overload",
    "pragma: no cover",
]

[tool.coverage.json]
output = ".coverage.json"
pretty_print = false
show_contexts = false

[tool.coverage.html]
directory = "htmlcov"

# ---------------------------------------------------------------------------
# interrogate  (docstring coverage)
# ---------------------------------------------------------------------------
[tool.interrogate]
ignore-init-method = true
ignore-magic = true
ignore-overloaded-functions = true
ignore-property-decorators = true
ignore-private = true
ignore-semiprivate = true
# Spec-driven modules document the per-step rationale in module docstrings
# and on the public methods. Every helper function having its own docstring
# would mostly restate the spec section number.
fail-under = 90
exclude = ["tests", "scripts", "reference"]

# ---------------------------------------------------------------------------
# python-semantic-release
# ---------------------------------------------------------------------------
[tool.semantic_release]
commit_parser = "conventional"
major_on_zero = false
allow_zero_version = true
tag_format = "v{version}"
version_variables = ["src/yarlpattern/_version.py:__version__"]
build_command = "uv lock --upgrade-package yarlpattern"

[tool.semantic_release.changelog]
mode = "update"
# Custom Jinja2 templates under .semantic-release/templates/ inject a versioned
# PyPI deep-link into each release heading — see
# .semantic-release/templates/.components/versioned_changes.md.j2. When this
# directory exists with any .j2 files, PSR uses these templates in place of its
# bundled defaults (binary switch, no merge with defaults).
template_dir = ".semantic-release/templates"
insertion_flag = "<!-- version list -->"

[tool.semantic_release.changelog.default_templates]
changelog_file = "CHANGELOG.md"
exclude_commit_patterns = [
    'chore\(release\): .*',
    'ci\(.*\): .*',
    'style\(.*\): .*',
    'Merged? .*',
]

[tool.semantic_release.remote]
type = "github"
token = { env = "GH_TOKEN" }

[tool.semantic_release.branches.main]
match = "^main$"
prerelease = false

# ---------------------------------------------------------------------------
# codespell
# ---------------------------------------------------------------------------
[tool.codespell]
# - ``caf`` appears in the canonical UTF-8 example string ``café``
# - ``deriver`` is a noun used in spec commentary
# - ``overrideable`` matches Python's ``__override__`` naming, not "overridable"
# - ``crate`` is the Rust analogue we reference in comments
ignore-words-list = "te,noth,caf,deriver,overrideable,crate"
skip = "*.lock,./dist,./build,./.mypy_cache,./.ruff_cache,./.scratch,./reference,./docs/wpt-compliance.md"