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 legal to_state values. 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.2 docs/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_TRANSITIONS for 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, or rejected (an ad server reopening a finished order), or a move back to an earlier phase (active → pending_start when the flight start is pushed later), has no edge in AdCP 3.2 and is not in this graph; status.monotonic rejects 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_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.

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_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.

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_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<code>, </code>pending_creatives → paused<code>, </code>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.

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_STATUSES

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.