themeparks 3.1.0__tar.gz → 3.2.0__tar.gz

{themeparks-3.1.0 → themeparks-3.2.0}/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [3.2.0] - 2026-09-26
+
+### Added
+
+- **The client reads the rate-limit headers, and acts on them.** Both meters,
+  the per-minute REST one and the separate hourly history budget, are exposed
+  on `client.rate_limit`:
+
+  ```python
+  tp.rate_limit.rest.remaining          # 299
+  tp.rate_limit.history.remaining       # on a history call
+  tp.rate_limit.rest.seconds_until_reset()
+  ```
+
+  Every field is optional, and `None` means the server did not say rather than
+  "nothing left". Use `.exhausted`, which is true only when the server said
+  zero. The per-minute figures ride most responses; the hourly history ones are
+  withheld from anything a shared cache may store, because they are per-caller;
+  an unmetered plan advertises nothing. A response served from a cache is
+  ignored entirely, because its figures belong to whoever populated the entry. `reset` is a
+  relative countdown frozen when it was read, so `seconds_until_reset()` ages
+  it rather than returning a stale number.
+
+  When a response says the window is spent, the next request now waits for the
+  advertised reset instead of sending one that is certain to be refused, and to
+  spend a unit of budget being refused. `RetryConfig(respect_remaining=False)`
+  turns it off.
+
+  The hourly history budget is new on the wire; before it there was nothing to
+  read.
+
+### Changed
+
+- **Calls may now block before sending.** When the server has said your window
+  is spent, or has issued a 429 that is still in force, the client waits rather
+  than sending a request that is certain to be refused. A call that used to
+  return in 200ms can now take up to `retry.max_retry_after` (120s) first. That
+  is a TOTAL across the call, not per wait: the shared 429 gate and the
+  spent-window wait stack, and before the budget existed a 429 carrying both a
+  `Retry-After` and a spent window blocked for 180 seconds under a 120 second
+  cap. Turn the two halves off with `RetryConfig(respect_remaining=False)` and
+  `RetryConfig(respect_429=False)`.
+
+### Fixed
+
+- **`respect_429=False` did not opt out.** It raised the error the caller asked
+  for and then held their NEXT call for the full `Retry-After` anyway, because
+  the shared gate was closed regardless of the setting.
+
+- **A 429 was waited out once per in-flight request.** The wait belongs to the
+  caller, not to whichever request met it, so ten concurrent requests each
+  slept their own `Retry-After` and then retried at the same instant,
+  re-tripping the limit together. It is now taken once, on a gate shared by the
+  whole client, with a little jitter so the waiters do not wake in unison. A
+  shorter wait arriving while a longer one is in force no longer brings the
+  gate forward.
+
 ## [3.1.0] - 2026-09-23
 
 ### Added

{themeparks-3.1.0 → themeparks-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: themeparks
-Version: 3.1.0
+Version: 3.2.0
 Summary: Official SDK for the ThemeParks.wiki API
 Project-URL: Homepage, https://api.themeparks.wiki
 Project-URL: Source, https://github.com/ThemeParks/ThemeParks_Python
@@ -132,7 +132,7 @@ Both `ThemeParks` and `AsyncThemeParks` take the same keyword-only options:
 | `api_key`    | `str \| None`                            | `None`                               | Sent as the `x-api-key` header. Needed for anything beyond the free tier: deeper history, higher rate limits. |
 | `user_agent` | `str \| None`                            | `themeparks-sdk-py/<version>`        | Sent as the `User-Agent` header. Set this to identify your app. |
 | `timeout`    | `float` (seconds)                        | `10.0`                               | Per-request timeout. |
-| `retry`      | `RetryConfig \| None`                    | `RetryConfig(max_retries=3, respect_429=True, max_retry_after=120.0)` | Retry/backoff behavior. `max_retries` is N retries beyond the first attempt (so N+1 total calls). `max_retry_after` is the longest `Retry-After` the client will sleep through; past it you get `RateLimitError` instead of a silent wait. |
+| `retry`      | `RetryConfig \| None`                    | `RetryConfig(max_retries=3, respect_429=True, max_retry_after=120.0, respect_remaining=True)` | Retry/backoff behavior. `max_retries` is N retries beyond the first attempt (so N+1 total calls). `max_retry_after` is the TOTAL the client will block for within one call, across both the shared 429 gate and any spent-window wait. Past a single `Retry-After` that long you get `RateLimitError` instead of a silent wait. |
 | `cache`      | `Cache \| CacheConfig \| bool \| None`   | `True` (in-memory LRU)               | See **Caching** below. `False` disables caching entirely. |
 
 Example:
@@ -255,6 +255,50 @@ remaining keys are whatever fields that variant carries.
 timezone-aware `datetime`, honoring the entity's IANA timezone for naive
 inputs.
 
+## Rate limits
+
+`client.rate_limit` is a read-only property, not a constructor option.
+
+The API meters requests per minute, and history requests again per hour. Both
+are advertised on every response that can carry them, and the client reads
+them:
+
+```python
+with ThemeParks(api_key=KEY) as tp:
+    tp.entity(park_id).live()
+
+    print(tp.rate_limit.rest.remaining)          # 299
+    print(tp.rate_limit.rest.seconds_until_reset())
+    print(tp.rate_limit.history.remaining)       # on a history call
+```
+
+**`None` means the server did not say, never "nothing left".** Use
+`.exhausted`, which is true only when the server actually said zero.
+
+Which figures you get depends on the response:
+
+- The **per-minute** figures ride most responses, anonymous ones included.
+- The **hourly history** figures are withheld from anything a shared cache may
+  store, because they are per-caller and a cache would hand one caller's budget
+  to another. In practice you get them on calls made with a key.
+- An **unmetered plan** advertises nothing at all.
+
+A response served from a cache is ignored entirely. Its figures belong to
+whoever populated the entry and its countdown is already wrong: a cached
+`remaining: 0` would otherwise make the client sleep out someone else's
+window.
+
+The client also acts on what it reads. When a response says the window is
+spent, the next request waits for the advertised reset rather than sending a
+request that is certain to be refused, and to cost a unit of budget being
+refused. Turn that off with `RetryConfig(respect_remaining=False)`.
+
+**A 429 is held once for the whole client.** The wait belongs to the caller,
+not to whichever request happened to meet it, so it goes on a shared gate with
+a little jitter. Without that, ten concurrent requests each sleep their own
+copy of `Retry-After` and then all retry at the same instant, re-tripping the
+limit together.
+
 ## History
 
 `tp.entity(id).history` reads the archive. Both methods page for you and yield

{themeparks-3.1.0 → themeparks-3.2.0}/README.md

@@ -93,7 +93,7 @@ Both `ThemeParks` and `AsyncThemeParks` take the same keyword-only options:
 | `api_key`    | `str \| None`                            | `None`                               | Sent as the `x-api-key` header. Needed for anything beyond the free tier: deeper history, higher rate limits. |
 | `user_agent` | `str \| None`                            | `themeparks-sdk-py/<version>`        | Sent as the `User-Agent` header. Set this to identify your app. |
 | `timeout`    | `float` (seconds)                        | `10.0`                               | Per-request timeout. |
-| `retry`      | `RetryConfig \| None`                    | `RetryConfig(max_retries=3, respect_429=True, max_retry_after=120.0)` | Retry/backoff behavior. `max_retries` is N retries beyond the first attempt (so N+1 total calls). `max_retry_after` is the longest `Retry-After` the client will sleep through; past it you get `RateLimitError` instead of a silent wait. |
+| `retry`      | `RetryConfig \| None`                    | `RetryConfig(max_retries=3, respect_429=True, max_retry_after=120.0, respect_remaining=True)` | Retry/backoff behavior. `max_retries` is N retries beyond the first attempt (so N+1 total calls). `max_retry_after` is the TOTAL the client will block for within one call, across both the shared 429 gate and any spent-window wait. Past a single `Retry-After` that long you get `RateLimitError` instead of a silent wait. |
 | `cache`      | `Cache \| CacheConfig \| bool \| None`   | `True` (in-memory LRU)               | See **Caching** below. `False` disables caching entirely. |
 
 Example:
@@ -216,6 +216,50 @@ remaining keys are whatever fields that variant carries.
 timezone-aware `datetime`, honoring the entity's IANA timezone for naive
 inputs.
 
+## Rate limits
+
+`client.rate_limit` is a read-only property, not a constructor option.
+
+The API meters requests per minute, and history requests again per hour. Both
+are advertised on every response that can carry them, and the client reads
+them:
+
+```python
+with ThemeParks(api_key=KEY) as tp:
+    tp.entity(park_id).live()
+
+    print(tp.rate_limit.rest.remaining)          # 299
+    print(tp.rate_limit.rest.seconds_until_reset())
+    print(tp.rate_limit.history.remaining)       # on a history call
+```
+
+**`None` means the server did not say, never "nothing left".** Use
+`.exhausted`, which is true only when the server actually said zero.
+
+Which figures you get depends on the response:
+
+- The **per-minute** figures ride most responses, anonymous ones included.
+- The **hourly history** figures are withheld from anything a shared cache may
+  store, because they are per-caller and a cache would hand one caller's budget
+  to another. In practice you get them on calls made with a key.
+- An **unmetered plan** advertises nothing at all.
+
+A response served from a cache is ignored entirely. Its figures belong to
+whoever populated the entry and its countdown is already wrong: a cached
+`remaining: 0` would otherwise make the client sleep out someone else's
+window.
+
+The client also acts on what it reads. When a response says the window is
+spent, the next request waits for the advertised reset rather than sending a
+request that is certain to be refused, and to cost a unit of budget being
+refused. Turn that off with `RetryConfig(respect_remaining=False)`.
+
+**A 429 is held once for the whole client.** The wait belongs to the caller,
+not to whichever request happened to meet it, so it goes on a shared gate with
+a little jitter. Without that, ten concurrent requests each sleep their own
+copy of `Retry-After` and then all retry at the same instant, re-tripping the
+limit together.
+
 ## History
 
 `tp.entity(id).history` reads the archive. Both methods page for you and yield

{themeparks-3.1.0 → themeparks-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "themeparks"
-version = "3.1.0"
+version = "3.2.0"
 description = "Official SDK for the ThemeParks.wiki API"
 readme = "README.md"
 requires-python = ">=3.9"

{themeparks-3.1.0 → themeparks-3.2.0}/themeparks/__init__.py

@@ -10,6 +10,7 @@ from themeparks._errors import (
     ThemeParksError,
     TimeoutError,
 )
+from themeparks._ratelimit import RateLimit, RateLimits
 from themeparks._transport import RetryConfig
 
 __all__ = [
@@ -17,6 +18,8 @@ __all__ = [
     "AsyncThemeParks",
     "BudgetExhaustedError",
     "HistorySpan",
+    "RateLimit",
+    "RateLimits",
     "Cache",
     "CacheConfig",
     "InMemoryLRUCache",

{themeparks-3.1.0 → themeparks-3.2.0}/themeparks/_client.py

@@ -10,6 +10,7 @@ import httpx
 from themeparks._cache import Cache, CacheConfig, InMemoryLRUCache, ttl_for_path
 from themeparks._ergonomic.destinations import AsyncDestinationsApi, DestinationsApi
 from themeparks._ergonomic.entity import AsyncEntityHandle, EntityHandle
+from themeparks._ratelimit import RateLimits
 from themeparks._raw import AsyncRawClient, RawClient
 from themeparks._transport import AsyncTransport, RetryConfig, SyncTransport
 
@@ -52,6 +53,16 @@ class _CachingSyncTransport:
         self._inner = inner
         self._cache = cache
 
+    @property
+    def rate_limit(self) -> RateLimits:
+        """Whatever the inner transport last learned.
+
+        A cache HIT sends no request and so learns nothing, which is correct:
+        the figures then keep saying what the last real response said. They
+        are not invalidated by a hit, because a hit spent no budget either.
+        """
+        return self._inner.rate_limit
+
     def get(self, path: str) -> Any:
         ttl = ttl_for_path(path)
         if ttl > 0:
@@ -69,6 +80,16 @@ class _CachingAsyncTransport:
         self._inner = inner
         self._cache = cache
 
+    @property
+    def rate_limit(self) -> RateLimits:
+        """Whatever the inner transport last learned.
+
+        A cache HIT sends no request and so learns nothing, which is correct:
+        the figures then keep saying what the last real response said. They
+        are not invalidated by a hit, because a hit spent no budget either.
+        """
+        return self._inner.rate_limit
+
     async def get(self, path: str) -> Any:
         ttl = ttl_for_path(path)
         if ttl > 0:
@@ -125,6 +146,24 @@ class ThemeParks:
         )
         self.destinations = DestinationsApi(raw=self.raw)
 
+    @property
+    def rate_limit(self) -> RateLimits:
+        """What the server last said about your two budgets.
+
+        `rate_limit.rest` is the per-minute REST meter; `rate_limit.history`
+        is the separate hourly history budget. Every field can be None,
+        because every field can be legitimately absent: an unmetered plan
+        advertises nothing, and neither does a publicly cacheable response,
+        since the figures belong to whoever populated the cache.
+
+        None therefore means "the server did not say", never "nothing left".
+
+            with ThemeParks(api_key=KEY) as tp:
+                tp.entity(park).live()
+                print(tp.rate_limit.rest.remaining)   # e.g. 299
+        """
+        return self.raw._t.rate_limit
+
     def entity(self, entity_id: str) -> EntityHandle:
         return self._entity_ctor(entity_id)
 
@@ -184,6 +223,24 @@ class AsyncThemeParks:
         )
         self.destinations = AsyncDestinationsApi(raw=self.raw)
 
+    @property
+    def rate_limit(self) -> RateLimits:
+        """What the server last said about your two budgets.
+
+        `rate_limit.rest` is the per-minute REST meter; `rate_limit.history`
+        is the separate hourly history budget. Every field can be None,
+        because every field can be legitimately absent: an unmetered plan
+        advertises nothing, and neither does a publicly cacheable response,
+        since the figures belong to whoever populated the cache.
+
+        None therefore means "the server did not say", never "nothing left".
+
+            with ThemeParks(api_key=KEY) as tp:
+                tp.entity(park).live()
+                print(tp.rate_limit.rest.remaining)   # e.g. 299
+        """
+        return self.raw._t.rate_limit
+
     def entity(self, entity_id: str) -> AsyncEntityHandle:
         return self._entity_ctor(entity_id)
 

themeparks-3.2.0/themeparks/_ratelimit.py

@@ -0,0 +1,182 @@
+"""What the server says about your budget, and how to stay inside it.
+
+TWO BUDGETS, SEPARATELY METERED. The API meters requests per minute, and
+history requests again per hour. They are different windows over different
+counters, so the server advertises them in two sets of headers:
+
+    RateLimit-Limit / -Policy / -Remaining / -Reset            per minute
+    RateLimit-History-Limit / -Policy / -Remaining / -Reset    per hour
+
+Both were being thrown away. The SDK only ever read `Retry-After`, and only
+after a 429 had already happened -- so it could tell you that you had run out,
+never that you were about to.
+
+ABSENCE IS NOT ZERO. A response a shared cache may store carries no per-caller
+figures at all, because they belong to whoever populated the cache entry. That
+is every anonymous response. So `None` here means "the server did not say",
+which is a different thing from "nothing left", and nothing in this module may
+confuse the two.
+"""
+
+from __future__ import annotations
+
+import random
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+#: Header prefixes for the two meters.
+_REST_PREFIX = "ratelimit"
+_HISTORY_PREFIX = "ratelimit-history"
+
+
+def _int_or_none(raw: str | None) -> int | None:
+    """These fields are integers per the draft spec; anything else is unknown.
+
+    `int()` alone was too generous and differed from the JavaScript sibling on
+    the same input: PEP 515 means it reads "1_0" as 10. The server only ever
+    sends a non-negative integer, so it does not fire today, but a pair of
+    libraries whose selling point is parity should not disagree on it.
+    """
+    if raw is None:
+        return None
+    trimmed = raw.strip()
+    if not trimmed.isdigit():
+        return None
+    return int(trimmed)
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    """One meter's state, as of the last response that mentioned it.
+
+    Every field is optional because every field can be legitimately absent:
+    an unmetered plan advertises nothing, and neither does a publicly
+    cacheable response.
+    """
+
+    #: Requests allowed per window, or None if the server did not say.
+    limit: int | None = None
+    #: Requests left in the current window, or None if the server did not say.
+    remaining: int | None = None
+    #: Seconds until the window resets, as of `observed_at`.
+    reset: int | None = None
+    #: The raw policy string, e.g. "300;w=60".
+    policy: str | None = None
+    #: `time.monotonic()` when this was read, so `reset` can be aged.
+    observed_at: float | None = None
+
+    @property
+    def exhausted(self) -> bool:
+        """True only when the server SAID there is nothing left.
+
+        An unknown remaining is not exhaustion. Treating it as such would make
+        an anonymous caller, whose responses never carry figures, wait forever.
+        """
+        return self.remaining == 0
+
+    def seconds_until_reset(self, now: float | None = None) -> float | None:
+        """How long is left of the window, counting down from when we read it.
+
+        `reset` is a relative value frozen at `observed_at`; using it later
+        without ageing it is how a client waits far longer than it needs to.
+        """
+        if self.reset is None or self.observed_at is None:
+            return None
+        elapsed = (time.monotonic() if now is None else now) - self.observed_at
+        return max(0.0, self.reset - elapsed)
+
+
+@dataclass(frozen=True)
+class RateLimits:
+    """Both meters. Reached as `client.rate_limit`."""
+
+    rest: RateLimit = field(default_factory=RateLimit)
+    history: RateLimit = field(default_factory=RateLimit)
+
+
+def _read_one(headers: Mapping[str, str], prefix: str, now: float) -> RateLimit:
+    limit = _int_or_none(headers.get(f"{prefix}-limit"))
+    remaining = _int_or_none(headers.get(f"{prefix}-remaining"))
+    reset = _int_or_none(headers.get(f"{prefix}-reset"))
+    policy = headers.get(f"{prefix}-policy")
+    if limit is None and remaining is None and reset is None and policy is None:
+        return RateLimit()
+    return RateLimit(limit=limit, remaining=remaining, reset=reset, policy=policy, observed_at=now)
+
+
+def read_rate_limits(headers: Mapping[str, str], previous: RateLimits) -> RateLimits:
+    """Merge whatever this response said into what we already knew.
+
+    A response that mentions neither meter leaves both alone, and so does a
+    response served from a cache. That matters
+    because most responses mention only one: the history headers appear on
+    history routes, and on a cacheable response neither appears. Overwriting
+    with blanks would mean the last cacheable response erased everything the
+    SDK had learned.
+
+    Header lookup is case-insensitive via httpx's own mapping, but a plain dict
+    is accepted too, so the keys are compared lowercased.
+    """
+    lowered = {k.lower(): v for k, v in headers.items()}
+    # A cache HIT carries the figures of whoever populated the entry, frozen
+    # at that moment. They are not ours and the countdown is already wrong, so
+    # the honest reading is that this response said nothing.
+    age = _int_or_none(lowered.get("age"))
+    if age is not None and age > 0:
+        return previous
+    # No prefix filtering needed: _read_one looks up EXACT keys, so
+    # "ratelimit-limit" and "ratelimit-history-limit" cannot collide. An
+    # earlier version filtered the history keys out before reading the REST
+    # meter; removing that filter changed no behaviour and no test, which is
+    # what a redundant guard looks like. The bleed it guarded against is
+    # covered by a test either way.
+    now = time.monotonic()
+    history = _read_one(lowered, _HISTORY_PREFIX, now)
+    rest = _read_one(lowered, _REST_PREFIX, now)
+    return RateLimits(
+        rest=rest if rest.observed_at is not None else previous.rest,
+        history=history if history.observed_at is not None else previous.history,
+    )
+
+
+class Gate:
+    """One shared "not before" instant for a whole client.
+
+    WHY SHARED. A 429 applies to the CALLER, not to the request that happened
+    to meet it. With a per-request backoff, ten concurrent requests each sleep
+    their own Retry-After and then all retry at the same instant, re-tripping
+    the limit together -- a thundering herd the client inflicts on itself, and
+    on us. One gate means the wait is taken once.
+
+    Each waiter adds its own small jitter on the way out, because waking
+    together is the other half of the same problem.
+    """
+
+    def __init__(self, jitter: float = 0.25) -> None:
+        self._until = 0.0
+        self._jitter = jitter
+        self._lock = threading.Lock()
+
+    @property
+    def deadline(self) -> float:
+        """When the gate opens, on the monotonic clock. 0 if it is open."""
+        with self._lock:
+            return self._until
+
+    def close_for(self, seconds: float) -> None:
+        """Hold every request on this client for at least `seconds`."""
+        deadline = time.monotonic() + max(0.0, seconds)
+        with self._lock:
+            # Never bring the gate forward: a shorter Retry-After arriving
+            # while a longer one is in force would release the herd early.
+            self._until = max(self._until, deadline)
+
+    def wait_seconds(self) -> float:
+        """How long this caller should hold off, jitter included. 0 if open."""
+        with self._lock:
+            remaining = self._until - time.monotonic()
+        if remaining <= 0:
+            return 0.0
+        return remaining + random.random() * self._jitter

themeparks-3.2.0/themeparks/_transport.py

@@ -0,0 +1,449 @@
+"""Sync and async HTTP transport for the ThemeParks SDK."""
+
+from __future__ import annotations
+
+import asyncio
+import email.utils
+import random
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import timezone
+from typing import Any
+
+import httpx
+
+from themeparks._errors import APIError, NetworkError, RateLimitError, TimeoutError
+from themeparks._ratelimit import Gate, RateLimits, read_rate_limits
+
+_STATUS_TOO_MANY_REQUESTS = 429
+_STATUS_SERVER_ERROR = 500
+_ERROR_BODY_EXCERPT_LIMIT = 200
+_ERROR_MESSAGE_LIMIT = 300
+#: Below this, a computed wait is floating-point residue rather than a wait.
+_MIN_SLEEP_SECONDS = 0.001
+#: Spread applied to a synchronised release, so waiters do not wake as one.
+_SPREAD_SECONDS = 0.25
+
+
+@dataclass
+class RetryConfig:
+    max_retries: int = 3
+    respect_429: bool = True
+    #: Longest `Retry-After` this client will sleep through, in seconds.
+    #:
+    #: A REST 429 asks for seconds and is worth waiting out. A HISTORY 429 is
+    #: a different animal: that budget is hourly, so a spent one can ask for
+    #: most of an hour, and honouring it up to `max_retries` times means a
+    #: process that sits silent for hours and looks hung. Past this cap we do
+    #: not sleep at all, and raise `RateLimitError` carrying `retry_after` so
+    #: the caller can checkpoint and come back.
+    max_retry_after: float = 120.0
+    #: Wait out a window the server has already told us is spent.
+    #:
+    #: When a response says `remaining: 0`, the next request is a guaranteed
+    #: 429 that also costs us a unit of the caller's budget to refuse. Waiting
+    #: for the reset it advertised is strictly better than sending it. Off
+    #: turns the client back into a purely reactive one.
+    respect_remaining: bool = True
+
+
+def _parse_retry_after(raw: str | None) -> float | None:
+    """Seconds to wait, or None when the header gives us nothing usable.
+
+    NONE AND ZERO ARE DIFFERENT ANSWERS, and conflating them turned the client
+    into a hammer. Only `None` reaches the exponential backoff, so a header
+    that parsed to 0 -- which `Retry-After: 0` is, legally, per RFC 9110, and
+    which a negative or already-past date also produces -- meant no wait at
+    all. Measured: four requests in 3ms against a server that had just said
+    429, where an absent header correctly took 1962ms. Ten threads made that
+    204 requests a second at a server actively refusing them.
+
+    So a non-positive wait is not a wait, and we say None.
+    """
+    if raw is None:
+        return None
+    seconds: float | None
+    try:
+        seconds = float(raw)
+    except ValueError:
+        seconds = _parse_http_date_delta(raw)
+    if seconds is None or seconds <= 0:
+        return None
+    return seconds
+
+
+def _parse_http_date_delta(raw: str) -> float | None:
+    """An HTTP-date Retry-After, as seconds from now.
+
+    RFC 9110 requires the IMF-fixdate (GMT) form, but RFC 5322 `-0000` and a
+    bare date both appear in the wild, and `parsedate_to_datetime` returns a
+    NAIVE datetime for them. `.timestamp()` then reads it as local time, so on
+    a host an hour off UTC the answer was wrong by exactly that hour -- and
+    because it came out negative it became 0, landing in the no-backoff spin
+    above. Assume UTC when the sender did not say.
+    """
+    try:
+        parsed = email.utils.parsedate_to_datetime(raw)
+    except Exception:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.timestamp() - time.time()
+
+
+def _wait_too_long(retry_after: float | None, retry: RetryConfig) -> bool:
+    """True when the server's wait is longer than this client will sleep for."""
+    return retry_after is not None and retry_after > retry.max_retry_after
+
+
+def _backoff(attempt: int) -> float:
+    base = 0.25 * (2**attempt)
+    jittered: float = base + random.random() * base * 0.25
+    return min(jittered, 5.0)
+
+
+def _format_error_message(status: int, reason: str, body: Any) -> str:
+    """Build a human-useful error message from an HTTP response.
+
+    Includes a body excerpt when present so callers see *why* the request
+    failed without having to inspect ``exc.body`` manually. Dict bodies
+    with an ``"error"`` key are formatted specially; other bodies are
+    stringified and truncated to 200 characters.
+    """
+    if body is None or body == "":
+        return f"{status} {reason}"
+    if isinstance(body, dict) and "error" in body:
+        return f"{status} {reason}: {body['error']}"[:_ERROR_MESSAGE_LIMIT]
+    body_str = str(body)
+    if len(body_str) > _ERROR_BODY_EXCERPT_LIMIT:
+        body_str = body_str[:_ERROR_BODY_EXCERPT_LIMIT] + "..."
+    return f"{status} {reason}: {body_str}"
+
+
+def _parse_body(response: httpx.Response) -> Any:
+    ct = response.headers.get("content-type", "")
+    if "application/json" in ct:
+        try:
+            return response.json()
+        except Exception:
+            return None
+    try:
+        return response.text
+    except Exception:
+        return None
+
+
+def _headers(user_agent: str, api_key: str | None) -> dict[str, str]:
+    """Request headers, with the API key when one was supplied.
+
+    The SDK could not send a key at all until 2026-09-23, which meant the
+    official library could reach only the anonymous window: seven days of
+    history and the unauthenticated rate limit. A paying customer had to drop
+    to raw HTTP to use what they had bought.
+
+    `x-api-key` is the header the API documents. Nothing here logs or repeats
+    the value.
+    """
+    headers = {"user-agent": user_agent, "accept": "application/json"}
+    if api_key:
+        headers["x-api-key"] = api_key
+    return headers
+
+
+class SyncTransport:
+    def __init__(  # noqa: PLR0913
+        self,
+        *,
+        client: httpx.Client,
+        base_url: str,
+        user_agent: str,
+        retry: RetryConfig,
+        api_key: str | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._client = client
+        self._base_url = base_url.rstrip("/")
+        self._user_agent = user_agent
+        self._retry = retry
+        self._headers = _headers(user_agent, api_key)
+        self._sleep = sleep
+        self.rate_limit = RateLimits()
+        self._gate = Gate()
+
+    def _hold(self, budget: float) -> float:
+        """Wait before sending, if we already know this request would fail.
+
+        Returns how long it slept, so the caller can keep a running total. The
+        TOTAL is what `max_retry_after` bounds, not each leg: the gate wait and
+        the spent-window wait are both self-initiated holds, and they stack.
+        Measured before this budget existed: a 429 carrying `Retry-After: 5`
+        and `RateLimit-Reset: 60` slept 5 then 55, three times over -- 180
+        seconds inside one call whose cap was 120. Each leg was under the cap,
+        so the per-leg check never fired, and the promise the cap makes was
+        reachable around.
+
+        Two reasons to hold, and they are different. The GATE is a 429 the
+        server has already issued to this caller: the wait belongs to them,
+        not to whichever request met it, so it is shared and taken once. The
+        REMAINING check is a window the server told us is spent -- sending
+        into it is a guaranteed 429 that also costs a unit of budget to
+        refuse, so waiting for the advertised reset is strictly better.
+
+        A remaining we were never told is not a spent one. Anonymous
+        responses carry no figures at all, so an unknown must never hold.
+        """
+        spent = 0.0
+        # Re-read the gate after waiting. It slept once and returned, so a
+        # waiter that woke while someone else's 429 had pushed the gate
+        # further out sent anyway. Only loop when the deadline actually
+        # MOVED: re-reading unconditionally spins against any clock that does
+        # not advance.
+        while True:
+            before = self._gate.deadline
+            wait = min(self._gate.wait_seconds(), budget - spent)
+            if wait <= _MIN_SLEEP_SECONDS:
+                break
+            self._sleep(wait)
+            spent += wait
+            if self._gate.deadline <= before:
+                break
+        if not self._retry.respect_remaining:
+            return spent
+        for meter in (self.rate_limit.rest, self.rate_limit.history):
+            if not meter.exhausted:
+                continue
+            left = meter.seconds_until_reset()
+            if left is None or left <= 0 or left > self._retry.max_retry_after:
+                # Past the cap we do not sit on it: the caller gets the 429
+                # and its Retry-After, and can decide. Same rule the retry
+                # path follows.
+                continue
+            # Jittered like the gate. Without it every waiter derived `left`
+            # from the same observed_at and woke at the same absolute
+            # instant -- the tightest burst in the client, on the very branch
+            # that exists to avoid a 429.
+            left = min(left + random.random() * _SPREAD_SECONDS, budget - spent)
+            if left <= _MIN_SLEEP_SECONDS:
+                break
+            self._sleep(left)
+            spent += left
+        return spent
+
+    def get(self, path: str) -> Any:
+        url = self._base_url + path
+        attempt = 0
+        # One budget for the whole call, because that is what the cap promises.
+        budget = self._retry.max_retry_after
+        while True:
+            budget -= self._hold(budget)
+            try:
+                response = self._client.get(
+                    path,
+                    headers=self._headers,
+                )
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(f"request to {url} timed out") from exc
+            except httpx.HTTPError as exc:
+                if attempt < self._retry.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise NetworkError(f"network error calling {url}") from exc
+
+            self.rate_limit = read_rate_limits(response.headers, self.rate_limit)
+
+            if response.is_success:
+                return _parse_body(response)
+
+            body = _parse_body(response)
+            status = response.status_code
+
+            retry_after = _parse_retry_after(response.headers.get("retry-after"))
+            if (
+                status == _STATUS_TOO_MANY_REQUESTS
+                and self._retry.respect_429
+                and retry_after is not None
+                and not _wait_too_long(retry_after, self._retry)
+            ):
+                # The wait belongs to the CALLER, not to whichever request met
+                # it, so it goes on the shared gate and _hold() serves it once.
+                #
+                # respect_429=False means "do not wait on a 429", so it must
+                # gate the gate too. Without this the caller got the exception
+                # they asked for and then their NEXT call silently blocked,
+                # which is an opt-out that does not opt out.
+                #
+                # Past the cap the gate is left OPEN on purpose: we raise
+                # instead, and blocking the caller's next call for most of an
+                # hour is the opposite of letting them checkpoint and resume.
+                self._gate.close_for(retry_after)
+            if (
+                status == _STATUS_TOO_MANY_REQUESTS
+                and self._retry.respect_429
+                and attempt < self._retry.max_retries
+                and not _wait_too_long(retry_after, self._retry)
+            ):
+                # No sleep here: the gate above holds the wait and _hold()
+                # at the top of the loop serves it once. Paying it here too
+                # would double every backoff, and ten concurrent requests
+                # would each pay their own and then retry in unison.
+                if retry_after is None:
+                    self._sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            if status == _STATUS_TOO_MANY_REQUESTS:
+                raise RateLimitError(
+                    _format_error_message(status, response.reason_phrase, body),
+                    status=status,
+                    body=body,
+                    url=url,
+                    retry_after=retry_after,
+                )
+            if status >= _STATUS_SERVER_ERROR and attempt < self._retry.max_retries:
+                self._sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            raise APIError(
+                _format_error_message(status, response.reason_phrase, body),
+                status=status,
+                body=body,
+                url=url,
+            )
+
+
+class AsyncTransport:
+    def __init__(  # noqa: PLR0913
+        self,
+        *,
+        client: httpx.AsyncClient,
+        base_url: str,
+        user_agent: str,
+        retry: RetryConfig,
+        api_key: str | None = None,
+        sleep: Callable[..., Awaitable[None]] | None = None,
+    ) -> None:
+        self._client = client
+        self._base_url = base_url.rstrip("/")
+        self._user_agent = user_agent
+        self._retry = retry
+        self._headers = _headers(user_agent, api_key)
+        self._sleep: Callable[..., Awaitable[None]] = sleep if sleep is not None else asyncio.sleep
+        self.rate_limit = RateLimits()
+        self._gate = Gate()
+
+    async def _hold(self, budget: float) -> float:
+        """Asynchronous mirror of :meth:`SyncTransport._hold`."""
+        spent = 0.0
+        # Re-read the gate after waiting. It slept once and returned, so a
+        # waiter that woke while someone else's 429 had pushed the gate
+        # further out sent anyway. Only loop when the deadline actually
+        # MOVED: re-reading unconditionally spins against any clock that does
+        # not advance.
+        while True:
+            before = self._gate.deadline
+            wait = min(self._gate.wait_seconds(), budget - spent)
+            if wait <= _MIN_SLEEP_SECONDS:
+                break
+            await self._sleep(wait)
+            spent += wait
+            if self._gate.deadline <= before:
+                break
+        if not self._retry.respect_remaining:
+            return spent
+        for meter in (self.rate_limit.rest, self.rate_limit.history):
+            if not meter.exhausted:
+                continue
+            left = meter.seconds_until_reset()
+            if left is None or left <= 0 or left > self._retry.max_retry_after:
+                continue
+            # Jittered like the gate. Without it every waiter derived `left`
+            # from the same observed_at and woke at the same absolute
+            # instant -- the tightest burst in the client, on the very branch
+            # that exists to avoid a 429.
+            left = min(left + random.random() * _SPREAD_SECONDS, budget - spent)
+            if left <= _MIN_SLEEP_SECONDS:
+                break
+            await self._sleep(left)
+            spent += left
+        return spent
+
+    async def get(self, path: str) -> Any:
+        url = self._base_url + path
+        attempt = 0
+        budget = self._retry.max_retry_after
+        while True:
+            budget -= await self._hold(budget)
+            try:
+                response = await self._client.get(
+                    path,
+                    headers=self._headers,
+                )
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(f"request to {url} timed out") from exc
+            except httpx.HTTPError as exc:
+                if attempt < self._retry.max_retries:
+                    await self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise NetworkError(f"network error calling {url}") from exc
+
+            self.rate_limit = read_rate_limits(response.headers, self.rate_limit)
+
+            if response.is_success:
+                return _parse_body(response)
+
+            body = _parse_body(response)
+            status = response.status_code
+
+            retry_after = _parse_retry_after(response.headers.get("retry-after"))
+            if (
+                status == _STATUS_TOO_MANY_REQUESTS
+                and self._retry.respect_429
+                and retry_after is not None
+                and not _wait_too_long(retry_after, self._retry)
+            ):
+                # The wait belongs to the CALLER, not to whichever request met
+                # it, so it goes on the shared gate and _hold() serves it once.
+                #
+                # respect_429=False means "do not wait on a 429", so it must
+                # gate the gate too. Without this the caller got the exception
+                # they asked for and then their NEXT call silently blocked,
+                # which is an opt-out that does not opt out.
+                #
+                # Past the cap the gate is left OPEN on purpose: we raise
+                # instead, and blocking the caller's next call for most of an
+                # hour is the opposite of letting them checkpoint and resume.
+                self._gate.close_for(retry_after)
+            if (
+                status == _STATUS_TOO_MANY_REQUESTS
+                and self._retry.respect_429
+                and attempt < self._retry.max_retries
+                and not _wait_too_long(retry_after, self._retry)
+            ):
+                # No sleep here: the gate above holds the wait and _hold()
+                # at the top of the loop serves it once. Paying it here too
+                # would double every backoff, and ten concurrent requests
+                # would each pay their own and then retry in unison.
+                if retry_after is None:
+                    await self._sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            if status == _STATUS_TOO_MANY_REQUESTS:
+                raise RateLimitError(
+                    _format_error_message(status, response.reason_phrase, body),
+                    status=status,
+                    body=body,
+                    url=url,
+                    retry_after=retry_after,
+                )
+            if status >= _STATUS_SERVER_ERROR and attempt < self._retry.max_retries:
+                await self._sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            raise APIError(
+                _format_error_message(status, response.reason_phrase, body),
+                status=status,
+                body=body,
+                url=url,
+            )

themeparks-3.1.0/themeparks/_transport.py

@@ -1,252 +0,0 @@
-"""Sync and async HTTP transport for the ThemeParks SDK."""
-
-from __future__ import annotations
-
-import asyncio
-import email.utils
-import random
-import time
-from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
-from typing import Any
-
-import httpx
-
-from themeparks._errors import APIError, NetworkError, RateLimitError, TimeoutError
-
-_STATUS_TOO_MANY_REQUESTS = 429
-_STATUS_SERVER_ERROR = 500
-_ERROR_BODY_EXCERPT_LIMIT = 200
-_ERROR_MESSAGE_LIMIT = 300
-
-
-@dataclass
-class RetryConfig:
-    max_retries: int = 3
-    respect_429: bool = True
-    #: Longest `Retry-After` this client will sleep through, in seconds.
-    #:
-    #: A REST 429 asks for seconds and is worth waiting out. A HISTORY 429 is
-    #: a different animal: that budget is hourly, so a spent one can ask for
-    #: most of an hour, and honouring it up to `max_retries` times means a
-    #: process that sits silent for hours and looks hung. Past this cap we do
-    #: not sleep at all, and raise `RateLimitError` carrying `retry_after` so
-    #: the caller can checkpoint and come back.
-    max_retry_after: float = 120.0
-
-
-def _parse_retry_after(raw: str | None) -> float | None:
-    if raw is None:
-        return None
-    try:
-        return max(0.0, float(raw))
-    except ValueError:
-        pass
-    try:
-        parsed = email.utils.parsedate_to_datetime(raw)
-        return max(0.0, parsed.timestamp() - time.time())
-    except Exception:
-        return None
-
-
-def _wait_too_long(retry_after: float | None, retry: RetryConfig) -> bool:
-    """True when the server's wait is longer than this client will sleep for."""
-    return retry_after is not None and retry_after > retry.max_retry_after
-
-
-def _backoff(attempt: int) -> float:
-    base = 0.25 * (2**attempt)
-    jittered: float = base + random.random() * base * 0.25
-    return min(jittered, 5.0)
-
-
-def _format_error_message(status: int, reason: str, body: Any) -> str:
-    """Build a human-useful error message from an HTTP response.
-
-    Includes a body excerpt when present so callers see *why* the request
-    failed without having to inspect ``exc.body`` manually. Dict bodies
-    with an ``"error"`` key are formatted specially; other bodies are
-    stringified and truncated to 200 characters.
-    """
-    if body is None or body == "":
-        return f"{status} {reason}"
-    if isinstance(body, dict) and "error" in body:
-        return f"{status} {reason}: {body['error']}"[:_ERROR_MESSAGE_LIMIT]
-    body_str = str(body)
-    if len(body_str) > _ERROR_BODY_EXCERPT_LIMIT:
-        body_str = body_str[:_ERROR_BODY_EXCERPT_LIMIT] + "..."
-    return f"{status} {reason}: {body_str}"
-
-
-def _parse_body(response: httpx.Response) -> Any:
-    ct = response.headers.get("content-type", "")
-    if "application/json" in ct:
-        try:
-            return response.json()
-        except Exception:
-            return None
-    try:
-        return response.text
-    except Exception:
-        return None
-
-
-def _headers(user_agent: str, api_key: str | None) -> dict[str, str]:
-    """Request headers, with the API key when one was supplied.
-
-    The SDK could not send a key at all until 2026-09-23, which meant the
-    official library could reach only the anonymous window: seven days of
-    history and the unauthenticated rate limit. A paying customer had to drop
-    to raw HTTP to use what they had bought.
-
-    `x-api-key` is the header the API documents. Nothing here logs or repeats
-    the value.
-    """
-    headers = {"user-agent": user_agent, "accept": "application/json"}
-    if api_key:
-        headers["x-api-key"] = api_key
-    return headers
-
-
-class SyncTransport:
-    def __init__(  # noqa: PLR0913
-        self,
-        *,
-        client: httpx.Client,
-        base_url: str,
-        user_agent: str,
-        retry: RetryConfig,
-        api_key: str | None = None,
-        sleep: Callable[[float], None] = time.sleep,
-    ) -> None:
-        self._client = client
-        self._base_url = base_url.rstrip("/")
-        self._user_agent = user_agent
-        self._retry = retry
-        self._headers = _headers(user_agent, api_key)
-        self._sleep = sleep
-
-    def get(self, path: str) -> Any:
-        url = self._base_url + path
-        attempt = 0
-        while True:
-            try:
-                response = self._client.get(
-                    path,
-                    headers=self._headers,
-                )
-            except httpx.TimeoutException as exc:
-                raise TimeoutError(f"request to {url} timed out") from exc
-            except httpx.HTTPError as exc:
-                if attempt < self._retry.max_retries:
-                    self._sleep(_backoff(attempt))
-                    attempt += 1
-                    continue
-                raise NetworkError(f"network error calling {url}") from exc
-
-            if response.is_success:
-                return _parse_body(response)
-
-            body = _parse_body(response)
-            status = response.status_code
-
-            retry_after = _parse_retry_after(response.headers.get("retry-after"))
-            if (
-                status == _STATUS_TOO_MANY_REQUESTS
-                and self._retry.respect_429
-                and attempt < self._retry.max_retries
-                and not _wait_too_long(retry_after, self._retry)
-            ):
-                self._sleep(retry_after if retry_after is not None else _backoff(attempt))
-                attempt += 1
-                continue
-            if status == _STATUS_TOO_MANY_REQUESTS:
-                raise RateLimitError(
-                    _format_error_message(status, response.reason_phrase, body),
-                    status=status,
-                    body=body,
-                    url=url,
-                    retry_after=retry_after,
-                )
-            if status >= _STATUS_SERVER_ERROR and attempt < self._retry.max_retries:
-                self._sleep(_backoff(attempt))
-                attempt += 1
-                continue
-            raise APIError(
-                _format_error_message(status, response.reason_phrase, body),
-                status=status,
-                body=body,
-                url=url,
-            )
-
-
-class AsyncTransport:
-    def __init__(  # noqa: PLR0913
-        self,
-        *,
-        client: httpx.AsyncClient,
-        base_url: str,
-        user_agent: str,
-        retry: RetryConfig,
-        api_key: str | None = None,
-        sleep: Callable[..., Awaitable[None]] | None = None,
-    ) -> None:
-        self._client = client
-        self._base_url = base_url.rstrip("/")
-        self._user_agent = user_agent
-        self._retry = retry
-        self._headers = _headers(user_agent, api_key)
-        self._sleep: Callable[..., Awaitable[None]] = sleep if sleep is not None else asyncio.sleep
-
-    async def get(self, path: str) -> Any:
-        url = self._base_url + path
-        attempt = 0
-        while True:
-            try:
-                response = await self._client.get(
-                    path,
-                    headers=self._headers,
-                )
-            except httpx.TimeoutException as exc:
-                raise TimeoutError(f"request to {url} timed out") from exc
-            except httpx.HTTPError as exc:
-                if attempt < self._retry.max_retries:
-                    await self._sleep(_backoff(attempt))
-                    attempt += 1
-                    continue
-                raise NetworkError(f"network error calling {url}") from exc
-
-            if response.is_success:
-                return _parse_body(response)
-
-            body = _parse_body(response)
-            status = response.status_code
-
-            retry_after = _parse_retry_after(response.headers.get("retry-after"))
-            if (
-                status == _STATUS_TOO_MANY_REQUESTS
-                and self._retry.respect_429
-                and attempt < self._retry.max_retries
-                and not _wait_too_long(retry_after, self._retry)
-            ):
-                await self._sleep(retry_after if retry_after is not None else _backoff(attempt))
-                attempt += 1
-                continue
-            if status == _STATUS_TOO_MANY_REQUESTS:
-                raise RateLimitError(
-                    _format_error_message(status, response.reason_phrase, body),
-                    status=status,
-                    body=body,
-                    url=url,
-                    retry_after=retry_after,
-                )
-            if status >= _STATUS_SERVER_ERROR and attempt < self._retry.max_retries:
-                await self._sleep(_backoff(attempt))
-                attempt += 1
-                continue
-            raise APIError(
-                _format_error_message(status, response.reason_phrase, body),
-                status=status,
-                body=body,
-                url=url,
-            )