httpx-hedged 0.2.0__tar.gz → 0.3.1__tar.gz

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/.github/workflows/ci.yml

@@ -15,6 +15,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history, so hatch-vcs can see tags
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
@@ -25,12 +27,17 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
-      # If you have a requirements.txt file, uv installs it directly into an ephemeral environment
+      - name: Install dependencies
+        run: uv sync --locked --group dev
+
       - name: Run Ruff Linter
-        run: uv run --with ruff ruff check .
+        run: uv run ruff check .
 
       - name: Run Ruff Formatter Check
-        run: uv run --with ruff ruff format --check .
+        run: uv run ruff format --check .
+
+      - name: Run Mypy
+        run: uv run mypy src
 
       - name: Run Tests with Pytest
-        run: uv run --with pytest pytest
+        run: uv run pytest -q

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/.github/workflows/release.yml

@@ -19,6 +19,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history, so hatch-vcs can resolve the tag's version
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v5

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/.gitignore

@@ -1,6 +1,9 @@
 # Reference clone, not part of this project
 /hedge-python/
 
+# Generated at build time by hatch-vcs from the git tag
+/src/httpx_hedged/_version.py
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

httpx_hedged-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brendan Fahy
+
+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.

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: httpx-hedged
-Version: 0.2.0
+Version: 0.3.1
 Summary: Adaptive, per-endpoint request hedging transport for httpx. Learns latency percentiles per endpoint with DDSketch, caps hedge rate with a token bucket, and stops hedging under a host/endpoint circuit breaker.
+License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.13
+Requires-Dist: ddsketch>=3.0.1
 Requires-Dist: httpx>=0.27.0
 Description-Content-Type: text/markdown
 
@@ -32,6 +34,10 @@ async def main():
 asyncio.run(main())
 ```
 
+For a runnable, end-to-end demo (a small backend with different latency
+profiles per route, driven by a client that prints a hedge/latency/circuit
+breaker report), see [`examples/`](examples/README.md).
+
 With no configuration, `HedgedTransport` learns a p90 latency estimate per
 host (via a [DDSketch](https://arxiv.org/abs/2004.08604) quantile sketch)
 and fires a hedge request whenever the primary exceeds it. 
@@ -39,7 +45,7 @@ and fires a hedge request whenever the primary exceeds it.
 ## Why per-endpoint?
 
 A single host can host wildly different endpoints. Learning one latency
-distribution per *host* -- rather than per endpoint -- means a handful of
+distribution per *host*, rather than per endpoint, means a handful of
 calls to a slow endpoint skew the hedge trigger for a fast one sharing the
 same host:
 
@@ -50,7 +56,7 @@ GET /api/v1/bulk-export   median 900ms, low RPS
 
 `HedgedTransport` lets you register per-endpoint config up front. Each
 registered endpoint gets its own latency sketch, rate estimate, and hedge
-budget -- all still funneled through a **single inner transport and
+budget, all still funneled through a **single inner transport and
 connection pool**, unlike using `httpx` `mounts={}`, which would mean one
 connection pool per pattern:
 
@@ -68,7 +74,7 @@ endpoints at all).
 
 Route patterns may contain `{name}` placeholders or a bare `*` for a single
 path segment, e.g. `/api/v1/users/{id}`. Patterns are matched in
-registration order -- register more specific patterns first.
+registration order, so register more specific patterns first.
 
 ## Hardcoded vs. adaptive delay
 
@@ -79,8 +85,8 @@ percentile:
 transport.register("GET", "/api/v1/search", EndpointConfig(percentile=0.95))
 ```
 
-For an endpoint where you already know the right delay -- or want
-deterministic behavior without a warmup period -- hardcode it instead:
+For an endpoint where you already know the right delay, or want
+deterministic behavior without a warmup period, hardcode it instead:
 
 ```python
 transport.register("GET", "/api/v1/health", EndpointConfig(hedge_delay=0.05))
@@ -92,7 +98,7 @@ observability; it just isn't consulted for the hedge-delay decision.
 ## Explicit endpoint override
 
 Auto-matching not precise enough for a particular call site (or you'd
-rather not register a pattern)? Tag the request directly -- this bypasses
+rather not register a pattern)? Tag the request directly; this bypasses
 pattern matching entirely:
 
 ```python
@@ -159,7 +165,7 @@ request ──────┤
 
 Only idempotent methods (`GET`, `HEAD`, `OPTIONS`) are ever hedged, to avoid
 duplicating side effects. A request with a body is also never hedged, even
-if the method is idempotent -- the primary and hedge send the same
+if the method is idempotent: the primary and hedge send the same
 `httpx.Request` object, and a body backed by a one-shot stream can't be
 safely read twice.
 
@@ -168,7 +174,9 @@ safely read twice.
 Each tracked key (an endpoint, or the per-host fallback) gets its own
 sliding-window DDSketch pair that rotates every `window_duration` seconds.
 DDSketch gives relative-error quantile guarantees regardless of the
-underlying latency distribution's shape.
+underlying latency distribution's shape. The sketch itself comes from the
+[`ddsketch`](https://github.com/DataDog/sketches-py) package (DataDog's
+reference implementation of the paper below).
 
 ### Token bucket budget
 
@@ -184,13 +192,13 @@ endpoint.
 
 A closed / open / half-open circuit breaker tracks request success/failure
 at **two independent tiers**: one breaker per host, one breaker per
-endpoint key. Either tripping open suppresses hedging for its scope -- a
+endpoint key. Either tripping open suppresses hedging for its scope: a
 host-level trip disables hedging for every endpoint on that host, while an
 endpoint-level trip disables hedging only for that one endpoint.
 
 Crucially, the breaker **only ever suppresses the hedge request**. The
 primary request is always sent, and its result or exception is always
-returned to the caller normally -- this is not a request-blocking circuit
+returned to the caller normally. This is not a request-blocking circuit
 breaker, so hedging can't pile extra load onto a backend that's already
 struggling.
 
@@ -201,7 +209,7 @@ HALF_OPEN ──(trial requests mostly succeed)──▶ CLOSED
 HALF_OPEN ──(trial requests mostly fail)────▶ OPEN
 ```
 
-Note: health is recorded from the *winning* task's outcome only -- a
+Note: health is recorded from the *winning* task's outcome only. A
 cancelled loser's real outcome is unknowable, and losers are cancelled
 deliberately (not doing so would defeat the point of reducing load on a
 struggling backend).
@@ -225,6 +233,20 @@ print(transport.health.host_state("api.example.com"))
 `primary_wins`, `budget_exhausted`, `warmup_requests`, `circuit_blocked`,
 and `errors` per key, plus a global aggregate.
 
+To see the learned latency estimate itself (e.g. the current p90 driving
+the hedge trigger), query `latency_quantile()` with the same key format:
+
+```python
+name = transport.register("GET", "/api/v1/search", EndpointConfig(percentile=0.90))
+# ... after running some traffic ...
+p90 = transport.latency_quantile(f"endpoint:{name}", 0.9)
+if p90 is not None:
+    print(f"p90: {p90 * 1000:.1f}ms")
+```
+
+Returns `None` if the key hasn't recorded any samples yet. You can query
+any quantile, not just the one driving the hedge decision.
+
 ### Push-based hooks: metrics and alerting
 
 Polling snapshots works for dashboards, but alerting on a circuit-breaker
@@ -267,14 +289,14 @@ async with httpx.AsyncClient(transport=transport) as client:
 ```
 
 `on_hedge_fired` is called with the key each time a hedge request is
-actually launched -- after the idempotency, circuit-breaker, and budget
+actually launched, after the idempotency, circuit-breaker, and budget
 gates have all passed, so it only fires for hedges that were genuinely
 sent. `on_circuit_open` is called once per OPEN transition (not on every
 suppressed hedge while it stays open), so it's safe to wire straight into
 an alerting/paging pipeline without flooding it.
 
 Both callbacks run synchronously on the request path, so keep them fast
-(increment a counter, log a line) -- don't do network I/O in them directly.
+(increment a counter, log a line); don't do network I/O in them directly.
 
 ## Relationship to hedge-python
 
@@ -290,11 +312,11 @@ for the motivating scenario.
 
 ## References
 
-- [The Tail at Scale](https://research.google/pubs/pub40801/) -- Google's paper on tail latency
-- [DDSketch: A fast and fully-mergeable quantile sketch with relative-error guarantees](https://arxiv.org/abs/2004.08604) -- Masson et al., VLDB 2019
-- [hedge-python](https://github.com/sunhailin-Leo/hedge-python) -- the project this one is modeled after
+- [The Tail at Scale](https://research.google/pubs/pub40801/): Google's paper on tail latency
+- [DDSketch: A fast and fully-mergeable quantile sketch with relative-error guarantees](https://arxiv.org/abs/2004.08604): Masson et al., VLDB 2019
+- [hedge-python](https://github.com/sunhailin-Leo/hedge-python): the project this one is modeled after
 - [httpx documentation](https://www.python-httpx.org/)
 
 ## License
 
-BSD 3-Clause License. See [LICENSE](LICENSE) file for details.
+MIT License. See [LICENSE](LICENSE) file for details.

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/README.md

@@ -23,6 +23,10 @@ async def main():
 asyncio.run(main())
 ```
 
+For a runnable, end-to-end demo (a small backend with different latency
+profiles per route, driven by a client that prints a hedge/latency/circuit
+breaker report), see [`examples/`](examples/README.md).
+
 With no configuration, `HedgedTransport` learns a p90 latency estimate per
 host (via a [DDSketch](https://arxiv.org/abs/2004.08604) quantile sketch)
 and fires a hedge request whenever the primary exceeds it. 
@@ -30,7 +34,7 @@ and fires a hedge request whenever the primary exceeds it.
 ## Why per-endpoint?
 
 A single host can host wildly different endpoints. Learning one latency
-distribution per *host* -- rather than per endpoint -- means a handful of
+distribution per *host*, rather than per endpoint, means a handful of
 calls to a slow endpoint skew the hedge trigger for a fast one sharing the
 same host:
 
@@ -41,7 +45,7 @@ GET /api/v1/bulk-export   median 900ms, low RPS
 
 `HedgedTransport` lets you register per-endpoint config up front. Each
 registered endpoint gets its own latency sketch, rate estimate, and hedge
-budget -- all still funneled through a **single inner transport and
+budget, all still funneled through a **single inner transport and
 connection pool**, unlike using `httpx` `mounts={}`, which would mean one
 connection pool per pattern:
 
@@ -59,7 +63,7 @@ endpoints at all).
 
 Route patterns may contain `{name}` placeholders or a bare `*` for a single
 path segment, e.g. `/api/v1/users/{id}`. Patterns are matched in
-registration order -- register more specific patterns first.
+registration order, so register more specific patterns first.
 
 ## Hardcoded vs. adaptive delay
 
@@ -70,8 +74,8 @@ percentile:
 transport.register("GET", "/api/v1/search", EndpointConfig(percentile=0.95))
 ```
 
-For an endpoint where you already know the right delay -- or want
-deterministic behavior without a warmup period -- hardcode it instead:
+For an endpoint where you already know the right delay, or want
+deterministic behavior without a warmup period, hardcode it instead:
 
 ```python
 transport.register("GET", "/api/v1/health", EndpointConfig(hedge_delay=0.05))
@@ -83,7 +87,7 @@ observability; it just isn't consulted for the hedge-delay decision.
 ## Explicit endpoint override
 
 Auto-matching not precise enough for a particular call site (or you'd
-rather not register a pattern)? Tag the request directly -- this bypasses
+rather not register a pattern)? Tag the request directly; this bypasses
 pattern matching entirely:
 
 ```python
@@ -150,7 +154,7 @@ request ──────┤
 
 Only idempotent methods (`GET`, `HEAD`, `OPTIONS`) are ever hedged, to avoid
 duplicating side effects. A request with a body is also never hedged, even
-if the method is idempotent -- the primary and hedge send the same
+if the method is idempotent: the primary and hedge send the same
 `httpx.Request` object, and a body backed by a one-shot stream can't be
 safely read twice.
 
@@ -159,7 +163,9 @@ safely read twice.
 Each tracked key (an endpoint, or the per-host fallback) gets its own
 sliding-window DDSketch pair that rotates every `window_duration` seconds.
 DDSketch gives relative-error quantile guarantees regardless of the
-underlying latency distribution's shape.
+underlying latency distribution's shape. The sketch itself comes from the
+[`ddsketch`](https://github.com/DataDog/sketches-py) package (DataDog's
+reference implementation of the paper below).
 
 ### Token bucket budget
 
@@ -175,13 +181,13 @@ endpoint.
 
 A closed / open / half-open circuit breaker tracks request success/failure
 at **two independent tiers**: one breaker per host, one breaker per
-endpoint key. Either tripping open suppresses hedging for its scope -- a
+endpoint key. Either tripping open suppresses hedging for its scope: a
 host-level trip disables hedging for every endpoint on that host, while an
 endpoint-level trip disables hedging only for that one endpoint.
 
 Crucially, the breaker **only ever suppresses the hedge request**. The
 primary request is always sent, and its result or exception is always
-returned to the caller normally -- this is not a request-blocking circuit
+returned to the caller normally. This is not a request-blocking circuit
 breaker, so hedging can't pile extra load onto a backend that's already
 struggling.
 
@@ -192,7 +198,7 @@ HALF_OPEN ──(trial requests mostly succeed)──▶ CLOSED
 HALF_OPEN ──(trial requests mostly fail)────▶ OPEN
 ```
 
-Note: health is recorded from the *winning* task's outcome only -- a
+Note: health is recorded from the *winning* task's outcome only. A
 cancelled loser's real outcome is unknowable, and losers are cancelled
 deliberately (not doing so would defeat the point of reducing load on a
 struggling backend).
@@ -216,6 +222,20 @@ print(transport.health.host_state("api.example.com"))
 `primary_wins`, `budget_exhausted`, `warmup_requests`, `circuit_blocked`,
 and `errors` per key, plus a global aggregate.
 
+To see the learned latency estimate itself (e.g. the current p90 driving
+the hedge trigger), query `latency_quantile()` with the same key format:
+
+```python
+name = transport.register("GET", "/api/v1/search", EndpointConfig(percentile=0.90))
+# ... after running some traffic ...
+p90 = transport.latency_quantile(f"endpoint:{name}", 0.9)
+if p90 is not None:
+    print(f"p90: {p90 * 1000:.1f}ms")
+```
+
+Returns `None` if the key hasn't recorded any samples yet. You can query
+any quantile, not just the one driving the hedge decision.
+
 ### Push-based hooks: metrics and alerting
 
 Polling snapshots works for dashboards, but alerting on a circuit-breaker
@@ -258,14 +278,14 @@ async with httpx.AsyncClient(transport=transport) as client:
 ```
 
 `on_hedge_fired` is called with the key each time a hedge request is
-actually launched -- after the idempotency, circuit-breaker, and budget
+actually launched, after the idempotency, circuit-breaker, and budget
 gates have all passed, so it only fires for hedges that were genuinely
 sent. `on_circuit_open` is called once per OPEN transition (not on every
 suppressed hedge while it stays open), so it's safe to wire straight into
 an alerting/paging pipeline without flooding it.
 
 Both callbacks run synchronously on the request path, so keep them fast
-(increment a counter, log a line) -- don't do network I/O in them directly.
+(increment a counter, log a line); don't do network I/O in them directly.
 
 ## Relationship to hedge-python
 
@@ -281,11 +301,11 @@ for the motivating scenario.
 
 ## References
 
-- [The Tail at Scale](https://research.google/pubs/pub40801/) -- Google's paper on tail latency
-- [DDSketch: A fast and fully-mergeable quantile sketch with relative-error guarantees](https://arxiv.org/abs/2004.08604) -- Masson et al., VLDB 2019
-- [hedge-python](https://github.com/sunhailin-Leo/hedge-python) -- the project this one is modeled after
+- [The Tail at Scale](https://research.google/pubs/pub40801/): Google's paper on tail latency
+- [DDSketch: A fast and fully-mergeable quantile sketch with relative-error guarantees](https://arxiv.org/abs/2004.08604): Masson et al., VLDB 2019
+- [hedge-python](https://github.com/sunhailin-Leo/hedge-python): the project this one is modeled after
 - [httpx documentation](https://www.python-httpx.org/)
 
 ## License
 
-BSD 3-Clause License. See [LICENSE](LICENSE) file for details.
+MIT License. See [LICENSE](LICENSE) file for details.

httpx_hedged-0.3.1/examples/README.md

@@ -0,0 +1,41 @@
+# Examples
+
+A runnable demo of `HedgedTransport` against a small local backend with
+three different latency profiles.
+
+| File | What it is |
+|---|---|
+| `app.py` | A tiny FastAPI backend exposing `/fast`, `/slow`, and `/flaky` routes, each with a different latency profile. |
+| `example_usage.py` | A client that registers per-endpoint hedge config, drives load through `HedgedTransport` against `app.py`, and prints a stats/latency/circuit-breaker report. |
+| `run_example.sh` | Installs deps, starts `app.py`, runs `example_usage.py` against it, and tears the server down. The easiest way to see the whole thing end to end. |
+
+## Running it
+
+From the repo root:
+
+```bash
+./examples/run_example.sh
+```
+
+Or run the pieces yourself:
+
+```bash
+uv sync --group examples
+uv run uvicorn examples.app:app --host 127.0.0.1 --port 8000 &
+uv run python examples/example_usage.py
+```
+
+## What to look for in the output
+
+- `/fast` rarely triggers a hedge, since the primary is almost always
+  faster than the learned delay.
+- `/slow` hedges often, but the hedge rarely *wins*, because the backup is
+  just as slow as the primary on this uniformly slow endpoint.
+- `/flaky` is the interesting case: after warmup, the learned p90 sits near
+  the fast latency, so the rare slow primary gets hedged against a fresh
+  (usually fast) request and the hedge usually wins the race.
+
+The final report prints per-endpoint stats (`total`, `hedged`,
+`hedge_wins`, `primary_wins`, ...), each endpoint's learned p90 latency
+estimate (via `transport.latency_quantile()`), and each endpoint's circuit
+breaker state.

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/examples/app.py

@@ -1,8 +1,8 @@
 """Tiny FastAPI backend with three latency profiles, for the hedging demo.
 
-    GET /fast   -- always responds in ~5-15ms
-    GET /slow   -- always takes 800ms
-    GET /flaky  -- 90% of requests are fast (~5-15ms), 10% take ~900ms
+    GET /fast   always responds in ~5-15ms
+    GET /slow   always takes 800ms
+    GET /flaky  90% of requests are fast (~5-15ms), 10% take ~900ms
 
 Run directly with uvicorn, e.g.:
 

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/examples/example_usage.py

@@ -39,7 +39,7 @@ CONCURRENCY = 6
 
 # The hedge token bucket auto-estimates RPS over a rolling ~10s window by
 # default, which under-counts traffic sent in a shorter burst like this
-# demo's -- so budget starves and hedges rarely fire. Pinning estimated_rps
+# demo's, so budget starves and hedges rarely fire. Pinning estimated_rps
 # (roughly concurrency / expected latency) avoids that ramp-up and keeps
 # the demo's hedge behavior visible run over run. /fast is left on the
 # default auto-estimate since it barely ever needs to hedge anyway.
@@ -91,6 +91,12 @@ def print_report(transport: HedgedTransport) -> None:
     print(f"\ntotal requests sent: {global_snap.total_requests}")
     print(f"total hedges fired:  {global_snap.hedged_requests}")
 
+    print("\n=== learned p90 latency estimates ===")
+    for route in ROUTES:
+        key = f"endpoint:{route}"
+        p90 = transport.latency_quantile(key, 0.9)
+        print(f"{key:<16} {f'{p90 * 1000:.1f}ms' if p90 is not None else 'n/a'}")
+
     print("\n=== circuit breaker state ===")
     for route in ROUTES:
         key = f"endpoint:{route}"
@@ -104,7 +110,7 @@ async def wait_for_server(client: httpx.AsyncClient) -> None:
         response.raise_for_status()
     except httpx.HTTPError:
         print(
-            f"Could not reach {BASE_URL} -- is examples/app.py running?",
+            f"Could not reach {BASE_URL}: is examples/app.py running?",
             file=sys.stderr,
         )
         sys.exit(1)

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/examples/run_example.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Installs deps, starts the demo FastAPI backend, runs the hedging demo
-# client against it, and prints the stats report -- then tears the server
+# client against it, and prints the stats report, then tears the server
 # down. Run from anywhere:
 #
 #   ./examples/run_example.sh

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/pyproject.toml

@@ -1,10 +1,13 @@
 [project]
 name = "httpx-hedged"
-version = "0.2.0"
+dynamic = ["version"]
 description = "Adaptive, per-endpoint request hedging transport for httpx. Learns latency percentiles per endpoint with DDSketch, caps hedge rate with a token bucket, and stops hedging under a host/endpoint circuit breaker."
 readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.13"
 dependencies = [
+    "ddsketch>=3.0.1",
     "httpx>=0.27.0",
 ]
 
@@ -15,6 +18,7 @@ dev = [
     "pytest>=9.0.1",
     "pytest-asyncio>=1.3.0",
     "python-lsp-server[all]>=1.13.2",
+    "ruff>=0.14.0",
 ]
 examples = [
     "fastapi>=0.115",
@@ -22,12 +26,18 @@ examples = [
 ]
 
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/httpx_hedged"]
 
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/httpx_hedged/_version.py"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/src/httpx_hedged/__init__.py

@@ -18,6 +18,7 @@ from httpx_hedged._config import CircuitBreakerConfig, EndpointConfig, HedgeConf
 from httpx_hedged._health import CircuitBreaker, CircuitState, HealthRegistry
 from httpx_hedged._matcher import Route, UnknownHedgeEndpointError
 from httpx_hedged._stats import Stats, StatsRegistry, StatsSnapshot
+from httpx_hedged._version import __version__
 from httpx_hedged.transport import HedgedTransport
 
 __all__ = [
@@ -33,6 +34,5 @@ __all__ = [
     "StatsRegistry",
     "StatsSnapshot",
     "UnknownHedgeEndpointError",
+    "__version__",
 ]
-
-__version__ = "0.2.0"

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/src/httpx_hedged/_bounded.py

@@ -2,8 +2,8 @@
 
 Per-key state (sketches, breakers, stats) is created lazily, keyed by
 endpoint name or a per-host fallback. Nothing ever evicted those keys, so a
-caller that talks to high-cardinality hosts (per-tenant subdomains, or -- in
-the pathological case -- one key per unique URL when a request has no
+caller that talks to high-cardinality hosts (per-tenant subdomains, or, in
+the pathological case, one key per unique URL when a request has no
 parseable host) would grow these maps forever. Bounding them with LRU
 eviction keeps memory bounded without requiring callers to know about it.
 """
@@ -17,7 +17,7 @@ DEFAULT_MAX_SIZE = 10_000
 
 
 class BoundedRegistry[V]:
-    """Not thread-safe by itself -- callers hold their own lock, as with the
+    """Not thread-safe by itself. Callers hold their own lock, as with the
     plain dicts this replaces."""
 
     def __init__(self, max_size: int = DEFAULT_MAX_SIZE) -> None:

{httpx_hedged-0.2.0 → httpx_hedged-0.3.1}/src/httpx_hedged/_config.py

@@ -39,7 +39,7 @@ def _validate_common(config: HedgeConfig | EndpointConfig) -> None:
 class CircuitBreakerConfig:
     """Configuration for the health circuit breaker that gates hedging.
 
-    Tripping the breaker only ever suppresses the *hedge* request -- the
+    Tripping the breaker only ever suppresses the *hedge* request. The
     primary request is always sent and its result or exception is always
     returned to the caller normally.
     """
@@ -163,7 +163,7 @@ class EndpointConfig:
 
     #: Health circuit-breaker configuration. When set, replaces the
     #: default breaker config as a whole object rather than being merged
-    #: field-by-field -- for a partial override, use
+    #: field-by-field. For a partial override, use
     #: ``dataclasses.replace(default.circuit_breaker, ...)``.
     circuit_breaker: CircuitBreakerConfig | None = None
 
@@ -175,7 +175,16 @@ class EndpointConfig:
 
 @dataclass(frozen=True, slots=True)
 class EffectiveConfig:
-    """Fully-resolved hedge configuration for a single key (no more None fields)."""
+    """Fully-resolved hedge configuration for a single key.
+
+    Every "inherit the default" field from ``EndpointConfig`` has been
+    resolved away by ``resolve()``. ``estimated_rps`` and ``hedge_delay``
+    stay ``Optional`` here regardless, since their ``None`` means something
+    different than "unresolved": ``estimated_rps=None`` means "auto-estimate
+    from traffic" and ``hedge_delay=None`` means "no hardcoded delay, learn
+    one from the sketch" (see ``is_hardcoded``). Both are real, permanent
+    states, not resolution artifacts.
+    """
 
     percentile: float
     budget_percent: float