sdmxlib 0.8.0__py3-none-any.whl

sdmxlib/model/datastructure.py

@@ -0,0 +1,390 @@
+"""DataStructure and its components — Dimension, TimeDimension, Attribute, Measure, Group."""
+
+from datetime import datetime
+from enum import Enum
+from typing import ClassVar
+
+from attrs import define, evolve, field
+
+from sdmxlib.model.annotations import Annotations
+from sdmxlib.model.base import MaintainableArtefact
+from sdmxlib.model.codelist import Code, Codelist
+from sdmxlib.model.collections import ItemList
+from sdmxlib.model.concept import Concept
+from sdmxlib.model.istring import InternationalString
+from sdmxlib.model.organisation import Agency, _to_agency, _to_annotations, _to_istring
+from sdmxlib.model.ref import Ref
+from sdmxlib.model.representation import Facet
+from sdmxlib.model.urn import SdmxUrn
+
+
+class AttachmentLevel(Enum):
+    """Where an attribute attaches within the observation structure."""
+
+    DATASET = "dataset"
+    OBSERVATION = "observation"
+    SERIES = "series"
+    GROUP = "group"
+
+
+class ConceptIdentityMixin:
+    """Typed access to the concept_identity Ref on a DSD component."""
+
+    __slots__ = ()
+
+    # Declared for type checking — concrete subclasses provide via attrs fields
+    concept: Ref[Concept] | None
+
+    @property
+    def concept_identity(self) -> Concept:
+        """The resolved Concept for this component.
+
+        Raises TypeError if no concept reference is set.
+        Raises UnresolvedRef if the concept has not been fetched.
+        """
+        concept = self.concept
+        if not isinstance(concept, Ref):
+            msg = f"No concept reference set: {concept!r}"
+            raise TypeError(msg)
+        return concept()
+
+
+class RepresentationMixin:
+    """Typed access to the codelist Ref on a DSD component."""
+
+    __slots__ = ()
+
+    # Declared for type checking — concrete subclasses provide via attrs fields
+    representation: Ref[Codelist] | Facet | None
+
+    @property
+    def codelist(self) -> Codelist:
+        """The resolved Codelist for this component.
+
+        Raises TypeError if the representation is not a codelist reference (e.g. Facet).
+        Raises UnresolvedRef if the codelist has not been fetched.
+        """
+        representation = self.representation
+        if not isinstance(representation, Ref):
+            msg = f"Representation is not a codelist reference: {type(representation).__name__}"
+            raise TypeError(msg)
+        return representation()
+
+
+def _to_concept_ref(v: "Ref[Concept] | SdmxUrn[Concept] | None") -> "Ref[Concept] | None":
+    if isinstance(v, SdmxUrn):
+        return Ref[Concept].unresolved(v)
+    return v
+
+
+def _to_codelist_ref(
+    v: "Ref[Codelist] | SdmxUrn[Codelist] | Codelist | Facet | None",
+) -> "Ref[Codelist] | Facet | None":
+    if isinstance(v, SdmxUrn):
+        return Ref[Codelist].unresolved(v)
+    if isinstance(v, Codelist):
+        return Ref.to(v)
+    return v
+
+
+def _to_dimensions(v: "ItemList[Dimension] | list[Dimension]") -> "ItemList[Dimension]":
+    return v if isinstance(v, ItemList) else ItemList(v)
+
+
+def _to_attributes(v: "ItemList[Attribute] | list[Attribute]") -> "ItemList[Attribute]":
+    return v if isinstance(v, ItemList) else ItemList(v)
+
+
+def _to_measures(v: "ItemList[Measure] | list[Measure]") -> "ItemList[Measure]":
+    return v if isinstance(v, ItemList) else ItemList(v)
+
+
+def _to_groups(v: "ItemList[Group] | list[Group] | None") -> "ItemList[Group] | None":
+    if isinstance(v, list):
+        return ItemList(v)
+    return v
+
+
+@define
+class Dimension(ConceptIdentityMixin, RepresentationMixin):
+    """An identifying component of a DataStructure."""
+
+    id: str
+    concept: Ref[Concept] | None = field(default=None, converter=_to_concept_ref)
+    representation: Ref[Codelist] | Facet | None = field(default=None, converter=_to_codelist_ref)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+
+    def __attrs_post_init__(self) -> None:
+        if self.representation is None and isinstance(self.concept, Ref) and self.concept.resolved:
+            core = self.concept_identity.core_representation
+            if core is not None:
+                self.representation = core
+
+    @property
+    def is_enumerated(self) -> bool:
+        """True if this dimension is constrained to a codelist."""
+        return isinstance(self.representation, Ref)
+
+    @property
+    def text_type(self) -> str | None:
+        """Text type string if representation is Facet, else None."""
+        return self.representation.type if isinstance(self.representation, Facet) else None
+
+    @property
+    def enumeration_urn(self) -> SdmxUrn[Codelist] | None:
+        """URN of the referenced codelist, or None."""
+        return self.representation.urn if isinstance(self.representation, Ref) else None
+
+    @property
+    def codes(self) -> ItemList[Code] | None:
+        """Codes from the resolved codelist, or None if unresolved."""
+        if isinstance(self.representation, Ref) and self.representation.resolved:
+            return self.representation().codes
+        return None
+
+
+@define
+class TimeDimension(ConceptIdentityMixin):
+    """The time dimension of a DataStructure (always id=TIME_PERIOD)."""
+
+    id: str = "TIME_PERIOD"
+    concept: Ref[Concept] | None = field(default=None, converter=_to_concept_ref)
+    representation: Facet | None = None
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+
+    @property
+    def text_type(self) -> str | None:
+        """Text type from the representation, or None."""
+        return self.representation.type if self.representation else None
+
+
+@define
+class Attribute(ConceptIdentityMixin, RepresentationMixin):
+    """A descriptive component attached to an observation, series, or dataset."""
+
+    id: str
+    usage: str | None = None
+    attachment: AttachmentLevel | None = None
+    related_dimensions: list[str] | None = None
+    related_measure: str | None = None
+    concept: Ref[Concept] | None = field(default=None, converter=_to_concept_ref)
+    representation: Ref[Codelist] | Facet | None = field(default=None, converter=_to_codelist_ref)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+
+    def __attrs_post_init__(self) -> None:
+        if self.representation is None and isinstance(self.concept, Ref) and self.concept.resolved:
+            core = self.concept_identity.core_representation
+            if core is not None:
+                self.representation = core
+
+    @property
+    def is_enumerated(self) -> bool:
+        """True if this attribute is constrained to a codelist."""
+        return isinstance(self.representation, Ref)
+
+    @property
+    def codes(self) -> ItemList[Code] | None:
+        """Codes from the resolved codelist, or None if unresolved."""
+        if isinstance(self.representation, Ref) and self.representation.resolved:
+            return self.representation().codes
+        return None
+
+
+@define
+class Measure(ConceptIdentityMixin, RepresentationMixin):
+    """An observed value component (primary measure in v2.1, Measure in v3.0)."""
+
+    id: str
+    usage: str | None = None
+    concept: Ref[Concept] | None = field(default=None, converter=_to_concept_ref)
+    representation: Ref[Codelist] | Facet | None = field(default=None, converter=_to_codelist_ref)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+
+    def __attrs_post_init__(self) -> None:
+        if self.representation is None and isinstance(self.concept, Ref) and self.concept.resolved:
+            core = self.concept_identity.core_representation
+            if core is not None:
+                self.representation = core
+
+    @property
+    def codes(self) -> ItemList[Code] | None:
+        """Codes from the resolved codelist, or None if unresolved."""
+        if isinstance(self.representation, Ref) and self.representation.resolved:
+            return self.representation().codes
+        return None
+
+
+@define
+class MeasureDimension(ConceptIdentityMixin, RepresentationMixin):
+    """The measure dimension in an SDMX 2.1 cross-sectional DSD.
+
+    Acts as a regular dimension whose codes name the measures present in the
+    dataset (e.g. EMPLOYMENT, UNEMPLOYMENT for an LFS flow). Its presence is
+    the formal SDMX 2.1 signal that data arrives in long format with one
+    ``OBS_VALUE`` per row — a pivot on this dimension produces the wide
+    (multi-measure) view analysts expect.
+
+    In SDMX 3.0 DSDs, multiple :class:`Measure` objects replace this pattern.
+    """
+
+    id: str
+    concept: Ref[Concept] | None = field(default=None, converter=_to_concept_ref)
+    representation: Ref[Codelist] | Facet | None = field(default=None, converter=_to_codelist_ref)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+
+    def __attrs_post_init__(self) -> None:
+        if self.representation is None and isinstance(self.concept, Ref) and self.concept.resolved:
+            core = self.concept_identity.core_representation
+            if core is not None:
+                self.representation = core
+
+    @property
+    def is_enumerated(self) -> bool:
+        """True if this dimension is constrained to a codelist."""
+        return isinstance(self.representation, Ref)
+
+    @property
+    def codes(self) -> ItemList[Code] | None:
+        """Codes from the resolved codelist, or None if unresolved."""
+        if isinstance(self.representation, Ref) and self.representation.resolved:
+            return self.representation().codes
+        return None
+
+
+@define
+class Group:
+    """A dimension grouping (v2.1). None for v3.0 sources."""
+
+    id: str
+    dimension_ids: list[str] = field(factory=list)
+
+
+@define
+class DataStructure(MaintainableArtefact):
+    """Defines the shape of a dataset — dimensions, attributes, measures.
+
+    Example:
+        dsd.dimensions["FREQ"].codes  # ItemList[Code] if resolved
+        dsd.code_map("en")  # {dim_id: {code_id: label}}
+        dsd.all_codelists  # {dim_id: Codelist}
+        dsd.column_labels("en")  # {dim_id: concept label}
+        dsd.enumerated_dimensions  # ItemList[Dimension]
+    """
+
+    sdmx_package: ClassVar[str] = "datastructure"
+    sdmx_class: ClassVar[str] = "DataStructure"
+    msg_field: ClassVar[str] = "data_structures"
+
+    id: str
+    maintainer: Agency = field(converter=_to_agency)
+    version: str = "1.0"
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    is_final: bool = False
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+    valid_from: datetime | None = None
+    valid_to: datetime | None = None
+    dimensions: ItemList[Dimension] = field(factory=ItemList, converter=_to_dimensions)
+    time_dimension: TimeDimension | None = None
+    measure_dimension: MeasureDimension | None = None
+    attributes: ItemList[Attribute] = field(factory=ItemList, converter=_to_attributes)
+    measures: ItemList[Measure] = field(factory=ItemList, converter=_to_measures)
+    groups: ItemList[Group] | None = field(default=None, converter=_to_groups)
+
+    @property
+    def components(self) -> "ItemList[Dimension | MeasureDimension | Attribute | Measure]":
+        """All components: dimensions + measure_dimension (if any) + attributes + measures."""
+        md: list[MeasureDimension] = [self.measure_dimension] if self.measure_dimension is not None else []
+        return ItemList([*self.dimensions, *md, *self.attributes, *self.measures])
+
+    @property
+    def enumerated_dimensions(self) -> ItemList[Dimension]:
+        """Dimensions that are constrained to a codelist."""
+        return self.dimensions.filter(lambda d: d.is_enumerated)
+
+    @property
+    def free_text_dimensions(self) -> ItemList[Dimension]:
+        """Dimensions that are not enumerated."""
+        return self.dimensions.filter(lambda d: not d.is_enumerated)
+
+    @property
+    def all_codelists(self) -> dict[str, Codelist]:
+        """All resolved codelists keyed by component id."""
+        result: dict[str, Codelist] = {}
+        for comp in [*self.dimensions, *self.attributes, *self.measures]:
+            if isinstance(comp.representation, Ref) and comp.representation.resolved:
+                result[comp.id] = comp.codelist
+        return result
+
+    def code_map(self, lang: str = "en") -> dict[str, dict[str, str]]:
+        """Build ``{component_id: {code_id: label}}`` for all resolved codelists."""
+        return {
+            comp_id: {code.id: code.name.get(lang) or code.id for code in cl.codes}
+            for comp_id, cl in self.all_codelists.items()
+        }
+
+    def column_labels(self, lang: str = "en") -> dict[str, str]:
+        """Map component ids to human labels from their concepts."""
+        result: dict[str, str] = {}
+        for comp in [*self.dimensions, *self.attributes, *self.measures]:
+            if isinstance(comp.concept, Ref) and comp.concept.resolved:
+                result[comp.id] = comp.concept_identity.name.get(lang) or comp.id
+            else:
+                result[comp.id] = comp.id
+        return result
+
+    def add(
+        self,
+        items: "Dimension | MeasureDimension | Attribute | Measure | list[Dimension | MeasureDimension | Attribute | Measure]",  # noqa: E501
+    ) -> "DataStructure":
+        """Return a new DataStructure with *items* added to the appropriate list(s).
+
+        Dispatches by type — dimensions go to dimensions, attributes to
+        attributes, measures to measures. Accepts a single component or a
+        mixed list.
+
+        Example:
+            dsd = dsd.add(sl.Dimension(id="PARTNER", representation=cl))
+            dsd = dsd.add([sl.Dimension(id="PARTNER", representation=cl),
+                           sl.Attribute(id="OBS_STATUS")])
+        """
+        item_list = [items] if not isinstance(items, list) else items
+        dims = list(self.dimensions)
+        attrs = list(self.attributes)
+        meas = list(self.measures)
+        md = self.measure_dimension
+        for item in item_list:
+            match item:
+                case MeasureDimension():
+                    md = item
+                case Dimension():
+                    dims.append(item)
+                case Attribute():
+                    attrs.append(item)
+                case Measure():
+                    meas.append(item)
+        return evolve(self, dimensions=dims, measure_dimension=md, attributes=attrs, measures=meas)
+
+    def drop(self, component_ids: str | list[str]) -> "DataStructure":
+        """Return a new DataStructure with the given component(s) removed.
+
+        Searches dimensions, attributes, and measures by id.
+        Accepts a single id string or a list of id strings.
+        Raises KeyError if any id is not found in any component list.
+
+        Example:
+            dsd = dsd.drop("SECTOR")
+            dsd = dsd.drop(["SECTOR", "OBS_STATUS"])
+        """
+        ids = [component_ids] if isinstance(component_ids, str) else list(component_ids)
+        all_ids = {d.id for d in self.dimensions} | {a.id for a in self.attributes} | {m.id for m in self.measures}
+        missing = [i for i in ids if i not in all_ids]
+        if missing:
+            raise KeyError(missing[0] if len(missing) == 1 else missing)
+        id_set = set(ids)
+        return evolve(
+            self,
+            dimensions=[d for d in self.dimensions if d.id not in id_set],
+            attributes=[a for a in self.attributes if a.id not in id_set],
+            measures=[m for m in self.measures if m.id not in id_set],
+        )

sdmxlib/model/expr.py

@@ -0,0 +1,120 @@
+"""ItemExpr, ItemPredicate, item() — expression-based filtering for ItemList.
+
+Provides a Polars-style expression API for ItemList.filter():
+
+    dims.filter(item("id") == "FREQ")
+    dims.filter(item("is_enumerated"))
+    dims.filter(~item("is_enumerated"))
+    dims.filter(item("id").is_in(["FREQ", "GEO"]))
+    dims.filter(item("codelist").is_null())
+
+Both lambda and expression forms are accepted by ItemList.filter():
+
+    dims.filter(lambda d: d.id == "FREQ")     # lambda
+    dims.filter(item("id") == "FREQ")          # expression
+"""
+
+from collections.abc import Callable, Collection
+from typing import Any
+
+
+class ItemPredicate:
+    """A composable predicate returned by ItemExpr operations.
+
+    Supports negation via ``~``:
+
+        ~item("is_enumerated")   # not is_enumerated
+    """
+
+    __slots__ = ("_fn",)
+
+    def __init__(self, fn: Callable[[Any], bool]) -> None:
+        self._fn = fn
+
+    def __call__(self, x: Any) -> bool:
+        """Evaluate the predicate against *x*."""
+        return self._fn(x)
+
+    def __invert__(self) -> "ItemPredicate":
+        fn = self._fn
+        return ItemPredicate(lambda x: not fn(x))
+
+    def __repr__(self) -> str:
+        return f"ItemPredicate({self._fn!r})"
+
+
+class ItemExpr:
+    """Expression builder for a single item attribute.
+
+    Created via ``item("attr_name")``. Calling the expression directly
+    performs a truthy check; comparison operators and methods return
+    composable ``ItemPredicate`` objects.
+
+    Example:
+        item("is_enumerated")            # truthy check
+        ~item("is_enumerated")           # negated truthy
+        item("id") == "FREQ"             # equality
+        item("id") != "FREQ"             # inequality
+        item("id").is_in(["FREQ", "GEO"])  # membership
+        item("codelist").is_null()       # None check
+    """
+
+    __slots__ = ("_attr",)
+
+    def __init__(self, attr: str) -> None:
+        self._attr = attr
+
+    # ── Direct use as predicate ───────────────────────────────────────────
+
+    def __call__(self, x: Any) -> bool:
+        """Truthy check — allows using ItemExpr directly as a filter predicate."""
+        return bool(getattr(x, self._attr))
+
+    def __invert__(self) -> ItemPredicate:
+        """Negated truthy check."""
+        attr = self._attr
+        return ItemPredicate(lambda x: not bool(getattr(x, attr)))
+
+    # ── Comparison operators ──────────────────────────────────────────────
+
+    def __eq__(self, other: object) -> ItemPredicate:  # type: ignore[override]
+        attr = self._attr
+        return ItemPredicate(lambda x: getattr(x, attr) == other)
+
+    def __ne__(self, other: object) -> ItemPredicate:  # type: ignore[override]
+        attr = self._attr
+        return ItemPredicate(lambda x: getattr(x, attr) != other)
+
+    # ── Methods ───────────────────────────────────────────────────────────
+
+    def is_in(self, values: Collection[Any]) -> ItemPredicate:
+        """True if the attribute value is in *values*."""
+        attr = self._attr
+        value_set = frozenset(values)
+        return ItemPredicate(lambda x: getattr(x, attr) in value_set)
+
+    def is_null(self) -> ItemPredicate:
+        """True if the attribute value is None."""
+        attr = self._attr
+        return ItemPredicate(lambda x: getattr(x, attr) is None)
+
+    # ── Identity ─────────────────────────────────────────────────────────
+
+    def __hash__(self) -> int:
+        return hash(self._attr)
+
+    def __repr__(self) -> str:
+        return f"item({self._attr!r})"
+
+
+def item(attr: str) -> ItemExpr:
+    """Build a filter expression for an item attribute.
+
+    Example:
+        dims.filter(item("id") == "FREQ")
+        dims.filter(item("is_enumerated"))
+        dims.filter(~item("is_enumerated"))
+        dims.filter(item("id").is_in(["FREQ", "GEO"]))
+        dims.filter(item("codelist").is_null())
+    """
+    return ItemExpr(attr)

