themeparks 3.1.0__tar.gz → 3.3.0__tar.gz

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

@@ -1,5 +1,108 @@
 # Changelog
 
+## [3.3.0] - 2026-09-28
+
+### Added
+
+- **`themeparks-backfill`: the archive download as a command.** It was an example
+  to copy off GitHub. The first paying customer followed that link and had to
+  work out that the library needed installing, then what the arguments were,
+  then read a traceback. Now:
+
+  ```bash
+  pip install themeparks
+  themeparks-backfill "Disneyland Park"
+  ```
+
+  - Takes a park or a **destination**, by name or id. A destination back fills
+    every park in it, one file each. `"Walt Disney World Resort"` is the handle
+    people actually have; four park uuids is not.
+  - `--list [text]` prints destinations with their parks underneath, and **needs
+    no key**, so you can find your park before deciding whether to pay.
+  - Refuses to guess between two matches. Two parks are named exactly
+    "Disneyland Park" (Anaheim and Paris), so the candidate list names the
+    destination as well.
+  - **Runs without a key**, reading the 7 days anonymous access allows, and says
+    what a key would add. It used to refuse to start with a message that
+    mentioned anonymous access in the same breath.
+  - NDJSON by default, `--format csv` for one wide row per entity per day.
+  - Checkpoints against the hourly history budget and exits 75 (`EX_TEMPFAIL`),
+    so a cron or timer retries rather than alerting. Re-running continues.
+
+  `python -m themeparks.backfill` is the same thing. `examples/backfill.py`
+  remains as a shim so existing links keep working.
+
+### Fixed
+
+- **The history window recovery now actually works.** 3.2.0's `examples/backfill.py`
+  read `earliestAllowedDate` from the top level of the 403 body; the API nests it
+  under `error`. So the recovery shipped doing nothing and a Pro customer still
+  got a traceback on their first request. The tests passed because the fixture was
+  built from the formatted text in a traceback rather than a real response, so the
+  code and the test were wrong together. The fixture is now captured from
+  production and a test fails if anyone flattens it.
+
+  The underlying gap is in the API, not the client: `/history/coverage` reports
+  where the archive starts and where your window ends, and nothing about where
+  your window begins. Until it does, the 403 is the only place that date exists.
+
+## [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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: themeparks
-Version: 3.1.0
+Version: 3.3.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
@@ -306,9 +350,25 @@ except BudgetExhaustedError as exc:
     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.
+### Or skip the code: there is a command
+
+Installing the library installs `themeparks-backfill`, which does all of the
+above and stops before the walls:
+
+```bash
+themeparks-backfill "Disneyland Park"           # a park, by name or id
+themeparks-backfill "Walt Disney World Resort"  # a destination: every park in it
+themeparks-backfill --list disney               # find an id. Needs no key.
+```
+
+It reads how far back your own key may ask and starts there, writes NDJSON or
+`--format csv`, names every row with the park and the entity, records what it
+has done so re-running never duplicates a file, and exits 75 when the hourly
+history budget runs out so a scheduler retries rather than alerts.
+
+`python -m themeparks.backfill` is the same thing, which is the one to use if
+`pip install --user` put the script somewhere off your PATH. `themeparks-backfill
+--help` has the rest.
 
 ## Low-level escape hatch
 

