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_url for 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 True

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.

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 True

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.

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