sdmxlib/model/hierarchy.py

@@ -0,0 +1,111 @@
+"""Hierarchy and HierarchicalCode — cross-codelist hierarchical views.
+
+SDMX 3.0 artefact that replaces HierarchicalCodelist from 2.1.
+The 2.1 reader maps the older structure into this model.
+"""
+
+from datetime import datetime
+from typing import ClassVar
+
+from attrs import define, field
+
+from sdmxlib.model.annotations import Annotations
+from sdmxlib.model.base import MaintainableArtefact
+from sdmxlib.model.codelist import Code
+from sdmxlib.model.collections import ItemList
+from sdmxlib.model.istring import InternationalString
+from sdmxlib.model.organisation import Agency, _to_agency, _to_annotations, _to_istring
+from sdmxlib.model.ref import Ref
+from sdmxlib.model.urn import SdmxUrn
+
+
+def _to_hcode_ref(v: "Ref[Code] | SdmxUrn[Code] | None") -> "Ref[Code] | None":
+    if isinstance(v, SdmxUrn):
+        return Ref[Code].unresolved(v)
+    return v
+
+
+def _to_hcodes(v: "ItemList[HierarchicalCode] | list[HierarchicalCode]") -> "ItemList[HierarchicalCode]":
+    return v if isinstance(v, ItemList) else ItemList(v)
+
+
+def _to_tree(v: "ItemList[HierarchicalCode] | list[HierarchicalCode]") -> "ItemList[HierarchicalCode]":
+    return v if isinstance(v, ItemList) else ItemList(v)
+
+
+@define
+class HierarchicalCode:
+    """A node in a Hierarchy tree, referencing a code from a Codelist.
+
+    Provides tree navigation via ``children`` and flat lookup via the
+    parent ``Hierarchy.codes`` index.
+
+    Example:
+        node = hierarchy.tree["CANADA"]
+        node.children["ON"]           # tree navigation
+        hierarchy.codes["ON"]          # flat O(1) lookup
+        node.code()                    # Ref[Code] unwrap → Code
+    """
+
+    id: str
+    code: Ref[Code] | None = field(default=None, converter=_to_hcode_ref)
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    children: "ItemList[HierarchicalCode]" = field(factory=ItemList, converter=_to_hcodes)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+    valid_from: datetime | None = None
+    valid_to: datetime | None = None
+
+
+def _flatten_nodes(nodes: ItemList["HierarchicalCode"]) -> ItemList["HierarchicalCode"]:
+    """Recursively collect all nodes into a flat ItemList."""
+    result: list[HierarchicalCode] = []
+
+    def _walk(node: HierarchicalCode) -> None:
+        result.append(node)
+        for child in node.children:
+            _walk(child)
+
+    for node in nodes:
+        _walk(node)
+    return ItemList(result)
+
+
+@define
+class Hierarchy(MaintainableArtefact):
+    """A standalone hierarchy of codes from one or more codelists.
+
+    Provides two access patterns:
+
+    - ``tree``: top-level entry points (roots) with ``children`` navigation
+    - ``codes``: flat O(1) index over ALL nodes in the hierarchy
+
+    Example:
+        hierarchy.tree["CANADA"].children["ON"]  # tree navigation
+        hierarchy.codes["OTTAWA"]                 # flat lookup
+        hierarchy.codes["OTTAWA"].code()          # Ref[Code] unwrap → Code
+    """
+
+    sdmx_package: ClassVar[str] = "codelist"
+    sdmx_class: ClassVar[str] = "Hierarchy"
+    msg_field: ClassVar[str] = "hierarchies"
+
+    id: str = ""
+    maintainer: Agency = field(factory=lambda: Agency(id=""), converter=_to_agency)
+    version: str = "1.0"
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    is_final: bool = False
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+    valid_from: datetime | None = None
+    valid_to: datetime | None = None
+    tree: ItemList[HierarchicalCode] = field(factory=ItemList, converter=_to_tree)
+    _codes: ItemList[HierarchicalCode] = field(init=False, repr=False, factory=ItemList)
+
+    def __attrs_post_init__(self) -> None:
+        self._codes = _flatten_nodes(self.tree)
+
+    @property
+    def codes(self) -> ItemList[HierarchicalCode]:
+        """Flat index of ALL nodes in the hierarchy. O(1) lookup by id."""
+        return self._codes