adcp 2.14.0__tar.gz → 2.15.0__tar.gz

{adcp-2.14.0/src/adcp.egg-info → adcp-2.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 2.14.0
+Version: 2.15.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0

{adcp-2.14.0 → adcp-2.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "2.14.0"
+version = "2.15.0"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}

{adcp-2.14.0 → adcp-2.15.0}/src/adcp/__init__.py

@@ -186,7 +186,7 @@ from adcp.webhooks import (
     get_adcp_signed_headers_for_webhook,
 )
 
-__version__ = "2.14.0"
+__version__ = "2.15.0"
 
 
 def get_adcp_version() -> str:

{adcp-2.14.0 → adcp-2.15.0}/src/adcp/types/__init__.py

@@ -6,13 +6,33 @@ Users should import from here or directly from adcp.
 Examples:
     from adcp.types import Product, CreativeFilters
     from adcp import Product, CreativeFilters
+
+Type Coercion:
+    For developer ergonomics, request types accept flexible input:
+
+    - Enum fields accept string values:
+        ListCreativeFormatsRequest(type="video")  # Works!
+        ListCreativeFormatsRequest(type=FormatCategory.video)  # Also works
+
+    - Context fields accept dicts:
+        GetProductsRequest(context={"key": "value"})  # Works!
+
+    - FieldModel lists accept strings:
+        ListCreativesRequest(fields=["creative_id", "name"])  # Works!
+
+    See adcp.types.coercion for implementation details.
 """
 
 from __future__ import annotations
 
+# Apply type coercion to generated types (must be imported before other types)
+from adcp.types import (
+    _ergonomic,  # noqa: F401
+    aliases,  # noqa: F401
+)
+
 # Also make submodules available for advanced use
 from adcp.types import _generated as generated  # noqa: F401
-from adcp.types import aliases  # noqa: F401
 
 # Import all types from generated code
 from adcp.types._generated import (

adcp-2.15.0/src/adcp/types/_ergonomic.py

@@ -0,0 +1,279 @@
+# AUTO-GENERATED by scripts/generate_ergonomic_coercion.py
+# Do not edit manually - changes will be overwritten on next type generation.
+# To regenerate: python scripts/generate_types.py
+"""Apply type coercion to generated types for better ergonomics.
+
+This module patches the generated types to accept more flexible input types
+while maintaining type safety. It uses Pydantic's model_rebuild() to add
+BeforeValidator annotations to fields.
+
+Why import-time patching?
+    We apply coercion at module load time rather than lazily because:
+    1. Pydantic validation runs during __init__, before any lazy access
+    2. model_rebuild() is the standard Pydantic pattern for post-hoc changes
+    3. The cost is minimal (~10-20ms for all types, once at import)
+    4. After import, there is zero runtime overhead
+    5. This approach maintains full type checker compatibility
+
+Coercion rules applied:
+1. Enum fields accept string values (e.g., "video" for FormatCategory.video)
+2. List[Enum] fields accept list of strings (e.g., ["image", "video"])
+3. ContextObject fields accept dict values
+4. ExtensionObject fields accept dict values
+5. FieldModel (enum) lists accept string lists
+
+Note: List variance issues (list[Subclass] not assignable to list[BaseClass])
+are a fundamental Python typing limitation. Users extending library types
+should use Sequence[T] in their own code or cast() for type checker appeasement.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import BeforeValidator
+
+from adcp.types.coercion import (
+    coerce_subclass_list,
+    coerce_to_enum,
+    coerce_to_enum_list,
+    coerce_to_model,
+)
+
+# Import types that need coercion
+from adcp.types.generated_poc.core.context import ContextObject
+from adcp.types.generated_poc.core.creative_asset import CreativeAsset
+from adcp.types.generated_poc.core.creative_assignment import CreativeAssignment
+from adcp.types.generated_poc.core.ext import ExtensionObject
+from adcp.types.generated_poc.enums.asset_content_type import AssetContentType
+from adcp.types.generated_poc.enums.creative_sort_field import CreativeSortField
+from adcp.types.generated_poc.enums.format_category import FormatCategory
+from adcp.types.generated_poc.enums.pacing import Pacing
+from adcp.types.generated_poc.enums.sort_direction import SortDirection
+from adcp.types.generated_poc.media_buy.create_media_buy_request import (
+    CreateMediaBuyRequest,
+)
+from adcp.types.generated_poc.media_buy.get_products_request import GetProductsRequest
+from adcp.types.generated_poc.media_buy.list_creative_formats_request import (
+    ListCreativeFormatsRequest,
+)
+from adcp.types.generated_poc.media_buy.list_creatives_request import (
+    FieldModel,
+    ListCreativesRequest,
+    Sort,
+)
+from adcp.types.generated_poc.media_buy.package_request import PackageRequest
+from adcp.types.generated_poc.media_buy.update_media_buy_request import (
+    Packages,
+    Packages1,
+)
+
+
+def _apply_coercion() -> None:
+    """Apply coercion validators to generated types.
+
+    This function modifies the generated types in-place to accept
+    more flexible input types.
+    """
+    # Apply coercion to ListCreativeFormatsRequest
+    # - asset_types: list[AssetContentType | str] | None
+    # - context: ContextObject | dict | None
+    # - ext: ExtensionObject | dict | None
+    # - type: FormatCategory | str | None
+    _patch_field_annotation(
+        ListCreativeFormatsRequest,
+        "asset_types",
+        Annotated[
+            list[AssetContentType] | None,
+            BeforeValidator(coerce_to_enum_list(AssetContentType)),
+        ],
+    )
+    _patch_field_annotation(
+        ListCreativeFormatsRequest,
+        "context",
+        Annotated[ContextObject | None, BeforeValidator(coerce_to_model(ContextObject))],
+    )
+    _patch_field_annotation(
+        ListCreativeFormatsRequest,
+        "ext",
+        Annotated[ExtensionObject | None, BeforeValidator(coerce_to_model(ExtensionObject))],
+    )
+    _patch_field_annotation(
+        ListCreativeFormatsRequest,
+        "type",
+        Annotated[FormatCategory | None, BeforeValidator(coerce_to_enum(FormatCategory))],
+    )
+    ListCreativeFormatsRequest.model_rebuild(force=True)
+
+    # Apply coercion to ListCreativesRequest
+    # - context: ContextObject | dict | None
+    # - ext: ExtensionObject | dict | None
+    # - fields: list[FieldModel | str] | None
+    _patch_field_annotation(
+        ListCreativesRequest,
+        "context",
+        Annotated[ContextObject | None, BeforeValidator(coerce_to_model(ContextObject))],
+    )
+    _patch_field_annotation(
+        ListCreativesRequest,
+        "ext",
+        Annotated[ExtensionObject | None, BeforeValidator(coerce_to_model(ExtensionObject))],
+    )
+    _patch_field_annotation(
+        ListCreativesRequest,
+        "fields",
+        Annotated[
+            list[FieldModel] | None,
+            BeforeValidator(coerce_to_enum_list(FieldModel)),
+        ],
+    )
+    ListCreativesRequest.model_rebuild(force=True)
+
+    # Apply coercion to Sort
+    # - direction: SortDirection | str | None
+    # - field: CreativeSortField | str | None
+    _patch_field_annotation(
+        Sort,
+        "direction",
+        Annotated[SortDirection | None, BeforeValidator(coerce_to_enum(SortDirection))],
+    )
+    _patch_field_annotation(
+        Sort,
+        "field",
+        Annotated[CreativeSortField | None, BeforeValidator(coerce_to_enum(CreativeSortField))],
+    )
+    Sort.model_rebuild(force=True)
+
+    # Apply coercion to GetProductsRequest
+    # - context: ContextObject | dict | None
+    # - ext: ExtensionObject | dict | None
+    _patch_field_annotation(
+        GetProductsRequest,
+        "context",
+        Annotated[ContextObject | None, BeforeValidator(coerce_to_model(ContextObject))],
+    )
+    _patch_field_annotation(
+        GetProductsRequest,
+        "ext",
+        Annotated[ExtensionObject | None, BeforeValidator(coerce_to_model(ExtensionObject))],
+    )
+    GetProductsRequest.model_rebuild(force=True)
+
+    # Apply coercion to PackageRequest
+    # - creatives: list[CreativeAsset] (accepts subclass instances)
+    # - ext: ExtensionObject | dict | None
+    # - pacing: Pacing | str | None
+    _patch_field_annotation(
+        PackageRequest,
+        "creatives",
+        Annotated[
+            list[CreativeAsset] | None,
+            BeforeValidator(coerce_subclass_list(CreativeAsset)),
+        ],
+    )
+    _patch_field_annotation(
+        PackageRequest,
+        "ext",
+        Annotated[ExtensionObject | None, BeforeValidator(coerce_to_model(ExtensionObject))],
+    )
+    _patch_field_annotation(
+        PackageRequest,
+        "pacing",
+        Annotated[Pacing | None, BeforeValidator(coerce_to_enum(Pacing))],
+    )
+    PackageRequest.model_rebuild(force=True)
+
+    # Apply coercion to CreateMediaBuyRequest
+    # - context: ContextObject | dict | None
+    # - ext: ExtensionObject | dict | None
+    # - packages: list[PackageRequest] (accepts subclass instances)
+    _patch_field_annotation(
+        CreateMediaBuyRequest,
+        "context",
+        Annotated[ContextObject | None, BeforeValidator(coerce_to_model(ContextObject))],
+    )
+    _patch_field_annotation(
+        CreateMediaBuyRequest,
+        "ext",
+        Annotated[ExtensionObject | None, BeforeValidator(coerce_to_model(ExtensionObject))],
+    )
+    _patch_field_annotation(
+        CreateMediaBuyRequest,
+        "packages",
+        Annotated[
+            list[PackageRequest],
+            BeforeValidator(coerce_subclass_list(PackageRequest)),
+        ],
+    )
+    CreateMediaBuyRequest.model_rebuild(force=True)
+
+    # Apply coercion to Packages
+    # - creative_assignments: list[CreativeAssignment] (accepts subclass instances)
+    # - creatives: list[CreativeAsset] (accepts subclass instances)
+    # - pacing: Pacing | str | None
+    _patch_field_annotation(
+        Packages,
+        "creative_assignments",
+        Annotated[
+            list[CreativeAssignment] | None,
+            BeforeValidator(coerce_subclass_list(CreativeAssignment)),
+        ],
+    )
+    _patch_field_annotation(
+        Packages,
+        "creatives",
+        Annotated[
+            list[CreativeAsset] | None,
+            BeforeValidator(coerce_subclass_list(CreativeAsset)),
+        ],
+    )
+    _patch_field_annotation(
+        Packages,
+        "pacing",
+        Annotated[Pacing | None, BeforeValidator(coerce_to_enum(Pacing))],
+    )
+    Packages.model_rebuild(force=True)
+
+    # Apply coercion to Packages1
+    # - creative_assignments: list[CreativeAssignment] (accepts subclass instances)
+    # - creatives: list[CreativeAsset] (accepts subclass instances)
+    # - pacing: Pacing | str | None
+    _patch_field_annotation(
+        Packages1,
+        "creative_assignments",
+        Annotated[
+            list[CreativeAssignment] | None,
+            BeforeValidator(coerce_subclass_list(CreativeAssignment)),
+        ],
+    )
+    _patch_field_annotation(
+        Packages1,
+        "creatives",
+        Annotated[
+            list[CreativeAsset] | None,
+            BeforeValidator(coerce_subclass_list(CreativeAsset)),
+        ],
+    )
+    _patch_field_annotation(
+        Packages1,
+        "pacing",
+        Annotated[Pacing | None, BeforeValidator(coerce_to_enum(Pacing))],
+    )
+    Packages1.model_rebuild(force=True)
+
+
+def _patch_field_annotation(
+    model: type,
+    field_name: str,
+    new_annotation: Any,
+) -> None:
+    """Patch a field annotation on a Pydantic model.
+
+    This modifies the model's __annotations__ dict to add
+    BeforeValidator coercion.
+    """
+    model.__annotations__[field_name] = new_annotation
+
+
+# Apply coercion when module is imported
+_apply_coercion()

adcp-2.15.0/src/adcp/types/coercion.py

@@ -0,0 +1,194 @@
+"""Type coercion utilities for improved type ergonomics.
+
+This module provides validators and utilities that enable flexible input types
+while maintaining type safety. It allows developers to use natural Python
+patterns (strings for enums, dicts for models) without explicit type construction.
+
+Examples:
+    # With coercion, these are equivalent:
+    ListCreativeFormatsRequest(type="video")
+    ListCreativeFormatsRequest(type=FormatCategory.video)
+
+    # Dict coercion for context:
+    ListCreativeFormatsRequest(context={"key": "value"})
+    ListCreativeFormatsRequest(context=ContextObject(key="value"))
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from enum import Enum
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+T = TypeVar("T", bound=Enum)
+M = TypeVar("M", bound="BaseModel")
+
+
+def coerce_to_enum(enum_class: type[T]) -> Callable[[Any], T | None]:
+    """Create a validator that coerces strings to enum values.
+
+    This allows users to pass string values where enums are expected,
+    which Pydantic will coerce at runtime anyway, but this makes it
+    type-checker friendly.
+
+    Args:
+        enum_class: The enum class to coerce to.
+
+    Returns:
+        A validator function for use with Pydantic's BeforeValidator.
+
+    Example:
+        ```python
+        from pydantic import BeforeValidator
+        from typing import Annotated
+
+        type: Annotated[
+            FormatCategory | None,
+            BeforeValidator(coerce_to_enum(FormatCategory))
+        ] = None
+        ```
+    """
+
+    def validator(value: Any) -> T | None:
+        if value is None:
+            return None
+        if isinstance(value, enum_class):
+            return value
+        if isinstance(value, str):
+            try:
+                return enum_class(value)
+            except ValueError:
+                # Let Pydantic handle the validation error
+                return value  # type: ignore
+        return value  # type: ignore
+
+    return validator
+
+
+def coerce_to_enum_list(enum_class: type[T]) -> Callable[[Any], list[T] | None]:
+    """Create a validator that coerces a list of strings to enum values.
+
+    Args:
+        enum_class: The enum class to coerce to.
+
+    Returns:
+        A validator function for use with Pydantic's BeforeValidator.
+    """
+
+    def validator(value: Any) -> list[T] | None:
+        if value is None:
+            return None
+        if not isinstance(value, (list, tuple)):
+            return value  # type: ignore
+        result: list[T] = []
+        for item in value:
+            if isinstance(item, enum_class):
+                result.append(item)
+            elif isinstance(item, str):
+                try:
+                    result.append(enum_class(item))
+                except ValueError:
+                    # Let Pydantic handle the validation error
+                    result.append(item)  # type: ignore
+            else:
+                result.append(item)
+        return result
+
+    return validator
+
+
+def coerce_to_model(model_class: type[M]) -> Callable[[Any], M | None]:
+    """Create a validator that coerces dicts to Pydantic model instances.
+
+    This allows users to pass dict values where model objects are expected,
+    making the API more ergonomic.
+
+    Args:
+        model_class: The Pydantic model class to coerce to.
+
+    Returns:
+        A validator function for use with Pydantic's BeforeValidator.
+
+    Example:
+        ```python
+        from pydantic import BeforeValidator
+        from typing import Annotated
+
+        context: Annotated[
+            ContextObject | None,
+            BeforeValidator(coerce_to_model(ContextObject))
+        ] = None
+        ```
+    """
+
+    def validator(value: Any) -> M | None:
+        if value is None:
+            return None
+        if isinstance(value, model_class):
+            return value
+        if isinstance(value, dict):
+            return model_class(**value)
+        return value  # type: ignore
+
+    return validator
+
+
+def coerce_subclass_list(base_class: type[M]) -> Callable[[Any], list[M] | None]:
+    """Create a validator that accepts lists containing subclass instances.
+
+    This addresses Python's list invariance limitation where `list[Subclass]`
+    cannot be assigned to `list[BaseClass]` despite being type-safe at runtime.
+
+    The validator:
+    1. Accepts Any as input (satisfies mypy for subclass lists)
+    2. Validates each item is an instance of base_class (or subclass)
+    3. Returns list[base_class] (satisfies the field type)
+
+    Args:
+        base_class: The base Pydantic model class for list items.
+
+    Returns:
+        A validator function for use with Pydantic's BeforeValidator.
+
+    Example:
+        ```python
+        class ExtendedCreative(CreativeAsset):
+            internal_id: str = Field(exclude=True)
+
+        # Without coercion: requires cast()
+        # PackageRequest(creatives=cast(list[CreativeAsset], [extended]))
+
+        # With coercion: just works
+        PackageRequest(creatives=[extended])  # No cast needed!
+        ```
+    """
+
+    def validator(value: Any) -> list[M] | None:
+        if value is None:
+            return None
+        if not isinstance(value, (list, tuple)):
+            return value  # type: ignore
+        # Return the list as-is - Pydantic will validate each item
+        # is an instance of base_class (including subclasses)
+        return list(value)
+
+    return validator
+
+
+# =============================================================================
+# List Variance Notes
+# =============================================================================
+#
+# The coerce_subclass_list validator above handles the common case of passing
+# `list[Subclass]` to a field expecting `list[BaseClass]` when constructing
+# request models.
+#
+# For function signatures in your own code, use Sequence[T] which is covariant:
+#
+#     from collections.abc import Sequence
+#     def process_creatives(creatives: Sequence[CreativeAsset]) -> None:
+#         ...  # Accepts list[ExtendedCreative] without cast()
+#

{adcp-2.14.0 → adcp-2.15.0/src/adcp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 2.14.0
+Version: 2.15.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0

{adcp-2.14.0 → adcp-2.15.0}/src/adcp.egg-info/SOURCES.txt

@@ -26,9 +26,11 @@ src/adcp/protocols/mcp.py
 src/adcp/testing/__init__.py
 src/adcp/testing/test_helpers.py
 src/adcp/types/__init__.py
+src/adcp/types/_ergonomic.py
 src/adcp/types/_generated.py
 src/adcp/types/aliases.py
 src/adcp/types/base.py
+src/adcp/types/coercion.py
 src/adcp/types/core.py
 src/adcp/types/generated_poc/__init__.py
 src/adcp/types/generated_poc/adagents.py
@@ -208,4 +210,5 @@ tests/test_response_parser.py
 tests/test_response_str.py
 tests/test_simple_api.py
 tests/test_type_aliases.py
+tests/test_type_coercion.py
 tests/test_webhook_handling.py