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. Thecreate_media_buyrequest'scontextcomes back onmedia_buys[].context, and each package request'scontextonmedia_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:MediaBuyContextStoreand backfills them onget_media_buyswherever 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=Falseopts out.targeting_overlay, for sellers claiming theproperty-listsorcollection-listsspecialism, which must echo persistedproperty_list/collection_listreferences insidepackages[].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:
MediaBuyStorethe framework calls aroundcreate_media_buy,update_media_buyandget_media_buys.:param adopter_store: The
targeting_overlaypersistence + echo implementation. Must satisfy the :class:MediaBuyStoreProtocol — three methods (persist_from_create,merge_from_update,backfill) sync or async. Invoked only whencapabilities.specialismsintersects{property-lists, collection-lists}, and required then. Omit it when the seller claims neither:contextecho 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 mutatecapabilities.specialismsafter 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-levelcontextfromcreate_media_buyis persisted for theget_media_buysecho. Defaults to a fresh :class:InMemoryMediaBuyContextStore; pass :class:PgMediaBuyContextStorefor a durable, multi-worker echo. :param echo_context:Falsedisablescontextpersistence and echo, for a platform that persists and echoescontextitself. Acontextthe platform returns is never overwritten either way.:returns: A :class:
MediaBuyStorewrapper, always distinct fromadopter_storeso 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-listsorcollection-listsbut noadopter_storewas 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 foundProcess-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:PgMediaBuyContextStorein 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
contextaget_media_buysread echoes.Writes are first-wins: a
create_media_buyrequest'scontextis echoed unchanged for the life of the buy, so :meth:save_contextsnever replaces a stored object. It records the buy-levelcontextif none is stored yet and each packagecontextwhosepackage_idis 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
contextobjects acreate_media_buyrequest carried.:param context: The request's top-level
context, echoed onmedia_buys[].context.Nonewhen the request carried none. :param package_contexts: Each package request'scontext, keyed by the seller-assignedpackage_id, echoed onmedia_buys[].packages[].context.Both are opaque buyer data, stored and returned unchanged — including
nullvalues, key order and number spelling.Instance variables
var context : dict[str, typing.Any] | Nonevar 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_createrecords overlays from a successfulcreate_media_buy, joining the request's per-package overlay with the response's seller-assignedpackage_id(orbuyer_refwhen present). - :meth:
merge_from_updateappliesupdate_media_buypatches with deep-merge semantics: keys absent from the patch keep prior values, keys present with non-null values replace, keys present andNoneclear. - :meth:
backfillfills in missingpackages[].targeting_overlayon aget_media_buysresponse 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: ...
- :meth: