sdmxlib 0.19.2__tar.gz → 0.20.0__tar.gz

{sdmxlib-0.19.2 → sdmxlib-0.20.0}/PKG-INFO

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

{sdmxlib-0.19.2 → sdmxlib-0.20.0}/pyproject.toml

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

{sdmxlib-0.19.2 → sdmxlib-0.20.0}/src/sdmxlib/model/code_query.py

@@ -145,6 +145,23 @@ class _AnyAncestorMatches(Predicate):
     depth: int | None = None
 
 
+@attrs.frozen
+class _InHierarchy(Predicate):
+    """The code is a node in a Hierarchy, optionally at a named Level.
+
+    Compiles to ``EXISTS`` against ``sdmx.hierarchy_node`` joined on
+    ``code_urn``. EXISTS (rather than INNER JOIN) preserves row identity
+    when a code appears at multiple nodes in the same hierarchy.
+    """
+
+    hierarchy_urn: str
+    level_id: str | None = None
+
+    def level(self, level_id: str) -> _InHierarchy:
+        """Narrow membership to a named Level within the same Hierarchy."""
+        return attrs.evolve(self, level_id=level_id)
+
+
 # ── Sort keys ───────────────────────────────────────────────────────────
 
 
@@ -328,6 +345,26 @@ class _CodeAccessor:
         """Sub-query ref for descendants. Use ``.any(predicate)`` to compose."""
         return _NarrowerTransitiveSubRef(depth=depth)
 
+    def hierarchy(self, hierarchy: object) -> _InHierarchy:
+        """Predicate: code is a node in ``hierarchy``.
+
+        Accepts a URN string or any artefact with a maintainable URN
+        (e.g. a :class:`Hierarchy`). Chain ``.level(level_id)`` to narrow
+        to nodes at a specific Level:
+
+            q.filter(code.hierarchy(h).level("Province"))
+
+        Compiles to a single ``EXISTS`` against ``sdmx.hierarchy_node`` —
+        no row multiplication when a code appears at multiple nodes.
+        """
+        if isinstance(hierarchy, str):
+            urn = hierarchy
+        else:
+            from sdmxlib.model.in_memory_registry import artefact_urn  # noqa: PLC0415
+
+            urn = str(artefact_urn(hierarchy))
+        return _InHierarchy(hierarchy_urn=urn, level_id=None)
+
 
 code = _CodeAccessor()
 """Predicate accessor namespace — exposed at the top level as ``sl.code``."""
@@ -633,10 +670,33 @@ def _emit_predicate(
         return _emit_any_ancestor_matches(pred, row_alias=row_alias)
     if isinstance(pred, _AnyDescendantMatches):
         return _emit_any_descendant_matches(pred, row_alias=row_alias)
+    if isinstance(pred, _InHierarchy):
+        return _emit_in_hierarchy(pred, row_alias=row_alias)
     msg = f"Unsupported predicate kind: {type(pred).__name__}"
     raise NotImplementedError(msg)
 
 
+def _emit_in_hierarchy(pred: _InHierarchy, *, row_alias: str) -> tuple[str, list[object]]:
+    """Compile a Hierarchy/Level membership predicate to an EXISTS clause."""
+    inner = f"{row_alias}_hn"
+    if pred.level_id is None:
+        clause = (
+            f"EXISTS ("
+            f"SELECT 1 FROM sdmx.hierarchy_node {inner} "
+            f"WHERE {inner}.code_urn = {row_alias}.code_urn "
+            f"AND {inner}.hierarchy_urn = ?)"
+        )
+        return clause, [pred.hierarchy_urn]
+    clause = (
+        f"EXISTS ("
+        f"SELECT 1 FROM sdmx.hierarchy_node {inner} "
+        f"WHERE {inner}.code_urn = {row_alias}.code_urn "
+        f"AND {inner}.hierarchy_urn = ? "
+        f"AND {inner}.level_id = ?)"
+    )
+    return clause, [pred.hierarchy_urn, pred.level_id]
+
+
 def _emit_eq(
     pred: _Eq,
     *,