Module adcp.types.domains.media_buy.package_control

Classes

class CatalogId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class CatalogId(ScalarStr):
    __slots__ = ()
    _constraints = {'min_length': 1}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class PackageControl (**data: Any)

Expand source code

class PackageControl(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    package_id: Annotated[str, Field(min_length=1)]
    budget: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's hard lifetime spend cap. A number in a resulting seller-optimized buy requires advertised media_buy.features.seller_optimized_package_budgets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.",
            ge=0.0,
        ),
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's subordinate hard daily cap; null removes it. Numeric changes apply immediately with package spend already incurred in the shared current cap day counted.",
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's soft minimum-spend target. A number is valid only for seller-optimized allocation and requires advertised media_buy.features.seller_optimized_min_spend_targets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.",
            ge=0.0,
        ),
    ] = None
    impressions: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Replace package pacing, subordinate to media-buy pacing. In a resulting seller-optimized buy, pacing that differs from the media-buy pacing requires advertised media_buy.features.seller_optimized_package_pacing; otherwise rejected with UNSUPPORTED_FEATURE.'
        ),
    ] = None
    bidding: bidding_policy.BiddingPolicy | None = None
    paused: StrictBool | None = None
    canceled: Annotated[
        Literal[True] | None,
        Field(
            description='Exercise an already-accepted unilateral package cancellation right. If seller agreement is required, refine the accepted proposal with change_kind amendment; cancellation proposals terminate the whole MediaBuy.'
        ),
    ] = None
    cancellation_reason: Annotated[str | None, Field(max_length=500, min_length=1)] = None
    targeting_overlay: Annotated[
        targeting_input.TargetingOverlayInput | None,
        Field(
            description='Per-dimension targeting patch. Omission preserves the current dimension, a non-null value replaces it, and null clears it. The resulting effective targeting must remain within the accepted commercial envelope and is read back without null dimensions.'
        ),
    ] = None
    catalog_ids: Annotated[
        list[CatalogId] | None,
        Field(
            description="Replace the package's promoted catalogs with references previously managed through sync_catalogs.",
            min_length=1,
        ),
    ] = None
    keyword_targets_add: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    keyword_targets_remove: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    negative_keywords_add: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    negative_keywords_remove: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    optimization_goals: Annotated[
        list[canonical_optimization_goal.CanonicalOptimizationGoal] | None, Field(min_length=1)
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> PackageControl:
        # ``required`` asks whether the caller supplied the field, which is what
        # model_fields_set answers. An explicit null is a supplied value — on a
        # mutation input it is the command to clear — and a default the caller
        # never sent is not.
        for group in (('budget',), ('daily_budget_cap',), ('min_spend_target',), ('impressions',), ('pacing',), ('bidding',), ('paused',), ('canceled',), ('targeting_overlay',), ('catalog_ids',), ('keyword_targets_add',), ('keyword_targets_remove',), ('negative_keywords_add',), ('negative_keywords_remove',), ('optimization_goals',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'PackageControl requires at least one of these field groups: budget | daily_budget_cap | min_spend_target | impressions | pacing | bidding | paused | canceled | targeting_overlay | catalog_ids | keyword_targets_add | keyword_targets_remove | negative_keywords_add | negative_keywords_remove | optimization_goals'
        )

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var bidding : BiddingPolicy | None

var budget : float | None

var canceled : Literal[True] | None

var cancellation_reason : str | None

var catalog_ids : list[CatalogId] | None

var daily_budget_cap : float | None

var impressions : float | None

var keyword_targets_add : list[KeywordTarget] | None

var keyword_targets_remove : list[KeywordTarget] | None

var min_spend_target : float | None

var model_config

var negative_keywords_add : list[KeywordTarget] | None

var negative_keywords_remove : list[KeywordTarget] | None

var optimization_goals : list[CanonicalOptimizationGoal1 | CanonicalOptimizationGoal2 | CanonicalOptimizationGoal3] | None

var pacing : Pacing | None

var package_id : str

var paused : bool | None

var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary