Module adcp.canonical_formats.fixtures

Public access to the vendored canonical-formats reference fixtures.

The SDK ships 14 v2 Product fixtures and a 50-entry v1 reference catalog vendored from adcontextprotocol/adcp upstream. They drive the SDK's own round-trip tests (see tests/test_canonical_formats_roundtrip.py); adopters writing their own canonical-formats consumers can reuse them via this module rather than re-vendoring.

Two access shapes:

• :func:load_reference_product()(name) returns one v2 product fixture as a parsed dict[str, Any].
• :func:load_v1_reference_catalog() returns the 50-entry v1 catalog as a list[dict[str, Any]].

The helper :data:REFERENCE_PRODUCT_NAMES lists every available fixture name so adopters can iterate without hardcoding.

Provenance + refresh procedure are documented at tests/fixtures/canonical/VENDOR.md in this repo.

Functions

def load_reference_product(name: str) ‑> dict[str, typing.Any]

Expand source code

def load_reference_product(name: str) -> dict[str, Any]:
    """Return one of the 14 vendored v2 ``Product`` fixtures.

    Args:
        name: One of :data:`REFERENCE_PRODUCT_NAMES`. The ``.json``
            suffix is optional — callers can pass either
            ``"meta_reels_us"`` or ``"meta_reels_us.json"``.

    Returns:
        The parsed product as a ``dict[str, Any]``. Returned object
        is cached; callers MUST NOT mutate it. ``copy.deepcopy`` if
        you need a writable copy.

    Raises:
        _UnknownFixtureError: when ``name`` isn't a known fixture.
    """
    stem = name.removesuffix(".json")
    if stem not in REFERENCE_PRODUCT_NAMES:
        raise _UnknownFixtureError(
            f"{name!r} is not a known reference product fixture; "
            f"valid names: {REFERENCE_PRODUCT_NAMES!r}"
        )
    return _load_by_stem(stem)

Return one of the 14 vendored v2 Product fixtures.

Args

name

One of :data:REFERENCE_PRODUCT_NAMES. The .json suffix is optional — callers can pass either "meta_reels_us" or "meta_reels_us.json".

Returns

The parsed product as a dict[str, Any]. Returned object is cached; callers MUST NOT mutate it. copy.deepcopy if you need a writable copy.

Raises

_UnknownFixtureError

when name isn't a known fixture.

def load_v1_reference_catalog() ‑> list[dict[str, typing.Any]]

Expand source code

@lru_cache(maxsize=1)
def load_v1_reference_catalog() -> list[dict[str, Any]]:
    """Return the 50-entry v1 reference catalog.

    Every entry carries an explicit ``canonical:`` annotation so the
    SDK's v1 → v2 projection
    (:func:`adcp.canonical_formats.project_v1_format_to_declaration`)
    walks resolution-order step 1 on every entry. Useful for adopter
    tests covering catalog migration flows.

    Returned list is cached; callers MUST NOT mutate it.
    ``copy.deepcopy`` if you need a writable copy.
    """
    raw = json.loads(_fixture_text(_V1_CATALOG_NAME))
    if not isinstance(raw, list):
        # The vendored fixture is a JSON array. Wrap a single-object
        # input defensively so a future vendoring mistake fails fast
        # rather than silently confusing callers.
        return [raw]
    catalog: list[dict[str, Any]] = raw
    return catalog

Return the 50-entry v1 reference catalog.

Every entry carries an explicit canonical: annotation so the SDK's v1 → v2 projection (:func:project_v1_format_to_declaration()) walks resolution-order step 1 on every entry. Useful for adopter tests covering catalog migration flows.

Returned list is cached; callers MUST NOT mutate it. copy.deepcopy if you need a writable copy.