headgate 0.2.0__tar.gz → 0.4.0__tar.gz

{headgate-0.2.0 → headgate-0.4.0}/.gitignore

@@ -12,3 +12,6 @@ htmlcov/
 .benchmarks/
 mutants/
 .hypothesis/
+
+# The docs site, built by `zensical build`
+site/

{headgate-0.2.0 → headgate-0.4.0}/CHANGELOG.md

@@ -6,6 +6,57 @@ change the public API; such changes are listed under **Changed** and **Removed**
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-26
+
+Bounds `paginate()`: a page budget, and a stop at pages with no items. The stop changes what three pagers do by
+default, so this is a minor release: see **Changed**.
+
+### Added
+
+- A page budget for `paginate()`: `limit=PageLimit(max_pages)` raises the new `PageLimitError` once the budget is spent
+  with pages still to come, or with `on_limit="stop"` ends the walk there
+  ([#14](https://github.com/kelsayed17/headgate/issues/14)).
+- A documentation site at <https://kelsayed17.github.io/headgate/>, built from `docs/`, with a page comparing headgate
+  with tenacity, stamina and a hand-rolled client.
+- `examples/github_client.py`: a tested client for a few GitHub REST endpoints.
+
+### Changed
+
+- `Cursor`, `NextUrl` and `LinkHeader` stop at a page with no items, as `Offset` already did, instead of following its
+  link: a link that advances while returning nothing made the walk spend requests for nothing. Pass
+  `stop_on_empty=False` for an endpoint that sends empty pages mid-walk
+  ([#15](https://github.com/kelsayed17/headgate/issues/15)).
+
+## [0.3.0] - 2026-10-26
+
+Fixes four bugs where a call's deadline, its timeouts, the rate budget and the cache disagreed. One of them makes a
+configuration that could never work an error, so this is a minor release: see **Changed**.
+
+### Added
+
+- `headgate.ratelimit.BudgetBacklogError`, raised by `RateBudget.wait` when a call's paced turn comes after its deadline.
+
+### Changed
+
+- A timeout longer than the deadline it runs under is refused with `ValueError` on the client, a view or a call, since
+  it could never take effect ([#6](https://github.com/kelsayed17/headgate/issues/6)). Raise the deadline with it, e.g.
+  `with_options(timeout=300.0, deadline=600.0)`.
+- A body past `max_response_bytes` is no longer stored in the cache, since it is not held to be written on accept.
+
+### Fixed
+
+- A cached miss is stored only once the call's reader accepts it, so a refusal inside a 200, an undecodable body or an
+  undeclared status is no longer served from the cache for the entry's lifetime
+  ([#9](https://github.com/kelsayed17/headgate/issues/9)). A `stream()` is accepted when its head checks pass.
+- Identical concurrent GETs share one cached download again when their timeouts are longer than the time their deadline
+  leaves; the sharing key now uses the timeouts the call asked for, not the deadline-cut ones
+  ([#4](https://github.com/kelsayed17/headgate/issues/4)).
+- A call whose rate-budget turn comes after its deadline fails at once with `ClientTimeoutError` saying it was never
+  sent, with `retryable=True` and `retry_after`, instead of waiting and failing like a slow upstream; a retry that
+  cannot be sent in time ends the call with the failure it already has, and such a hedge is not sent. A deadline that
+  passes before an attempt is sent says so, and `attempts` counts only the sends made
+  ([#5](https://github.com/kelsayed17/headgate/issues/5)).
+
 ## [0.2.0] - 2026-10-25
 
 The first release published to PyPI. It reshapes the client around option objects and rebuilds every policy
@@ -185,6 +236,8 @@ Python 3.14.
 - The `headgate.msgspec` and `headgate.pydantic` codec flavors, the optional `AsyncCurlTransport` (`headgate[curl]`),
   `headgate.health` snapshots and `headgate.policy.policy_disabled()`.
 
-[Unreleased]: https://github.com/kelsayed17/headgate/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/kelsayed17/headgate/compare/f319ad8...v0.2.0
+[Unreleased]: https://github.com/kelsayed17/headgate/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/kelsayed17/headgate/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/kelsayed17/headgate/compare/159a3c2...v0.3.0
+[0.2.0]: https://github.com/kelsayed17/headgate/compare/f319ad8...159a3c2
 [0.1.0]: https://github.com/kelsayed17/headgate/commit/f319ad8

{headgate-0.2.0 → headgate-0.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: headgate
-Version: 0.2.0
+Version: 0.4.0
 Summary: The async API-client base on httpx2: safe retries, rate budgets, per-origin breakers, credential-safe caching, typed events and declared responses.
 Project-URL: Homepage, https://github.com/kelsayed17/headgate
-Project-URL: Documentation, https://github.com/kelsayed17/headgate/tree/main/docs
+Project-URL: Documentation, https://kelsayed17.github.io/headgate/
 Project-URL: Repository, https://github.com/kelsayed17/headgate
 Project-URL: Issues, https://github.com/kelsayed17/headgate/issues
 Project-URL: Changelog, https://github.com/kelsayed17/headgate/blob/main/CHANGELOG.md
@@ -37,8 +37,19 @@ Provides-Extra: pydantic
 Requires-Dist: pydantic>=2.14.1; extra == 'pydantic'
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kelsayed17/headgate/main/docs/assets/logo.png" alt="headgate logo: a gate metering a stream of requests" width="160">
+</p>
+
 # headgate
 
+[![PyPI](https://img.shields.io/pypi/v/headgate)](https://pypi.org/project/headgate/)
+[![Python](https://img.shields.io/pypi/pyversions/headgate)](https://pypi.org/project/headgate/)
+[![CI](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml)
+[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)](CONTRIBUTING.md)
+[![Docs](https://img.shields.io/badge/docs-kelsayed17.github.io%2Fheadgate-blue)](https://kelsayed17.github.io/headgate/)
+[![Licence: MIT](https://img.shields.io/pypi/l/headgate)](LICENSE)
+
 **An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass
 `AsyncBaseClient`, declare what each endpoint answers, and every client you build gets the same production behaviour:
 retries that re-send only when it is safe, a shared rate budget that listens to the server, a per-origin circuit
@@ -48,10 +59,19 @@ events and OpenTelemetry, and errors that say exactly what happened. Each endpoi
 A headgate controls how much water gets through a channel. This library does the same for requests, in one place,
 so that no client has to get it right on its own.
 
+**Docs:** <https://kelsayed17.github.io/headgate/>. New here? See [how headgate compares](docs/comparison.md) with
+tenacity, stamina and a hand-rolled client, and a [GitHub API client](examples/github_client.py) written with it.
+
 ## Requirements and install
 
-Python 3.14 or newer (endpoint paths are t-strings) and `httpx2`, pydantic's fork of httpx. Upstream `httpx` is not
-supported: passing one of its objects raises a `TypeError` naming the mistake.
+Python 3.14 or newer, and `httpx2`, pydantic's fork of httpx.
+
+- **Why 3.14:** endpoint paths are [template strings](https://peps.python.org/pep-0750/) (`t"orders/{order_id}"`), so
+  each value is escaped into its own path segment by default: `BTC/USD` becomes `BTC%2FUSD` instead of a new path.
+  Template strings exist only from Python 3.14.
+- **Why httpx2:** headgate is built and tested on it alone. Its API is httpx's, so moving a client over is mostly
+  `import httpx2` where you had `import httpx`. Upstream `httpx` is not supported: passing one of its objects raises a
+  `TypeError` naming the mistake. See [why httpx2](docs/comparison.md#why-httpx2).
 
 ```bash
 pip install headgate               # or: uv add headgate. Brings httpx2[http2], hishel and msgspec
@@ -360,6 +380,7 @@ uv run ty check
 uv run python -m pytest --cov             # 100% line and branch coverage is required
 uv run python -m pytest benchmarks        # the benchmarks, as CI runs them
 uv run mutmut run                         # mutation testing; slow, run it before a release
+uv run --only-group docs zensical serve   # preview the docs site at http://localhost:8000
 ```
 
 Lint selects every ruff rule, ty treats every rule as an error, and suppression comments are not accepted. See

{headgate-0.2.0 → headgate-0.4.0}/README.md

@@ -1,5 +1,16 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kelsayed17/headgate/main/docs/assets/logo.png" alt="headgate logo: a gate metering a stream of requests" width="160">
+</p>
+
 # headgate
 
+[![PyPI](https://img.shields.io/pypi/v/headgate)](https://pypi.org/project/headgate/)
+[![Python](https://img.shields.io/pypi/pyversions/headgate)](https://pypi.org/project/headgate/)
+[![CI](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml)
+[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)](CONTRIBUTING.md)
+[![Docs](https://img.shields.io/badge/docs-kelsayed17.github.io%2Fheadgate-blue)](https://kelsayed17.github.io/headgate/)
+[![Licence: MIT](https://img.shields.io/pypi/l/headgate)](LICENSE)
+
 **An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass
 `AsyncBaseClient`, declare what each endpoint answers, and every client you build gets the same production behaviour:
 retries that re-send only when it is safe, a shared rate budget that listens to the server, a per-origin circuit
@@ -9,10 +20,19 @@ events and OpenTelemetry, and errors that say exactly what happened. Each endpoi
 A headgate controls how much water gets through a channel. This library does the same for requests, in one place,
 so that no client has to get it right on its own.
 
+**Docs:** <https://kelsayed17.github.io/headgate/>. New here? See [how headgate compares](docs/comparison.md) with
+tenacity, stamina and a hand-rolled client, and a [GitHub API client](examples/github_client.py) written with it.
+
 ## Requirements and install
 
-Python 3.14 or newer (endpoint paths are t-strings) and `httpx2`, pydantic's fork of httpx. Upstream `httpx` is not
-supported: passing one of its objects raises a `TypeError` naming the mistake.
+Python 3.14 or newer, and `httpx2`, pydantic's fork of httpx.
+
+- **Why 3.14:** endpoint paths are [template strings](https://peps.python.org/pep-0750/) (`t"orders/{order_id}"`), so
+  each value is escaped into its own path segment by default: `BTC/USD` becomes `BTC%2FUSD` instead of a new path.
+  Template strings exist only from Python 3.14.
+- **Why httpx2:** headgate is built and tested on it alone. Its API is httpx's, so moving a client over is mostly
+  `import httpx2` where you had `import httpx`. Upstream `httpx` is not supported: passing one of its objects raises a
+  `TypeError` naming the mistake. See [why httpx2](docs/comparison.md#why-httpx2).
 
 ```bash
 pip install headgate               # or: uv add headgate. Brings httpx2[http2], hishel and msgspec
@@ -321,6 +341,7 @@ uv run ty check
 uv run python -m pytest --cov             # 100% line and branch coverage is required
 uv run python -m pytest benchmarks        # the benchmarks, as CI runs them
 uv run mutmut run                         # mutation testing; slow, run it before a release
+uv run --only-group docs zensical serve   # preview the docs site at http://localhost:8000
 ```
 
 Lint selects every ruff rule, ty treats every rule as an error, and suppression comments are not accepted. See

{headgate-0.2.0 → headgate-0.4.0}/docs/auth.md

@@ -65,7 +65,7 @@ class PartnerAuth(CachedTokenAuth):
 
 Or `_mint_flow(request)` yields the requests the exchange needs, so they travel through the owning client's own stack
 (its transport, rate budget, retries and error mapping), and ends by yielding `Minted(token, lifetime)`.
-[`examples/orders_client.py`](../examples/orders_client.py) has a complete one. What the flow can count on:
+[`examples/orders_client.py`](https://github.com/kelsayed17/headgate/blob/main/examples/orders_client.py) has a complete one. What the flow can count on:
 
 - **Each response arrives read**, so `.content`, `.text` and `.json()` work on it. It is read up to 1 MiB
   (`headgate.MAX_MINT_RESPONSE_BYTES`, decompressed); a larger one fails the mint with `ResponseTooLargeError`.

{headgate-0.2.0 → headgate-0.4.0}/docs/caching.md

@@ -30,13 +30,18 @@ policy = TransportPolicy(cache=cache)
 - **`policy`** is a hishel `FilterPolicy`. headgate supplies three filters: `PathFragmentFilter(fragments)` (the URL path
   contains one of them), `MethodFilter(methods)` and `StatusCodeFilter(codes)`. A `FilterPolicy` stores whenever a
   request filter matches and an allowed status comes back, **even past a `no-store`**, which is the point for a
-  provider that sends no cache headers, or wrong ones. Store only 200s, so an error body never poisons the cache.
-  Body-keyed POST caching is hishel's own `FilterPolicy.use_body_key`.
+  provider that sends no cache headers, or wrong ones. Body-keyed POST caching is hishel's own
+  `FilterPolicy.use_body_key`.
+- **Stored on accept.** A response the policy allows is written to storage only once the call's `expect=` reader has
+  accepted it. A call whose reader raises stores nothing, so the cache never serves an answer the client refused:
+  a refusal inside a 200 that a `check` catches, an undecodable body, an undeclared status. A declared non-2xx
+  (`Expect(...).on(404, ...)`) is stored when the filters allow its status. A `stream()` has no reader, so passing its
+  head checks accepts it. A write that fails then is counted as a degradation; the call keeps its answer.
 - **`ttl`** is the client's default lifetime in seconds; a call's `cache_ttl=` overrides it.
 - **TTL, not revalidation.** An entry is served until its lifetime ends and is never revalidated with the origin. For
   revalidation, use [conditional reads](#conditional-reads).
 - The body is held up to `HttpOptions.max_response_bytes`, and a body past it raises `ResponseTooLargeError` as it would
-  uncached.
+  uncached. A body past the cap is not stored, not even for a `stream()`.
 
 ## Partitions
 
@@ -66,10 +71,12 @@ stored either; the request that fetched it still receives it.
 
 hishel has no request coalescing, so an identical GET arriving while the first is still being fetched would miss too.
 headgate makes it wait and gives it a copy of the first one's response (a hit, a miss or a degraded fetch). Identical
-means the same URL, every header, the same timeouts and the same retry policy. A network failure fails every waiting
-request from the one attempt, each with its own copy of the error, and each caller's retry layer then retries (and
-shares again). Only the request that fetched counts toward the [breaker](breaker.md). A body past the size cap is not
-held, so each waiting request fetches its own. POSTs are never shared.
+means the same URL, every header, the same timeouts and the same retry policy; the timeouts compared are the ones the
+call asked for, not the ones its deadline cut, so calls with different time left still share. A timeout that only the
+first request's deadline cut short is not passed on: each waiting request then fetches its own. A network failure fails
+every waiting request from the one attempt, each with its own copy of the error, and each caller's retry layer then
+retries (and shares again). Only the request that fetched counts toward the [breaker](breaker.md). A body past the size
+cap is not held, so each waiting request fetches its own. POSTs are never shared.
 
 ## Storage faults
 

headgate-0.4.0/docs/comparison.md

@@ -0,0 +1,50 @@
+---
+hide:
+  - toc
+---
+
+# Compared with others
+
+headgate is a base for **HTTP API clients**: it owns the whole call, from building the request to reading the body,
+and handles the concerns every client shares. The libraries people usually reach for each solve one of those concerns,
+for any code. This page says what that difference buys, and when to use them instead.
+
+## At a glance
+
+<div class="hg-compare" markdown>
+
+| | tenacity | stamina | a hand-rolled httpx client | headgate |
+| --- | --- | --- | --- | --- |
+| Scope | retry any callable | retry any callable (an opinionated tenacity wrapper) | what you write | HTTP API clients |
+| What is retried | the whole decorated call | the whole decorated call | what you write | only the send: below auth and the cache, so a cache hit is never retried and each re-send spends its own rate turn |
+| Which requests are safe to re-send | your predicate | your `on=` | what you write | idempotent methods; a POST or PATCH only when it provably never left, or under an idempotency key stamped once per call |
+| `Retry-After` | write it yourself | write it yourself | write it yourself | waited exactly, up to a cap; past it the call fails at once with `retry_after` |
+| Total deadline | `stop_after_delay` | `timeout=` | write it yourself | one deadline over every attempt, backoff, rate-budget wait and the body read |
+| Retry budget across calls | no | no | write it yourself | yes, so retries cannot multiply an outage |
+| Rate limiting | no | no | add aiolimiter or similar | a shared budget that reads `RateLimit` and `X-RateLimit-*` headers and backs off on pushback |
+| Circuit breaker | no | no | add a breaker library | per origin, thread-safe, charged only for the host's own failures |
+| Caching | no | no | add hishel | hishel, partitioned by credential, never storing credentials, storing only what the call accepted |
+| Credential safety | n/a | n/a | write it yourself | credentials pinned to their origin, an https-to-http redirect refused, an optional SSRF guard |
+| Observability | `before_sleep` and other hooks | instrumentation built in | write it yourself | typed events and an OpenTelemetry observer |
+| Test support | none built in | `set_testing()` | patch what you must | `headgate.testing`: a fake network, instant retries, failure schedules, a test clock |
+
+</div>
+
+## When to use something else
+
+- **Retrying code that is not an HTTP call** (a database query, a file operation): use stamina, or tenacity when you
+  need its full flexibility. headgate's retry lives in its transport stack and retries only HTTP sends.
+- **Python before 3.14**: headgate needs 3.14 for its template-string paths. Use httpx with stamina or tenacity, and
+  add rate limiting and caching yourself.
+- **Upstream httpx**: headgate runs on httpx2 and refuses httpx objects, to catch the mix-up early. If your code has to
+  stay on httpx, headgate is not for you yet.
+- **A synchronous codebase**: headgate is async only.
+- **One or two calls in a script**: a plain httpx2 call is fine. headgate pays off when a client has several endpoints,
+  several consumers, or has to survive a provider's bad day.
+
+## Why httpx2
+
+headgate is built and tested on [httpx2](https://pypi.org/project/httpx2/), pydantic's fork of httpx, and on nothing
+else. Its API is httpx's, so moving a client over is mostly an import change: `import httpx2` where you had
+`import httpx`, and the same for the exceptions you catch. headgate refuses an `httpx` object anywhere it takes an httpx2
+one, with a `TypeError` naming the mistake, rather than failing later in a confusing way.

{headgate-0.2.0 → headgate-0.4.0}/docs/deadlines.md

@@ -32,8 +32,15 @@ below act on it as well as the outer timer:
 - the retry layer starts no attempt or wait with less than `RetryPolicy.min_attempt_time` (0.05 s) left, and raises
   the last failure with the note `deadline exhausted` instead;
 - a rate-budget pause that would outlast the deadline raises `RateLimitError` at once rather than waiting;
+- a turn in the rate budget that comes at or after the deadline is not waited for. On the first attempt the call
+  raises `ClientTimeoutError` at once, naming it as never sent, with `attempts=0`, `retryable=True` and `retry_after`
+  the wait it was refused. On a retry, the call ends with the failure it already has, noted `deadline exhausted`, and a
+  hedge is simply not sent;
 - after a rate-budget wait the send's timeouts are cut again, to what the wait left.
 
+A deadline that passes before the request is sent (waiting for an in-flight slot, say) says so too:
+`GET item/3: deadline exceeded after 3s, before attempt 1 was sent`, with `attempts` counting only the sends made.
+
 For [`stream()`](streaming.md) the deadline bounds opening the stream (every attempt, backoff and the head checks), not
 reading it: the caller's pace of iteration decides how long the body takes. Wrap the block in `asyncio.timeout` to
 bound the whole body.
@@ -47,8 +54,18 @@ number replaces the read timeout only: `HttpOptions(timeout=60.0)` keeps the oth
 A call overrides them with `timeout=`: a `Timeouts` replaces all four, a number the read timeout alone. A view made with
 `with_options(timeout=...)` does the same for its calls. Every value must be positive.
 
+A timeout must fit the deadline it runs under, or it could never take effect: each attempt's timeouts are cut to the
+time left. So a timeout longer than that deadline is refused with `ValueError` where it is set: on the client (against
+the policy's deadline), on a view, or on a call. A bare number is checked as the read timeout, and a `Timeouts` by the
+phases set away from their defaults. Shortening the deadline instead is always allowed; cutting the timeouts is what a
+short deadline is for. To give a slow endpoint a long read timeout, raise the deadline with it:
+
+```python
+reports = client.with_options(timeout=300.0, deadline=600.0)
+```
+
 ## Choosing values
 
-- Keep `read` below the deadline, or a single slow response takes the whole call and leaves no time to retry it.
+- Keep `read` well below the deadline, or a single slow response takes the whole call and leaves no time to retry it.
 - A long export or report endpoint wants a `Route` with a longer deadline rather than a client-wide one.
 - `deadline=None` exists for calls that legitimately run unbounded (a long poll); prefer a generous number.

headgate-0.4.0/docs/index.md

@@ -0,0 +1,158 @@
+---
+title: An async API-client base for Python
+hide:
+  - toc
+---
+
+<div class="hg-hero" markdown>
+
+![headgate logo](assets/logo.png)
+
+<div markdown>
+
+# headgate
+
+**An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass
+`AsyncBaseClient`, declare what each endpoint answers, and every client you build gets the same production behaviour.
+Each endpoint method stays one line.
+
+[Get started](#install){ .md-button .md-button--primary }
+[How it compares](comparison.md){ .md-button }
+[:fontawesome-brands-github: GitHub](https://github.com/kelsayed17/headgate){ .md-button }
+
+</div>
+
+</div>
+
+<div class="grid cards" markdown>
+
+-   :lucide-rotate-cw:{ .lg .hg-icon } **Retries that are safe**
+
+    ---
+
+    Idempotent methods only, or a POST under an idempotency key. `Retry-After` is waited exactly, and a budget stops
+    retries multiplying an outage.
+
+    [:lucide-arrow-right: Retries](retries.md)
+
+-   :lucide-gauge:{ .lg .hg-icon } **A rate budget that listens**
+
+    ---
+
+    One budget shared by every call, paused by `RateLimit` and `X-RateLimit-*` headers and slowed by pushback.
+
+    [:lucide-arrow-right: Rate budgets](rate-budgets.md)
+
+-   :lucide-timer:{ .lg .hg-icon } **Deadlines and a breaker**
+
+    ---
+
+    One deadline bounds every attempt, wait and read. A per-origin circuit breaker stops calls to a host that is down.
+
+    [:lucide-arrow-right: Deadlines](deadlines.md) · [Circuit breaker](breaker.md)
+
+-   :lucide-key-round:{ .lg .hg-icon } **Credentials that stay home**
+
+    ---
+
+    Credentials are pinned to their origin, an https-to-http redirect is refused, and an SSRF guard is one option away.
+
+    [:lucide-arrow-right: Security](security.md)
+
+-   :lucide-database-zap:{ .lg .hg-icon } **A cache that keeps no secrets**
+
+    ---
+
+    hishel's cache, partitioned by credential, never storing one, and storing only what your reader accepted.
+
+    [:lucide-arrow-right: Caching](caching.md)
+
+-   :lucide-activity:{ .lg .hg-icon } **Errors and events that explain**
+
+    ---
+
+    Typed errors that say what happened and whether to retry, typed events, and an OpenTelemetry observer.
+
+    [:lucide-arrow-right: Errors](errors.md) · [Observability](observability.md)
+
+</div>
+
+## Install
+
+=== "pip"
+
+    ```bash
+    pip install headgate
+    ```
+
+=== "uv"
+
+    ```bash
+    uv add headgate
+    ```
+
+headgate needs **Python 3.14** or newer: endpoint paths are [template strings](https://peps.python.org/pep-0750/), so
+each value is escaped into its own path segment by default. It runs on **httpx2**, pydantic's fork of httpx; see
+[why httpx2](comparison.md#why-httpx2).
+
+## A real client
+
+A client for a few GitHub REST endpoints. The full version, with its tests, is
+[`examples/github_client.py`](https://github.com/kelsayed17/headgate/blob/main/examples/github_client.py).
+
+```python
+from http import HTTPStatus
+
+import msgspec
+
+from headgate import AsyncBaseClient, Expect, HttpOptions, LinkHeader, Rate, RateBudget, StaticHeaderAuth, nothing
+from headgate.msgspec import decoder
+
+
+class Repository(msgspec.Struct, frozen=True):
+    full_name: str
+    stargazers_count: int
+
+
+class Issue(msgspec.Struct, frozen=True):
+    number: int
+    title: str
+
+
+REPOSITORY_OR_NONE = Expect(decoder(Repository)).on(HTTPStatus.NOT_FOUND, nothing)
+ISSUE_PAGES = LinkHeader(items=lambda page: page)  # each page is a JSON list of issues
+
+
+class GitHub(AsyncBaseClient):
+    def __init__(self, token: str) -> None:
+        super().__init__(
+            base_url="https://api.github.com",
+            rate=RateBudget(Rate.per_second(10), max_in_flight=50),
+            auth=StaticHeaderAuth({"Authorization": f"Bearer {token}"}),
+            http=HttpOptions(headers={"Accept": "application/vnd.github+json"}),
+        )
+
+    async def repository(self, owner: str, name: str) -> Repository | None:
+        return await self.get(t"repos/{owner}/{name}", expect=REPOSITORY_OR_NONE)
+
+    def open_issues(self, owner: str, name: str):
+        return self.paginate(t"repos/{owner}/{name}/issues", expect=decoder(list[Issue]), pages=ISSUE_PAGES)
+```
+
+```python
+async with GitHub(token) as github:
+    repository = await github.repository("python", "cpython")
+    async for issue in github.open_issues("python", "cpython"):
+        print(issue.number, issue.title)
+```
+
+Retries, pacing under GitHub's limits, pausing when its hourly limit is spent, following `Link` headers, and keeping
+the token on `api.github.com` all come from the base class.
+
+## Where to next
+
+- [Compared with others](comparison.md): what headgate does that tenacity, stamina or a hand-rolled httpx client
+  does not, and when to pick those instead.
+- [Configuration](configuration.md): every option, and where it lives.
+- [Declared responses](responses.md) and [errors](errors.md): what an endpoint answers, and what it raises.
+- [Testing a client](testing.md): fake networks, instant retries and failure schedules, with nothing private patched.

{headgate-0.2.0 → headgate-0.4.0}/docs/pagination.md

@@ -27,6 +27,31 @@ Nothing is fetched until iteration starts, no page is kept once the iteration mo
 nothing more, and iterating again starts again from the first page. A page that leads back to a request already made
 (a cursor or next URL that repeats) raises `ClientError` instead of looping forever.
 
+## A page budget
+
+A walk ends at its last page, but a server bug, an unordered dataset or a too-broad filter can keep naming new pages
+for as long as you keep asking. `limit=PageLimit(max_pages)` bounds the walk:
+
+```python
+from headgate import PageLimit, PageLimitError
+
+orders = client.paginate("orders", expect=decoder(Page), pages=ORDER_PAGES, limit=PageLimit(50))
+try:
+    async for order in orders:
+        ...
+except PageLimitError as exc:
+    print(f"stopped after {exc.pages} pages: the result is incomplete")
+```
+
+- **`on_limit="raise"`** (the default) raises `PageLimitError`, a `ClientError`, once the budget is spent with pages
+  still to come. The pages within the budget were already yielded; `exc.pages` says how many. A caller cannot mistake
+  a cut-short walk for a complete one.
+- **`on_limit="stop"`** ends the walk at the budget instead, for a caller that wants only the first pages:
+  `PageLimit(5, on_limit="stop")`.
+- A walk whose last page falls within the budget, or exactly on it, is unaffected.
+
+Set the budget where the client calls `paginate`, so every caller of that endpoint gets it.
+
 `paginate` sends GETs, so it refuses body options (`json`, `data`, `content`, `files`) with `ValueError`. Its `params=`
 are the first page's query, and a pager's parameter is added to them. `expect=` may be an `Expect`: a page can be a
 declared answer like any other.
@@ -35,10 +60,14 @@ declared answer like any other.
 
 | Strategy | The next page is | Last page |
 | --- | --- | --- |
-| `Cursor(items=, next=, param=)` | the same request with `param` set to the cursor `next(page)` returns | `next` returns `None` or `""` |
+| `Cursor(items=, next=, param=)` | the same request with `param` set to the cursor `next(page)` returns | `next` returns `None` or `""`, or a page with no items |
 | `Offset(items=, limit=, param="offset", start=0)` | the same request with `param` advanced by the items this page held | a page with fewer than `limit` items |
-| `LinkHeader(items=)` | the target of the response's `Link: <...>; rel="next"` (RFC 8288) | no `rel="next"` link |
-| `NextUrl(items=, next=)` | the URL `next(page)` returns, absolute or relative | `next` returns `None` or `""` |
+| `LinkHeader(items=)` | the target of the response's `Link: <...>; rel="next"` (RFC 8288) | no `rel="next"` link, or a page with no items |
+| `NextUrl(items=, next=)` | the URL `next(page)` returns, absolute or relative | `next` returns `None` or `""`, or a page with no items |
+
+A page with no items ends a `Cursor`, `LinkHeader` or `NextUrl` walk even when it links to another: a link that
+advances while returning nothing makes no progress, and following it spends the rate budget for nothing. For an
+endpoint that sends empty pages mid-walk, pass `stop_on_empty=False`.
 
 `Offset` sends only the offset; the page size goes in `params=`, under whatever name the endpoint uses (`limit`,
 `per_page`, `page_size`). A next URL from the wire (`LinkHeader`, `NextUrl`) is resolved against the URL that answered

{headgate-0.2.0 → headgate-0.4.0}/docs/rate-budgets.md

@@ -28,7 +28,8 @@ under a `threading.Lock` and nothing in it is bound to a loop.
 
 - **Pacing** is GCRA, the virtual-scheduling form of a leaky bucket. Up to `rate.requests` requests (at least one) go
   out back to back; after that they are `period / requests` seconds apart. Waiters are served in arrival order, and a
-  waiter cancelled in the queue (its deadline passed, say) gives its turn back when nobody reserved after it.
+  waiter cancelled in the queue gives its turn back when nobody reserved after it. A call whose turn comes at or after
+  its deadline does not queue: it gives the turn back and the attempt is never sent (see [deadlines](deadlines.md)).
 - **`max_in_flight`** caps how many requests are open at once. A request holds its slot from the send until its
   response body is **closed**, not until the head arrives, since the server is still busy with a body that streams.
   Every path that drops a response closes it, so a slot cannot leak.

headgate-0.4.0/docs/stylesheets/extra.css

@@ -0,0 +1,91 @@
+/* headgate's colours, taken from the logo: deep navy, a working blue and a bright cyan. */
+:root {
+  --hg-navy: #011740;
+  --hg-blue: #0a82e0;
+  --hg-cyan: #1fd6f5;
+}
+
+[data-md-color-scheme="default"] {
+  --md-primary-fg-color: var(--hg-navy);
+  --md-primary-fg-color--light: #0b2a63;
+  --md-primary-fg-color--dark: #000d26;
+  --md-accent-fg-color: var(--hg-blue);
+  --md-typeset-a-color: var(--hg-blue);
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: var(--hg-cyan);
+  --md-primary-fg-color--light: #6ae4fa;
+  --md-primary-fg-color--dark: #0fb3cf;
+  /* Text on the cyan: navy, since white on a light cyan is hard to read. */
+  --md-primary-bg-color: var(--hg-navy);
+  --md-primary-bg-color--light: rgba(1, 23, 64, 0.7);
+  --md-accent-fg-color: var(--hg-cyan);
+  --md-typeset-a-color: var(--hg-cyan);
+}
+
+/* The landing page's hero: the logo, the name, one sentence and the ways in. */
+.hg-hero {
+  display: grid;
+  grid-template-columns: 9rem 1fr;
+  gap: 1.5rem 2rem;
+  align-items: center;
+  margin: 1rem 0 2.5rem;
+}
+
+.hg-hero img {
+  width: 9rem;
+  height: 9rem;
+  border-radius: 1.6rem;
+  box-shadow: 0 0.6rem 2rem rgba(10, 130, 224, 0.35);
+}
+
+.md-typeset .hg-hero h1 {
+  margin: 0 0 0.4rem;
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.hg-hero p {
+  margin: 0 0 1rem;
+  font-size: 1.05rem;
+}
+
+.md-typeset .hg-hero .md-button {
+  margin: 0.2rem 0.4rem 0.2rem 0;
+}
+
+@media screen and (max-width: 44.9375em) {
+  .hg-hero {
+    grid-template-columns: 1fr;
+    justify-items: center;
+    text-align: center;
+  }
+
+  .hg-hero img {
+    width: 6rem;
+    height: 6rem;
+    border-radius: 1.1rem;
+  }
+}
+
+/* Feature cards: a coloured icon above each title. */
+.md-typeset .grid.cards .hg-icon {
+  color: var(--md-accent-fg-color);
+}
+
+/* Wide tables read better a little smaller, with each row named in bold. */
+.md-typeset table:not([class]) {
+  font-size: 0.7rem;
+}
+
+.md-typeset table:not([class]) td:first-child {
+  min-width: 8rem;
+  font-weight: 600;
+}
+
+/* The comparison's last column is headgate's: tinted, so it reads as the answer. */
+.hg-compare table td:last-child,
+.hg-compare table th:last-child {
+  background-color: color-mix(in srgb, var(--md-accent-fg-color) 9%, transparent);
+}

{headgate-0.2.0 → headgate-0.4.0}/docs/testing.md

@@ -4,7 +4,7 @@
 with nothing private patched. Two seams make that possible:
 
 - **the network** is `HttpOptions(transport=...)`. Have the client accept a transport and pass it through, as the
-  [examples](../examples/) do: `CatalogClient(api_key, transport=fake)`;
+  [examples](https://github.com/kelsayed17/headgate/tree/main/examples) do: `CatalogClient(api_key, transport=fake)`;
 - **time and breaker state** are read when a client is **constructed**, from context variables the kit's context
   managers set. Build the client inside them; entering one around a client that already exists changes nothing.