Skip to content

adcp.types.CreativeAsset resolves to a different type at runtime than under mypy #1141

Closed

Description

@bokelley

Summary

In adcp==6.6.0, the public adcp.types.CreativeAsset symbol has incompatible runtime and static meanings. Runtime resolves it to the legacy CreativeAsset1 branch, while mypy resolves it to the generated CreativeAsset root union over CreativeAsset1 | CreativeAsset2.

This makes code that type-checks against the 3.1+ format_kind branch fail or become impossible when it uses the public runtime symbol.

Reproduction

Python 3.12, adcp==6.6.0:

from typing import get_args, get_origin
from adcp.types import CreativeAsset

print(CreativeAsset)
print(get_origin(CreativeAsset), get_args(CreativeAsset))

Runtime output:

<class 'adcp.types.generated_poc.core.creative_asset.CreativeAsset1'>
None ()

For the same import, mypy 2.3.1 reports:

Revealed type is "def (root: CreativeAsset1 | CreativeAsset2) -> CreativeAsset"

The generated module does define the root union, but _generated.py then deliberately replaces the public runtime binding for subclassing compatibility:

CreativeAssetUnion = CreativeAsset
CreativeAsset = CreativeAsset1  # type: ignore[misc,assignment]

Because the reassignment is ignored statically, the TYPE_CHECKING re-export and runtime lazy re-export disagree.

Impact

A downstream request DTO can subclass or construct CreativeAsset believing it represents both schema branches, while runtime actually fixes it to the legacy branch that requires format_id. The spec-legal format_kind branch is represented by CreativeAsset2 and is unavailable through that public name.

Expected

The public symbol should mean the same thing at runtime and under static analysis. Either:

  1. export the root union as CreativeAsset and give the concrete compatibility class a separate explicit name, or
  2. type CreativeAsset as CreativeAsset1 and document/use CreativeAssetUnion for the schema union.

SDK 7's canonical CreativeAsset plus explicit LegacyCreativeAsset surface provides a clearer migration seam, but the 6.6.0 mismatch should at least be documented and covered by a runtime/static alias regression test if a 6.x patch is not planned.

Affected version

  • Confirmed: 6.6.0
  • SDK 7 uses the canonical creative boundary for unqualified CreativeAsset; its explicit LegacyCreativeAsset imports the generated root model, so this exact mismatch does not appear to apply there.

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 11, 2026
  2. bokelley commented on Sep 11, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug (confirmed in 6.6.0; already fixed in current main)
    Bucket(s): client (public type export surface — no matching label in repo; noted here)
    Status: ready-to-implement
    Milestone: (omitted — fix already shipped in main; remaining work is test coverage)

    What the experts said:

    • code-reviewer: The specific CreativeAsset runtime/static split is gone in 8.0.0b14. _eager.py line 891 binds CreativeAsset = _canonical_creative.CreativeAsset — a straight assignment, no type: ignore, pointing to a concrete CanonicalBoundaryModel subclass built by _canonical_clone. No union, no rebind. However, _generated.py lines 3744–3753 still use the identical # type: ignore[misc,assignment] rebind for AuthorizedAgents (six-step chain) and Transport — producing the same static/runtime split for those names today.
    • dx-expert: (analysis pending; will update if material new information arrives)

    My take: The reported mismatch is fixed in current main via the canonical creative boundary (canonical_creative.py). The outstanding work is a regression test to prevent recurrence, plus a decision on AuthorizedAgents/Transport which exhibit the same footgun pattern. Both items are non-breaking.

    Implementation scope:

    • Add tests/test_creative_asset_regression.py:
      from adcp.types.canonical_creative import CanonicalBoundaryModel
      import adcp, adcp.types
      from pydantic import BaseModel
      
      def test_creative_asset_is_concrete_canonical_class() -> None:
          cls = adcp.types.CreativeAsset
          assert isinstance(cls, type), "CreativeAsset must be a class, not a union"
          assert issubclass(cls, CanonicalBoundaryModel)
          assert issubclass(cls, BaseModel)
          assert cls.__name__ == "CreativeAsset"
          assert cls is not adcp.types.LegacyCreativeAsset
          assert adcp.CreativeAsset is adcp.types.CreativeAsset
          assert "format_id" in cls.model_fields
          assert "format_kind" in cls.model_fields
          assert cls.model_fields["format_kind"].is_required()
    • Separately (or in the same PR if reviewer prefers): replace # type: ignore[misc,assignment] rebinds for AuthorizedAgents/Transport in _generated.py lines 3744–3753 with accurate TypeAlias annotations, or document why the static/runtime split is intentional for those names.
    • Required checks: pytest tests/test_creative_asset_regression.py, mypy src/, ruff check ., black --check .
    • Non-breaking rationale: test-only addition for primary scope; TypeAlias annotation changes are internal (_generated.py is not a public import path per CLAUDE.md).

    Note: a 6.x backport is out of scope — main is at 8.0.0b14 and the fix has been in place since SDK 7.

    Note: no client bucket label exists in this repo — flagging for maintainer to create if desired.


    Triaged by Claude Code. Session: https://claude.ai/code/session_01Rg7rwcYtZYMcNRsoGnePSa


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions