sdmxlib 0.16.2__tar.gz → 0.17.1__tar.gz

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.16.2
+Version: 0.17.1
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner
@@ -17,6 +17,7 @@ Requires-Dist: duckdb>=1.0.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: lxml>=6.0.2
 Requires-Dist: polars>=1.39.3
+Requires-Dist: pyarrow>=18.0.0
 Requires-Python: >=3.13
 Project-URL: Homepage, https://gitlab.com/pinax-suite/sdmxlib
 Project-URL: Repository, https://gitlab.com/pinax-suite/sdmxlib

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.16.2"
+version = "0.17.1"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -21,6 +21,7 @@ dependencies = [
     "httpx>=0.28.1",
     "lxml>=6.0.2",
     "polars>=1.39.3",
+    "pyarrow>=18.0.0",
 ]
 
 [project.urls]

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/__init__.py

@@ -11,6 +11,7 @@ from sdmxlib.data_store import DataStore
 from sdmxlib.formats import parse, read, serialize, to_json, to_xml
 from sdmxlib.local import LazyCodelist, LocalRegistry
 from sdmxlib.local._data_store import DuckDBDataStore
+from sdmxlib.rest import KeyFilter, parse_key
 from sdmxlib.model.convert import from_dict, to_dict
 from sdmxlib.model.validation import ReferenceIssue, ValidationIssue, validate, validate_references
 from sdmxlib.model import (
@@ -148,6 +149,7 @@ __all__ = [
     "ItemExpr",
     "ItemList",
     "ItemPredicate",
+    "KeyFilter",
     "KeyValue",
     "LazyCodelist",
     "Level",
@@ -186,6 +188,7 @@ __all__ = [
     "from_dict",
     "item",
     "parse",
+    "parse_key",
     "read",
     "serialize",
     "to_dict",

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/catalog.py

@@ -43,6 +43,7 @@ Example:
 
 from __future__ import annotations
 
+from collections.abc import Iterator
 from typing import TYPE_CHECKING
 
 import polars as pl
@@ -55,9 +56,12 @@ from sdmxlib.model.istring import InternationalString
 from sdmxlib.model.ref import Ref
 
 if TYPE_CHECKING:
+    import pyarrow as pa
+
     from sdmxlib.data_store import DataStore
     from sdmxlib.model.registry import Registry
     from sdmxlib.model.urn import SdmxUrn
+    from sdmxlib.rest import KeyFilter
 
 
 @frozen
@@ -132,6 +136,7 @@ class FederatedCatalog:
         *,
         where: list[str] | None = None,
         params: list[object] | None = None,
+        key_filter: KeyFilter | None = None,
         columns: list[str] | None = None,
         order_by: str | None = None,
         limit: int | None = None,
@@ -146,6 +151,9 @@ class FederatedCatalog:
                 from ``bindings``.
             where: Optional list of SQL WHERE-clause fragments.
             params: Positional parameters for the WHERE clauses.
+            key_filter: Optional :class:`~sdmxlib.rest.KeyFilter` parsed
+                from an SDMX REST dotted key. ANDed with ``where`` after
+                translation via the binding's dimension column map.
             columns: Optional column projection.
             order_by: Optional SQL ORDER BY clause.
             limit: Optional row cap.
@@ -189,6 +197,7 @@ class FederatedCatalog:
             binding,
             where=where,
             params=params,
+            key_filter=key_filter,
             columns=columns,
             order_by=order_by,
             limit=limit,
@@ -205,6 +214,62 @@ class FederatedCatalog:
 
         return df
 
+    def query_stream(
+        self,
+        dataflow_urn: SdmxUrn[Dataflow],
+        *,
+        where: list[str] | None = None,
+        params: list[object] | None = None,
+        key_filter: KeyFilter | None = None,
+        columns: list[str] | None = None,
+        order_by: str | None = None,
+        chunk_rows: int = 10_000,
+    ) -> Iterator[pa.RecordBatch]:
+        """Stream observations as Arrow record batches.
+
+        Mirrors :meth:`query` (binding lookup → scan) but skips the
+        labelling step — labels are a DataFrame transform that doesn't
+        compose cleanly with streaming. Callers that need labelled
+        streaming output should join codelists themselves on the way to
+        their sink.
+
+        Args:
+            dataflow_urn: As :meth:`query`.
+            where: As :meth:`query`.
+            params: As :meth:`query`.
+            key_filter: As :meth:`query`.
+            columns: As :meth:`query`.
+            order_by: As :meth:`query`.
+            chunk_rows: Target rows per emitted record batch.
+
+        Yields:
+            One :class:`pyarrow.RecordBatch` at a time, in scan order.
+
+        Raises:
+            KeyError: If no binding exists for ``dataflow_urn``.
+        """
+        binding_urn = DataflowBinding.urn(
+            agency=dataflow_urn.agency,
+            id=dataflow_urn.id,
+            version=dataflow_urn.version,
+        )
+        binding = self._bindings.get(binding_urn)
+        if binding is None:
+            err = f"No DataflowBinding found for {dataflow_urn}. Add a binding to the bindings registry first."
+            raise KeyError(err)
+        if not isinstance(binding, DataflowBinding):
+            err = f"Expected DataflowBinding for {binding_urn}, got {type(binding).__name__}"
+            raise TypeError(err)
+        yield from self._data.query_stream(
+            binding,
+            where=where,
+            params=params,
+            key_filter=key_filter,
+            columns=columns,
+            order_by=order_by,
+            chunk_rows=chunk_rows,
+        )
+
     def browse(self) -> list[DataflowEntry]:
         """Enumerate every locally-bound dataflow with provenance annotations.
 

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/data_store.py

@@ -16,12 +16,20 @@ or DSDs. Result annotation (joining labels onto code columns) is the
 structural side.
 """
 
-from typing import Protocol, runtime_checkable
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 import polars as pl
 
 from sdmxlib.model.binding import DataflowBinding
 
+if TYPE_CHECKING:
+    import pyarrow as pa
+
+    from sdmxlib.rest import KeyFilter
+
 
 @runtime_checkable
 class DataStore(Protocol):
@@ -37,6 +45,7 @@ class DataStore(Protocol):
         *,
         where: list[str] | None = None,
         params: list[object] | None = None,
+        key_filter: KeyFilter | None = None,
         columns: list[str] | None = None,
         order_by: str | None = None,
         limit: int | None = None,
@@ -51,6 +60,10 @@ class DataStore(Protocol):
             params: Positional parameters interpolated into the WHERE
                 fragments via the backend's parameterisation. Must be
                 separately passed (not f-stringed) to avoid SQL injection.
+            key_filter: Optional :class:`~sdmxlib.rest.KeyFilter` parsed
+                from an SDMX REST dotted key. Translated to additional
+                WHERE-IN clauses against ``binding.dimension_column_map``;
+                ANDed with any caller-supplied ``where`` fragments.
             columns: Optional projection. ``None`` = all columns. Names
                 are SDMX-side; binding maps them to physical columns.
             order_by: Optional SQL ORDER BY clause (e.g.
@@ -62,3 +75,36 @@ class DataStore(Protocol):
             named on the SDMX side (mapped from physical via the binding).
         """
         ...
+
+    def query_stream(
+        self,
+        binding: DataflowBinding,
+        *,
+        where: list[str] | None = None,
+        params: list[object] | None = None,
+        key_filter: KeyFilter | None = None,
+        columns: list[str] | None = None,
+        order_by: str | None = None,
+        chunk_rows: int = 10_000,
+    ) -> Iterator[pa.RecordBatch]:
+        """Same scan as :meth:`query` but streamed in Arrow record batches.
+
+        Lets bulk callers process or stream a result of arbitrary size in
+        bounded memory — peak RSS is roughly ``chunk_rows * row_bytes``
+        rather than ``num_rows * row_bytes``. The natural sink is a
+        format writer (e.g. :func:`sdmxlib.formats.sdmx_csv.write_sdmx_csv`).
+
+        Args:
+            binding: As :meth:`query`.
+            where: As :meth:`query`.
+            params: As :meth:`query`.
+            key_filter: As :meth:`query`.
+            columns: As :meth:`query`.
+            order_by: As :meth:`query`. Note that ordering may force the
+                backend to materialise everything before streaming.
+            chunk_rows: Target number of rows per emitted batch.
+
+        Yields:
+            One :class:`pyarrow.RecordBatch` at a time, in scan order.
+        """
+        ...

sdmxlib-0.17.1/src/sdmxlib/formats/sdmx_csv/__init__.py

@@ -0,0 +1,6 @@
+"""SDMX-CSV data message reader and writer."""
+
+from sdmxlib.formats.sdmx_csv.reader import scan_csv
+from sdmxlib.formats.sdmx_csv.writer import write_sdmx_csv
+
+__all__ = ["scan_csv", "write_sdmx_csv"]

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/formats/sdmx_csv/reader.py

@@ -31,6 +31,10 @@ if TYPE_CHECKING:
 
 _DATAFLOW_COL = "DATAFLOW"
 _KEY_COL = "KEY"
+# SDMX-CSV 2.0.0 envelope columns — not DSD components, dropped on read.
+_STRUCTURE_COL = "STRUCTURE"
+_STRUCTURE_ID_COL = "STRUCTURE_ID"
+_ACTION_COL = "ACTION"
 _DATAFLOW_RE = re.compile(r"^([^:]+):([^(]+)\(([^)]+)\)$")
 
 
@@ -60,9 +64,12 @@ def _peek_dataflow_id(source: "str | Path | bytes") -> str | None:
         header = next(reader)
     except StopIteration:
         return None
-    try:
-        df_idx = header.index(_DATAFLOW_COL)
-    except ValueError:
+    df_idx: int | None = None
+    for col in (_DATAFLOW_COL, _STRUCTURE_ID_COL):
+        if col in header:
+            df_idx = header.index(col)
+            break
+    if df_idx is None:
         return None
     try:
         first_row = next(reader)
@@ -138,9 +145,17 @@ def scan_csv(
             infer_schema_length=infer_schema_length,
         ).lazy()
 
-    # Drop metadata columns that are not DSD components.
+    # Drop metadata columns that are not DSD components. Covers both
+    # SDMX-CSV 1.0 (DATAFLOW, KEY) and 2.0 (STRUCTURE, STRUCTURE_ID, ACTION).
     col_names = lf.collect_schema().names()
-    to_drop = [c for c in (_DATAFLOW_COL, _KEY_COL) if c in col_names]
+    envelope_cols = (
+        _DATAFLOW_COL,
+        _KEY_COL,
+        _STRUCTURE_COL,
+        _STRUCTURE_ID_COL,
+        _ACTION_COL,
+    )
+    to_drop = [c for c in envelope_cols if c in col_names]
     if to_drop:
         lf = lf.drop(to_drop)
 

sdmxlib-0.17.1/src/sdmxlib/formats/sdmx_csv/writer.py

@@ -0,0 +1,137 @@
+"""SDMX-CSV 2.0.0 data writer (streaming).
+
+Consumes an iterator of Arrow record batches (typically from
+:meth:`sdmxlib.DataStore.query_stream`) and emits SDMX-CSV bytes one
+chunk at a time. The header is emitted once with the first chunk;
+subsequent chunks contain data rows only.
+
+SDMX-CSV 2.0.0 header layout::
+
+    STRUCTURE,STRUCTURE_ID,ACTION,<dim cols>,<measure cols>,<attribute cols>
+
+where:
+
+- ``STRUCTURE`` is the artefact type ("dataflow" / "datastructure" /
+  "provisionagreement"). Defaults to ``"dataflow"``.
+- ``STRUCTURE_ID`` is ``AGENCY:ID(VERSION)``. The caller passes this
+  in — typically derived from the bound dataflow's URN.
+- ``ACTION`` is one of ``I`` / ``R`` / ``A`` / ``D`` (Insert / Replace /
+  Append / Delete). Defaults to ``"I"``.
+
+Dim/measure/attribute column ordering is taken from the binding's
+column maps in their dict-insertion order, which matches the order in
+which they were declared on the binding.
+
+Performance: rows are serialised via Polars' Rust CSV writer
+(``pl.from_arrow(batch).write_csv``) rather than Python's :mod:`csv`,
+which makes the writer fast enough that bulk SDMX-CSV downloads are
+network-bound rather than writer-bound (#61).
+
+Example:
+    from sdmxlib.formats.sdmx_csv import write_sdmx_csv
+
+    chunks = write_sdmx_csv(
+        catalog.query_stream(flow_urn, key_filter=kf),
+        binding,
+        structure_id="ESTAT:STS_INPR_M(1.0)",
+    )
+    with open("out.csv", "wb") as f:
+        for b in chunks:
+            f.write(b)
+"""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING
+
+import polars as pl
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    import pyarrow as pa
+
+    from sdmxlib.model.binding import DataflowBinding
+
+
+def write_sdmx_csv(
+    batches: Iterable[pa.RecordBatch],
+    binding: DataflowBinding,
+    *,
+    structure_id: str,
+    structure: str = "dataflow",
+    action: str = "I",
+) -> Iterator[bytes]:
+    """Stream SDMX-CSV 2.0.0 bytes for a sequence of Arrow record batches.
+
+    Args:
+        batches: Iterable of :class:`pyarrow.RecordBatch` (e.g. the output
+            of :meth:`sdmxlib.FederatedCatalog.query_stream`). Each batch
+            must contain every column listed in the binding's column maps.
+        binding: The :class:`~sdmxlib.model.binding.DataflowBinding`.
+            Determines column order in the output: dimensions, then
+            measures, then attributes, each in the binding's
+            dict-insertion order.
+        structure_id: The ``AGENCY:ID(VERSION)`` identifier emitted in
+            the ``STRUCTURE_ID`` column on every row.
+        structure: Value emitted in the ``STRUCTURE`` column. SDMX-CSV
+            allows ``"dataflow"``, ``"datastructure"``, or
+            ``"provisionagreement"``. Defaults to ``"dataflow"``.
+        action: Value emitted in the ``ACTION`` column. One of ``I``
+            (Insert), ``R`` (Replace), ``A`` (Append), ``D`` (Delete).
+            Defaults to ``"I"``.
+
+    Yields:
+        UTF-8 bytes — header on the first chunk, data rows on every
+        chunk including the first. Each yielded ``bytes`` is one record
+        batch's worth of CSV.
+
+    Raises:
+        KeyError: If a batch is missing a column the binding declares.
+    """
+    dim_cols = list(binding.dimension_column_map.values())
+    measure_cols = list(binding.measure_column_map.values())
+    attr_cols = list(binding.attribute_column_map.values())
+    data_cols = [*dim_cols, *measure_cols, *attr_cols]
+    out_cols = ["STRUCTURE", "STRUCTURE_ID", "ACTION", *data_cols]
+
+    # Header is plain bytes — one line, never quoted by polars' writer
+    # because none of the column names contain commas or newlines.
+    header_bytes = (",".join(out_cols) + "\n").encode("utf-8")
+    header_emitted = False
+
+    for batch in batches:
+        missing = [c for c in data_cols if c not in batch.schema.names]
+        if missing:
+            msg = (
+                f"Record batch is missing column(s) {missing!r} declared by "
+                f"the binding. Available columns: {batch.schema.names}"
+            )
+            raise KeyError(msg)
+
+        df = (
+            pl.from_arrow(batch)
+            .select(data_cols)  # type: ignore[union-attr]
+            .with_columns(
+                pl.lit(structure).alias("STRUCTURE"),
+                pl.lit(structure_id).alias("STRUCTURE_ID"),
+                pl.lit(action).alias("ACTION"),
+            )
+            .select(out_cols)
+        )
+
+        buf = io.BytesIO()
+        df.write_csv(buf, include_header=False)
+        body = buf.getvalue()
+
+        if not header_emitted:
+            yield header_bytes + body
+            header_emitted = True
+        else:
+            yield body
+
+    if not header_emitted:
+        # Empty stream — emit just the header so consumers get a valid
+        # (if empty) SDMX-CSV file.
+        yield header_bytes

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/local/_data_store.py

@@ -14,6 +14,7 @@ this lands, cenprof's bespoke engine becomes a 4-line catalog setup.
 
 from __future__ import annotations
 
+from collections.abc import Iterator
 from typing import TYPE_CHECKING
 
 import polars as pl
@@ -22,8 +23,10 @@ from sdmxlib.model.binding import DataflowBinding
 
 if TYPE_CHECKING:
     import duckdb
+    import pyarrow as pa
 
     from sdmxlib.local._registry import LocalRegistry
+    from sdmxlib.rest import KeyFilter
 
 
 class DuckDBDataStore:
@@ -98,6 +101,7 @@ class DuckDBDataStore:
         *,
         where: list[str] | None = None,
         params: list[object] | None = None,
+        key_filter: KeyFilter | None = None,
         columns: list[str] | None = None,
         order_by: str | None = None,
         limit: int | None = None,
@@ -109,15 +113,24 @@ class DuckDBDataStore:
         assume identity mapping (SDMX id == physical column) — when
         non-identity mappings are needed, this method is the seam to
         wire in the rename.
+
+        When ``binding.series_attributes_location`` is set, the sidecar
+        table is LEFT JOINed on the columns common to both tables (found
+        via DuckDB ``DESCRIBE``). This is what makes
+        ``binding.attribute_column_map`` columns reachable when the
+        attributes live on a sibling table rather than denormalised into
+        the fact table.
         """
-        sql = _build_select(
-            table=binding.table_location,
-            columns=columns,
+        sql, sql_params = _build_query(
+            conn=self._conn,
+            binding=binding,
             where=where,
+            params=params,
+            key_filter=key_filter,
+            columns=columns,
             order_by=order_by,
             limit=limit,
         )
-        sql_params = list(params or [])
         cur = self._conn.execute(sql, sql_params)
         col_names = [d[0] for d in cur.description] if cur.description else []
         rows = cur.fetchall()
@@ -125,34 +138,105 @@ class DuckDBDataStore:
             return pl.DataFrame(schema=col_names)
         return pl.from_records(rows, schema=col_names, orient="row")
 
+    def query_stream(
+        self,
+        binding: DataflowBinding,
+        *,
+        where: list[str] | None = None,
+        params: list[object] | None = None,
+        key_filter: KeyFilter | None = None,
+        columns: list[str] | None = None,
+        order_by: str | None = None,
+        chunk_rows: int = 10_000,
+    ) -> Iterator[pa.RecordBatch]:
+        """Stream the same scan as :meth:`query` as Arrow record batches.
+
+        Uses DuckDB's Arrow integration (``to_arrow_reader``) so peak
+        memory stays roughly proportional to ``chunk_rows`` rather than
+        the full result size. See :meth:`sdmxlib.DataStore.query_stream`.
+        """
+        sql, sql_params = _build_query(
+            conn=self._conn,
+            binding=binding,
+            where=where,
+            params=params,
+            key_filter=key_filter,
+            columns=columns,
+            order_by=order_by,
+            limit=None,
+        )
+        reader = self._conn.execute(sql, sql_params).to_arrow_reader(chunk_rows)
+        yield from reader
+
 
 # ── SQL helpers ─────────────────────────────────────────────────────────
 
 
-def _build_select(
+def _build_query(
     *,
-    table: str,
-    columns: list[str] | None,
+    conn: duckdb.DuckDBPyConnection,
+    binding: DataflowBinding,
     where: list[str] | None,
+    params: list[object] | None,
+    key_filter: KeyFilter | None,
+    columns: list[str] | None,
     order_by: str | None,
     limit: int | None,
-) -> str:
-    """Build a parameterised SELECT against ``table``.
-
-    The table name is interpolated as-is (it comes from the binding,
-    which is a sdmxlib-controlled artefact). WHERE clauses are also
-    interpolated as-is (callers compose them) but their values must
-    be passed via ``params`` for parameterisation — never f-stringed.
+) -> tuple[str, list[object]]:
+    """Build a parameterised SELECT + parameter list against the binding's table(s).
+
+    Table names come from the binding (sdmxlib-controlled artefact) and
+    are interpolated as-is. WHERE clauses are interpolated as-is too
+    (callers compose them) but their values must be passed via ``params``
+    for parameterisation — never f-stringed.
+
+    When ``binding.series_attributes_location`` is set, the sidecar table
+    is LEFT JOINed on the columns common to both tables. When ``key_filter``
+    is provided, it is translated to additional ``col IN (?, ?, ...)``
+    fragments via ``binding.dimension_column_map`` and ANDed in.
     """
     cols_sql = ", ".join(columns) if columns else "*"
-    sql = f"SELECT {cols_sql} FROM {table}"
-    if where:
-        sql += " WHERE " + " AND ".join(where)
+    main = binding.table_location
+    sidecar = binding.series_attributes_location
+    if sidecar is None:
+        sql = f"SELECT {cols_sql} FROM {main}"
+    else:
+        join_keys = _shared_columns(conn, main, sidecar)
+        if not join_keys:
+            msg = (
+                f"DataflowBinding.series_attributes_location {sidecar!r} "
+                f"shares no columns with {main!r}; cannot derive JOIN keys"
+            )
+            raise ValueError(msg)
+        keys_sql = ", ".join(join_keys)
+        sql = f"SELECT {cols_sql} FROM {main} LEFT JOIN {sidecar} USING ({keys_sql})"
+
+    fragments = list(where or [])
+    sql_params: list[object] = list(params or [])
+    if key_filter is not None:
+        kf_fragments, kf_params = key_filter.to_where_clauses(binding.dimension_column_map)
+        fragments.extend(kf_fragments)
+        sql_params.extend(kf_params)
+
+    if fragments:
+        sql += " WHERE " + " AND ".join(fragments)
     if order_by:
         sql += f" ORDER BY {order_by}"
     if limit is not None:
         sql += f" LIMIT {int(limit)}"
-    return sql
+    return sql, sql_params
+
+
+def _describe_columns(conn: duckdb.DuckDBPyConnection, table: str) -> list[str]:
+    """Return column names for ``table`` via DuckDB ``DESCRIBE``."""
+    rows = conn.execute(f"DESCRIBE {table}").fetchall()
+    return [str(r[0]) for r in rows]
+
+
+def _shared_columns(conn: duckdb.DuckDBPyConnection, table_a: str, table_b: str) -> list[str]:
+    """Columns present in both tables, in ``table_a`` order."""
+    cols_b = set(_describe_columns(conn, table_b))
+    return [c for c in _describe_columns(conn, table_a) if c in cols_b]
 
 
 def _sql_identifier(name: str) -> str:

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/model/base.py

@@ -59,3 +59,30 @@ class MaintainableArtefact:
             id=id,
             version=version,
         )
+
+    @classmethod
+    def parse_rest_ref(cls, ref: str) -> SdmxUrn[Self]:
+        """Parse an SDMX REST comma-separated artefact reference.
+
+        SDMX REST URLs identify a maintainable artefact as
+        ``AGENCY,ID,VERSION``. Symmetric with :meth:`urn`.
+
+        Example:
+            Dataflow.parse_rest_ref("ESTAT,STS_INPR_M,1.0")
+
+        Args:
+            ref: Comma-separated ``AGENCY,ID,VERSION`` string.
+
+        Returns:
+            A typed :class:`SdmxUrn` for this artefact class.
+
+        Raises:
+            ValueError: If ``ref`` does not have exactly three
+                comma-separated parts.
+        """
+        parts = ref.split(",")
+        if len(parts) != 3:
+            msg = f"REST ref {ref!r} must be 'AGENCY,ID,VERSION' (got {len(parts)} parts)"
+            raise ValueError(msg)
+        agency, id_, version = parts
+        return cls.urn(agency=agency, id=id_, version=version)

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/model/datastructure.py

@@ -260,6 +260,23 @@ class DataStructure(MaintainableArtefact):
         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 key_dimensions(self) -> list[Dimension | TimeDimension]:
+        """Dimension components in SDMX-key order — regular dimensions then time.
+
+        This is the canonical ordering for SDMX REST keys (e.g. ``CA+US.M.2021``).
+        ``dimensions`` excludes the time dimension; this property includes it.
+        """
+        dims: list[Dimension | TimeDimension] = list(self.dimensions)
+        if self.time_dimension is not None:
+            dims.append(self.time_dimension)
+        return dims
+
+    @property
+    def key_dimension_ids(self) -> list[str]:
+        """Component ids in SDMX-key order. See :attr:`key_dimensions`."""
+        return [d.id for d in self.key_dimensions]
+
     @property
     def enumerated_dimensions(self) -> ItemList[Dimension]:
         """Dimensions that are constrained to a codelist."""

{sdmxlib-0.16.2 → sdmxlib-0.17.1}/src/sdmxlib/model/message.py

@@ -88,6 +88,45 @@ class StructureMessage:
             *self.metadataflows,
         ]
 
+    @classmethod
+    def containing(cls, artefact: Any) -> StructureMessage:
+        """Wrap a single structural artefact in a fresh :class:`StructureMessage`.
+
+        Dispatches on the artefact's runtime type to the matching
+        collection slot (``Codelist`` → ``codelists``, ``Dataflow`` →
+        ``dataflows``, …) using the artefact class's ``msg_field``
+        ClassVar. Saves REST handlers from a long ``isinstance`` chain.
+
+        Example:
+            return StructureMessage.containing(dataflow)
+            # equivalent to: StructureMessage(dataflows=[dataflow])
+
+        Args:
+            artefact: A maintainable artefact whose type maps to one of
+                this message's slots.
+
+        Raises:
+            TypeError: If the artefact's class has no ``msg_field`` or
+                its ``msg_field`` is not a slot on
+                :class:`StructureMessage`.
+        """
+        slot = getattr(type(artefact), "msg_field", None)
+        if not isinstance(slot, str):
+            msg = (
+                f"StructureMessage.containing: {type(artefact).__name__} has no "
+                f"msg_field — not a known maintainable artefact"
+            )
+            raise TypeError(msg)
+        valid_slots = {a.name for a in cls.__attrs_attrs__}  # type: ignore[attr-defined]
+        if slot not in valid_slots:
+            msg = (
+                f"StructureMessage.containing: {type(artefact).__name__} maps to "
+                f"slot {slot!r} which is not a StructureMessage field "
+                f"(valid: {sorted(valid_slots)})"
+            )
+            raise TypeError(msg)
+        return cls(**{slot: [artefact]})
+
 
 @frozen
 class MetadataMessage:

sdmxlib-0.17.1/src/sdmxlib/rest.py

@@ -0,0 +1,130 @@
+"""SDMX REST utilities — URL/key parsing shared by REST facades.
+
+The SDMX REST API identifies a slice of a dataflow with a *dotted key*:
+each dimension's allowed values, separated by ``.``, with ``+`` joining
+alternatives within one dimension and an empty segment meaning "any value".
+The shorthand ``all`` (or the empty string) means "every observation".
+
+This module turns those keys into :class:`KeyFilter`, a structured filter
+that data stores translate to their own query language. Keeping the parser
+here means every facade gets the same wildcard / mismatch / OR semantics.
+
+Example:
+    >>> kf = parse_key("CA+US.M.2021", ["GEO", "FREQ", "TIME_PERIOD"])
+    >>> kf.dimension_ids
+    ['GEO', 'FREQ', 'TIME_PERIOD']
+    >>> kf.segments
+    [['CA', 'US'], ['M'], ['2021']]
+    >>> kf = parse_key("all", ["GEO", "FREQ", "TIME_PERIOD"])
+    >>> kf.is_wildcard
+    True
+"""
+
+from __future__ import annotations
+
+from attrs import frozen
+
+
+@frozen
+class KeyFilter:
+    """Structured form of an SDMX REST dotted key.
+
+    Self-describing: the filter carries the dimension ids it was built
+    against alongside the per-dimension allowed values (``None`` = wildcard,
+    list = OR semantics). Data stores translate it to WHERE-IN clauses
+    via :meth:`to_where_clauses`.
+
+    Attributes:
+        dimension_ids: Dimension ids in DSD-key order.
+        segments: Parallel list — ``segments[i]`` constrains
+            ``dimension_ids[i]``. ``None`` means no constraint.
+    """
+
+    dimension_ids: list[str]
+    segments: list[list[str] | None]
+
+    def __attrs_post_init__(self) -> None:
+        if len(self.dimension_ids) != len(self.segments):
+            msg = (
+                f"KeyFilter has {len(self.dimension_ids)} dimension_ids but "
+                f"{len(self.segments)} segments — must be parallel arrays"
+            )
+            raise ValueError(msg)
+
+    @property
+    def is_wildcard(self) -> bool:
+        """True if every dimension is unconstrained."""
+        return all(s is None for s in self.segments)
+
+    def to_where_clauses(self, column_map: dict[str, str]) -> tuple[list[str], list[object]]:
+        """Render this filter as ``(where_fragments, params)``.
+
+        Each constrained dimension becomes one ``"col IN (?, ?, ...)"``
+        fragment with values appended to ``params`` in order. Wildcard
+        segments are skipped.
+
+        Args:
+            column_map: SDMX dimension id → physical column name. Usually
+                ``binding.dimension_column_map``.
+
+        Returns:
+            A pair of ``(fragments, params)`` ready to pass through to
+            :meth:`sdmxlib.DataStore.query` as ``where=`` and ``params=``.
+
+        Raises:
+            KeyError: If a constrained dimension is not in ``column_map``.
+        """
+        fragments: list[str] = []
+        params: list[object] = []
+        for dim_id, seg in zip(self.dimension_ids, self.segments, strict=True):
+            if seg is None:
+                continue
+            if dim_id not in column_map:
+                msg = (
+                    f"KeyFilter constrains dimension {dim_id!r} but it is not "
+                    f"in column_map (have: {sorted(column_map)})"
+                )
+                raise KeyError(msg)
+            col = column_map[dim_id]
+            placeholders = ", ".join(["?"] * len(seg))
+            fragments.append(f"{col} IN ({placeholders})")
+            params.extend(seg)
+        return fragments, params
+
+
+def parse_key(key: str, key_dimension_ids: list[str]) -> KeyFilter:
+    """Parse an SDMX REST dotted key into a :class:`KeyFilter`.
+
+    Args:
+        key: The dotted-key fragment from the URL. ``"all"`` and ``""``
+            both mean "every observation". Empty segments are wildcards.
+            ``+`` joins alternatives within a single dimension.
+        key_dimension_ids: Dimension ids in DSD key order. Used both to
+            size the result and to validate the segment count.
+
+    Returns:
+        A :class:`KeyFilter` with one entry per dimension.
+
+    Raises:
+        ValueError: If the key has a different number of segments than
+            ``key_dimension_ids`` (and is not the ``all`` wildcard).
+    """
+    n = len(key_dimension_ids)
+    if key in {"", "all"}:
+        return KeyFilter(dimension_ids=list(key_dimension_ids), segments=[None] * n)
+
+    raw_segments = key.split(".")
+    if len(raw_segments) != n:
+        msg = (
+            f"SDMX key has {len(raw_segments)} segments but DSD has {n} "
+            f"key dimensions ({', '.join(key_dimension_ids)}): {key!r}"
+        )
+        raise ValueError(msg)
+
+    segments: list[list[str] | None] = []
+    for raw in raw_segments:
+        if raw == "":
+            segments.append(None)
+        else:
+            segments.append(raw.split("+"))
+    return KeyFilter(dimension_ids=list(key_dimension_ids), segments=segments)

sdmxlib-0.16.2/src/sdmxlib/formats/sdmx_csv/__init__.py

@@ -1,5 +0,0 @@
-"""SDMX-CSV data message reader."""
-
-from sdmxlib.formats.sdmx_csv.reader import scan_csv
-
-__all__ = ["scan_csv"]