sdmxlib 0.32.0__tar.gz → 0.32.2__tar.gz

{sdmxlib-0.32.0 → sdmxlib-0.32.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.32.0
+Version: 0.32.2
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner

{sdmxlib-0.32.0 → sdmxlib-0.32.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.32.0"
+version = "0.32.2"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{sdmxlib-0.32.0 → sdmxlib-0.32.2}/src/sdmxlib/model/ref.py

@@ -78,6 +78,20 @@ class Ref[T]:
             )
             if self._resolved is None:
                 self._resolved = obj  # type: ignore[assignment]
+        elif not isinstance(self.urn, SdmxUrn):
+            # Reject anything that's neither a SdmxUrn nor a MaintainableArtefact.
+            # Most common offender: Ref.to(dim) on a child item (Dimension,
+            # Code, Concept, ...) — these are identifiable but not maintainable,
+            # so their identity lives inside the parent's URN as an item_id
+            # fragment. Construct the URN explicitly via SdmxUrn.make(...).
+            msg = (
+                f"Ref expects a SdmxUrn or a MaintainableArtefact, got {type(self.urn).__name__}. "
+                "Child items (Dimension, Code, Concept, ...) are not maintainable — "
+                "build the URN with SdmxUrn.make(<Class>, package=..., artefact_class=..., "
+                "agency=..., id=..., version=..., item_id=...) and pass Ref.unresolved(urn) "
+                "or Ref.of(urn, obj)."
+            )
+            raise TypeError(msg)
 
     # ── Resolution ────────────────────────────────────────────────────────
 
@@ -144,8 +158,12 @@ class Ref[T]:
     def to(cls, obj: T) -> "Ref[T]":
         """Create a resolved Ref from a MaintainableArtefact instance.
 
-        The object must satisfy HasUrn — it needs ``agency_id``, ``id``,
-        ``version``, ``sdmx_package``, and ``sdmx_class`` attributes.
+        The object must be a ``MaintainableArtefact`` (Codelist, DataStructure,
+        Dataflow, …). Child items like ``Dimension``, ``Code``, or ``Concept``
+        are not maintainable — their identity lives inside the parent's URN as
+        an item_id fragment, so this method raises ``TypeError`` on them.
+        Construct their URN explicitly via ``SdmxUrn.make(...)`` and pass it
+        to ``Ref.unresolved(urn)`` or ``Ref.of(urn, obj)`` instead.
 
         Example:
             cl = Codelist(id="CL_FREQ", maintainer="SDMX", version="1.0", ...)

{sdmxlib-0.32.0 → sdmxlib-0.32.2}/src/sdmxlib/storage/_kinds.py

@@ -20,7 +20,7 @@ from sdmxlib.model.concept import ConceptScheme
 from sdmxlib.model.constraint import DataConstraint
 from sdmxlib.model.dataflow import Dataflow
 from sdmxlib.model.datastructure import DataStructure
-from sdmxlib.model.hierarchy import Hierarchy
+from sdmxlib.model.hierarchy import Hierarchy, HierarchyAssociation
 from sdmxlib.model.mapping import RepresentationMap
 from sdmxlib.model.metadataflow import Metadataflow
 from sdmxlib.model.metadataset import MetadataSet
@@ -43,6 +43,7 @@ ARTEFACT_KINDS: tuple[ArtefactKind, ...] = (
     ArtefactKind(DataStructure, "DataStructure"),
     ArtefactKind(Dataflow, "Dataflow"),
     ArtefactKind(Hierarchy, "Hierarchy"),
+    ArtefactKind(HierarchyAssociation, "HierarchyAssociation"),
     ArtefactKind(DataConstraint, "DataConstraint"),
     ArtefactKind(CategoryScheme, "CategoryScheme"),
     ArtefactKind(Categorisation, "Categorisation"),

{sdmxlib-0.32.0 → sdmxlib-0.32.2}/src/sdmxlib/storage/readers.py

@@ -42,7 +42,7 @@ from sdmxlib.model.datastructure import (
     MeasureDimension,
     TimeDimension,
 )
-from sdmxlib.model.hierarchy import HierarchicalCode, Hierarchy, Level
+from sdmxlib.model.hierarchy import HierarchicalCode, Hierarchy, HierarchyAssociation, Level
 from sdmxlib.model.istring import InternationalString
 from sdmxlib.model.mapping import LiteralValueMap, RepresentationMap
 from sdmxlib.model.metadataflow import Metadataflow
@@ -900,6 +900,41 @@ def _read_categorisation(conn: duckdb.DuckDBPyConnection, urn: str) -> "Categori
     )
 
 
+def _read_hierarchy_association(conn: duckdb.DuckDBPyConnection, urn: str) -> "HierarchyAssociation | None":
+    """Read a HierarchyAssociation from spine + extension."""
+    meta = _read_spine(conn, urn)
+    if meta is None:
+        return None
+    name = _read_istring(conn, urn, "name")
+    desc = _read_istring(conn, urn, "description")
+    anns = _read_annotations(conn, urn)
+
+    row = conn.execute(
+        "SELECT linked_hierarchy_urn, linked_object_urn, context_object_urn FROM hierarchy_association WHERE urn = ?",
+        [urn],
+    ).fetchone()
+    if row is None:
+        return None
+    linked_h, linked_o, context_o = row
+    linked_h_ref: Ref[Hierarchy] | None = Ref[Hierarchy].unresolved(SdmxUrn.parse(linked_h)) if linked_h else None
+    linked_o_ref = Ref[object].unresolved(SdmxUrn.parse(linked_o)) if linked_o else None
+    context_o_ref = Ref[object].unresolved(SdmxUrn.parse(context_o)) if context_o else None
+
+    return HierarchyAssociation(
+        id=meta["resource_id"],
+        maintainer=Agency(id=meta["agency_id"]),
+        version=meta["version"],
+        name=name,
+        description=desc,
+        annotations=anns,
+        valid_from=meta["valid_from"],
+        valid_to=meta["valid_to"],
+        linked_hierarchy=linked_h_ref,
+        linked_object=linked_o_ref,
+        context_object=context_o_ref,
+    )
+
+
 def _read_provision_agreement(conn: duckdb.DuckDBPyConnection, urn: str) -> "ProvisionAgreement | None":
     """Read a ProvisionAgreement from spine + extension."""
     meta = _read_spine(conn, urn)
@@ -1386,6 +1421,7 @@ _READER_DISPATCH: dict[str, Any] = {
     "Dataflow": _read_dataflow,
     "ConceptScheme": _read_concept_scheme,
     "Hierarchy": _read_hierarchy,
+    "HierarchyAssociation": _read_hierarchy_association,
     "DataConstraint": _read_data_constraint,
     "CategoryScheme": _read_category_scheme,
     "Categorisation": _read_categorisation,

{sdmxlib-0.32.0 → sdmxlib-0.32.2}/src/sdmxlib/storage/schema.py

@@ -16,7 +16,7 @@ Example:
 
 import duckdb
 
-SCHEMA_VERSION = "2.1"
+SCHEMA_VERSION = "2.2"
 
 
 # ── DDL ─────────────────────────────────────────────────────────────────
@@ -259,6 +259,13 @@ CREATE TABLE IF NOT EXISTS categorisation (
     target_urn      TEXT NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS hierarchy_association (
+    urn                  TEXT PRIMARY KEY,
+    linked_hierarchy_urn TEXT,
+    linked_object_urn    TEXT,
+    context_object_urn   TEXT
+);
+
 CREATE TABLE IF NOT EXISTS hierarchy_meta (
     urn               TEXT PRIMARY KEY,
     has_formal_levels BOOLEAN DEFAULT FALSE
@@ -470,6 +477,7 @@ ALL_TABLES: frozenset[str] = frozenset(
         "dataflow",
         "provision_agreement",
         "categorisation",
+        "hierarchy_association",
         "hierarchy_meta",
         "hierarchy_level",
         "hierarchy_node",

{sdmxlib-0.32.0 → sdmxlib-0.32.2}/src/sdmxlib/storage/writers.py

@@ -26,7 +26,7 @@ from sdmxlib.model.concept import ConceptScheme
 from sdmxlib.model.constraint import DataConstraint
 from sdmxlib.model.dataflow import Dataflow
 from sdmxlib.model.datastructure import DataStructure
-from sdmxlib.model.hierarchy import HierarchicalCode, Hierarchy
+from sdmxlib.model.hierarchy import HierarchicalCode, Hierarchy, HierarchyAssociation
 from sdmxlib.model.istring import InternationalString
 from sdmxlib.model.mapping import LiteralValueMap, RepresentationMap
 from sdmxlib.model.metadataflow import Metadataflow
@@ -398,6 +398,7 @@ def _delete_artefact_cascade(conn: duckdb.DuckDBPyConnection, urn: str) -> None:
     conn.execute("DELETE FROM dataflow WHERE urn = ?", p)
     conn.execute("DELETE FROM provision_agreement WHERE urn = ?", p)
     conn.execute("DELETE FROM categorisation WHERE urn = ?", p)
+    conn.execute("DELETE FROM hierarchy_association WHERE urn = ?", p)
     conn.execute("DELETE FROM hierarchy_meta WHERE urn = ?", p)
     # Constraint tables
     conn.execute("DELETE FROM region_key_value WHERE constraint_urn = ?", p)
@@ -979,6 +980,38 @@ def put_categorisation(
     _put_refs(conn, refs)
 
 
+def put_hierarchy_association(
+    conn: duckdb.DuckDBPyConnection,
+    ha: HierarchyAssociation,
+    *,
+    source_registry: str | None = None,
+) -> None:
+    """Write a HierarchyAssociation to artefact + hierarchy_association extension."""
+    urn = str(artefact_urn(ha))
+
+    _delete_artefact_cascade(conn, urn)
+    _put_spine(conn, urn, "HierarchyAssociation", ha, source_registry=source_registry)
+    _put_artefact_text_and_annotations(conn, urn, ha)
+
+    linked_h = str(ha.linked_hierarchy.urn) if ha.linked_hierarchy is not None else ""
+    linked_o = str(ha.linked_object.urn) if ha.linked_object is not None else ""
+    context_o = str(ha.context_object.urn) if ha.context_object is not None else ""
+    conn.execute(
+        "INSERT INTO hierarchy_association (urn, linked_hierarchy_urn, linked_object_urn, context_object_urn) "
+        "VALUES (?, ?, ?, ?)",
+        [urn, linked_h, linked_o, context_o],
+    )
+
+    refs: list[tuple[str, str, str, int | None]] = []
+    if ha.linked_hierarchy is not None:
+        refs.append((urn, linked_h, "linked_hierarchy", None))
+    if ha.linked_object is not None:
+        refs.append((urn, linked_o, "linked_object", None))
+    if ha.context_object is not None:
+        refs.append((urn, context_o, "context_object", None))
+    _put_refs(conn, refs)
+
+
 def put_provision_agreement(
     conn: duckdb.DuckDBPyConnection, pa: "ProvisionAgreement", *, source_registry: str | None = None
 ) -> None:
@@ -1435,6 +1468,7 @@ _WRITER_DISPATCH: dict[type, Any] = {
     Dataflow: put_dataflow,
     ConceptScheme: put_concept_scheme,
     Hierarchy: put_hierarchy,
+    HierarchyAssociation: put_hierarchy_association,
     DataConstraint: put_data_constraint,
     CategoryScheme: put_category_scheme,
     Categorisation: put_categorisation,