themeparks 2.0.1__tar.gz → 3.1.0__tar.gz

themeparks-3.1.0/CHANGELOG.md

@@ -0,0 +1,207 @@
+# 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
+
+- **Schedule entries now carry `purchases`.** The upstream spec described a
+  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
+  served 26 of 79 upcoming entries with purchases on the day this shipped.
+
+  ```python
+  sched = client.entity(park_id).schedule.upcoming()
+  for day in sched.schedule or []:
+      for p in day.purchases or []:
+          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
+  `PriceData`. Tokyo Disneyland serves six Premier Access rows with a null
+  amount, and this client raised `ValidationError` on every one of them.
+
+- Schedule entries gained the `description` field the API has always sent.
+
+### Changed
+
+- **BREAKING — `ScheduleEntry.type` is an enum, not a `str`.** It was
+  `type: str`; it is now a `Type` enum. This breaks *silently*: the comparison
+  does not raise, it just stops being true.
+
+  ```python
+  # before: True.  now: False, with no error.
+  if day.type == "OPERATING":
+      ...
+
+  # use one of these instead
+  if day.type.value == "OPERATING":
+      ...
+  from themeparks._generated.models import Type
+  if day.type is Type.OPERATING:
+      ...
+  ```
+
+  Audit any comparison of `.type` against a string literal before upgrading.
+  This is the one change here that will not announce itself.
+
+- **BREAKING — the `PricedScheduleEntry` and `Price` models are gone.**
+  `PricedScheduleEntry` is now `ScheduleEntry`, and the inline `Price` model
+  is replaced by `PriceData`. Neither was exported from the package root, so
+  this only affects code importing from `themeparks._generated.models`
+  directly — a private module.
+
+- The duplicate `EntityType1` and `EntityType2` enums collapse into
+  `EntityType`. Same members, same values.
+
+## [2.0.1] - 2026-09-01
+### Fixed
+- `PriceData.amount` is now nullable. The API returns `null` when a paid queue
+  exists but the provider does not publish a price, and `0` only when the queue
+  is genuinely free. Both previously arrived as `0`, so an unknown price was
+  indistinguishable from a free one.
+
+  Before this, a single null amount on one attraction made pydantic reject the
+  **entire** live response for that park, not just the one field.
+
+  Code testing `if price.amount:` or `if not price.amount:` now conflates
+  "free" with "price unknown" — the exact confusion this change exists to
+  remove. Switch to an explicit check:
+
+  ```python
+  if price.amount is None:
+      label = "price not published"
+  else:
+      label = f"{price.currency} {price.amount / 100:.2f}"
+  ```
+
+  `price.formatted` is optional and may be absent when the amount is unknown,
+  so do not rely on it alone to detect the case.
+
+## [2.0.0] - 2026-04-15
+First stable v2 release. Identical surface to `2.0.0a1` after a brief alpha
+soak; no code changes since `2.0.0a1`. Bumped `Development Status` classifier
+to `Production/Stable`.
+
+## [2.0.0a1] - 2026-04-15
+### Added
+- MkDocs Material documentation site with full API reference and a cookbook
+  (recipes for sorted wait times, 7-day schedules, geo-locations grouped by
+  entity type, every queue variant, and HTTP debugging).
+- Top-level exports for `current_wait_time`, `iter_queues`, `parse_api_datetime`.
+- Class-level docstrings on every public surface for readable API reference rendering.
+- README sections explaining every queue variant (STANDBY, PAID_RETURN_TIME,
+  BOARDING_GROUP, etc.) and how to enable the httpx logger for HTTP debugging.
+
+### Fixed
+- `walk()` now makes a single API call instead of one per descendant — the
+  `/children` endpoint already returns the entire subtree recursively. Walking
+  Walt Disney World dropped from ~250 requests to 1.
+- `get_entity_schedule_month` now zero-pads the month (`/schedule/2026/05`,
+  not `/schedule/2026/5`) per the API requirement.
+- `RetryConfig` field renamed `max_attempts` → `max_retries` to match its
+  actual semantics (N retries beyond the first attempt = N+1 total calls).
+- `APIError` now includes a server-body excerpt in the exception message;
+  `RateLimitError.__repr__` includes `retry_after`.
+- `destinations.find()` now performs the loose, case-insensitive substring
+  match it had always promised in its docstring (was exact equality).
+- Generated queue variant classes renamed (`STANDBY` → `StandbyQueue` etc.)
+  so users access `queue.STANDBY` instead of the awkward `queue.STANDBY_1`.
+- `eval-type-backport` is now a conditional dep on Python 3.9 so pydantic
+  can evaluate PEP 604 union syntax in the generated models.
+
+## [2.0.0a0] - 2026-04-14
+### Added
+- Full rewrite on pydantic v2 + httpx.
+- Sync `ThemeParks` and `AsyncThemeParks` clients with shared core.
+- Ergonomic `client.entity(id)` navigation, `walk()`, `schedule.range()`.
+- Typed pydantic models, correctly handling nullable queue fields (fixes #1, #2).
+- Default-on caching with per-endpoint TTLs and pluggable adapter.
+- 429 `Retry-After` handling.
+
+### Removed
+- Legacy `openapi_client` top-level import and generated surface. See MIGRATION.md.
+- `urllib3`-based transport.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: themeparks
-Version: 2.0.1
+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-2.0.1 → 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-2.0.1 → themeparks-3.1.0}/pyproject.toml

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

{themeparks-2.0.1 → 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-2.0.1 → 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-2.0.1 → 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)