sdmxlib 0.44.0__tar.gz → 0.45.0__tar.gz

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

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

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

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

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

@@ -10,7 +10,7 @@ from sdmxlib.catalog import DataflowEntry, FederatedCatalog
 from sdmxlib.data_store import DataStore
 from sdmxlib.sql import CompileContext, Predicate, SqlRelation
 from sdmxlib.formats import parse, read, serialize, to_json, to_xml
-from sdmxlib.local import LazyCodelist, LazyHierarchy, Registry
+from sdmxlib.local import LazyCodelist, LazyHierarchy, QueryPlan, Registry, SchemaInspector
 from sdmxlib.local.data_store import DuckDBDataStore, DuckLakeVersionError
 from sdmxlib.rest import ComponentFilter, parse_components
 from sdmxlib.model.convert import from_dict, to_dict
@@ -206,6 +206,7 @@ __all__ = [
     "Predicate",
     "Provider",
     "ProvisionAgreement",
+    "QueryPlan",
     "Ref",
     "ReferenceIssue",
     "ReferencePeriod",
@@ -220,6 +221,7 @@ __all__ = [
     "Representation",
     "RepresentationMap",
     "RestRegistry",
+    "SchemaInspector",
     "SdmxRef",
     "SdmxUrn",
     "SqlRelation",

{sdmxlib-0.44.0 → sdmxlib-0.45.0}/src/sdmxlib/formats/sdmx_json/metadata.py

@@ -111,6 +111,10 @@ def _read_metadata_set(obj: dict[str, Any]) -> MetadataSet:
     targets = [Ref[Any].unresolved(SdmxUrn.parse(t)) for t in obj.get("targets") or []]
     attributes = [_read_reported_attribute(a) for a in obj.get("attributes") or []]
 
+    def _dt(key: str) -> datetime | None:
+        val = obj.get(key)
+        return datetime.fromisoformat(val) if isinstance(val, str) and val else None
+
     return MetadataSet(
         id=obj["id"],
         maintainer=Agency(id=obj.get("agencyID", "")),
@@ -119,6 +123,9 @@ def _read_metadata_set(obj: dict[str, Any]) -> MetadataSet:
         name=_read_istring(obj, "name"),
         description=_read_istring(obj, "description"),
         is_final=bool(obj.get("isFinal", False)),
+        # Writer emits validFrom/validTo; parse them back so they round-trip (#159).
+        valid_from=_dt("validFrom"),
+        valid_to=_dt("validTo"),
         targets=targets,
         attributes=ItemList(attributes),
     )

{sdmxlib-0.44.0 → sdmxlib-0.45.0}/src/sdmxlib/formats/sdmx_json/reader.py

@@ -5,7 +5,7 @@ All references within the message are auto-resolved where possible.
 """
 
 import warnings
-from datetime import datetime
+from datetime import date, datetime
 from typing import Any
 
 import orjson
@@ -45,11 +45,14 @@ from sdmxlib.model.mapping import (
     CategorySchemeMap,
     ComponentMap,
     ConceptSchemeMap,
+    IndexValueMap,
     ItemMap,
     LiteralValueMap,
     MapDataType,
+    RegexValueMap,
     RepresentationMap,
     StructureMap,
+    ValueMap,
 )
 from sdmxlib.model.message import StructureMessage
 from sdmxlib.model.metadataflow import Metadataflow
@@ -90,25 +93,43 @@ def _read_datetime_str(obj: dict[str, Any], key: str) -> datetime | None:
     return datetime.fromisoformat(val)
 
 
+def _annotation_url(ann: dict[str, Any]) -> str | None:
+    """Extract the annotation URL from its ``links`` entry (``rel: "self"``).
+
+    Per the SDMX-JSON 2.0 structure schema an annotation's URL rides in
+    the ``links`` array under the ``self`` relationship. Fall back to a
+    bare ``url`` key for lenience toward non-conformant producers.
+    """
+    links = ann.get("links")
+    if isinstance(links, list):
+        for link in links:
+            if isinstance(link, dict) and link.get("rel") == "self":
+                href = link.get("href")
+                if isinstance(href, str):
+                    return href
+    url = ann.get("url")
+    return url if isinstance(url, str) else None
+
+
 def _read_annotations(obj: dict[str, Any]) -> Annotations:
     """Parse the optional ``annotations`` array on any artefact."""
     raw = obj.get("annotations")
     if not raw:
         return Annotations()
-    items: list[Annotation] = []
-    for ann in raw:
-        text_raw = ann.get("text")
-        text = InternationalString.of(text_raw) if isinstance(text_raw, dict) else InternationalString()
-        items.append(
+    return Annotations(
+        [
             Annotation(
                 id=ann.get("id"),
                 title=ann.get("title"),
                 type=ann.get("type"),
-                url=ann.get("url"),
-                text=text,
+                url=_annotation_url(ann),
+                # SDMX-JSON 2.0: localised body splits into ``text`` (best
+                # match) + ``texts`` (lang map), same shape as name/desc.
+                text=_istring(ann, "text"),
             )
-        )
-    return Annotations(items)
+            for ann in raw
+        ]
+    )
 
 
 # ── Ref / URN helpers ─────────────────────────────────────────────────────────
@@ -459,6 +480,21 @@ def _read_attachment(
     return AttachmentLevel.DATASET, None, None, None
 
 
+def _read_concept_roles(obj: dict[str, Any]) -> tuple[str, ...]:
+    """Parse ``conceptRoles`` URN strings → tuple of role ids (item id)."""
+    roles: list[str] = []
+    for raw in obj.get("conceptRoles") or []:
+        if not isinstance(raw, str):
+            continue
+        try:
+            urn = SdmxUrn.parse(raw)
+        except (ValueError, TypeError):
+            continue
+        if urn.item_id is not None:
+            roles.append(urn.item_id)
+    return tuple(roles)
+
+
 def _read_dimension(dim: dict[str, Any], index: dict[str, Any]) -> Dimension:
     concept_ref = _resolve_urn(dim.get("conceptIdentity"), index)
     return Dimension(
@@ -466,6 +502,7 @@ def _read_dimension(dim: dict[str, Any], index: dict[str, Any]) -> Dimension:
         concept=concept_ref,
         representation=_read_representation(dim.get("localRepresentation"), index),
         annotations=_read_annotations(dim),
+        concept_role=_read_concept_roles(dim),
     )
 
 
@@ -499,6 +536,7 @@ def _read_attribute(attr: dict[str, Any], index: dict[str, Any]) -> Attribute:
         concept=concept_ref,
         representation=_read_representation(attr.get("localRepresentation"), index),
         annotations=_read_annotations(attr),
+        concept_role=_read_concept_roles(attr),
     )
 
 
@@ -509,6 +547,7 @@ def _read_measure(meas: dict[str, Any], index: dict[str, Any]) -> Measure:
         concept=concept_ref,
         representation=_read_representation(meas.get("localRepresentation"), index),
         annotations=_read_annotations(meas),
+        concept_role=_read_concept_roles(meas),
     )
 
 
@@ -742,6 +781,37 @@ def _read_mapped_value(arr: Any) -> str | None:
     return str(entry)
 
 
+def _read_value_map(m: dict[str, Any]) -> ValueMap | None:
+    """Reconstruct the correct ``ValueMap`` variant from a representationMapping.
+
+    The ``sourceValues`` MappedValueType entry discriminates the operation
+    via ``isRegEx`` (regex) or ``startIndex``/``endIndex`` (substring
+    slice); absent both it is a literal equality map. Reading only the
+    ``value`` collapses all three to literal (#159).
+    """
+    source_arr = m.get("sourceValues")
+    s_val = _read_mapped_value(source_arr)
+    t_val = _read_mapped_value(m.get("targetValues"))
+    if s_val is None or t_val is None:
+        return None
+    entry = source_arr[0] if isinstance(source_arr, list) and source_arr else {}
+    entry = entry if isinstance(entry, dict) else {}
+
+    def _d(key: str) -> date | None:
+        val = m.get(key)
+        return date.fromisoformat(val) if isinstance(val, str) and val else None
+
+    validity = {"valid_from": _d("validFrom"), "valid_to": _d("validTo")}
+    if entry.get("isRegEx") is True:
+        return RegexValueMap(source_value=s_val, target_value=t_val, **validity)
+    start, end = entry.get("startIndex"), entry.get("endIndex")
+    if isinstance(start, int) and isinstance(end, int):
+        return IndexValueMap(
+            source_value=s_val, target_value=t_val, source_start_index=start, source_end_index=end, **validity
+        )
+    return LiteralValueMap(source_value=s_val, target_value=t_val, **validity)
+
+
 def _read_structure_sets(
     data: dict[str, Any],
     index: dict[str, Any],
@@ -772,10 +842,9 @@ def _read_structure_sets(
     for rm in data.get("representationMaps") or []:
         value_maps = []
         for m in rm.get("representationMappings") or []:
-            s_val = _read_mapped_value(m.get("sourceValues"))
-            t_val = _read_mapped_value(m.get("targetValues"))
-            if s_val is not None and t_val is not None:
-                value_maps.append(LiteralValueMap(source_value=s_val, target_value=t_val))
+            vm = _read_value_map(m)
+            if vm is not None:
+                value_maps.append(vm)
         rep_maps.append(
             RepresentationMap(
                 id=rm.get("id", ""),
@@ -786,6 +855,7 @@ def _read_structure_sets(
                 source=_read_map_endpoint(rm.get("source"), index),
                 target=_read_map_endpoint(rm.get("target"), index),
                 maps=tuple(value_maps),
+                annotations=_read_annotations(rm),
             )
         )
     for csm in data.get("conceptSchemeMaps") or []:
@@ -804,6 +874,7 @@ def _read_structure_sets(
                 source=_resolve_urn(csm.get("source"), index),
                 target=_resolve_urn(csm.get("target"), index),
                 maps=tuple(item_maps),
+                annotations=_read_annotations(csm),
             )
         )
     for catm in data.get("categorySchemeMaps") or []:
@@ -822,6 +893,7 @@ def _read_structure_sets(
                 source=_resolve_urn(catm.get("source"), index),
                 target=_resolve_urn(catm.get("target"), index),
                 maps=tuple(item_maps),
+                annotations=_read_annotations(catm),
             )
         )
     for sm in data.get("structureMaps") or []:
@@ -840,6 +912,7 @@ def _read_structure_sets(
                 source=_resolve_urn(sm.get("source"), index),
                 target=_resolve_urn(sm.get("target"), index),
                 maps=tuple(comp_maps),
+                annotations=_read_annotations(sm),
             )
         )
 
@@ -883,6 +956,8 @@ def _read_hierarchical_code(
         children=children,
         annotations=_read_annotations(obj),
         level=level,
+        valid_from=_read_datetime_str(obj, "validFrom"),
+        valid_to=_read_datetime_str(obj, "validTo"),
     )
 
 
@@ -899,10 +974,15 @@ def _read_hierarchies(
         levels_by_id: dict[str, Level] = {}
         node = h.get("level")
         while isinstance(node, dict):
+            coding = node.get("codingFormat")
+            # codingFormat is always a text format (never an enumeration), so
+            # the resolution index is unused — pass an empty one.
+            coding_facet = _read_representation({"format": coding}, {}) if isinstance(coding, dict) else None
             lv = Level(
                 id=node["id"],
                 name=_istring(node, "name"),
                 description=_istring(node, "description"),
+                coding_format=coding_facet if isinstance(coding_facet, Facet) else None,
                 annotations=_read_annotations(node),
             )
             levels.append(lv)
@@ -918,6 +998,7 @@ def _read_hierarchies(
                 name=_istring(h, "name"),
                 description=_istring(h, "description"),
                 is_final=bool(h.get("isFinal", False)),
+                has_formal_levels=bool(h.get("hasFormalLevels", False)),
                 levels=levels,
                 tree=tree,
                 annotations=_read_annotations(h),

{sdmxlib-0.44.0 → sdmxlib-0.45.0}/src/sdmxlib/formats/sdmx_json/structure_values.py

@@ -20,6 +20,7 @@ What it does NOT own:
 
 from typing import Any
 
+from sdmxlib.model.annotations import Annotation
 from sdmxlib.model.codelist import Code, Codelist
 from sdmxlib.model.concept import Concept, ConceptScheme
 from sdmxlib.model.istring import InternationalString
@@ -37,13 +38,44 @@ def _emit_istring(obj: dict[str, Any], key: str, value: InternationalString | No
     """
     if not value:
         return
-    pairs = dict(value.items())
-    if not pairs:
-        return
+    pairs = value.as_dict()
     obj[key] = next(iter(pairs.values()))
     obj[key + "s"] = pairs
 
 
+def _annotation_dict(ann: Annotation) -> dict[str, Any]:
+    """Render one ``Annotation`` as a SDMX-JSON 2.0 ``annotations[*]`` entry.
+
+    Follows the structure-schema shape: ``id`` / ``title`` / ``type``
+    scalars (omitted when None), ``text`` + ``texts`` for the localised
+    body, and the annotation ``url`` as a ``links`` entry with
+    ``rel: "self"`` (per the schema's Annotation.links contract).
+    """
+    out: dict[str, Any] = {}
+    if ann.id is not None:
+        out["id"] = ann.id
+    if ann.title is not None:
+        out["title"] = ann.title
+    if ann.type is not None:
+        out["type"] = ann.type
+    _emit_istring(out, "text", ann.text)
+    if ann.url is not None:
+        out["links"] = [{"rel": "self", "href": ann.url}]
+    return out
+
+
+def emit_annotations(obj: dict[str, Any], artefact: Any) -> None:
+    """Set ``obj["annotations"]`` from ``artefact.annotations`` when present.
+
+    Shared by every artefact- and item-level SDMX-JSON writer so annotations
+    round-trip through the reader. No-op when the artefact carries none.
+    """
+    annotations = getattr(artefact, "annotations", None)
+    if not annotations:
+        return
+    obj["annotations"] = [_annotation_dict(a) for a in annotations]
+
+
 def serialize_code(code: Code) -> dict[str, Any]:
     """Render one ``Code`` as a SDMX-JSON ``codelists[*].codes[*]`` entry.
 
@@ -59,6 +91,7 @@ def serialize_code(code: Code) -> dict[str, Any]:
     _emit_istring(obj, "description", code.description)
     if code.parent_id is not None:
         obj["parent"] = code.parent_id
+    emit_annotations(obj, code)
     return obj
 
 
@@ -100,6 +133,7 @@ def serialize_concept(concept: Concept) -> dict[str, Any]:
         tf = {k: v for k, v in pairs if v is not None}
         if tf:
             obj["coreRepresentation"] = {"format": tf}
+    emit_annotations(obj, concept)
     return obj