ccdirectives 0.2.0__tar.gz

ccdirectives-0.2.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

ccdirectives-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Third-party reference files, fetched locally by scripts/fetch_upstream.py; only the manifest is tracked.
+tests/upstream/*
+!tests/upstream/MANIFEST.json

ccdirectives-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0]
+
+### Added
+
+- Strict mode: `parse(header, strict=True, context=...)` raises `CacheControlError` with the
+  offset for syntax outside RFC 9111 section 5.2, control characters, repeated directives,
+  malformed delta-seconds, arguments on directives that take none and field lists that are
+  not field names.
+- Several field lines can be passed as a list.
+- Freshness helpers: `assess` and `Freshness`, `freshness_lifetime`, `current_age` and
+  `may_store`, covering RFC 9111 section 4.2, RFC 5861 and request directives.
+- Targeted fields (RFC 9213): `parse_targeted`, `build_targeted` and `select`, on a
+  structured field dictionary parser checked against the httpwg test corpus.
+- `REGISTERED_DIRECTIVES`, `REQUEST_DIRECTIVES`, `RESPONSE_DIRECTIVES`, `DELTA_MAX`,
+  `CacheControl.duplicates`, `extensions()`, `has()`, `seconds()`, `no_cache_fields` and
+  `private_fields`.
+- A `ccdirectives` command that prints the policy of a header value or a response head.
+
+### Fixed
+
+- delta-seconds accept ASCII digits only (no sign, underscore or other digits) and values
+  above 2147483648 become 2147483648.
+- The first occurrence of a repeated directive wins instead of the last.
+- `no-cache=""` and `private=""` count as present; a bare `max-stale` reads as unlimited.
+- An unterminated quote no longer swallows the directives after it.
+- CR, LF and NUL in a value become spaces; names fold ASCII letters only.
+- `build` refuses names that are not tokens, control characters, non-ASCII text, negative
+  numbers and malformed delta-seconds, and writes field lists in quoted-string form.
+
+## [0.1.0]
+
+- Parse a Cache-Control header into a typed, case-insensitive `CacheControl` structure.
+- Build a header string back from a `CacheControl`, quoting and escaping arguments when needed.
+- Typed accessors for the common directives, with unknown directives preserved verbatim.

ccdirectives-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/ccdirectives/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests inject time, disk and network; they
+  never touch the real thing.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

ccdirectives-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ccdirectives-0.2.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: ccdirectives
+Version: 0.2.0
+Summary: Parse, validate and build HTTP Cache-Control and CDN-Cache-Control, and decide freshness, typed and zero-dependency
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/ccdirectives
+Project-URL: Issues, https://github.com/JaviLianes8/ccdirectives/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/ccdirectives/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache-control,caching,cdn-cache-control,freshness,headers,http,rfc5861,rfc9111,rfc9213
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ccdirectives
+
+Parse, validate and build the HTTP `Cache-Control` header (RFC 9111) and targeted fields
+such as `CDN-Cache-Control` (RFC 9213), and decide freshness, typed and zero-dependency.
+
+## Install
+
+```
+pip install ccdirectives
+```
+
+## Usage
+
+Read what a response allows:
+
+```python
+from ccdirectives import parse
+
+cc = parse('max-age=600, no-cache="Set-Cookie", x-vendor=custom, MAX-AGE=5')
+print(cc.max_age, cc.no_cache, cc.no_cache_fields)
+# 600 True ('set-cookie',)
+print(cc["x-vendor"], cc.extensions(), sorted(cc.duplicates))
+# custom ('x-vendor',) ['max-age']
+```
+
+Names compare case-insensitively (ASCII letters only), delta-seconds become ints, and the
+first occurrence of a repeated directive wins, as RFC 9111 section 4.2.1 says; repeated
+names are listed in `duplicates`. delta-seconds are ASCII digits only, and a value too
+large to represent is read as 2147483648, the "forever" of section 1.2.2:
+
+```python
+from ccdirectives import parse
+
+print(parse("max-age=99999999999").max_age, parse("max-age=-5").max_age)
+# 2147483648 None
+print(parse("max-stale").max_stale, parse(["max-age=60", "public"]).public)
+# 2147483648 True
+```
+
+The default parser never raises on content: what it cannot read is skipped, and a broken
+quote cannot hide the directives after it. Strict mode validates instead, with the rules
+of a request or a response when you pass `context`. It holds a header to what a recipient
+must accept, so `max-age="60"` passes although a sender should not write it:
+
+```python
+from ccdirectives import CacheControlError, parse
+
+print(parse('private="a, x="open, no-store').no_store)
+# True
+try:
+    parse("max-age=60, no-store=1", strict=True, context="response")
+except CacheControlError as error:
+    print(error)
+# 'no-store' takes no argument at offset 12
+```
+
+`build` writes a value back and refuses what the grammar cannot carry, such as a line
+break in an argument, a negative age or a name that is not a token. delta-seconds go out
+as tokens and field lists as quoted strings, so the output always passes strict mode:
+
+```python
+from ccdirectives import CacheControl, build
+
+print(build(CacheControl({"max-age": 3600, "private": "Set-Cookie", "immutable": True})))
+# max-age=3600, private="Set-Cookie", immutable
+```
+
+### Freshness
+
+`assess` applies RFC 9111 section 4.2 and RFC 5861 to a stored response of a given age,
+optionally narrowed by the request directives:
+
+```python
+from ccdirectives import assess, parse
+
+response = parse("max-age=600, stale-while-revalidate=30, stale-if-error=1200")
+verdict = assess(response, age=620)
+print(verdict.fresh, verdict.reusable, verdict.stale_while_revalidate, verdict.stale_if_error)
+# False False True True
+print(assess(response, age=620, request=parse("max-stale=60")).reusable)
+# True
+```
+
+`freshness_lifetime` and `current_age` expose the two calculations on their own (Expires
+and Date are passed as seconds since the epoch), and `may_store` says whether the
+directives let a private or shared cache store a response at all.
+
+### Targeted fields
+
+Targeted fields are structured field dictionaries (RFC 9651) with their own error rules:
+an empty or invalid field is ignored. `select` walks a cache's target list and falls back
+on `Cache-Control`:
+
+```python
+from ccdirectives import assess, select
+
+headers = {"Cache-Control": "max-age=60, s-maxage=120", "CDN-Cache-Control": "max-age=600"}
+field, policy = select(headers, ["CDN-Cache-Control"])
+print(field, assess(policy, age=0, shared=True).lifetime)
+# CDN-Cache-Control 600
+broken = {"CDN-Cache-Control": "max-age=1.5", "Cache-Control": "no-store"}
+print(select(broken, ["CDN-Cache-Control"]))
+# ('CDN-Cache-Control', CacheControl(directives={}, duplicates=frozenset()))
+```
+
+A `max-age` that is a Decimal breaks the directive's rules, so RFC 9213 says not to use
+it; the field itself is valid, so it still wins over `Cache-Control`.
+
+### Command line
+
+```
+$ curl -sI https://example.com/ | ccdirectives --shared
+$ ccdirectives --strict --age 30 "max-age=60, stale-while-revalidate=30"
+```
+
+It reads a header value, or a response head on standard input (the last response of a
+redirect chain), and prints the chosen field, its directives and the freshness verdict as
+JSON. From a head it takes the age from `Age` and, when `Cache-Control` applies, the
+lifetime fallback from `Expires` and `Date`. `--target` sets the target list; it defaults
+to `CDN-Cache-Control` with `--shared`. The exit status is 1 for a value `--strict`
+rejects and 2 for a usage error.
+
+## API
+
+| Name | What it does |
+| --- | --- |
+| `parse(header, *, strict=False, context=None)` | Read a field value or a list of field lines into a `CacheControl` |
+| `build(cc)` | Write a `CacheControl` as a field value |
+| `CacheControl` | Ordered, case-insensitive mapping with typed accessors and `duplicates` |
+| `DirectiveValue` | `int`, `str` or `bool`, the type of a directive value |
+| `CacheControlError` | `ValueError` with `reason` and `offset` for strict mode and `build` |
+| `parse_targeted(value)` | Read a targeted field, or None when RFC 9213 says to ignore it |
+| `build_targeted(cc)` | Write a `CacheControl` as a structured field dictionary |
+| `select(headers, targets)` | The field name and policy a cache with that target list follows |
+| `assess(response, *, age, ...)` | A `Freshness` verdict for a stored response |
+| `Freshness` | Lifetime, age, fresh, reusable and the two stale windows |
+| `freshness_lifetime(response, ...)` | Lifetime by the rules of RFC 9111 section 4.2.1 |
+| `current_age(...)` | Age by the rules of RFC 9111 section 4.2.3 |
+| `may_store(response, ...)` | Whether the directives allow a cache to store the response |
+| `DELTA_MAX` | 2147483648, the value an overflowing delta-seconds becomes |
+| `REGISTERED_DIRECTIVES` | The names in the IANA HTTP Cache Directive Registry |
+| `REQUEST_DIRECTIVES`, `RESPONSE_DIRECTIVES` | The registered names defined for each direction |
+
+## Why
+
+Every HTTP client, server and cache has to read `Cache-Control`, yet the parsers that
+exist are framework-bound: `werkzeug.http.parse_cache_control_header` ties you to Werkzeug
+and `webob.cachecontrol` to WebOb, while packages such as `CacheControl` and `hishel` are
+full cache transports, not directive codecs. None of them reads `CDN-Cache-Control` as the
+structured field it is. This library is the codec and the freshness arithmetic: a typed
+structure in, a correct header out, and nothing else to install.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

ccdirectives-0.2.0/README.md

@@ -0,0 +1,161 @@
+# ccdirectives
+
+Parse, validate and build the HTTP `Cache-Control` header (RFC 9111) and targeted fields
+such as `CDN-Cache-Control` (RFC 9213), and decide freshness, typed and zero-dependency.
+
+## Install
+
+```
+pip install ccdirectives
+```
+
+## Usage
+
+Read what a response allows:
+
+```python
+from ccdirectives import parse
+
+cc = parse('max-age=600, no-cache="Set-Cookie", x-vendor=custom, MAX-AGE=5')
+print(cc.max_age, cc.no_cache, cc.no_cache_fields)
+# 600 True ('set-cookie',)
+print(cc["x-vendor"], cc.extensions(), sorted(cc.duplicates))
+# custom ('x-vendor',) ['max-age']
+```
+
+Names compare case-insensitively (ASCII letters only), delta-seconds become ints, and the
+first occurrence of a repeated directive wins, as RFC 9111 section 4.2.1 says; repeated
+names are listed in `duplicates`. delta-seconds are ASCII digits only, and a value too
+large to represent is read as 2147483648, the "forever" of section 1.2.2:
+
+```python
+from ccdirectives import parse
+
+print(parse("max-age=99999999999").max_age, parse("max-age=-5").max_age)
+# 2147483648 None
+print(parse("max-stale").max_stale, parse(["max-age=60", "public"]).public)
+# 2147483648 True
+```
+
+The default parser never raises on content: what it cannot read is skipped, and a broken
+quote cannot hide the directives after it. Strict mode validates instead, with the rules
+of a request or a response when you pass `context`. It holds a header to what a recipient
+must accept, so `max-age="60"` passes although a sender should not write it:
+
+```python
+from ccdirectives import CacheControlError, parse
+
+print(parse('private="a, x="open, no-store').no_store)
+# True
+try:
+    parse("max-age=60, no-store=1", strict=True, context="response")
+except CacheControlError as error:
+    print(error)
+# 'no-store' takes no argument at offset 12
+```
+
+`build` writes a value back and refuses what the grammar cannot carry, such as a line
+break in an argument, a negative age or a name that is not a token. delta-seconds go out
+as tokens and field lists as quoted strings, so the output always passes strict mode:
+
+```python
+from ccdirectives import CacheControl, build
+
+print(build(CacheControl({"max-age": 3600, "private": "Set-Cookie", "immutable": True})))
+# max-age=3600, private="Set-Cookie", immutable
+```
+
+### Freshness
+
+`assess` applies RFC 9111 section 4.2 and RFC 5861 to a stored response of a given age,
+optionally narrowed by the request directives:
+
+```python
+from ccdirectives import assess, parse
+
+response = parse("max-age=600, stale-while-revalidate=30, stale-if-error=1200")
+verdict = assess(response, age=620)
+print(verdict.fresh, verdict.reusable, verdict.stale_while_revalidate, verdict.stale_if_error)
+# False False True True
+print(assess(response, age=620, request=parse("max-stale=60")).reusable)
+# True
+```
+
+`freshness_lifetime` and `current_age` expose the two calculations on their own (Expires
+and Date are passed as seconds since the epoch), and `may_store` says whether the
+directives let a private or shared cache store a response at all.
+
+### Targeted fields
+
+Targeted fields are structured field dictionaries (RFC 9651) with their own error rules:
+an empty or invalid field is ignored. `select` walks a cache's target list and falls back
+on `Cache-Control`:
+
+```python
+from ccdirectives import assess, select
+
+headers = {"Cache-Control": "max-age=60, s-maxage=120", "CDN-Cache-Control": "max-age=600"}
+field, policy = select(headers, ["CDN-Cache-Control"])
+print(field, assess(policy, age=0, shared=True).lifetime)
+# CDN-Cache-Control 600
+broken = {"CDN-Cache-Control": "max-age=1.5", "Cache-Control": "no-store"}
+print(select(broken, ["CDN-Cache-Control"]))
+# ('CDN-Cache-Control', CacheControl(directives={}, duplicates=frozenset()))
+```
+
+A `max-age` that is a Decimal breaks the directive's rules, so RFC 9213 says not to use
+it; the field itself is valid, so it still wins over `Cache-Control`.
+
+### Command line
+
+```
+$ curl -sI https://example.com/ | ccdirectives --shared
+$ ccdirectives --strict --age 30 "max-age=60, stale-while-revalidate=30"
+```
+
+It reads a header value, or a response head on standard input (the last response of a
+redirect chain), and prints the chosen field, its directives and the freshness verdict as
+JSON. From a head it takes the age from `Age` and, when `Cache-Control` applies, the
+lifetime fallback from `Expires` and `Date`. `--target` sets the target list; it defaults
+to `CDN-Cache-Control` with `--shared`. The exit status is 1 for a value `--strict`
+rejects and 2 for a usage error.
+
+## API
+
+| Name | What it does |
+| --- | --- |
+| `parse(header, *, strict=False, context=None)` | Read a field value or a list of field lines into a `CacheControl` |
+| `build(cc)` | Write a `CacheControl` as a field value |
+| `CacheControl` | Ordered, case-insensitive mapping with typed accessors and `duplicates` |
+| `DirectiveValue` | `int`, `str` or `bool`, the type of a directive value |
+| `CacheControlError` | `ValueError` with `reason` and `offset` for strict mode and `build` |
+| `parse_targeted(value)` | Read a targeted field, or None when RFC 9213 says to ignore it |
+| `build_targeted(cc)` | Write a `CacheControl` as a structured field dictionary |
+| `select(headers, targets)` | The field name and policy a cache with that target list follows |
+| `assess(response, *, age, ...)` | A `Freshness` verdict for a stored response |
+| `Freshness` | Lifetime, age, fresh, reusable and the two stale windows |
+| `freshness_lifetime(response, ...)` | Lifetime by the rules of RFC 9111 section 4.2.1 |
+| `current_age(...)` | Age by the rules of RFC 9111 section 4.2.3 |
+| `may_store(response, ...)` | Whether the directives allow a cache to store the response |
+| `DELTA_MAX` | 2147483648, the value an overflowing delta-seconds becomes |
+| `REGISTERED_DIRECTIVES` | The names in the IANA HTTP Cache Directive Registry |
+| `REQUEST_DIRECTIVES`, `RESPONSE_DIRECTIVES` | The registered names defined for each direction |
+
+## Why
+
+Every HTTP client, server and cache has to read `Cache-Control`, yet the parsers that
+exist are framework-bound: `werkzeug.http.parse_cache_control_header` ties you to Werkzeug
+and `webob.cachecontrol` to WebOb, while packages such as `CacheControl` and `hishel` are
+full cache transports, not directive codecs. None of them reads `CDN-Cache-Control` as the
+structured field it is. This library is the codec and the freshness arithmetic: a typed
+structure in, a correct header out, and nothing else to install.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

ccdirectives-0.2.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ccdirectives"
+version = "0.2.0"
+description = "Parse, validate and build HTTP Cache-Control and CDN-Cache-Control, and decide freshness, typed and zero-dependency"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = ["cache-control", "cdn-cache-control", "http", "caching", "rfc9111", "rfc9213", "rfc5861", "freshness", "headers"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.scripts]
+ccdirectives = "ccdirectives._cli:main"
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/ccdirectives"
+Issues = "https://github.com/JaviLianes8/ccdirectives/issues"
+Changelog = "https://github.com/JaviLianes8/ccdirectives/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ccdirectives"]
+
+[tool.hatch.build.targets.sdist]
+# Third-party reference files are fetched locally and never shipped; only their manifest is.
+exclude = [
+    ".github",
+    "IMPROVEMENTS-round*.md",
+    "tests/upstream/*.txt",
+    "tests/upstream/*.csv",
+    "tests/upstream/sf",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

ccdirectives-0.2.0/requirements-dev.txt

@@ -0,0 +1,3 @@
+# Development dependencies: the package in editable mode plus its dev extras
+# (ruff, mypy, pytest, build, twine). Install with:  pip install -r requirements-dev.txt
+-e .[dev]

ccdirectives-0.2.0/scripts/check.ps1

@@ -0,0 +1,16 @@
+# Local quality gate. Run before every commit. No CI runs in the cloud.
+# $ErrorActionPreference does NOT stop on a native command's non-zero exit, so each tool's
+# exit code is checked explicitly: a red gate must fail, never pass silently.
+$ErrorActionPreference = "Stop"
+
+function Invoke-Step($label, [scriptblock]$cmd) {
+    Write-Host "== $label =="
+    & $cmd
+    if ($LASTEXITCODE -ne 0) { Write-Host "FAILED: $label (exit $LASTEXITCODE)"; exit $LASTEXITCODE }
+}
+
+Invoke-Step "ruff format" { ruff format --check . }
+Invoke-Step "ruff lint"   { ruff check . }
+Invoke-Step "mypy"        { mypy --strict src tests }
+Invoke-Step "pytest"      { pytest }
+Write-Host "gate green"

ccdirectives-0.2.0/scripts/fetch_upstream.py

@@ -0,0 +1,39 @@
+"""Fetch the third-party test files listed in tests/upstream/MANIFEST.json.
+
+The files are not part of the repository. Their tests skip until this script has fetched
+them; each download is checked against the size and sha256 in the manifest.
+
+    python scripts/fetch_upstream.py
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+import urllib.request
+from pathlib import Path
+
+FOLDER = Path(__file__).resolve().parents[1] / "tests" / "upstream"
+
+
+def main() -> int:
+    manifest = json.loads((FOLDER / "MANIFEST.json").read_text(encoding="utf-8"))
+    failed = 0
+    for name, entry in manifest.items():
+        with urllib.request.urlopen(entry["url"], timeout=60) as response:
+            body = response.read()
+        digest = hashlib.sha256(body).hexdigest()
+        if len(body) != entry["size"] or digest != entry["sha256"]:
+            print(f"{name}: got {len(body)} bytes, sha256 {digest}; manifest differs")
+            failed += 1
+            continue
+        target = FOLDER / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(body)
+        print(f"{name}: ok")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ccdirectives-0.2.0/scripts/release.ps1

@@ -0,0 +1,28 @@
+# Build and upload to PyPI. Run scripts/check.ps1 first.
+# The name must not already exist on PyPI; the token is read from a secret store, never git.
+$ErrorActionPreference = "Stop"
+
+# Works on both Windows PowerShell 5.1 and pwsh 7 (generic catch, no PS7-only types).
+$taken = $true
+try {
+    Invoke-WebRequest -UseBasicParsing "https://pypi.org/pypi/ccdirectives/json" | Out-Null
+} catch {
+    if ($_.Exception.Response.StatusCode.value__ -eq 404) { $taken = $false } else { throw }
+}
+if ($taken) { throw "The name 'ccdirectives' already exists on PyPI. Choose another before publishing." }
+
+$token = $env:PYPI_TOKEN
+if (-not $token -and (Test-Path "C:\secrets\pypi-token.txt")) {
+    $token = (Get-Content "C:\secrets\pypi-token.txt" -Raw).Trim()
+}
+if (-not $token) {
+    throw "No PyPI token. Set `$env:PYPI_TOKEN or save it to C:\secrets\pypi-token.txt (never commit it)."
+}
+
+Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue
+python -m build
+python -m twine check dist/*
+
+$env:TWINE_USERNAME = "__token__"
+$env:TWINE_PASSWORD = $token
+try { python -m twine upload dist/* } finally { Remove-Item Env:\TWINE_PASSWORD -ErrorAction SilentlyContinue }

ccdirectives-0.2.0/src/ccdirectives/__init__.py

@@ -0,0 +1,34 @@
+"""Parse and build the HTTP Cache-Control header as a typed, zero-dependency structure."""
+
+from __future__ import annotations
+
+from ._build import build
+from ._chars import DELTA_MAX
+from ._errors import CacheControlError
+from ._fresh import Freshness, assess, current_age, freshness_lifetime, may_store
+from ._model import CacheControl, DirectiveValue
+from ._parse import parse
+from ._registry import REGISTERED_DIRECTIVES, REQUEST_DIRECTIVES, RESPONSE_DIRECTIVES
+from ._targeted import build_targeted, parse_targeted, select
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DELTA_MAX",
+    "REGISTERED_DIRECTIVES",
+    "REQUEST_DIRECTIVES",
+    "RESPONSE_DIRECTIVES",
+    "CacheControl",
+    "CacheControlError",
+    "DirectiveValue",
+    "Freshness",
+    "assess",
+    "build",
+    "build_targeted",
+    "current_age",
+    "freshness_lifetime",
+    "may_store",
+    "parse",
+    "parse_targeted",
+    "select",
+]

ccdirectives-0.2.0/src/ccdirectives/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m ccdirectives``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())