sdmxlib 0.62.2__tar.gz → 0.63.0__tar.gz

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/PKG-INFO

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

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.62.2"
+version = "0.63.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 requires-python = ">=3.13"

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/pyproject.toml.orig

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

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/__init__.py

@@ -11,6 +11,7 @@ from sdmxlib.api.client import ResponseTooLargeError
 from sdmxlib.api.registry import BearerToken, FmrRegistry, RestRegistry
 from sdmxlib.data_store import DataStore, WriteSource
 from sdmxlib.model.datastructure import ComponentRole
+from sdmxlib.model.ref import short_urn as short_urn
 from sdmxlib.model.ref import SupportsUrn
 from sdmxlib.model.rest_api import ApiVersion
 from sdmxlib.model.rollup import AncestorMap

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/api/federated.py

@@ -32,7 +32,7 @@ Example:
 
 import functools
 import inspect
-from typing import TYPE_CHECKING, Any, overload
+from typing import TYPE_CHECKING, overload
 
 import httpx
 
@@ -124,7 +124,7 @@ class FederatedRegistry:
     @overload
     def get[T](
         self,
-        target: "SdmxUrn[object] | Ref[Any]",
+        target: "SdmxUrn[object] | Ref[object]",
         /,
         *,
         expect: "type[T]",
@@ -144,7 +144,7 @@ class FederatedRegistry:
 
     def get[T](
         self,
-        target: "SdmxUrn[object] | Ref[Any]",
+        target: "SdmxUrn[object] | Ref[object]",
         /,
         *,
         expect: "type[T] | None" = None,

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/api/registry.py

@@ -4,7 +4,7 @@ import tempfile
 import threading
 from collections.abc import Callable, Sequence
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Self, Unpack, cast, overload
+from typing import TYPE_CHECKING, Self, Unpack, cast, overload
 
 import attrs
 from attrs import frozen
@@ -779,7 +779,7 @@ class RestRegistry:
     @overload
     def get[T](
         self,
-        target: "SdmxUrn[object] | Ref[Any]",
+        target: "SdmxUrn[object] | Ref[object]",
         /,
         *,
         expect: "type[T]",
@@ -799,7 +799,7 @@ class RestRegistry:
 
     def get[T](
         self,
-        target: "SdmxUrn[object] | Ref[Any]",
+        target: "SdmxUrn[object] | Ref[object]",
         /,
         *,
         expect: "type[T] | None" = None,

sdmxlib-0.63.0/src/sdmxlib/formats/sdmx_csv/reader.py

@@ -0,0 +1,321 @@
+"""SDMX-CSV data reader.
+
+Parses SDMX-CSV messages into `Dataset` objects.
+
+SDMX-CSV format::
+
+    DATAFLOW,FREQ,REF_AREA,INDICATOR,TIME_PERIOD,OBS_VALUE,OBS_STATUS
+    ESTAT:STS_INPR_M(1.0),M,AT,INDPRO,2024-01,98.5,A
+
+The ``DATAFLOW`` column identifies the dataflow but is not a DSD component.
+It is extracted and then dropped; the remaining columns are parsed using the
+DSD schema.
+"""
+
+import csv
+import io
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Final
+
+import polars as pl
+
+import sdmxlib.polars as slpl
+from sdmxlib.model.dataflow import Dataflow
+from sdmxlib.model.dataset import Dataset
+from sdmxlib.model.datastructure import DataStructure
+from sdmxlib.model.provision import ProvisionAgreement
+from sdmxlib.model.ref import Ref, short_urn
+from sdmxlib.model.urn import SdmxUrn
+
+if TYPE_CHECKING:
+    from sdmxlib.model.registry import SupportsGet
+    from sdmxlib.polars import CodedAs
+
+_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"^([^:]+):([^(]+)\(([^)]+)\)$")
+
+
+def parse_dataflow_id(dataflow_id: str) -> tuple[str, str, str]:
+    """Parse an SDMX-CSV DATAFLOW value into ``(agency, id, version)``.
+
+    Example:
+        parse_dataflow_id("ESTAT:STS_INPR_M(1.0)")  # ("ESTAT", "STS_INPR_M", "1.0")
+    """
+    m = _DATAFLOW_RE.match(dataflow_id)
+    if m is None:
+        msg = f"Cannot parse DATAFLOW value {dataflow_id!r} — expected 'AGENCY:ID(VERSION)'"
+        raise ValueError(msg)
+    return m.group(1), m.group(2), m.group(3)
+
+
+#: The values SDMX-CSV 2.0's ``STRUCTURE`` column may carry.
+#:
+#: Verbatim from the field guide: "The first column contains: ``dataflow``,
+#: ``datastructure`` or ``dataprovision``". Worth stating because two of our own
+#: docstrings said ``provisionagreement`` — which is the RFC 5988 *link
+#: relation* SDMX-JSON uses, a different vocabulary — and a caller following
+#: them wrote a non-conformant file. sdmx1's CSV reader enumerates the same
+#: three (#409).
+STRUCTURE_KINDS: Final[tuple[str, ...]] = ("dataflow", "datastructure", "dataprovision")
+
+
+def _peek_dataflow_id(source: "str | Path | bytes") -> str | None:
+    """Extract the DATAFLOW value from the first data row without reading the whole file."""
+    if isinstance(source, (str, Path)):
+        with Path(source).open(newline="", encoding="utf-8") as f:
+            head = f.read(4096)
+    else:
+        head = source[:4096].decode("utf-8", errors="replace")
+
+    reader = csv.reader(io.StringIO(head))
+    try:
+        header = next(reader)
+    except StopIteration:
+        return None
+    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)
+    except StopIteration:
+        return None
+    return first_row[df_idx] if df_idx < len(first_row) else None
+
+
+def _peek_structure(source: "str | Path | bytes") -> "tuple[str | None, str | None]":
+    """``(STRUCTURE, STRUCTURE_ID)`` from the first data row, without reading on.
+
+    The kind matters: an SDMX-CSV file may name a dataflow, a data structure or
+    a provision agreement, and resolving all three is the difference between
+    honouring the column and assuming what it says (#409). SDMX-CSV 1.0 has no
+    ``STRUCTURE`` column at all — its ``DATAFLOW`` implies the kind — so the
+    first element is None there and the caller treats it as a dataflow.
+    """
+    if isinstance(source, (str, Path)):
+        with Path(source).open(newline="", encoding="utf-8") as f:
+            head = f.read(4096)
+    else:
+        head = source[:4096].decode("utf-8", errors="replace")
+    reader = csv.reader(io.StringIO(head))
+    try:
+        header = next(reader)
+        first_row = next(reader)
+    except StopIteration:
+        return None, None
+
+    def value(column: str) -> str | None:
+        if column not in header:
+            return None
+        index = header.index(column)
+        return first_row[index] if index < len(first_row) else None
+
+    kind = value(_STRUCTURE_COL)
+    identifier = value(_STRUCTURE_ID_COL) or value(_DATAFLOW_COL)
+    return kind, identifier
+
+
+def _dataflow_ref(dataflow_str: str) -> "Ref[Dataflow]":
+    """Build an unresolved Ref[Dataflow] from an SDMX-CSV DATAFLOW column value."""
+    agency, id_, version = parse_dataflow_id(dataflow_str)
+    urn = SdmxUrn.make(
+        Dataflow,
+        package="datastructure",
+        artefact_class="Dataflow",
+        agency=agency,
+        id=id_,
+        version=version,
+    )
+    return Ref[Dataflow].unresolved(urn)
+
+
+def _resolve_structure(
+    source: "str | Path | bytes",
+    registry: "SupportsGet",
+) -> "tuple[DataStructure, Ref[Dataflow] | None]":
+    """The `DataStructure` this file names, looked up in *registry*.
+
+    Every SDMX-CSV 2.0 row names its own structure, and this reader has always
+    parsed that column and then thrown it away — `scan_csv` required the DSD as
+    a positional argument, so the file's answer was only available after you had
+    supplied it. #409 is that asymmetry.
+
+    All three kinds are honoured rather than assuming `dataflow`, which is what
+    "only `dataflow` appears to be considered" described. A provision agreement
+    resolves through its dataflow, which is the same second hop a dataflow makes
+    to its structure.
+
+    Raises:
+        ValueError: If the file names no structure (no ``STRUCTURE_ID`` and no
+            ``DATAFLOW`` column), if its ``STRUCTURE`` value is not one of
+            `STRUCTURE_KINDS`, if the registry cannot resolve what it names, or
+            if what it resolves to has no structure to read. Four distinct
+            messages, because a caller's next move differs for each.
+        TypeError: If the URN resolves to something that is not a dataflow,
+            provision agreement or data structure at all.
+    """
+    kind, identifier = _peek_structure(source)
+    if identifier is None:
+        msg = (
+            "this file names no structure: no STRUCTURE_ID column (SDMX-CSV 2.0) "
+            "and no DATAFLOW column (1.0). Pass structure=<DataStructure> instead"
+        )
+        raise ValueError(msg)
+    if kind is not None and kind not in STRUCTURE_KINDS:
+        msg = f"unknown STRUCTURE value {kind!r} — SDMX-CSV allows {', '.join(STRUCTURE_KINDS)}"
+        raise ValueError(msg)
+
+    agency, id_, version = parse_dataflow_id(identifier)
+    artefact_class = {"datastructure": DataStructure, "dataprovision": ProvisionAgreement}.get(
+        kind or "dataflow", Dataflow
+    )
+    urn = artefact_class.urn_for(agency=agency, id=id_, version=version)
+    found: object = registry.get(urn)
+    if found is None:
+        msg = f"{kind or 'dataflow'} {identifier} is not in this registry — add it, or pass structure=<DataStructure>"
+        raise ValueError(msg)
+
+    flow_ref: Ref[Dataflow] | None = None
+    if isinstance(found, ProvisionAgreement):
+        if found.dataflow is None:
+            msg = f"provision agreement {identifier} has no dataflow, so its structure cannot be reached"
+            raise ValueError(msg)
+        flow_ref = found.dataflow
+        found = found.dataflow()
+    if isinstance(found, Dataflow):
+        flow_ref = flow_ref or _dataflow_ref(identifier)
+        if found.structure is None:
+            msg = f"dataflow {identifier} has no structure — it cannot say how to read this file"
+            raise ValueError(msg)
+        found = found.structure()
+    if not isinstance(found, DataStructure):
+        # A `TypeError`, per ruff's TRY004 and correctly: the registry answered
+        # with the wrong *kind* of thing, which is a different fault from the
+        # file naming something absent.
+        msg = f"{identifier} resolved to {type(found).__name__}, which is not a DataStructure"
+        raise TypeError(msg)
+    return found, flow_ref
+
+
+def scan_csv(
+    source: "str | Path | bytes",
+    structure: "DataStructure | Dataflow | None" = None,
+    *,
+    registry: "SupportsGet | None" = None,
+    infer_schema_length: "int | None" = 0,
+    dataflow: "Ref[Dataflow] | None" = None,
+    coded_as: "CodedAs" = "enum",
+) -> Dataset:
+    """Parse an SDMX-CSV message into a `Dataset`.
+
+    File paths are scanned lazily via ``pl.scan_csv``; bytes (e.g. from an
+    HTTP response) are read eagerly and wrapped in a ``LazyFrame``. Either
+    way the returned ``Dataset.data`` is always a ``pl.LazyFrame``.
+
+    Args:
+        source: File path or raw bytes from an SDMX-CSV response.
+        structure: Fully resolved `DataStructure`, or the `Dataflow` that names
+                   one — the flow is unwrapped for you, as sdmx1's reader does.
+                   Codelists should be resolved for ``pl.Enum`` typing.
+                   Omit it and pass ``registry`` to use the file's own
+                   ``STRUCTURE_ID`` instead (#409).
+        registry: Any `Registry` to resolve the file's ``STRUCTURE_ID``
+                  against, when ``structure`` is omitted. All three
+                  ``STRUCTURE`` kinds are honoured — ``dataflow``,
+                  ``datastructure`` and ``dataprovision``.
+        infer_schema_length: Passed to Polars. ``0`` (default) means
+                             schema is fully DSD-driven with no row sampling,
+                             which is required for true streaming on paths.
+        dataflow: Optional resolved `Dataflow` ref.
+                  When ``None`` and a ``DATAFLOW`` column is present, an
+                  unresolved ref is built from the column value.
+        coded_as: How coded columns are typed — see `sdmxlib.polars.schema`.
+                  ``"enum"`` (default) fails fast on a value outside its
+                  codelist; ``"string"`` lets it through so
+                  `Dataset.validate` can report every one (#408).
+
+    Returns:
+        A `Dataset` with a lazy ``data`` frame.
+
+    Example:
+        import sdmxlib.polars as slpl
+
+        ds = slpl.scan_csv("data.csv", dsd)
+        df = ds.collect(with_labels=True, lang="en")
+
+        # The file says which structure it needs; the registry has it:
+        ds = slpl.scan_csv("data.csv", registry=reg)
+
+        # Or hand over the flow and skip the `.structure()` unwrap:
+        ds = slpl.scan_csv("data.csv", message.dataflows["DF"])
+
+        # A report rather than a raise, for a file you do not trust yet:
+        report = slpl.scan_csv("suspect.csv", dsd, coded_as="string").validate()
+    """
+    resolved_ref: Ref[Dataflow] | None = None
+    if isinstance(structure, Dataflow):
+        # sdmx1's CSV reader takes either, and for the same reason: a caller
+        # holding the flow has already done the lookup, and making them add
+        # `.structure()` is the hand-written join #409 is about.
+        if structure.structure is None:
+            msg = f"dataflow {short_urn(structure)} has no structure — it cannot say how to read this file"
+            raise ValueError(msg)
+        resolved_ref = _dataflow_ref(short_urn(structure))
+        structure = structure.structure()
+    elif structure is None:
+        if registry is None:
+            msg = (
+                "scan_csv needs structure=<DataStructure | Dataflow>, or "
+                "registry=<Registry> to resolve the file's own STRUCTURE_ID"
+            )
+            raise ValueError(msg)
+        structure, resolved_ref = _resolve_structure(source, registry)
+
+    # Only a `dataflow` file gets a `Dataset.dataflow`. This used to build one
+    # from `STRUCTURE_ID` whatever the `STRUCTURE` column said, so a
+    # `datastructure` file came back claiming a dataflow whose id was really a
+    # DSD's. Reading the kind (#409) is what makes the distinction available.
+    kind, identifier = _peek_structure(source)
+    dataflow_ref = dataflow or resolved_ref
+    if dataflow_ref is None and identifier is not None and kind in (None, "dataflow"):
+        dataflow_ref = _dataflow_ref(identifier)
+
+    schema_overrides = slpl.schema(structure, coded_as=coded_as)
+
+    if isinstance(source, (str, Path)):
+        lf = pl.scan_csv(
+            source,
+            schema_overrides=schema_overrides,
+            infer_schema_length=infer_schema_length,
+        )
+    else:
+        lf = pl.read_csv(
+            io.BytesIO(source),
+            schema_overrides=schema_overrides,
+            infer_schema_length=infer_schema_length,
+        ).lazy()
+
+    # 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()
+    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)
+
+    return Dataset(structure=structure, data=lf, dataflow=dataflow_ref)

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/formats/sdmx_csv/writer.py

@@ -47,6 +47,21 @@ from typing import TYPE_CHECKING, cast
 
 import polars as pl
 
+from sdmxlib.formats.sdmx_csv.reader import STRUCTURE_KINDS
+from sdmxlib.model.dataflow import Dataflow
+from sdmxlib.model.datastructure import DataStructure
+from sdmxlib.model.provision import ProvisionAgreement
+from sdmxlib.model.ref import short_urn
+
+#: Artefact class -> the ``STRUCTURE`` value SDMX-CSV gives it, for the form of
+#: `write_sdmx_csv` that takes the artefact instead of a pre-formatted string.
+_KIND_OF: dict[type, str] = {
+    Dataflow: "dataflow",
+    DataStructure: "datastructure",
+    ProvisionAgreement: "dataprovision",
+}
+
+
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
 
@@ -59,7 +74,7 @@ def write_sdmx_csv(
     batches: Iterable[pa.RecordBatch],
     dsd: DataStructure,
     *,
-    structure_id: str,
+    structure_id: str | Dataflow | DataStructure | ProvisionAgreement,
     structure: str = "dataflow",
     action: str = "I",
 ) -> Iterator[bytes]:
@@ -73,11 +88,18 @@ def write_sdmx_csv(
             Determines column order in the output: dimensions, then
             measures, then attributes, each in the order the structure
             declares them.
-        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"``.
+        structure_id: The ``AGENCY:ID(VERSION)`` identifier emitted in the
+            ``STRUCTURE_ID`` column on every row — or the artefact itself, in
+            which case both this and ``structure`` are read off it. Passing the
+            artefact is the point of #409: every caller was formatting the short
+            URN by hand while `parse_dataflow_id` owned reading it.
+        structure: Value emitted in the ``STRUCTURE`` column. SDMX-CSV allows
+            ``"dataflow"``, ``"datastructure"`` or ``"dataprovision"``, and the
+            field guide's wording is exactly those three. This said
+            ``"provisionagreement"`` until #409 — that is SDMX-JSON's RFC 5988
+            link relation, a different vocabulary, and a caller who followed it
+            wrote a file no conformant reader accepts. Ignored when
+            ``structure_id`` is an artefact.
         action: Value emitted in the ``ACTION`` column. One of ``I``
             (Insert), ``R`` (Replace), ``A`` (Append), ``D`` (Delete).
             Defaults to ``"I"``.
@@ -89,7 +111,14 @@ def write_sdmx_csv(
 
     Raises:
         KeyError: If a batch is missing a component the structure declares.
+        ValueError: If ``structure`` is not one of SDMX-CSV's three kinds.
     """
+    if not isinstance(structure_id, str):
+        structure = _KIND_OF.get(type(structure_id), "dataflow")
+        structure_id = short_urn(structure_id)
+    if structure not in STRUCTURE_KINDS:
+        msg = f"STRUCTURE must be one of {', '.join(STRUCTURE_KINDS)}, not {structure!r}"
+        raise ValueError(msg)
     # Component ids, in SDMX order, from the structure. This read the
     # *binding's* physical column names until an observation query began
     # projecting by component id — after which it raised a `KeyError` naming

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/local/registry.py

@@ -37,7 +37,7 @@ import time
 from collections.abc import Generator, Iterable
 from contextlib import contextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Final, Literal, Self, cast, overload, override
+from typing import TYPE_CHECKING, Final, Literal, Self, cast, overload, override
 
 import duckdb
 
@@ -921,7 +921,7 @@ class LocalRegistry(SessionFactory):
     # phantom happens to be. See the docstring for why it exists.
     @overload
     def get[T](
-        self, target: "SdmxUrn[object] | Ref[Any]", /, *, expect: "type[T]", eager: bool = False
+        self, target: "SdmxUrn[object] | Ref[object]", /, *, expect: "type[T]", eager: bool = False
     ) -> "T | None": ...
 
     @overload
@@ -938,7 +938,7 @@ class LocalRegistry(SessionFactory):
     def get[T](self, target: "SdmxUrn[T] | Ref[T]", /, *, eager: bool = False) -> "T | None": ...
 
     def get[T](
-        self, target: "SdmxUrn[object] | Ref[Any]", /, *, expect: "type[T] | None" = None, eager: bool = False
+        self, target: "SdmxUrn[object] | Ref[object]", /, *, expect: "type[T] | None" = None, eager: bool = False
     ) -> "object":
         """Look up an artefact by URN, or by a `Ref` naming one.
 
@@ -959,9 +959,12 @@ class LocalRegistry(SessionFactory):
         claiming `Codelist` for a `LazyCodelist`, the silent lie #397 removed,
         and the explicit spelling is the common one. **Narrowing
         `SdmxUrn.parse` to `SdmxUrn[object]`** — #399's option 2 — measures at
-        52 basedpyright + 27 pyrefly findings, every one the same fact: `Ref`
-        is invariant by design (#289), so `Ref[object]` does not go where
-        `Ref[Codelist]` is wanted. They are sites of correct code, not defects.
+        52 basedpyright + 27 pyrefly findings, every one the same fact: a
+        `Ref[object]` does not go where a `Ref[Codelist]` is wanted. `Ref` is
+        *covariant* (see `Ref`'s own class comment and #289), so the assignment
+        that works is the other direction; narrowing `parse` asks for this one,
+        which covariance does not give. They are sites of correct code, not
+        defects.
 
         Pass a typed URN where you have one; narrow with `isinstance` where you
         do not. `tests/typing/probe_urn_any.py` pins the declared types and

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/model/__init__.py

@@ -95,6 +95,7 @@ from sdmxlib.model.organisation import (
     MetadataProviderScheme,
 )
 from sdmxlib.model.provision import ProvisionAgreement
+from sdmxlib.model.ref import short_urn as short_urn
 from sdmxlib.model.ref import Ref, SdmxRef, UnresolvedRef
 from sdmxlib.model.registry import InMemoryRegistry, RegistryReader, artefact_urn
 from sdmxlib.model.representation import DataType, Facet, Representation

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/model/_items.py

@@ -38,12 +38,12 @@ import attrs
 from sdmxlib.model._refshape import item_fields
 from sdmxlib.model.base import MaintainableArtefact
 from sdmxlib.model.collections import ArtefactList, ItemList, SdmxItem
+from sdmxlib.model.ref import Ref, SupportsUrn
+from sdmxlib.model.urn import SdmxUrn
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Mapping
 
-    from sdmxlib.model.urn import SdmxUrn
-
 #: The component classes SDMX spells differently across versions. A URN carries
 #: the spelling of whatever produced it — 2.1 names an attribute ``Attribute``
 #: and the single measure ``PrimaryMeasure``, 3.0 names them ``DataAttribute``
@@ -297,3 +297,93 @@ def _search(owner: object, owner_cls: type, item_id: str, wanted: tuple[str, ...
                 if found is not None:
                     return found
     return None
+
+
+def item_urn_of[T: SdmxItem](scheme: SupportsUrn, item_cls: type[T], item_id: str) -> SdmxUrn[T]:
+    """The URN of *item_id* inside *scheme*, as SDMX spells it.
+
+    The inverse of `scheme_urn_of`, and the constructive half of what #404 and
+    #405 made the library able to *read*. Agency, id and version come off the
+    scheme rather than from the caller, which is the whole point: a URN built by
+    hand can name a parent that does not exist — six keyword arguments, three of
+    them restating the scheme — and `validate_references` will now correctly
+    report that as broken (#407).
+    """
+    return SdmxUrn.make(
+        item_cls,
+        package=item_cls.sdmx_package,
+        artefact_class=item_cls.sdmx_class,
+        agency=scheme.agency_id,
+        id=scheme.id,
+        version=scheme.version,
+        item_id=item_id,
+    )
+
+
+def locate_item(scheme: object) -> Iterator[tuple[str, type[SdmxItem]]]:
+    """The (field name, item class) pairs `ref_to` searches, in order."""
+    yield from item_fields(type(scheme))
+
+
+def item_ref[T: SdmxItem](scheme: SupportsUrn, item_id: str, item_cls: type[T]) -> Ref[T]:
+    """A resolved `Ref` to one item of *scheme*, found by id.
+
+    Raises:
+        KeyError: If no item of that class in *scheme* has this id. The message
+            names the scheme, so a caller who passed the right id to the wrong
+            artefact is told which artefact answered.
+    """
+    found = _search(scheme, type(scheme), item_id, spellings(item_cls.sdmx_class))
+    if found is None and isinstance(scheme, SupportsItemLookup):
+        # A lazy facade keeps its items behind a query, so the declared-field
+        # walk finds nothing; its subscript is the targeted lookup. Same order
+        # as `find_item`, and the reason `LazyCodelist.ref_to` can exist at all
+        # rather than being refused until you materialise (#407).
+        found = _by_subscript(scheme, item_id, spellings(item_cls.sdmx_class))
+    # `isinstance` rather than a cast: it narrows `_search`'s `object | None` to
+    # `T` with a runtime check, and covers "not found" in the same branch.
+    if not isinstance(found, item_cls):
+        msg = (
+            f"no {item_cls.sdmx_class} with id {item_id!r} in "
+            f"{type(scheme).__name__} {scheme.agency_id}:{scheme.id}({scheme.version})"
+        )
+        raise KeyError(msg)
+    return Ref[T].of(item_urn_of(scheme, item_cls, item_id), found)
+
+
+def any_item_ref(scheme: SupportsUrn, item_id: str) -> Ref[object]:
+    """A resolved `Ref` to one item of *scheme*, whichever kind holds the id.
+
+    For a `DataStructure`, whose `dimensions`, `time_dimension`,
+    `measure_dimension`, `measures`, `attributes` and `groups` are six item
+    lists under one maintainable. Dispatching is unambiguous rather than
+    convenient: `storage.schema` declares
+    ``PRIMARY KEY (dsd_urn, component_id)`` on `dsd_component`, so this library
+    already treats a component id as unique across the whole DSD, whichever
+    list it sits in (#407).
+
+    `Ref[object]` because the class varies and every field that consumes one of
+    these — `HierarchyAssociation.linked_object`, `Categorisation.target` — is
+    declared `Ref[object]`. The URN carries the real class, so nothing is lost
+    at runtime; a caller who needs it statically can `isinstance` the unwrapped
+    item.
+
+    Raises:
+        KeyError: If no item of *scheme* has this id, naming the fields
+            searched so the message says where it looked.
+    """
+    for name, item_cls in locate_item(scheme):
+        value = getattr(scheme, name, None)
+        found = _by_id(value, item_id)
+        if found is None:
+            found = _search(value, item_cls, item_id, spellings(item_cls.sdmx_class))
+        # `isinstance` rather than `is not None`: it narrows to the item class,
+        # which is what `Ref.of` needs to type the pair it is handed.
+        if isinstance(found, item_cls):
+            return Ref[object].of(item_urn_of(scheme, item_cls, item_id), found)
+    searched = ", ".join(name for name, _ in locate_item(scheme)) or "no item fields"
+    msg = (
+        f"no item with id {item_id!r} in {type(scheme).__name__} "
+        f"{scheme.agency_id}:{scheme.id}({scheme.version}) — searched {searched}"
+    )
+    raise KeyError(msg)

{sdmxlib-0.62.2 → sdmxlib-0.63.0}/src/sdmxlib/model/category.py

@@ -5,6 +5,7 @@ from typing import ClassVar
 
 from attrs import define, evolve, field
 
+from sdmxlib.model._items import item_ref
 from sdmxlib.model._refshape import derived_view
 from sdmxlib.model.annotations import Annotations
 from sdmxlib.model.base import MaintainableArtefact
@@ -73,6 +74,22 @@ class CategoryScheme(MaintainableArtefact):
     _flat: ItemList[Category] = field(init=False, repr=False, factory=ItemList, metadata=derived_view())
     _parent_of: dict[str, str | None] = field(init=False, repr=False, eq=False, factory=dict)
 
+    def ref_to(self, category_id: str) -> "Ref[Category]":
+        """Build a resolved `Ref` to a category within this scheme.
+
+        The URN is built from *this* scheme's agency, id and version, so it
+        cannot name a parent that does not exist — which is what six hand-written
+        keyword arguments to `SdmxUrn.make` invite, and what
+        `validate_references` now correctly reports as broken (#407).
+
+        Raises:
+            KeyError: If no category with this id is in this scheme.
+
+        Example:
+            Categorisation(..., target=cs.ref_to("ECON"))
+        """
+        return item_ref(self, category_id, Category)
+
     def __attrs_post_init__(self) -> None:
         self._flat = _flatten_categories(self.categories)
         parent: dict[str, str | None] = {n.id: None for n in self._flat}