Module adcp.types.domains.media_buy.package_update

Classes

class KeywordTargetsAddItem (**data: Any)

Expand source code

class KeywordTargetsAddItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to target', min_length=1)]
    match_type: match_type_1.MatchType
    bid_price: Annotated[
        StrictFloat | None,
        Field(
            description="Per-keyword bid price. Inherits currency and max_bid interpretation from the package's pricing option.",
            ge=0.0,
        ),
    ] = None

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 bid_price : float | None

var keyword : str

var match_type : MatchType

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class KeywordTargetsRemoveItem (**data: Any)

Expand source code

class KeywordTargetsRemoveItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to stop targeting', min_length=1)]
    match_type: match_type_1.MatchType

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 keyword : str

var match_type : MatchType

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class NegativeKeywordsAddItem (**data: Any)

Expand source code

class NegativeKeywordsAddItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to exclude', min_length=1)]
    match_type: match_type_1.MatchType

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 keyword : str

var match_type : MatchType

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class NegativeKeywordsRemoveItem (**data: Any)

Expand source code

class NegativeKeywordsRemoveItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to stop excluding', min_length=1)]
    match_type: match_type_1.MatchType

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 keyword : str

var match_type : MatchType

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PackageUpdate (**data: Any)

Expand source code

class PackageUpdate(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description="Seller's ID of package to update")]
    budget: Annotated[
        StrictFloat | None,
        Field(
            description='Updated hard spend cap for this package in the media-buy currency. Every selected pricing option in an AdCP-authored media buy MUST declare that same currency. In seller-optimized mode a number changes the package ceiling and null removes it so only the shared total and other constraints bound the package. null is invalid when the resulting allocation mode is fixed. 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
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description='Updated soft lifetime spend target for this package. A number is valid only for seller-optimized allocation, requires advertised media_buy.features.seller_optimized_min_spend_targets (otherwise UNSUPPORTED_FEATURE, before any over-subscription validation), and must not exceed the resulting package budget when one exists. null removes the target. Sellers MUST validate the complete post-update state atomically.',
            ge=0.0,
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Updated 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
    bid_price: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Use bidding. A package update MUST NOT supply both a non-null bidding object and bid_price. During migration, bidding:null MAY accompany bid_price to clear the canonical block and set the legacy representation atomically.',
            ge=0.0,
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Replace the complete package-authored bidding policy. An object replaces any prior package block and remains a complete override of the media-buy default. `{automatic:true}` explicitly selects provider automatic bidding at package scope. null clears the package-authored block so the package inherits media-buy bidding; if the media-buy block is also absent, provider automatic delivery applies. Monetary fields use the media-buy currency and require the package pricing option to declare that currency. During legacy migration, null MAY accompany bid_price or monetary optimization-goal targets; only a non-null canonical bidding object conflicts with those representations.'
        ),
    ] = None
    impressions: Annotated[
        StrictFloat | None, Field(description='Updated impression goal for this package', ge=0.0)
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's hard daily cap; null removes it. Numeric changes apply immediately with current-day package spend counted. A cap below that spend pauses the package for the day; the aggregate cap remains independently binding.",
            ge=0.0,
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Updated flight start date/time for this package in ISO 8601 format. Must fall within the media buy's date range."
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Updated flight end date/time for this package in ISO 8601 format. Must fall within the media buy's date range."
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(description='Pause/resume specific package (true = paused, false = active)'),
    ] = None
    canceled: Annotated[
        Literal[True] | None,
        Field(
            description='Cancel this specific package. Cancellation is irreversible — canceled packages stop delivery and cannot be reactivated. When true, package cancellation takes precedence over sibling fields on this package: the seller applies only canceled and cancellation_reason for this package and SHOULD return a structured warning naming ignored sibling fields. Root fields and other package updates still participate in the same atomic update when root canceled is absent. Sellers MAY reject with NOT_CANCELLABLE.'
        ),
    ] = None
    cancellation_reason: Annotated[
        str | None, Field(description='Reason for canceling this package.', max_length=500)
    ] = None
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description='Replace the catalogs this package promotes. Uses replacement semantics — the provided array replaces the current list. Omit to leave catalogs unchanged.',
            min_length=1,
        ),
    ] = None
    optimization_goals: Annotated[
        list[optimization_goal.OptimizationGoal] | None,
        Field(
            description='Replace all optimization goals for this package. Uses replacement semantics — omit to leave goals unchanged.',
            min_length=1,
        ),
    ] = None
    targeting_overlay: Annotated[
        targeting_input.TargetingOverlayInput | None,
        Field(
            description='Per-dimension targeting patch for this package. Omit targeting_overlay, or omit an individual dimension inside it, to leave the corresponding effective targeting unchanged. A non-null dimension replaces its current value; null clears it, including a value inherited from configured-product selection or a product default. Every resulting effective overlay must remain executable by the product. Sellers reject unsupported or partially applicable changes and use REQUOTE_REQUIRED when a change, including a broader inventory set, falls outside the priced envelope. placement_selection is purchased-inventory targeting; mode default restores the product default, null clears the dimension when the product permits it, and successful readback echoes the committed selected set when enumerable. If a patch removes a placement referenced by an existing creative assignment, the seller MUST reject the update unless the same atomic package mutation supplies a compatible complete creative_assignments replacement. Sellers MUST NOT silently delete assignments or retain orphan placement refs.'
        ),
    ] = None
    keyword_targets_add: Annotated[
        list[KeywordTargetsAddItem] | None,
        Field(
            description='Keyword targets to add or update on this package. Upserts by (keyword, match_type) identity: if the pair already exists, its bid_price is updated; if not, a new keyword target is added. Use targeting_overlay.keyword_targets in create_media_buy to set the initial list.',
            min_length=1,
        ),
    ] = None
    keyword_targets_remove: Annotated[
        list[KeywordTargetsRemoveItem] | None,
        Field(
            description='Keyword targets to remove from this package. Removes matching (keyword, match_type) pairs. If a specified pair is not present, sellers SHOULD treat it as a no-op for that entry.',
            min_length=1,
        ),
    ] = None
    negative_keywords_add: Annotated[
        list[NegativeKeywordsAddItem] | None,
        Field(
            description='Negative keywords to add to this package. Appends to the existing negative keyword list — does not replace it. If a keyword+match_type pair already exists, sellers SHOULD treat it as a no-op for that entry. Use targeting_overlay.negative_keywords in create_media_buy to set the initial list.',
            min_length=1,
        ),
    ] = None
    negative_keywords_remove: Annotated[
        list[NegativeKeywordsRemoveItem] | None,
        Field(
            description='Negative keywords to remove from this package. Removes matching keyword+match_type pairs from the existing list. If a specified pair is not present, sellers SHOULD treat it as a no-op for that entry.',
            min_length=1,
        ),
    ] = None
    creative_assignments: Annotated[
        list[creative_assignment.CreativeAssignment] | None,
        Field(
            description='Replace creative assignments for this package with optional rotation, grouping, weights, and placement routing. Uses replacement semantics - omit to leave assignments unchanged. rotation_mode is package-scoped: omission resolves to weighted, and every assignment MUST resolve to the same effective mode. In sequential mode, sequence_position MUST be unique within each package-local group. Sellers reject conflicts with VALIDATION_ERROR before mutation. When the same mutation narrows or clears targeting_overlay.placement_selection, this complete replacement MUST remove or reroute every assignment reference that would otherwise be orphaned; the seller validates both changes atomically.'
        ),
    ] = None
    creatives: Annotated[
        list[creative_asset.CreativeAsset] | None,
        Field(
            description="Replace this package's inline creative assets. Native localization is not accepted on this path; use sync_creatives before assigning the library creative. When the seller also advertises creative.has_creative_library: true, new inline creatives enter the seller's creative library and can be reused by creative_id while retained; inline-only sellers may store them as package-scoped assets. Use creative_assignments instead for existing library creatives.",
            max_length=100,
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

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

Subclasses

• PackageUpdate

Class variables

var bidding : BiddingPolicy | None

var budget : float | None

var canceled : Literal[True] | None

var cancellation_reason : str | None

var catalogs : list[Catalog] | None

var context : ContextObject | None

var creative_assignments : list[CreativeAssignment] | None

var creatives : list[CreativeAsset] | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var impressions : float | None

var keyword_targets_add : list[KeywordTargetsAddItem] | None

var keyword_targets_remove : list[KeywordTargetsRemoveItem] | None

var min_spend_target : float | None

var model_config

var negative_keywords_add : list[NegativeKeywordsAddItem] | None

var negative_keywords_remove : list[NegativeKeywordsRemoveItem] | None

var optimization_goals : list[OptimizationGoal8 | OptimizationGoal9 | OptimizationGoal10] | None

var pacing : Pacing | None

var package_id : str

var paused : bool | None

var start_time : pydantic.types.AwareDatetime | None

var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Instance variables

var bid_price : float | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary