pyproject.toml

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

[project]
name = "pyhaul"
description = "Resumable, cursor-based, CDN-safe HTTP downloads for Python"
dynamic = ["version", "readme"]
license = "MIT"
license-files = ["LICENSE"]
requires-python = ">=3.12"
authors = [
    { name = "pyhaul contributors" },
]
keywords = [
    "http",
    "download",
    "resume",
    "range",
    "partial",
    "aiohttp",
]
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Developers",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Programming Language :: Python :: 3.15",
    "Topic :: Internet :: WWW/HTTP",
    "Topic :: System :: Networking",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Typing :: Typed",
]
dependencies = []

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

[project.optional-dependencies]
niquests = [
    "niquests>=3.14",
]
requests = [
    "requests>=2.32",
]
httpx = [
    "httpx>=0.27",
]
urllib3 = [
    "urllib3>=2.0",
]
aiohttp = [
    "aiohttp>=3.10",
]
wreq = [
    "wreq>=0.11",
]

[tool.hatch.version]
path = "src/pyhaul/_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/pyhaul/blob/main/\2)'

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

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

[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.
# All optional HTTP stacks for the test suite (mirrors optional-extras version floors).
compat-all = [
    "niquests>=3.14",
    "requests>=2.32",
    "types-requests>=2.33.0.20260906",
    "httpx>=0.27",
    "urllib3>=2.0",
    "aiohttp>=3.10",
    "wreq>=0.11",
]
test = [
    { include-group = "compat-all" },
    "pytest>=9.1.1",
    "pytest-cov>=7.1.0",
    "hypothesis>=6.168.4",
    "anyio>=4.15.1",
]
lint = [
    "ruff>=0.16.10",
    "mypy>=2.4.0",
    "prek>=0.5.5",
    "pyright>=1.1.414",
    "tenacity>=9.1.4",
    "ty>=0.0.84",
    "codespell>=2.4.3",
    "validate-pyproject[all]>=0.26",
    "semgrep>=1.179.0",
    "interrogate>=1.7.0",
]
# Extra tooling (not needed for the library at runtime) — pyclean for cache cleaning.
dev = [
    "pyclean>=3.7.0",
]
# Maintainer / CI-surface tools (workflows, Renovate, markdown policy). Includes `dev`
# (pyclean) so `just clean` and maintainer lints share one resolved set.
docs = [
    "properdocs>=1.6.7",
    "mkdocs-material>=9.7.7",
    "mkdocstrings[python]>=1.0.6",
    "mkdocs-code-validator>=0.2.1",
    "mike>=2.2.0",
]
maintainer = [
    { include-group = "dev" },
    "python-semantic-release>=10.7.0",
    "rumdl>=0.2.78",
    "check-jsonschema>=0.38.1",
    "zizmor>=1.30.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, exempt only that package until the fix ages past
# 72h: add `exclude-newer-package = { <name> = false }` here, then `uv lock --upgrade-package <name>`.
exclude-newer = "72h"

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

[tool.rumdl]
respect-gitignore = true
exclude = [".git", "node_modules", "dist", "build", ".scratch"]

# --- 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 ---
[tool.rumdl.MD033]
allowed-elements = ["details", "summary", "strong"]

[tool.rumdl.MD044]
names = ["pyhaul", "Python", "GitHub"]
code-blocks = 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]
"docs/**/*.md" = "mkdocs"

[tool.rumdl.per-file-ignores]
".github/PULL_REQUEST_TEMPLATE.md" = ["MD041"]
"SECURITY.md" = ["MD036"]
"README.md" = ["MD044", "MD061"]
# PSR changelog output: list style / blank lines differ from repo-wide markdown rules
"CHANGELOG.md" = ["MD004", "MD012", "MD044"]

[tool.ruff]
line-length = 120
target-version = "py312"
respect-gitignore = true
extend-exclude = []

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    "ANN",      # type annotations — mypy / pyright / ty are authoritative
    "COM812",   # missing trailing comma — conflicts with ruff formatter
    "ISC001",   # implicit string concat — conflicts with ruff formatter
    "CPY001",   # per-file copyright headers — LICENSE covers the package
    "D104",     # missing package __init__.py docstring — noise for marker files
    "D107",     # missing __init__ docstring — class docstring suffices
    "EM101",    # string literal in exception — descriptive messages are intentional
    "EM102",    # f-string in exception — same
    "TRY003",   # long exception message — same
    "E501",     # line length — formatter handles this
    "PLC0415",  # import not at top level — lazy imports are deliberate
    "PLR0913",  # too many arguments — complex constructors are fine
    "TC001",    # typing-only first-party import — deferred to future refactor
    "TC002",    # typing-only third-party import — same
    "TC003",    # typing-only stdlib import — same
]
unfixable = ["F401"]

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

[tool.ruff.lint.pylint]
max-args = 5
max-branches = 12
max-statements = 50
max-returns = 6

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

[tool.ruff.lint.isort]
combine-as-imports = true
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
known-first-party = ["pyhaul"]

[tool.ruff.lint.per-file-ignores]
# Standalone CI, action, and docs-build scripts, run by path rather than imported.
".github/actions/**/*.py" = ["INP001", "D1", "T201"]
".github/scripts/*.py" = ["INP001", "D1", "S603", "S607"]
"docs/.hooks/*.py" = ["INP001", "D1"]
"**/test_*.py" = [
    "S101",     # assert is how you test
    "D",        # no docstrings in tests
    "ARG",      # unused args from fixtures / protocol stubs
    "S108",     # /tmp paths in test assertions
    "FBT",      # boolean positional args in test helpers
    "SLF001",   # private-member access for testing internals
    "PLR2004",  # magic values in assertions
    "N802",     # function-name conventions (test method names)
    "C901",     # complexity in tests is fine
    "PYI034",   # non-self return type in test doubles
    "A002",     # builtin-arg shadowing in test helpers
    "PT011",    # raises too broad — errno checks are more precise than match=
    "PT017",    # assert in except — sometimes clearer than pytest.raises
]
"**/conftest.py" = ["D", "ARG", "S101", "SLF001", "A002", "N802", "C901"]
"examples/**" = ["T20", "INP001", "D", "ASYNC240"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
line-ending = "auto"

[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/
)'''

[tool.pyright]
pythonVersion = "3.12"
pythonPlatform = "All"
typeCheckingMode = "strict"
include = ["src", "tests", "examples"]
exclude = [".venv", "build", "dist", "**/__pycache__"]

# Tests need repo root on the path for ``from tests.…``; relax noisy rules there only.
[[tool.pyright.executionEnvironments]]
root = "src"
extraPaths = ["src"]

[[tool.pyright.executionEnvironments]]
root = "tests"
extraPaths = ["src", "."]
reportPrivateUsage = false
reportUnknownMemberType = false
reportUnknownVariableType = false
reportUnknownLambdaType = false
reportUnknownArgumentType = false
reportAttributeAccessIssue = false

[[tool.pyright.executionEnvironments]]
root = "examples"
extraPaths = ["src"]
reportUnknownParameterType = false
reportUnknownArgumentType = false
reportMissingTypeStubs = false

# ---------------------------------------------------------------------------
# ty  (Astral's Rust-based type checker — scoped to library code only)
# ---------------------------------------------------------------------------
[tool.ty.src]
include = ["src"]

[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"]

# ---------------------------------------------------------------------------
# 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 = ["pyhaul"]
branch = true
parallel = true
data_file = ".coverage"
omit = [
    "*/pyhaul/__init__.py",
    "*/pyhaul/_types.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/pyhaul", "*/site-packages/pyhaul"]

[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-private = true
ignore-semiprivate = true
fail-under = 100
exclude = ["tests", "examples"]

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

[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]
ignore-words-list = "te,noth"
skip = "*.lock,./dist,./build,./.mypy_cache,./.ruff_cache,./.scratch"