headgate 0.3.0__tar.gz → 0.4.0__tar.gz

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

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

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

@@ -6,6 +6,27 @@ 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
@@ -215,7 +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.3.0...HEAD
+[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.3.0 → headgate-0.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: headgate
-Version: 0.3.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
@@ -43,6 +43,13 @@ Description-Content-Type: text/markdown
 
 # 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
@@ -52,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
@@ -364,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.3.0 → headgate-0.4.0}/README.md

@@ -4,6 +4,13 @@
 
 # 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
@@ -13,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
@@ -325,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.3.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.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.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.3.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.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.3.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.
 

headgate-0.4.0/examples/github_client.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""A client for a few GitHub REST endpoints: the API everyone knows, written as a headgate client.
+
+GitHub needs a bearer token, two fixed headers, pagination by ``Link`` header, a 404 for a repository that does not
+exist (or that the token cannot see), and pacing under its limits. headgate covers each with a declaration, so every
+endpoint method stays one line:
+
+* the rate budget reads GitHub's ``X-RateLimit-Remaining`` / ``X-RateLimit-Reset`` headers by default, and pauses every
+  call until the reset when the hourly limit is spent, instead of spending requests on certain refusals;
+* ``max_in_flight`` keeps under GitHub's limit on concurrent requests;
+* the bearer token never leaves ``api.github.com``, even when a ``Link`` header points elsewhere.
+"""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+from typing import TYPE_CHECKING
+
+import msgspec
+
+from headgate import AsyncBaseClient, Expect, HttpOptions, LinkHeader, Rate, RateBudget, StaticHeaderAuth, nothing
+from headgate.msgspec import decoder
+
+if TYPE_CHECKING:
+    import httpx2
+
+    from headgate import Paginated
+
+API = "https://api.github.com"
+
+
+class Repository(msgspec.Struct, frozen=True):
+    """The fields of a repository this client reads; GitHub sends many more, which are ignored."""
+
+    full_name: str
+    description: str | None
+    stargazers_count: int
+    default_branch: str
+
+
+class Issue(msgspec.Struct, frozen=True):
+    """An issue. GitHub lists pull requests as issues too; ``pull_request`` is set on those."""
+
+    number: int
+    title: str
+    pull_request: dict[str, object] | None = None
+
+
+def _issues(page: list[Issue]) -> list[Issue]:
+    """Return the issues on a page, which is a JSON list."""
+    return page
+
+
+# Readers and pagers are values: build them once, at import, where a bad declaration fails.
+REPOSITORY = decoder(Repository)
+REPOSITORY_OR_NONE = Expect(REPOSITORY).on(HTTPStatus.NOT_FOUND, nothing)  # a missing or hidden repository
+ISSUES = decoder(list[Issue])
+ISSUE_PAGES = LinkHeader(items=_issues)
+
+
+class GitHub(AsyncBaseClient):
+    """Read repositories and their open issues from the GitHub REST API."""
+
+    def __init__(self, token: str, *, transport: httpx2.AsyncBaseTransport | None = None) -> None:
+        """Authenticate with *token*; *transport* replaces the network, as a test does."""
+        super().__init__(
+            base_url=API,
+            # Well under the 5,000 requests an hour a token gets, and never more than 50 at once.
+            rate=RateBudget(Rate.per_second(10), max_in_flight=50),
+            auth=StaticHeaderAuth({"Authorization": f"Bearer {token}"}),
+            http=HttpOptions(
+                transport=transport,
+                headers={"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28"},
+            ),
+        )
+
+    async def repository(self, owner: str, name: str) -> Repository | None:
+        """Return the repository *owner*/*name*, or ``None`` when it does not exist or the token cannot see it."""
+        return await self.get(t"repos/{owner}/{name}", expect=REPOSITORY_OR_NONE)
+
+    def open_issues(self, owner: str, name: str) -> Paginated[list[Issue], Issue]:
+        """Return the open issues (and pull requests) of *owner*/*name*, 100 a page, fetched as they are iterated."""
+        params = {"state": "open", "per_page": 100}
+        return self.paginate(t"repos/{owner}/{name}/issues", expect=ISSUES, pages=ISSUE_PAGES, params=params)

{headgate-0.3.0 → headgate-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "headgate"
-version = "0.3.0"
+version = "0.4.0"
 description = "The async API-client base on httpx2: safe retries, rate budgets, per-origin breakers, credential-safe caching, typed events and declared responses."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -44,7 +44,7 @@ cache = ["hishel[async]>=1.4.0"]
 
 [project.urls]
 Homepage = "https://github.com/kelsayed17/headgate"
-Documentation = "https://github.com/kelsayed17/headgate/tree/main/docs"
+Documentation = "https://kelsayed17.github.io/headgate/"
 Repository = "https://github.com/kelsayed17/headgate"
 Issues = "https://github.com/kelsayed17/headgate/issues"
 Changelog = "https://github.com/kelsayed17/headgate/blob/main/CHANGELOG.md"
@@ -67,6 +67,7 @@ dev = [
     "mutmut>=3.8",
     "vcrpy>=8.3",
 ]
+docs = ["zensical>=0.0.72"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/headgate"]

{headgate-0.3.0 → headgate-0.4.0}/src/headgate/__init__.py

@@ -51,6 +51,7 @@ from headgate.errors import (
     ClientTimeoutError,
     DecodeError,
     ForbiddenDestinationError,
+    PageLimitError,
     Problem,
     RateLimitError,
     ResponseParseError,
@@ -58,7 +59,7 @@ from headgate.errors import (
     TransportError,
     UpstreamStatusError,
 )
-from headgate.pagination import Cursor, LinkHeader, NextUrl, Offset, Pager, PageRequest, Paginated
+from headgate.pagination import Cursor, LinkHeader, NextUrl, Offset, PageLimit, Pager, PageRequest, Paginated
 from headgate.ratelimit import Adaptive, Rate, RateBudget, RateRule
 from headgate.retry import NO_RETRY, Backoff, Hedge, RetryBudget, RetryPolicy
 from headgate.streaming import Stream
@@ -95,6 +96,8 @@ __all__ = [
     "NotModified",
     "Observer",
     "Offset",
+    "PageLimit",
+    "PageLimitError",
     "PageRequest",
     "Pager",
     "Paginated",