{themeparks-3.1.0 → themeparks-3.3.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
@@ -267,9 +311,25 @@ except BudgetExhaustedError as exc:
     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.
+### Or skip the code: there is a command
+
+Installing the library installs `themeparks-backfill`, which does all of the
+above and stops before the walls:
+
+```bash
+themeparks-backfill "Disneyland Park"           # a park, by name or id
+themeparks-backfill "Walt Disney World Resort"  # a destination: every park in it
+themeparks-backfill --list disney               # find an id. Needs no key.
+```
+
+It reads how far back your own key may ask and starts there, writes NDJSON or
+`--format csv`, names every row with the park and the entity, records what it
+has done so re-running never duplicates a file, and exits 75 when the hourly
+history budget runs out so a scheduler retries rather than alerts.
+
+`python -m themeparks.backfill` is the same thing, which is the one to use if
+`pip install --user` put the script somewhere off your PATH. `themeparks-backfill
+--help` has the rest.
 
 ## Low-level escape hatch
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "themeparks"
-version = "3.1.0"
+version = "3.3.0"
 description = "Official SDK for the ThemeParks.wiki API"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -30,6 +30,12 @@ dependencies = [
   "eval-type-backport>=0.2; python_version < '3.10'",
 ]
 
+[project.scripts]
+# The archive backfill, as a command rather than a file to copy off GitHub.
+# `pip install themeparks` then `themeparks-backfill "Disneyland Park"` is the
+# whole path from nothing to a file of history.
+themeparks-backfill = "themeparks.backfill:main"
+
 [project.urls]
 Homepage = "https://api.themeparks.wiki"
 Source = "https://github.com/ThemeParks/ThemeParks_Python"

themeparks-3.3.0/tests/fixtures/README.md

@@ -0,0 +1,37 @@
+# Fixtures captured from the live API
+
+Not hand-written. Each file here was taken from a real response, and the header
+below says which endpoint and when. That matters because of a specific failure
+this project keeps repeating.
+
+## Why this directory exists
+
+On 2026-09-28 a 403-recovery fix shipped doing nothing. Its tests passed because
+the fixture was built from the *formatted text of a traceback* rather than from a
+response body, so the code and the test were wrong together and agreed with each
+other. The memory note for that pattern is `self-confirming-harness`, and it was
+its fifth occurrence in one day.
+
+A fixture the author of the code also invented proves only that the two are
+consistent. A fixture taken from the real thing can disagree.
+
+## destinations_slice.json
+
+`GET https://api.themeparks.wiki/v1/destinations`, captured 2026-09-28, trimmed
+to 9 destinations and 20 parks and otherwise verbatim — every id, name and slug
+is exactly what the API returned.
+
+It is trimmed to keep, deliberately, every case that broke name resolution:
+
+| Case | Why it is here |
+|---|---|
+| `Walt Disney World® Resort` | U+00AE. The command's own documented example, `"Walt Disney World Resort"`, did not match it. |
+| `LEGOLAND® Korea` | the same, on a destination whose park shares the name |
+| `Walibi Rhône-Alpes` | U+00F4, so a normaliser must decompose accents |
+| `Knott's Berry Farm` + `Knott’s Soak City` | ASCII `'` and U+2019 **in one destination**. Nobody types the curly one. |
+| `Disneyland Park` ×2 | Anaheim and Paris, identical park names. The reason the candidate list names the destination. |
+| `Hurricane Harbor` + `Hurricane Harbor Chicago` | an exact match with a substring rival: the shape that silently downloaded the wrong park |
+| `Cedar Point` | destination name == park name, with a second park, so "exact destination beats exact park" is observable |
+
+**Do not edit these by hand.** Re-capture them. If a name upstream has drifted,
+that is a real change and the test should notice.

{themeparks-3.1.0 → themeparks-3.3.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.3.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.1.0 → themeparks-3.3.0}/themeparks/_ergonomic/history.py

@@ -111,17 +111,54 @@ def _reraise_if_too_long(exc: RateLimitError, max_wait: float) -> None:
     raise exc
 
 
-def _daily_rows(envelope: DailyEnvelope) -> Iterator[tuple[str, HistoryDailyRow]]:
-    """Yield (entity id, row). A park envelope carries many entities; an entity
-    envelope carries its own rows, so both flatten to the same stream."""
+class EntityRef(NamedTuple):
+    """Who a history row belongs to, AS THE HISTORY RESPONSE REPORTS IT.
+
+    The name matters and the source of it matters more. A park's current
+    `/children` list gives today's name, which is the wrong label for a row
+    recorded years ago: rides are renamed, and stamping today's name on old data
+    quietly rewrites history. The history envelope carries its own `name` and
+    `entityType` per entity, and that is the name to use.
+    """
+
+    id: str
+    name: str
+    entity_type: str
+
+
+def _ref(entity: Any) -> EntityRef:
+    kind = getattr(entity, "entityType", None)
+    # The generated models use an enum, and str(EntityType.SHOW) is
+    # "EntityType.SHOW". `.value` is what the API sends.
+    inner = getattr(kind, "value", kind)
+    return EntityRef(
+        entity.id, getattr(entity, "name", "") or "", "" if inner is None else str(inner)
+    )
+
+
+def _daily_entity_rows(envelope: DailyEnvelope) -> Iterator[tuple[EntityRef, HistoryDailyRow]]:
+    """Yield (entity ref, row), keeping the name the response gave.
+
+    `_daily_rows` below is the same walk with the ref flattened to its id, kept
+    because `days()` has yielded `(id, row)` since 3.0 and that shape is public.
+    """
     entities = getattr(envelope, "entities", None)
     if entities is not None:
         for entity in entities:
+            ref = _ref(entity)
             for row in entity.days or []:
-                yield (entity.id, row)
+                yield (ref, row)
         return
+    ref = _ref(envelope)
     for row in getattr(envelope, "days", None) or []:
-        yield (envelope.id, row)
+        yield (ref, row)
+
+
+def _daily_rows(envelope: DailyEnvelope) -> Iterator[tuple[str, HistoryDailyRow]]:
+    """Yield (entity id, row). A park envelope carries many entities; an entity
+    envelope carries its own rows, so both flatten to the same stream."""
+    for ref, row in _daily_entity_rows(envelope):
+        yield (ref.id, row)
 
 
 def _raw_rows(envelope: RawEnvelope) -> Iterator[tuple[str, HistoryRow]]:
@@ -154,6 +191,29 @@ class HistoryApi:
         """
         return _span(self.coverage())
 
+    def days_with_entities(
+        self,
+        start: str | _date | None = None,
+        end: str | _date | None = None,
+        *,
+        max_wait: float = DEFAULT_MAX_WAIT_SECONDS,
+    ) -> Iterator[tuple[EntityRef, HistoryDailyRow]]:
+        """`days()`, but each row arrives with the entity's name and type.
+
+        Use this when you are writing history to a file. The name comes from the
+        history response itself, so it is the label that response gives for those
+        rows rather than the park's current `/children` list -- rides get renamed,
+        and today's name on a row from three years ago is a quiet rewrite of the
+        record.
+
+        It also saves a request: the name is already in the payload, so nothing
+        needs to ask what an id refers to.
+        """
+        envelope: DailyEnvelope | None = self._first_daily(start, end, max_wait)
+        while envelope is not None:
+            yield from _daily_entity_rows(envelope)
+            envelope = self._next_daily(envelope, max_wait)
+
     def days(
         self,
         start: str | _date | None = None,
@@ -165,6 +225,9 @@ class HistoryApi:
 
         Pages automatically. Given a park id this uses the park call, which
         answers every entity in the park in one request.
+
+        `days_with_entities()` is the same stream with the entity's name and type
+        attached; this shape is kept because it is public API from 3.0.
         """
         envelope: DailyEnvelope | None = self._first_daily(start, end, max_wait)
         while envelope is not None: