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 fixed parameter
    (``width``, ``height``, and ``duration_ms``).
    """
    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 ("width", "height", "duration_ms"):
        supported_value = getattr(sup, field)
        if supported_value is None:
            continue
        if getattr(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 fixed parameter (width, height, and duration_ms).

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 parameter on either
    side is treated as unspecified rather than a mismatch. Use
    :func:`format_is_supported` for product/capability gating where a
    supported fixed size or duration 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 ("width", "height", "duration_ms"):
        left_value = getattr(left, field)
        right_value = getattr(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 parameter on either side is treated as unspecified rather than a mismatch. Use :func:format_is_supported() for product/capability gating where a supported fixed size or duration 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.