Module `adcp.types.domains.core.catchment`

Classes

class Catchment (**data: Any)

Expand source code

class Catchment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catchment_id: Annotated[
        str,
        Field(
            description="Identifier for this catchment, used to reference specific catchment areas in targeting (e.g., 'walk', 'drive', 'primary')."
        ),
    ]
    label: Annotated[
        str | None,
        Field(
            description="Human-readable label for this catchment (e.g., '15-min drive', '1km walking radius')."
        ),
    ] = None
    travel_time: Annotated[
        TravelTime | None,
        Field(
            description='Travel time limit for isochrone calculation. The platform resolves this to a geographic boundary based on actual transportation networks, accounting for road connectivity, transit schedules, and terrain.'
        ),
    ] = None
    transport_mode: Annotated[
        transport_mode_1.TransportMode | None,
        Field(
            description='Transportation mode for isochrone calculation. Required when travel_time is provided.'
        ),
    ] = None
    radius: Annotated[
        Radius | None,
        Field(
            description="Simple radius from the store location. The platform draws a circle of this distance around the store's coordinates."
        ),
    ] = None
    geometry: Annotated[
        Geometry | None,
        Field(
            description='Pre-computed GeoJSON geometry defining the catchment boundary. Use this when the buyer has already calculated isochrones (via TravelTime, Mapbox, etc.) or has custom trade area boundaries. Supports Polygon and MultiPolygon types.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> Catchment:
        # ``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 (('travel_time', 'transport_mode'), ('radius',), ('geometry',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'Catchment requires at least one of these field groups: travel_time+transport_mode | radius | geometry'
        )

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 catchment_id : str
var ext : ExtensionObject | None
var geometry : Geometry | None
var label : str | None
var model_config
var radius : Radius | None
var transport_mode : TransportMode | None
var travel_time : TravelTime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Geometry (**data: Any)

Expand source code

class Geometry(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    type: Annotated[Type, Field(description='GeoJSON geometry type.')]
    coordinates: Annotated[
        list[Any],
        Field(
            description='GeoJSON coordinates array. For Polygon: array of linear rings. For MultiPolygon: array of polygons.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

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 coordinates : list[typing.Any]
var model_config
var type : Type

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Radius (**data: Any)

Expand source code

class Radius(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    value: Annotated[StrictFloat, Field(description='Radius distance.', gt=0.0)]
    unit: Annotated[distance_unit.DistanceUnit, Field(description='Distance unit.')]

Base model for AdCP types with spec-compliant serialization.

Important

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 model_config
var unit : DistanceUnit
var value : float

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TravelTime (**data: Any)

Expand source code

class TravelTime(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    value: Annotated[StrictFloat, Field(description='Travel time limit.', ge=1.0)]
    unit: travel_time_unit.TravelTimeUnit

Base model for AdCP types with spec-compliant serialization.

Important

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 model_config
var unit : TravelTimeUnit
var value : float

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Type (*args, **kwds)

Expand source code

class Type(StrEnum):
    Polygon = 'Polygon'
    MultiPolygon = 'MultiPolygon'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var MultiPolygon
var Polygon