Module adcp.decisioning.media_buy_store

create_media_buy_store() — framework wiring for what get_media_buys must echo from create_media_buy.

AdCP 3.2 get_media_buys read surfaces echo two things a seller persisted at create time:

  • context, on every media buy and every package. The create_media_buy request's context comes back on media_buys[].context, and each package request's context on media_buys[].packages[].context, unchanged (schemas/cache/<v>/media-buy/get-media-buys-response.json, core/package.json: "echoed unchanged in responses, webhooks, and read surfaces"). This is a MUST for every seller, so it is on by default: the wrapper persists both levels into a :class:MediaBuyContextStore and backfills them on get_media_buys wherever the platform left them out. The default store is in-memory; pass :class:PgMediaBuyContextStore (or any :class:MediaBuyContextStore) so the echo survives restarts and spans workers. echo_context=False opts out.
  • targeting_overlay, for sellers claiming the property-lists or collection-lists specialism, which must echo persisted property_list / collection_list references inside packages[].targeting_overlay. The adopter supplies that persistence as a :class:MediaBuyStore; the wrapper delegates to it only for sellers claiming one of the two specialisms and never invokes it otherwise.

Mirrors the JS-side createMediaBuyStore from @adcp/sdk@6.7 (commit dda2a77e) with one shape change: the JS factory builds the overlay persistence itself on top of an AdcpStateStore. The Python SDK doesn't ship an AdcpStateStore Protocol, so adopters supply their own :class:MediaBuyStore for overlays; the SDK owns the context store.

Usage::

from adcp.decisioning import create_media_buy_store
from adcp.decisioning.pg import PgMediaBuyContextStore

platform.media_buy_store = create_media_buy_store(
    adopter_store,  # optional unless claiming property-/collection-lists
    capabilities=platform.capabilities,
    context_store=PgMediaBuyContextStore(pool=pool),
)

The wrapper is always a fresh object so adopters can reason about identity at the assignment site without aliasing surprises.

Functions

def create_media_buy_store(adopter_store: MediaBuyStore | None = None,
*,
capabilities: DecisioningCapabilities,
context_store: MediaBuyContextStore | None = None,
echo_context: bool = True) ‑> MediaBuyStore
Expand source code
def create_media_buy_store(
    adopter_store: MediaBuyStore | None = None,
    *,
    capabilities: DecisioningCapabilities,
    context_store: MediaBuyContextStore | None = None,
    echo_context: bool = True,
) -> MediaBuyStore:
    """Build the :class:`MediaBuyStore` the framework calls around
    ``create_media_buy``, ``update_media_buy`` and ``get_media_buys``.

    :param adopter_store: The ``targeting_overlay`` persistence + echo
        implementation. Must satisfy the :class:`MediaBuyStore` Protocol —
        three methods (``persist_from_create``, ``merge_from_update``,
        ``backfill``) sync or async. Invoked only when
        ``capabilities.specialisms`` intersects
        ``{property-lists, collection-lists}``, and required then. Omit it
        when the seller claims neither: ``context`` echo needs no adopter
        code.
    :param capabilities: The seller's :class:`DecisioningCapabilities`.
        Read once at construction to decide whether overlay calls delegate
        or no-op; not re-read per request, so adopters who mutate
        ``capabilities.specialisms`` after building the store won't see the
        change reflected. Build-time decision matches the boot-time
        validation pattern used elsewhere (``validate_platform``).
    :param context_store: Where buy- and package-level ``context`` from
        ``create_media_buy`` is persisted for the ``get_media_buys`` echo.
        Defaults to a fresh :class:`InMemoryMediaBuyContextStore`; pass
        :class:`adcp.decisioning.pg.PgMediaBuyContextStore` for a durable,
        multi-worker echo.
    :param echo_context: ``False`` disables ``context`` persistence and
        echo, for a platform that persists and echoes ``context`` itself.
        A ``context`` the platform returns is never overwritten either way.

    :returns: A :class:`MediaBuyStore` wrapper, always distinct from
        ``adopter_store`` so adopters can reason about identity at the
        assignment site (``platform.media_buy_store = ...``) without
        aliasing the underlying persistence layer.

    :raises ValueError: if the seller claims ``property-lists`` or
        ``collection-lists`` but no ``adopter_store`` was supplied.
    """
    # ``capabilities.specialisms`` is ``list[Specialism | str]`` per #479
    # — spec-known slugs are coerced to ``Specialism`` enum members at
    # construction; novel/typo slugs pass through as strings. Extract the
    # slug uniformly before set intersection.
    declared_slugs = {
        entry.value if hasattr(entry, "value") else entry for entry in capabilities.specialisms
    }
    claimed = declared_slugs & _OVERLAY_ECHO_SPECIALISMS
    if claimed and adopter_store is None:
        raise ValueError(
            f"create_media_buy_store: the seller claims {sorted(claimed)}, which "
            "requires an adopter MediaBuyStore to persist and echo "
            "targeting_overlay on get_media_buys"
        )
    contexts: MediaBuyContextStore | None = None
    if echo_context:
        contexts = context_store if context_store is not None else InMemoryMediaBuyContextStore()
    return _MediaBuyStoreWrapper(adopter_store, overlays=bool(claimed), contexts=contexts)

Build the :class:MediaBuyStore the framework calls around create_media_buy, update_media_buy and get_media_buys.

:param adopter_store: The targeting_overlay persistence + echo implementation. Must satisfy the :class:MediaBuyStore Protocol — three methods (persist_from_create, merge_from_update, backfill) sync or async. Invoked only when capabilities.specialisms intersects {property-lists, collection-lists}, and required then. Omit it when the seller claims neither: context echo needs no adopter code. :param capabilities: The seller's :class:DecisioningCapabilities. Read once at construction to decide whether overlay calls delegate or no-op; not re-read per request, so adopters who mutate capabilities.specialisms after building the store won't see the change reflected. Build-time decision matches the boot-time validation pattern used elsewhere (validate_platform). :param context_store: Where buy- and package-level context from create_media_buy is persisted for the get_media_buys echo. Defaults to a fresh :class:InMemoryMediaBuyContextStore; pass :class:PgMediaBuyContextStore for a durable, multi-worker echo. :param echo_context: False disables context persistence and echo, for a platform that persists and echoes context itself. A context the platform returns is never overwritten either way.

:returns: A :class:MediaBuyStore wrapper, always distinct from adopter_store so adopters can reason about identity at the assignment site (platform.media_buy_store = ...) without aliasing the underlying persistence layer.

:raises ValueError: if the seller claims property-lists or collection-lists but no adopter_store was supplied.

Classes

class InMemoryMediaBuyContextStore
Expand source code
class InMemoryMediaBuyContextStore:
    """Process-local :class:`MediaBuyContextStore`.

    The default for :func:`create_media_buy_store`. Records live as long as
    the process and are not shared across workers, so a restarted or
    load-balanced seller loses the echo for buys created elsewhere. Use
    :class:`adcp.decisioning.pg.PgMediaBuyContextStore` in production.
    """

    def __init__(self) -> None:
        self._records: dict[tuple[str, str], tuple[Any, dict[str, Any]]] = {}

    def save_contexts(self, account_id: str, media_buy_id: str, contexts: MediaBuyContexts) -> None:
        key = (account_id, media_buy_id)
        context, packages = self._records.get(key, (None, {}))
        if context is None and contexts.context is not None:
            context = deepcopy(contexts.context)
        for package_id, package_context in contexts.package_contexts.items():
            packages.setdefault(package_id, deepcopy(package_context))
        self._records[key] = (context, packages)

    def load_contexts(
        self, account_id: str, media_buy_ids: Sequence[str]
    ) -> dict[str, MediaBuyContexts]:
        found: dict[str, MediaBuyContexts] = {}
        for media_buy_id in media_buy_ids:
            record = self._records.get((account_id, media_buy_id))
            if record is not None:
                found[media_buy_id] = MediaBuyContexts(
                    context=deepcopy(record[0]), package_contexts=deepcopy(record[1])
                )
        return found

Process-local :class:MediaBuyContextStore.

The default for :func:create_media_buy_store(). Records live as long as the process and are not shared across workers, so a restarted or load-balanced seller loses the echo for buys created elsewhere. Use :class:PgMediaBuyContextStore in production.

Methods

def load_contexts(self, account_id: str, media_buy_ids: Sequence[str]) ‑> dict[str, MediaBuyContexts]
Expand source code
def load_contexts(
    self, account_id: str, media_buy_ids: Sequence[str]
) -> dict[str, MediaBuyContexts]:
    found: dict[str, MediaBuyContexts] = {}
    for media_buy_id in media_buy_ids:
        record = self._records.get((account_id, media_buy_id))
        if record is not None:
            found[media_buy_id] = MediaBuyContexts(
                context=deepcopy(record[0]), package_contexts=deepcopy(record[1])
            )
    return found
def save_contexts(self,
account_id: str,
media_buy_id: str,
contexts: MediaBuyContexts) ‑> None
Expand source code
def save_contexts(self, account_id: str, media_buy_id: str, contexts: MediaBuyContexts) -> None:
    key = (account_id, media_buy_id)
    context, packages = self._records.get(key, (None, {}))
    if context is None and contexts.context is not None:
        context = deepcopy(contexts.context)
    for package_id, package_context in contexts.package_contexts.items():
        packages.setdefault(package_id, deepcopy(package_context))
    self._records[key] = (context, packages)
class MediaBuyContextStore (*args, **kwargs)
Expand source code
@runtime_checkable
class MediaBuyContextStore(Protocol):
    """Persistence for the ``context`` a ``get_media_buys`` read echoes.

    Writes are first-wins: a ``create_media_buy`` request's ``context`` is
    echoed unchanged for the life of the buy, so :meth:`save_contexts` never
    replaces a stored object. It records the buy-level ``context`` if none is
    stored yet and each package ``context`` whose ``package_id`` is new, which
    makes an idempotent create replay harmless.

    Every read and write is scoped by ``account_id``; a store MUST NOT return
    another account's record. Methods may be sync or async.

    Shipped implementations: :class:`InMemoryMediaBuyContextStore` (the
    default, process-local) and
    :class:`adcp.decisioning.pg.PgMediaBuyContextStore` (durable).
    """

    def save_contexts(
        self,
        account_id: str,
        media_buy_id: str,
        contexts: MediaBuyContexts,
    ) -> Any: ...

    def load_contexts(
        self,
        account_id: str,
        media_buy_ids: Sequence[str],
    ) -> Any:
        """Return ``{media_buy_id: MediaBuyContexts}`` for the stored ids."""
        ...

Persistence for the context a get_media_buys read echoes.

Writes are first-wins: a create_media_buy request's context is echoed unchanged for the life of the buy, so :meth:save_contexts never replaces a stored object. It records the buy-level context if none is stored yet and each package context whose package_id is new, which makes an idempotent create replay harmless.

Every read and write is scoped by account_id; a store MUST NOT return another account's record. Methods may be sync or async.

Shipped implementations: :class:InMemoryMediaBuyContextStore (the default, process-local) and :class:PgMediaBuyContextStore (durable).

Ancestors

  • typing.Protocol
  • typing.Generic

Methods

def load_contexts(self, account_id: str, media_buy_ids: Sequence[str]) ‑> Any
Expand source code
def load_contexts(
    self,
    account_id: str,
    media_buy_ids: Sequence[str],
) -> Any:
    """Return ``{media_buy_id: MediaBuyContexts}`` for the stored ids."""
    ...

Return {media_buy_id: MediaBuyContexts} for the stored ids.

def save_contexts(self,
account_id: str,
media_buy_id: str,
contexts: MediaBuyContexts) ‑> Any
Expand source code
def save_contexts(
    self,
    account_id: str,
    media_buy_id: str,
    contexts: MediaBuyContexts,
) -> Any: ...
class MediaBuyContexts (context: dict[str, Any] | None = None,
package_contexts: Mapping[str, dict[str, Any]] = <factory>)
Expand source code
@dataclass(frozen=True)
class MediaBuyContexts:
    """The buyer ``context`` objects a ``create_media_buy`` request carried.

    :param context: The request's top-level ``context``, echoed on
        ``media_buys[].context``. ``None`` when the request carried none.
    :param package_contexts: Each package request's ``context``, keyed by
        the seller-assigned ``package_id``, echoed on
        ``media_buys[].packages[].context``.

    Both are opaque buyer data, stored and returned unchanged — including
    ``null`` values, key order and number spelling.
    """

    context: dict[str, Any] | None = None
    package_contexts: Mapping[str, dict[str, Any]] = field(default_factory=dict)

The buyer context objects a create_media_buy request carried.

:param context: The request's top-level context, echoed on media_buys[].context. None when the request carried none. :param package_contexts: Each package request's context, keyed by the seller-assigned package_id, echoed on media_buys[].packages[].context.

Both are opaque buyer data, stored and returned unchanged — including null values, key order and number spelling.

Instance variables

var context : dict[str, typing.Any] | None
var package_contexts : Mapping[str, dict[str, typing.Any]]
class MediaBuyStore (*args, **kwargs)
Expand source code
@runtime_checkable
class MediaBuyStore(Protocol):
    """Adopter-supplied persistence + echo for ``targeting_overlay``.

    Three methods cover the full lifecycle of a per-package overlay:

    * :meth:`persist_from_create` records overlays from a successful
      ``create_media_buy``, joining the request's per-package overlay
      with the response's seller-assigned ``package_id`` (or
      ``buyer_ref`` when present).
    * :meth:`merge_from_update` applies ``update_media_buy`` patches
      with deep-merge semantics: keys absent from the patch keep prior
      values, keys present with non-null values replace, keys present
      and ``None`` clear.
    * :meth:`backfill` fills in missing
      ``packages[].targeting_overlay`` on a ``get_media_buys`` response
      from the persisted store. Mutates the response in place; packages
      the seller already echoed are left untouched.

    Methods may be sync or async — the wrapper awaits at call time.
    """

    def persist_from_create(
        self,
        account_id: str,
        request: Any,
        result: Any,
    ) -> Any: ...

    def merge_from_update(
        self,
        account_id: str,
        media_buy_id: str,
        patch: Any,
    ) -> Any: ...

    def backfill(self, account_id: str, result: Any) -> Any: ...

Adopter-supplied persistence + echo for targeting_overlay.

Three methods cover the full lifecycle of a per-package overlay:

  • :meth:persist_from_create records overlays from a successful create_media_buy, joining the request's per-package overlay with the response's seller-assigned package_id (or buyer_ref when present).
  • :meth:merge_from_update applies update_media_buy patches with deep-merge semantics: keys absent from the patch keep prior values, keys present with non-null values replace, keys present and None clear.
  • :meth:backfill fills in missing packages[].targeting_overlay on a get_media_buys response from the persisted store. Mutates the response in place; packages the seller already echoed are left untouched.

Methods may be sync or async — the wrapper awaits at call time.

Ancestors

  • typing.Protocol
  • typing.Generic

Methods

def backfill(self, account_id: str, result: Any) ‑> Any
Expand source code
def backfill(self, account_id: str, result: Any) -> Any: ...
def merge_from_update(self, account_id: str, media_buy_id: str, patch: Any) ‑> Any
Expand source code
def merge_from_update(
    self,
    account_id: str,
    media_buy_id: str,
    patch: Any,
) -> Any: ...
def persist_from_create(self, account_id: str, request: Any, result: Any) ‑> Any
Expand source code
def persist_from_create(
    self,
    account_id: str,
    request: Any,
    result: Any,
) -> Any: ...