Module adcp.decisioning.state_machines
Canonical state-machine helpers for AdCP lifecycle objects.
The AdCP spec defines a finite-state graph for media buys and creatives;
adopters who hand-roll lifecycle methods (update_media_buy,
sync_creatives, etc.) repeatedly re-implement the same legality
checks. These helpers project the spec state graph as a single source
of truth and raise a spec-conformant INVALID_STATE error when an
adopter tries an illegal transition.
Use in update_media_buy / lifecycle-changing handlers to refuse
non-monotonic state changes (e.g., active → pending_creatives).
The helpers are deliberately small — adopters who need richer guards
(e.g., role-based authorization on transitions) compose their own
checks alongside these.
Media buys have two graphs. :data:MEDIA_BUY_TRANSITIONS is the
requested graph: what a handler may do when a buyer asks for a state
change, enforced by :func:assert_media_buy_transition().
:data:OBSERVED_MEDIA_BUY_TRANSITIONS is the observed graph: every
move a seller may record when it mirrors status from its own platform.
It is a strict superset, and it equals the full AdCP 3.2 published
lifecycle graph.
State enum values track the AdCP spec at
schemas/cache/enums/media-buy-status.json and
schemas/cache/enums/creative-status.json.
Global variables
var CREATIVE_ASSET_TRANSITIONS : Mapping[str, frozenset[str]]-
Legal creative-asset state transitions per the AdCP spec. Maps
from_state→ set of legalto_statevalues. Terminal states map to an empty frozenset. var MEDIA_BUY_TERMINAL_STATUSES : frozenset[str]-
Derived from :data:
MEDIA_BUY_TRANSITIONS, so it cannot drift from the graph. AdCP 3.2docs/media-buy/specification.mdx, "Media Buy State Transitions": "Terminal states (completed,rejected,canceled) allow no further transitions." var MEDIA_BUY_TRANSITIONS : Mapping[str, frozenset[str]]-
This is the requested graph that :func:
assert_media_buy_transition()enforces. It omits three published edges that follow from the seller's lifecycle rather than from a status a buyer asks for; see :data:OBSERVED_MEDIA_BUY_TRANSITIONSfor recording what an ad server reports. var OBSERVED_MEDIA_BUY_TRANSITIONS : Mapping[str, frozenset[str]]-
Terminal states stay terminal. A platform move out of
completed,canceled, orrejected(an ad server reopening a finished order), or a move back to an earlier phase (active → pending_startwhen the flight start is pushed later), has no edge in AdCP 3.2 and is not in this graph;status.monotonicrejects a buyer-visible history that contains one. A seller that sees one should keep the status it reports to buyers on the published graph and track the platform state separately.
Functions
def assert_creative_transition(from_state: str, to_state: str, *, creative_id: str | None = None) ‑> None-
Expand source code
def assert_creative_transition( from_state: str, to_state: str, *, creative_id: str | None = None, ) -> None: """Raise ``INVALID_STATE`` on illegal creative-asset transitions. Use inside ``sync_creatives`` / creative-approval handlers to refuse non-monotonic state changes (e.g., ``archived`` → ``approved``). :param from_state: Current creative status. :param to_state: Requested next status. :param creative_id: Optional id, surfaced in ``error.details`` for buyer-side debugging. :raises AdcpError: with ``code='INVALID_STATE'`` and ``recovery='correctable'`` per the spec when the transition is not in :data:`CREATIVE_ASSET_TRANSITIONS`. """ _assert_transition( from_state, to_state, graph=CREATIVE_ASSET_TRANSITIONS, resource_kind="creative", resource_id=creative_id, id_field="creative_id", )Raise
INVALID_STATEon illegal creative-asset transitions.Use inside
sync_creatives/ creative-approval handlers to refuse non-monotonic state changes (e.g.,archived→approved).:param from_state: Current creative status. :param to_state: Requested next status. :param creative_id: Optional id, surfaced in
error.detailsfor buyer-side debugging. :raises AdcpError: withcode='INVALID_STATE'andrecovery='correctable'per the spec when the transition is not in :data:CREATIVE_ASSET_TRANSITIONS. def assert_media_buy_transition(from_state: str, to_state: str, *, media_buy_id: str | None = None) ‑> None-
Expand source code
def assert_media_buy_transition( from_state: str, to_state: str, *, media_buy_id: str | None = None, ) -> None: """Raise ``INVALID_STATE`` on illegal media-buy transitions. Use inside ``update_media_buy`` / ``cancel_media_buy`` / lifecycle-changing handlers to refuse non-monotonic state changes (e.g., ``active`` → ``pending_creatives``). :param from_state: Current media-buy status. :param to_state: Requested next status. :param media_buy_id: Optional id, surfaced in ``error.details`` for buyer-side debugging. :raises AdcpError: with ``code='INVALID_STATE'`` and ``recovery='correctable'`` per the spec when the transition is not in :data:`MEDIA_BUY_TRANSITIONS`. """ _assert_transition( from_state, to_state, graph=MEDIA_BUY_TRANSITIONS, resource_kind="media buy", resource_id=media_buy_id, id_field="media_buy_id", )Raise
INVALID_STATEon illegal media-buy transitions.Use inside
update_media_buy/cancel_media_buy/ lifecycle-changing handlers to refuse non-monotonic state changes (e.g.,active→pending_creatives).:param from_state: Current media-buy status. :param to_state: Requested next status. :param media_buy_id: Optional id, surfaced in
error.detailsfor buyer-side debugging. :raises AdcpError: withcode='INVALID_STATE'andrecovery='correctable'per the spec when the transition is not in :data:MEDIA_BUY_TRANSITIONS. def is_observable_media_buy_transition(from_state: str, to_state: str) ‑> bool-
Expand source code
def is_observable_media_buy_transition(from_state: str, to_state: str) -> bool: """Return whether a seller may record ``from_state → to_state``. Use when mirroring status from the seller's own platform, where the move already happened and refusing it with ``INVALID_STATE`` would only hide it. The check is against :data:`OBSERVED_MEDIA_BUY_TRANSITIONS`, which adds the AdCP 3.2 published edges that no buyer request produces (``pending_creatives → active``, ``pending_creatives → paused``, ``pending_start → paused``) to :data:`MEDIA_BUY_TRANSITIONS`. Returns ``False`` for an unknown status, for an unchanged status (not a transition), and for any move out of a terminal status. For a buyer's request, use :func:`assert_media_buy_transition` instead. :param from_state: Status the seller last recorded. :param to_state: Status the seller's platform now reports. """ return to_state in OBSERVED_MEDIA_BUY_TRANSITIONS.get(from_state, frozenset())Return whether a seller may record
from_state → to_state.Use when mirroring status from the seller's own platform, where the move already happened and refusing it with
INVALID_STATEwould only hide it. The check is against :data:OBSERVED_MEDIA_BUY_TRANSITIONS, which adds the AdCP 3.2 published edges that no buyer request produces (pending_creatives → active<code>, </code>pending_creatives → paused<code>, </code>pending_start → paused) to :data:MEDIA_BUY_TRANSITIONS.Returns
Falsefor an unknown status, for an unchanged status (not a transition), and for any move out of a terminal status. For a buyer's request, use :func:assert_media_buy_transition()instead.:param from_state: Status the seller last recorded. :param to_state: Status the seller's platform now reports.
def is_terminal_media_buy_status(status: str) ‑> bool-
Expand source code
def is_terminal_media_buy_status(status: str) -> bool: """Return whether ``status`` is a terminal media-buy status. An unknown status returns ``False`` rather than raising, so an adopter's internal pre-lifecycle statuses (``draft``, ``pending_approval``) are simply non-terminal. :param status: A media-buy status string or ``MediaBuyStatus`` member. """ return status in MEDIA_BUY_TERMINAL_STATUSESReturn whether
statusis a terminal media-buy status.An unknown status returns
Falserather than raising, so an adopter's internal pre-lifecycle statuses (draft,pending_approval) are simply non-terminal.:param status: A media-buy status string or
MediaBuyStatusmember.