History¶
Reached as tp.entity(id).history. Both methods page for you and yield rows
as they arrive, so a resort's five years never has to fit in memory.
Ask a park id wherever you can. Both history endpoints answer a whole park in one request, and a park-by-park backfill of a large resort costs around a hundred times fewer calls than the same data fetched ride by ride.
History for one entity id, reached as tp.entity(id).history.
coverage ¶
What history exists here, field by field. Ask this before a backfill.
span ¶
The dates a backfill should run between, as a :class:HistorySpan.
One call, and the same three fields whether this id is a park or a single ride.
days_with_entities ¶
days_with_entities(start: str | date | None = None, end: str | date | None = None, *, max_wait: float = DEFAULT_MAX_WAIT_SECONDS, on_page: Callable[[HistoryPage], None] | None = None) -> 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.
on_page is called once every row of a page has been yielded, with a
:class:HistoryPage. Checkpoint on that, never on the last row you saw.
days ¶
days(start: str | date | None = None, end: str | date | None = None, *, max_wait: float = DEFAULT_MAX_WAIT_SECONDS, on_page: Callable[[HistoryPage], None] | None = None) -> Iterator[tuple[str, HistoryDailyRow]]
One summary row per park-local day, as (entity id, row).
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.
changes ¶
changes(date: str | date | None = None, *, start: str | date | None = None, end: str | date | None = None, max_wait: float = DEFAULT_MAX_WAIT_SECONDS) -> HistoryChanges
Every recorded change, as (entity id, row), plus the state before them.
A single day for a park, or up to 31 days for one entity. The caller does not have to know which cap applies: ask for what you want and the API answers or tells you the range is too long.
Iterate the result for the rows. Its opening is each entity's state at
the start of the range, which is what a day has to be rebuilt from --
see :class:HistoryChanges.
Asynchronous mirror of :class:HistoryApi.
changes ¶
changes(date: str | date | None = None, *, start: str | date | None = None, end: str | date | None = None, max_wait: float = DEFAULT_MAX_WAIT_SECONDS) -> AsyncHistoryChanges
Asynchronous mirror of :meth:HistoryApi.changes.
Not a coroutine, as before: async for pair in history.changes(day)
works unchanged. See :class:AsyncHistoryChanges for opening.
Bases: Iterator[tuple[str, HistoryRow]]
What :meth:HistoryApi.changes returns: the rows, and the state before them.
Iterate it exactly as before, for (entity id, row) pairs. Each row is the
entity's complete live data from its time until the next row's.
opening is the one thing the rows cannot tell you: the state in force at
the START of the range, before the first change. Without it the stretch
between midnight and an entity's first change has no known status -- on a
night a ride runs past midnight that is real operating time, and a day
rebuilt from the rows alone disagrees with the daily summary. It is a dict
of :class:HistoryOpening keyed by entity id, with an entry for every
entity in the response, including one that did not change at all that day.
Nothing is requested until the result is first used, as when this was a
plain generator, and reading opening before or after iterating costs the
same single request. close() ends it early, as it did a generator.
An opening can be incomplete: degraded is true when the server could not
look far enough back in time for this response, and degradedReason says
why. Fields may then be missing from it; ask again a minute later for the
full opening. observedAt is when that state was last seen, which can be
long before the range for an entity whose feed stopped.
Bases: AsyncIterator[tuple[str, HistoryRow]]
What :meth:AsyncHistoryApi.changes returns. See :class:HistoryChanges.
Iterate it with async for. A property cannot await, so opening is
readable once the response has arrived: after the first step of iteration,
or straight away with changes = await history.changes(day).load().
Bases: ApiModel
The opening object: the complete state at the start of the range, in the same shape as a row. A field is present only if the entity has it. An unknown value is its empty form (standby {"waitTime": null}, showtimes []); an unknown status is null.
time
instance-attribute
¶
Start of the range (UTC, whole seconds). The state below is effective from this instant.
observedAt
class-attribute
instance-attribute
¶
When this state was last seen (UTC, whole seconds): the newest entry in observedAtByKind. Earlier than time means it was carried in from before the range, possibly from long ago; a ride whose feed stopped keeps its last values. Absent means we hold nothing for this entity from before the range, unless degraded is set.
observedAtByKind
class-attribute
instance-attribute
¶
When each field of the opening was last seen (UTC, whole seconds), keyed by its path: status, queue.StandbyQueue, showtimes and so on. A wait that did not change for weeks is dated weeks back, so check a queue's own entry before treating it as current. Usually, but not always, the moment the value last changed.
degraded
class-attribute
instance-attribute
¶
Present, and true, when we could not look far enough back for this response, so the opening may be missing a field we hold. Ask again in a minute for the full opening.
degradedReason
class-attribute
instance-attribute
¶
Why the lookup was cut short: timeout, error, or capacity when it needed more reading than one request is allowed.
status
class-attribute
instance-attribute
¶
Live status at the start of the range; null when unknown.
Bases: NamedTuple
The three dates a backfill needs, in one shape for parks and rides.
A park's coverage document nests these under summary and an entity's
carries them at the top level under different names, so without this
every caller writes the same branch before they can ask their first
question.
retrievable_through is the end date to use. It is what YOUR key may
retrieve, not what the archive holds, so a backfill bounded by it stops
at the edge of the plan instead of walking into 403s.
final_through
property
¶
The newest day the archive has recorded that this key may read, or None.
retrievable_through is usually today, and today's row is the day so
far. Recent days can still change after that: a run that crosses
midnight is reported on the day it started, and the archive records
days 2 to 3 behind live data. recorded_to is the newest day the
archive holds, so a day on or before it is what the server has
recorded, and is the place to stop if you fetch each day once. Ask for
anything later again once final_through has moved past it.
Recorded is not immutable: the server can re-record a past day, for example after repairing a park's feed. Fetch a range again if you need to pick that up.
The earlier of the two dates, because a key may be entitled to fewer days than the archive holds. None when either is unknown.
Bases: RateLimitError
The hourly history budget is spent and the wait is longer than allowed.
Carries retry_after from the underlying 429, so a backfill can record
where it got to and resume after that long rather than holding a process
open waiting for a budget window to roll.