Data and availability constraints

Model for SDMX Data Constraints.

class pysdmx.model.constraint.AvailabilityConstraint(*, annotations: Sequence[Annotation] = (), constraint_attachment: ConstraintAttachment, cube_region: CubeRegion, series_count: int | None = None, obs_count: int | None = None)

The data actually present for one data-related artefact.

Mirrors the SDMX 3.1 AvailabilityConstraint: contrary to a DataConstraint, it is not maintainable (no agency, id, version or name) as it is generated dynamically, typically by availability queries. It is attached to exactly one data-related artefact and carries exactly one cube region.

constraint_attachment

The artefact for which availability is described (exactly one data structure, dataflow or provision agreement).

cube_region

The values available for the attached artefact.

series_count

The number of series matching the query.

obs_count

The number of observations matching the query.

Note

Annotations are serialized in every representation. On the legacy SDMX-ML 2.1/3.0 and SDMX-JSON 2.0 representations (where availability is written as a data/content constraint), series_count/obs_count have no dedicated field, so they are carried as FMR-style sdmx_metrics annotations (alongside any other annotation) and lifted back on read.

Raises:

Invalid – If the constraint is not attached to exactly one data structure, dataflow or provision agreement.

property reference: str

The URN of the artefact for which availability is described.

property short_urn: str

A synthetic Short URN, used to key availability constraints.

Note

The short URN is derived solely from the referenced artefact, not from the constraint’s content. Two AvailabilityConstraint instances attached to the same artefact therefore share a short URN; the readers and the structure writers reject such duplicates with Invalid instead of silently keeping only the last one.

class pysdmx.model.constraint.ConstraintAttachment(data_provider: str | None, data_structures: Sequence[str] | None = None, dataflows: Sequence[str] | None = None, provision_agreements: Sequence[str] | None = None)

The artefacts to which the data constraint is attached.

class pysdmx.model.constraint.CubeKeyValue(id: str, values: Sequence[CubeValue] = (), time_range: CubeTimeRange | None = None, valid_from: datetime | None = None, valid_to: datetime | None = None)

The list of values (or a time range) for a cube’s component.

id

The referenced component (e.g. a dimension).

values

The set of allowed/excluded values.

time_range

A time range, for a time dimension (mutually exclusive with values in SDMX-ML).

valid_from

Start of the validity period (SDMX-ML 3.0/3.1 only).

valid_to

End of the validity period (SDMX-ML 3.0/3.1 only).

Raises:

Invalid – If both values and time_range are set.

class pysdmx.model.constraint.CubeRegion(key_values: Sequence[CubeKeyValue], is_included: bool = True)

A cube region, with its associated values (by default, included).

class pysdmx.model.constraint.CubeTimeRange(before_period: TimePeriodBoundary | None = None, after_period: TimePeriodBoundary | None = None, start_period: TimePeriodBoundary | None = None, end_period: TimePeriodBoundary | None = None)

A time range for a cube region’s time dimension.

Mirrors the SDMX TimeRange, a choice of three shapes: a period before, a period after, or a range with both a start and an end period. Only the boundaries of the chosen shape are set.

Raises:

Invalid – If the boundaries do not match one of the three SDMX shapes (before only, after only, or start and end).

class pysdmx.model.constraint.CubeValue(value: str, valid_from: datetime | None = None, valid_to: datetime | None = None)

A value of the cube, with optional business validity.

class pysdmx.model.constraint.DataConstraint(id: str, uri: str | None = None, urn: str | None = None, name: str | None = None, description: str | None = None, version: str = '1.0', valid_from: datetime | None = None, valid_to: datetime | None = None, is_final: bool = False, is_external_reference: bool = False, service_url: str | None = None, structure_url: str | None = None, agency: str | Agency = '', constraint_attachment: ConstraintAttachment | None = None, cube_regions: Sequence[CubeRegion] = (), key_sets: Sequence[KeySet] = (), *, annotations: Sequence[Annotation] = ())

A data constraint, defining the allowed values.

Available content is modelled by AvailabilityConstraint.

class pysdmx.model.constraint.DataKey(keys_values: Sequence[DataKeyValue], valid_from: datetime | None = None, valid_to: datetime | None = None)

A data key, i.e. one value per dimension in the data key.

class pysdmx.model.constraint.DataKeyValue(id: str, value: str)

A key value, i.e. a component of the key (e.g. FREQ=M).

class pysdmx.model.constraint.KeySet(keys: Sequence[DataKey], is_included: bool)

A set of keys, inluded by default.

class pysdmx.model.constraint.TimePeriodBoundary(period: str, is_inclusive: bool = True)

One end of a cube-region time range, with inclusivity.