Module adcp.canonical_formats.compat_helpers
Compatibility helpers for legacy and parameterized creative format IDs.
These helpers cover the common migration case where older buyers or catalogs
refer to a named format such as display_300x250 while newer schema surfaces
carry the canonical template display_image plus explicit dimensions.
Global variables
var CANONICAL_CREATIVE_AGENT_URL-
Default
agent_urlfor AdCP standard creative formats.
Functions
def format_is_supported(requested: FormatIdInput,
supported: FormatIdInput,
*,
default_agent_url: str = 'https://creative.adcontextprotocol.org') ‑> bool-
Expand source code
def format_is_supported( requested: FormatIdInput, supported: FormatIdInput, *, default_agent_url: str = CANONICAL_CREATIVE_AGENT_URL, ) -> bool: """Return true when ``requested`` is acceptable for ``supported``. This is intentionally stricter than :func:`formats_are_equivalent`. A broad supported format such as ``display_image`` accepts a specific request such as ``display_image`` 300x250, but a fixed supported product format requires the request to provide and match every parameter the supported side fixes — every parameter ``core/format-id.json`` declares, not a chosen few. ``pixel_ratio`` is the one parameter whose absence carries a value rather than meaning "unspecified": the schema describes omitting it as selecting the backward-compatible 1x variant. That reading applies to both sides of a dimensioned reference: a product fixed at 2x refuses a request that omits the field, a product that omits it (so is 1x) refuses a 2x request, and a product fixed at 1x accepts a request that omits it. """ req = _upgrade_legacy_format_id( requested, default_agent_url=default_agent_url, param="requested" ) sup = _upgrade_legacy_format_id( supported, default_agent_url=default_agent_url, param="supported" ) if not formats_are_equivalent(req, sup, default_agent_url=default_agent_url): return False for field in _PARAMETER_FIELDS: supported_value = _parameter_value(sup, field) if supported_value is None: continue if _parameter_value(req, field) != supported_value: return False return TrueReturn true when
requestedis acceptable forsupported.This is intentionally stricter than :func:
formats_are_equivalent(). A broad supported format such asdisplay_imageaccepts a specific request such asdisplay_image300x250, but a fixed supported product format requires the request to provide and match every parameter the supported side fixes — every parametercore/format-id.jsondeclares, not a chosen few.pixel_ratiois the one parameter whose absence carries a value rather than meaning "unspecified": the schema describes omitting it as selecting the backward-compatible 1x variant. That reading applies to both sides of a dimensioned reference: a product fixed at 2x refuses a request that omits the field, a product that omits it (so is 1x) refuses a 2x request, and a product fixed at 1x accepts a request that omits it. def formats_are_equivalent(a: FormatIdInput,
b: FormatIdInput,
*,
default_agent_url: str = 'https://creative.adcontextprotocol.org') ‑> bool-
Expand source code
def formats_are_equivalent( a: FormatIdInput, b: FormatIdInput, *, default_agent_url: str = CANONICAL_CREATIVE_AGENT_URL, ) -> bool: """Return true when two format IDs identify the same canonical family. Both inputs are first passed through :func:`upgrade_legacy_format_id`. Declared parameters must not conflict, but an omitted width, height or duration on either side is treated as unspecified rather than a mismatch: omitting them names the template, which covers every variant. An omitted ``pixel_ratio`` on a sized reference is not unspecified — it names the 1x variant — so 300x250 and 300x250 at 2x are different formats here too. Use :func:`format_is_supported` for product/capability gating, where a supported fixed size, duration or pixel density requires the request to state that value. """ left = _upgrade_legacy_format_id(a, default_agent_url=default_agent_url, param="a") right = _upgrade_legacy_format_id(b, default_agent_url=default_agent_url, param="b") if canonicalize_agent_url(left.agent_url) != canonicalize_agent_url(right.agent_url): return False if left.id != right.id: return False for field in _PARAMETER_FIELDS: left_value = _parameter_value(left, field) right_value = _parameter_value(right, field) if left_value is not None and right_value is not None and left_value != right_value: return False return TrueReturn true when two format IDs identify the same canonical family.
Both inputs are first passed through :func:
upgrade_legacy_format_id(). Declared parameters must not conflict, but an omitted width, height or duration on either side is treated as unspecified rather than a mismatch: omitting them names the template, which covers every variant. An omittedpixel_ratioon a sized reference is not unspecified — it names the 1x variant — so 300x250 and 300x250 at 2x are different formats here too. Use :func:format_is_supported()for product/capability gating, where a supported fixed size, duration or pixel density requires the request to state that value. def upgrade_legacy_format_id(value: FormatIdInput,
*,
default_agent_url: str = 'https://creative.adcontextprotocol.org') ‑> FormatReferenceStructuredObject-
Expand source code
def upgrade_legacy_format_id( value: FormatIdInput, *, default_agent_url: str = CANONICAL_CREATIVE_AGENT_URL, ) -> FormatId: """Return ``value`` as a canonical, parameterized ``FormatId`` when known. The current canonical upgrade maps legacy display size IDs such as ``display_300x250`` and ``display_300x250_image`` to ``display_image`` with ``width=300`` and ``height=250``. Unknown IDs are still returned as structured ``FormatId`` values so callers can compare them consistently. """ return _upgrade_legacy_format_id(value, default_agent_url=default_agent_url, param="value")Return
valueas a canonical, parameterizedFormatIdwhen known.The current canonical upgrade maps legacy display size IDs such as
display_300x250anddisplay_300x250_imagetodisplay_imagewithwidth=300andheight=250. Unknown IDs are still returned as structuredFormatIdvalues so callers can compare them consistently.