sdmxlib 0.43.0__tar.gz → 0.44.0__tar.gz

{sdmxlib-0.43.0 → sdmxlib-0.44.0}/PKG-INFO

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

{sdmxlib-0.43.0 → sdmxlib-0.44.0}/pyproject.toml

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

{sdmxlib-0.43.0 → sdmxlib-0.44.0}/src/sdmxlib/__init__.py

@@ -90,6 +90,7 @@ from sdmxlib.model import (
     MeasureDimension,
     MetadataAttribute,
     MetadataMessage,
+    MetadataSection,
     MetadataSet,
     MetadataStructure,
     Metadataflow,
@@ -198,6 +199,7 @@ __all__ = [
     "MemberValue",
     "MetadataAttribute",
     "MetadataMessage",
+    "MetadataSection",
     "MetadataSet",
     "MetadataStructure",
     "Metadataflow",

{sdmxlib-0.43.0 → sdmxlib-0.44.0}/src/sdmxlib/local/registry.py

@@ -36,13 +36,14 @@ import time
 from collections.abc import Iterable, Iterator
 from contextlib import contextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Self
+from typing import TYPE_CHECKING, Any, Self, cast
 
 import attrs
 import duckdb
 
 from sdmxlib._duckdb import scalar
 from sdmxlib.model.collections import ItemList
+from sdmxlib.model.istring import InternationalString
 from sdmxlib.model.ref import Ref
 from sdmxlib.model.registry import InMemoryRegistry, artefact_urn
 from sdmxlib.model.urn import SdmxUrn
@@ -60,6 +61,19 @@ if TYPE_CHECKING:
     from sdmxlib.model.binding import DataflowBinding, DriftIssue
     from sdmxlib.model.dataflow import Dataflow
     from sdmxlib.model.hierarchy import Hierarchy
+    from sdmxlib.model.metadataset import MetadataSection, MetadataSet
+
+
+def _leaf_attribute_id(attribute_path: str) -> str:
+    """Leaf attribute id from a dotted ``attribute_path``.
+
+    Strips the parent path and any ``[n]`` sibling suffix, e.g.
+    ``"QUALITY.COVERAGE[1]"`` -> ``"COVERAGE"``.
+    """
+    leaf = attribute_path.rsplit(".", 1)[-1]
+    bracket = leaf.find("[")
+    return leaf[:bracket] if bracket != -1 else leaf
+
 
 # Map item-level artefact class -> (parent scheme type name, items attribute name)
 _ITEM_TO_SCHEME: dict[str, tuple[str, str]] = {
@@ -657,6 +671,157 @@ class Registry:
         if issues:
             raise DriftError(issues)
 
+    # ── Reference-metadata queries ──────────────────────────────────────
+
+    def metadata_for_target(
+        self,
+        target_urn: "str | SdmxUrn[Any]",
+        *,
+        structure_urn: "str | SdmxUrn[Any] | None" = None,
+    ) -> "list[MetadataSet]":
+        """All MetadataSets whose targets include ``target_urn``.
+
+        The reverse of ``MetadataSet.targets`` — given any artefact URN
+        (a Code, Codelist, Concept, Dataflow, …), return every reported
+        MetadataSet attached to it. This is the SDMX 3.0
+        ``/metadata/structure/{artefactType}/…`` by-target lookup realised
+        locally, and the primitive both the REST view and the search
+        indexer navigate.
+
+        Sets are returned without resolving their target/structure Refs
+        (the URNs are all present) — cheap even for sets with many
+        targets. Ordered by set URN for determinism.
+
+        Args:
+            target_urn: The artefact URN to find attached metadata for.
+            structure_urn: Optional MSD or Metadataflow URN to filter by,
+                e.g. return only reference-guide sets targeting the code.
+
+        Returns:
+            The matching MetadataSets (empty list if none).
+        """
+        cur = self._read_cursor()
+        params: list[str] = [str(target_urn)]
+        sql = "SELECT DISTINCT t.set_urn FROM metadata_target t"
+        if structure_urn is not None:
+            sql += " JOIN metadata_set s ON s.urn = t.set_urn AND s.structure_urn = ?"
+            params.append(str(structure_urn))
+        sql += " WHERE t.target_urn = ? ORDER BY t.set_urn"
+        # target_urn is the last positional param; structure_urn (if any)
+        # precedes it in SQL text, so order params to match.
+        ordered = ([params[1]] if structure_urn is not None else []) + [params[0]]
+        rows = cur.execute(sql, ordered).fetchall()
+
+        sets: list[MetadataSet] = []
+        for (set_urn,) in rows:
+            artefact = readers.get_artefact(cur, set_urn, lazy_conn=self._conn)
+            if artefact is not None:
+                sets.append(cast("MetadataSet", artefact))
+        return sets
+
+    def metadata_report(
+        self,
+        set_urn: "str | SdmxUrn[Any]",
+    ) -> "list[MetadataSection]":
+        """Flattened, MSD-typed view of a MetadataSet's reported values.
+
+        Returns one ``MetadataSection`` per ``metadata_value`` row,
+        each carrying the leaf attribute's declared ``text_type`` (e.g.
+        ``"String"`` / ``"XHTML"``) and ``is_presentational`` flag joined
+        from the MSD. Sections are ordered by ``(path, sibling_index)``.
+
+        This is the sectioned input a chunker / search indexer consumes —
+        it turns the reported tree + schema into a flat, typed list without
+        the caller re-joining the MSD. Returns an empty list if the set has
+        no values (or does not exist).
+
+        Args:
+            set_urn: The MetadataSet URN to project.
+        """
+        from sdmxlib.model.metadataset import MetadataSection  # noqa: PLC0415
+
+        cur = self._read_cursor()
+        type_by_id = self._msd_attribute_types(cur, str(set_urn))
+
+        rows = cur.execute(
+            """
+            SELECT attribute_path, sibling_index, value_kind, scalar, i18n
+            FROM metadata_value
+            WHERE set_urn = ?
+            ORDER BY attribute_path, sibling_index
+            """,
+            [str(set_urn)],
+        ).fetchall()
+
+        sections: list[MetadataSection] = []
+        for attribute_path, sibling_index, value_kind, scalar_val, i18n_val in rows:
+            leaf_id = _leaf_attribute_id(attribute_path)
+            text_type, is_pres = type_by_id.get(leaf_id, (None, False))
+            value: Any
+            if value_kind == "i18n":
+                value = InternationalString.of(dict(i18n_val)) if i18n_val else None
+            else:
+                value = scalar_val
+            sections.append(
+                MetadataSection(
+                    path=attribute_path,
+                    attribute_id=leaf_id,
+                    sibling_index=sibling_index,
+                    value=value,
+                    text_type=text_type,
+                    is_presentational=is_pres,
+                )
+            )
+        return sections
+
+    def _msd_attribute_types(
+        self,
+        cur: "duckdb.DuckDBPyConnection",
+        set_urn: str,
+    ) -> "dict[str, tuple[str | None, bool]]":
+        """Map ``attribute id → (text_type, is_presentational)`` for a set's MSD.
+
+        Resolves the set's structure (an MSD directly, or the MSD behind a
+        Metadataflow) and walks its attribute tree. Empty if the structure
+        is absent.
+        """
+        from sdmxlib.model.metadatastructure import MetadataAttribute, MetadataStructure  # noqa: PLC0415
+        from sdmxlib.model.representation import Facet  # noqa: PLC0415
+
+        set_row = cur.execute(
+            "SELECT structure_urn, structure_kind FROM metadata_set WHERE urn = ?",
+            [set_urn],
+        ).fetchone()
+        if set_row is None:
+            return {}
+        structure_urn, structure_kind = set_row
+
+        msd_urn = structure_urn
+        if structure_kind == "Metadataflow":
+            flow = readers.get_artefact(cur, structure_urn, lazy_conn=self._conn)
+            structure_ref = getattr(flow, "structure", None)
+            if structure_ref is None:
+                return {}
+            msd_urn = str(structure_ref.urn)
+
+        msd = readers.get_artefact(cur, msd_urn, lazy_conn=self._conn)
+        if not isinstance(msd, MetadataStructure):
+            return {}
+
+        out: dict[str, tuple[str | None, bool]] = {}
+
+        def _walk(attr: MetadataAttribute) -> None:
+            text_type: str | None = None
+            if isinstance(attr.representation, Facet) and attr.representation.type is not None:
+                text_type = str(attr.representation.type)
+            out[attr.id] = (text_type, attr.is_presentational)
+            for child in attr.children:
+                _walk(child)
+
+        for root in msd.attributes:
+            _walk(root)
+        return out
+
     # ── Ref resolution ─────────────────────────────────────────────────
 
     def _resolve_refs(  # noqa: C901

{sdmxlib-0.43.0 → sdmxlib-0.44.0}/src/sdmxlib/model/__init__.py

@@ -78,6 +78,7 @@ from sdmxlib.model.message import MetadataMessage, StructureMessage
 from sdmxlib.model.metadataflow import Metadataflow
 from sdmxlib.model.metadatastructure import MetadataAttribute, MetadataStructure
 from sdmxlib.model.metadataset import (
+    MetadataSection,
     MetadataSet,
     ReportedAttribute,
     ReportedAttributeValue,
@@ -157,6 +158,7 @@ __all__ = [
     "MemberValue",
     "MetadataAttribute",
     "MetadataMessage",
+    "MetadataSection",
     "MetadataSet",
     "MetadataStructure",
     "Metadataflow",

{sdmxlib-0.43.0 → sdmxlib-0.44.0}/src/sdmxlib/model/metadataset.py

@@ -19,7 +19,7 @@ from collections.abc import Sequence
 from datetime import datetime
 from typing import Any, ClassVar, cast
 
-from attrs import define, evolve, field
+from attrs import define, evolve, field, frozen
 
 from sdmxlib.model.annotations import Annotations
 from sdmxlib.model.base import MaintainableArtefact
@@ -70,6 +70,29 @@ class ReportedAttribute:
     annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
 
 
+@frozen
+class MetadataSection:
+    """A flattened, MSD-typed view of one reported metadata value.
+
+    The retrieval projection of a MetadataSet: one ``MetadataSection`` per
+    ``metadata_value`` row, with the leaf attribute's declared data type
+    (``text_type``, e.g. ``"String"`` / ``"XHTML"``) joined in from the
+    MSD. This is the sectioned input a chunker / search indexer wants —
+    ``path`` gives the dotted hierarchical location (with ``[n]`` sibling
+    suffixes preserved), ``attribute_id`` the leaf id, and ``value`` the
+    scalar or ``InternationalString`` content.
+
+    Produced by ``Registry.metadata_report``.
+    """
+
+    path: str
+    attribute_id: str
+    sibling_index: int
+    value: ReportedAttributeValue | None = None
+    text_type: str | None = None
+    is_presentational: bool = False
+
+
 # ── MetadataSet ──────────────────────────────────────────────────────────