themeparks 3.0.0__tar.gz → 3.1.0__tar.gz

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

@@ -1,5 +1,81 @@
 # Changelog
 
+## [3.1.0] - 2026-09-23
+
+### Added
+
+- **History.** `tp.entity(id).history` reads the archive, and pages for you:
+
+  ```python
+  with ThemeParks(api_key=KEY) as tp:
+      history = tp.entity(DISNEYLAND).history
+      span = history.span()
+      for entity_id, row in history.days(span.archive_from, span.retrievable_through):
+          ...
+  ```
+
+  - `span()` returns `archive_from`, `recorded_to` and `retrievable_through`
+    in one shape. The underlying coverage documents do not: a park nests them
+    under `summary`, an entity carries them at the top level under different
+    names, so without this every caller writes that branch first.
+    `retrievable_through` is the end date to bound a backfill by, because it
+    is what the key may read rather than what the archive holds.
+  - `days(start, end)` yields `(entity id, row)` for one summary row per
+    park-local day; `changes(date)` yields every recorded observation.
+    Both follow the server's paging links to the end and yield as they go, so
+    a resort's five years never has to be in memory at once.
+  - Given a park id, both use the park-level call, which answers every entity
+    in the park in one request. The same data fetched ride by ride is around a
+    hundred times more calls against the same budget.
+  - `BudgetExhaustedError` (a `RateLimitError`) is raised when the history
+    budget is spent and the server asks for a longer wait than `max_wait`
+    (120s by default). It carries `retry_after`, so a backfill can checkpoint
+    and resume rather than hold a process open for most of an hour.
+
+- **`examples/backfill.py`** — a complete backfill with resume and NDJSON or
+  CSV output. It pulls Disneyland Resort's whole daily archive, 98,452 rows,
+  in one run.
+
+### Fixed
+
+- **A 429 could park the client for hours.** The transport honoured any
+  `Retry-After` up to `max_retries` times. That is right for a REST 429, which
+  asks for seconds, and wrong for a history 429: that budget is hourly, so a
+  spent one can ask for most of an hour, and three of those is roughly two and
+  a half hours of a silent process. `RetryConfig` gains `max_retry_after`
+  (120s by default): past it the client does not sleep at all and raises
+  `RateLimitError` with `retry_after` set. Without this `BudgetExhaustedError`
+  was unreachable in practice, because the transport rode out the wait before
+  the history layer ever saw the 429.
+
+- **The user agent announced the wrong version.** `PACKAGE_VERSION` was a
+  literal reading `2.0.0` in a package at `3.1.0`, so every request this SDK
+  has made since 3.0.0 named a version two majors old, and nothing anywhere
+  failed. It is now read from the installed package metadata, which cannot
+  drift, and a gate test pins it to `pyproject.toml` and to the `User-Agent`
+  the transport builds.
+
+- **The client had no way to send an API key.** There was no `api_key`
+  parameter anywhere, and the transport sent only `user-agent` and `accept`,
+  so every request this SDK made was anonymous: the lowest rate limit and the
+  most recent seven days of history, whatever the caller had paid for. A
+  paying customer had to drop to raw `httpx` to use their own plan.
+  `ThemeParks(api_key=...)` and `AsyncThemeParks(api_key=...)` now send
+  `x-api-key`. An empty string is treated as no key, because an unset
+  environment variable arrives as `""` far more often than as `None`, and
+  sending an empty key is a 401 rather than an anonymous request.
+
+- **The model generator was silently under-patching every documented class.**
+  `scripts/regenerate.py` restores nullability that `datamodel-code-generator`
+  drops, by matching the field line inside its class. The pattern could not
+  cross the blank line after a class docstring, so it matched only classes
+  without one and left every documented class unpatched, printing a warning
+  nobody read. That included `next` on all four history envelopes, which is
+  null on the last page of every paged response, so the SDK would have failed
+  to parse the page that ends a backfill. The pattern now spans blank lines,
+  an unmatched patch is a hard failure rather than a warning, and the 22
+  fields the spec marks both required and nullable are all listed.
+
 ## [3.0.0] - 2026-09-08
 
 ### Fixed
@@ -8,15 +84,20 @@
   park's schedule two different ways: precisely when nested under a
   destination, loosely when fetched directly. This client uses the direct
   path, so `purchases` was absent from the model entirely. Magic Kingdom
-  serves 26 entries carrying purchases.
+  served 26 of 79 upcoming entries with purchases on the day this shipped.
 
   ```python
-  sched = client.entity(park_id).schedule()
+  sched = client.entity(park_id).schedule.upcoming()
   for day in sched.schedule or []:
       for p in day.purchases or []:
-          print(p.name, p.price.amount, p.price.currency)
+          print(day.date, p.name, p.price.amount, p.price.currency)
+          # 2026-09-08 Lightning Lane for Seven Dwarfs Mine Train 1100.0 USD
   ```
 
+  Purchases are not limited to `TICKETED_EVENT` days — Lightning Lane entries
+  attach to ordinary `OPERATING` days, so do not filter on `type` to find
+  them.
+
 - **A null price on a schedule purchase no longer rejects the response.**
   2.0.1 made `PriceData.amount` nullable, but the schedule path used a
   second, inline price model that kept `amount` non-nullable. Both now use

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: themeparks
-Version: 3.0.0
+Version: 3.1.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
@@ -129,23 +129,31 @@ Both `ThemeParks` and `AsyncThemeParks` take the same keyword-only options:
 | Option       | Type                                     | Default                              | Purpose |
 |--------------|------------------------------------------|--------------------------------------|---------|
 | `base_url`   | `str`                                    | `https://api.themeparks.wiki/v1`     | API base URL (point at a mock / staging if you need to). |
+| `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)` | Retry/backoff behavior. `max_retries` is N retries beyond the first attempt (so N+1 total calls). |
+| `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. |
 | `cache`      | `Cache \| CacheConfig \| bool \| None`   | `True` (in-memory LRU)               | See **Caching** below. `False` disables caching entirely. |
 
 Example:
 
 ```python
+import os
+
 from themeparks import ThemeParks, RetryConfig
 
 tp = ThemeParks(
+    api_key=os.environ["THEMEPARKS_API_KEY"],
     user_agent="my-app/1.2.3 (+https://example.com)",
     timeout=15.0,
     retry=RetryConfig(max_retries=5, respect_429=True),
 )
 ```
 
+Without a key you get the anonymous tier: the most recent seven days of
+history and the lowest rate limit. Keys are issued from your account at
+[api.themeparks.wiki](https://api.themeparks.wiki).
+
 ## Ergonomic helpers
 
 ```python
@@ -247,6 +255,61 @@ remaining keys are whatever fields that variant carries.
 timezone-aware `datetime`, honoring the entity's IANA timezone for naive
 inputs.
 
+## History
+
+`tp.entity(id).history` reads the archive. Both methods page for you and yield
+rows as they arrive, so a resort's five years never has to fit in memory.
+
+```python
+from themeparks import ThemeParks
+
+DISNEYLAND = "7340550b-c14d-4def-80bb-acdb51d49a66"
+
+with ThemeParks(api_key=KEY) as tp:
+    history = tp.entity(DISNEYLAND).history
+
+    # What exists, and what your key may read. Same three fields whether the
+    # id is a park or a single ride.
+    span = history.span()
+    print(span.archive_from, span.recorded_to, span.retrievable_through)
+
+    # One summary row per park-local day, as (entity id, row).
+    for entity_id, row in history.days(span.archive_from, span.retrievable_through):
+        print(row.date, entity_id, row.operatingMinutes, row.standby.p50 if row.standby else None)
+
+    # Every recorded change on one day.
+    for entity_id, row in history.changes("2026-09-20"):
+        print(row.time, entity_id, row.status)
+```
+
+**Ask the park, not the rides.** Both history endpoints answer every entity in
+a park in one request. Pulling the same data ride by ride is around a hundred
+times more calls for a large resort, against the same budget. Pass a park id
+and you are on the cheap path without having to know the expensive one exists.
+
+**History has its own hourly budget**, separate from the per-minute rate limit.
+A large backfill will hit it, and the wait can be most of an hour because that
+is when the window rolls. The client will not sleep through that: past
+`retry.max_retry_after` (120s) it stops retrying, and the history layer turns
+the result into `BudgetExhaustedError` (a `RateLimitError`) carrying
+`retry_after`, so you can checkpoint and come back:
+
+```python
+from themeparks import BudgetExhaustedError
+
+try:
+    for entity_id, row in history.days(start, end):
+        write(entity_id, row)
+        last_day = row.date
+except BudgetExhaustedError as exc:
+    checkpoint(last_day)
+    print(f"resume in {exc.retry_after:.0f}s")
+```
+
+A complete backfill script with resume and CSV output is in
+[`examples/backfill.py`](examples/backfill.py); it pulls Disneyland Resort's
+whole daily archive, 98,452 rows, in one run.
+
 ## Low-level escape hatch
 
 Every ergonomic helper is built on top of `tp.raw`, which is a thin, typed

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

@@ -90,23 +90,31 @@ Both `ThemeParks` and `AsyncThemeParks` take the same keyword-only options:
 | Option       | Type                                     | Default                              | Purpose |
 |--------------|------------------------------------------|--------------------------------------|---------|
 | `base_url`   | `str`                                    | `https://api.themeparks.wiki/v1`     | API base URL (point at a mock / staging if you need to). |
+| `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)` | Retry/backoff behavior. `max_retries` is N retries beyond the first attempt (so N+1 total calls). |
+| `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. |
 | `cache`      | `Cache \| CacheConfig \| bool \| None`   | `True` (in-memory LRU)               | See **Caching** below. `False` disables caching entirely. |
 
 Example:
 
 ```python
+import os
+
 from themeparks import ThemeParks, RetryConfig
 
 tp = ThemeParks(
+    api_key=os.environ["THEMEPARKS_API_KEY"],
     user_agent="my-app/1.2.3 (+https://example.com)",
     timeout=15.0,
     retry=RetryConfig(max_retries=5, respect_429=True),
 )
 ```
 
+Without a key you get the anonymous tier: the most recent seven days of
+history and the lowest rate limit. Keys are issued from your account at
+[api.themeparks.wiki](https://api.themeparks.wiki).
+
 ## Ergonomic helpers
 
 ```python
@@ -208,6 +216,61 @@ remaining keys are whatever fields that variant carries.
 timezone-aware `datetime`, honoring the entity's IANA timezone for naive
 inputs.
 
+## History
+
+`tp.entity(id).history` reads the archive. Both methods page for you and yield
+rows as they arrive, so a resort's five years never has to fit in memory.
+
+```python
+from themeparks import ThemeParks
+
+DISNEYLAND = "7340550b-c14d-4def-80bb-acdb51d49a66"
+
+with ThemeParks(api_key=KEY) as tp:
+    history = tp.entity(DISNEYLAND).history
+
+    # What exists, and what your key may read. Same three fields whether the
+    # id is a park or a single ride.
+    span = history.span()
+    print(span.archive_from, span.recorded_to, span.retrievable_through)
+
+    # One summary row per park-local day, as (entity id, row).
+    for entity_id, row in history.days(span.archive_from, span.retrievable_through):
+        print(row.date, entity_id, row.operatingMinutes, row.standby.p50 if row.standby else None)
+
+    # Every recorded change on one day.
+    for entity_id, row in history.changes("2026-09-20"):
+        print(row.time, entity_id, row.status)
+```
+
+**Ask the park, not the rides.** Both history endpoints answer every entity in
+a park in one request. Pulling the same data ride by ride is around a hundred
+times more calls for a large resort, against the same budget. Pass a park id
+and you are on the cheap path without having to know the expensive one exists.
+
+**History has its own hourly budget**, separate from the per-minute rate limit.
+A large backfill will hit it, and the wait can be most of an hour because that
+is when the window rolls. The client will not sleep through that: past
+`retry.max_retry_after` (120s) it stops retrying, and the history layer turns
+the result into `BudgetExhaustedError` (a `RateLimitError`) carrying
+`retry_after`, so you can checkpoint and come back:
+
+```python
+from themeparks import BudgetExhaustedError
+
+try:
+    for entity_id, row in history.days(start, end):
+        write(entity_id, row)
+        last_day = row.date
+except BudgetExhaustedError as exc:
+    checkpoint(last_day)
+    print(f"resume in {exc.retry_after:.0f}s")
+```
+
+A complete backfill script with resume and CSV output is in
+[`examples/backfill.py`](examples/backfill.py); it pulls Disneyland Resort's
+whole daily archive, 98,452 rows, in one run.
+
 ## Low-level escape hatch
 
 Every ergonomic helper is built on top of `tp.raw`, which is a thin, typed

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

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

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

@@ -1,6 +1,7 @@
 from themeparks._cache import Cache, CacheConfig, InMemoryLRUCache
 from themeparks._client import AsyncThemeParks, ThemeParks
 from themeparks._ergonomic.dates import parse_api_datetime
+from themeparks._ergonomic.history import BudgetExhaustedError, HistorySpan
 from themeparks._ergonomic.live import current_wait_time, iter_queues
 from themeparks._errors import (
     APIError,
@@ -14,6 +15,8 @@ from themeparks._transport import RetryConfig
 __all__ = [
     "APIError",
     "AsyncThemeParks",
+    "BudgetExhaustedError",
+    "HistorySpan",
     "Cache",
     "CacheConfig",
     "InMemoryLRUCache",

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from importlib import metadata
 from typing import Any, Callable
 
 import httpx
@@ -13,7 +14,23 @@ from themeparks._raw import AsyncRawClient, RawClient
 from themeparks._transport import AsyncTransport, RetryConfig, SyncTransport
 
 DEFAULT_BASE_URL = "https://api.themeparks.wiki/v1"
-PACKAGE_VERSION = "2.0.0"
+
+
+def _package_version() -> str:
+    """Read the installed version rather than restating it.
+
+    This was a literal, and it said 2.0.0 in a package at 3.1.0: every request
+    the SDK made announced a version two majors old, and nothing failed. A
+    literal only stays right while someone remembers to change it, and nobody
+    did across two releases.
+    """
+    try:
+        return metadata.version("themeparks")
+    except metadata.PackageNotFoundError:  # running from a source tree
+        return "0+unknown"
+
+
+PACKAGE_VERSION = _package_version()
 
 
 def _default_user_agent() -> str:
@@ -89,6 +106,7 @@ class ThemeParks:
         retry: RetryConfig | None = None,
         cache: Cache | bool | CacheConfig | None = None,
         transport: httpx.BaseTransport | None = None,
+        api_key: str | None = None,
     ) -> None:
         self._client = httpx.Client(base_url=base_url, timeout=timeout, transport=transport)
         sync_t = SyncTransport(
@@ -96,6 +114,7 @@ class ThemeParks:
             base_url=base_url,
             user_agent=user_agent or _default_user_agent(),
             retry=retry or RetryConfig(),
+            api_key=api_key,
         )
         cache_impl = _build_cache(cache)
         inner: Any = _CachingSyncTransport(sync_t, cache_impl) if cache_impl else sync_t
@@ -146,6 +165,7 @@ class AsyncThemeParks:
         retry: RetryConfig | None = None,
         cache: Cache | bool | CacheConfig | None = None,
         transport: httpx.AsyncBaseTransport | None = None,
+        api_key: str | None = None,
     ) -> None:
         self._client = httpx.AsyncClient(base_url=base_url, timeout=timeout, transport=transport)
         async_t = AsyncTransport(
@@ -153,6 +173,7 @@ class AsyncThemeParks:
             base_url=base_url,
             user_agent=user_agent or _default_user_agent(),
             retry=retry or RetryConfig(),
+            api_key=api_key,
         )
         cache_impl = _build_cache(cache)
         inner: Any = _CachingAsyncTransport(async_t, cache_impl) if cache_impl else async_t

{themeparks-3.0.0 → themeparks-3.1.0}/themeparks/_ergonomic/entity.py

@@ -6,6 +6,7 @@ import asyncio
 from collections.abc import AsyncIterator, Iterator
 from datetime import date
 
+from themeparks._ergonomic.history import AsyncHistoryApi, HistoryApi
 from themeparks._generated.models import (
     EntityChild,
     EntityChildrenResponse,
@@ -76,6 +77,7 @@ class EntityHandle:
         self._raw = raw
         self.entity_id = entity_id
         self.schedule = _ScheduleApi(raw, entity_id)
+        self.history = HistoryApi(raw, entity_id)
 
     def get(self) -> EntityData:
         return self._raw.get_entity(self.entity_id)
@@ -143,6 +145,7 @@ class AsyncEntityHandle:
         self._raw = raw
         self.entity_id = entity_id
         self.schedule = _AsyncScheduleApi(raw, entity_id)
+        self.history = AsyncHistoryApi(raw, entity_id)
 
     async def get(self) -> EntityData:
         return await self._raw.get_entity(self.entity_id)