sdmxlib 0.8.0__py3-none-any.whl

sdmxlib/model/registry.py

@@ -0,0 +1,191 @@
+"""Registry — pure-domain SDMX artefact store.
+
+The ``Registry`` is the SDMX Information Model concept of a local artefact
+graph: a URN-keyed store that connects artefacts through interned ``Ref``
+objects.
+
+Key behaviours:
+
+- **One Ref per URN** — interning means every holder of a given Ref shares
+  the same object. Resolving it once propagates everywhere automatically.
+- **Eager accept, lazy resolve** — add artefacts in any order; Refs get
+  resolved as their targets arrive.
+- **Pure domain** — no network, no HTTP, no serialisation.
+
+Example::
+
+    reg = Registry()
+    reg.add(cl_freq)
+    reg.add(dsd)  # Refs to cl_freq resolve here
+    dsd.dimensions["FREQ"].codelist()  # Codelist — no fetch needed
+"""
+
+from collections.abc import Iterable
+from typing import Any
+
+import attrs
+
+from sdmxlib.model.collections import ItemList
+from sdmxlib.model.ref import AnyRef, HasUrn, Ref
+from sdmxlib.model.urn import SdmxUrn
+
+
+class Registry:
+    """In-memory SDMX artefact store with URN identity and Ref interning.
+
+    Example::
+
+        reg = Registry()
+        reg.add_all([cl_freq, concept_scheme, dsd])
+
+        dsd = reg.get(DataStructure.urn(agency="ESTAT", id="CPI", version="1.0"))
+        dims = reg.get_all(Dimension)  # not typically used; prefer dsd.dimensions
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, Any] = {}  # str(urn) → artefact
+        self._refs: dict[str, AnyRef] = {}  # str(urn) → canonical Ref
+        self._by_type: dict[type, list[Any]] = {}  # Python type → [artefact, ...]
+
+    # ── Public API ────────────────────────────────────────────────────────
+
+    def add(self, artefact: Any) -> None:
+        """Add an artefact to the registry.
+
+        - Interns the artefact under its URN.
+        - Resolves the canonical ``Ref`` for this URN so all existing
+          holders see the artefact immediately.
+        - Walks all outgoing ``Ref`` fields, replaces them with canonical
+          interned Refs, and resolves any that point to artefacts already
+          present.
+
+        Raises ``TypeError`` if the artefact does not satisfy ``HasUrn``.
+        """
+        if not isinstance(artefact, HasUrn):
+            msg = (
+                f"{type(artefact).__name__} does not satisfy HasUrn — "
+                "it needs sdmx_package, sdmx_class, agency_id, id, version"
+            )
+            raise TypeError(msg)
+
+        urn = _artefact_urn(artefact)
+        urn_str = str(urn)
+
+        # Store under exact URN
+        self._store[urn_str] = artefact
+
+        # Track by Python type for get_all()
+        t = type(artefact)
+        if t not in self._by_type:
+            self._by_type[t] = []
+        if artefact not in self._by_type[t]:
+            self._by_type[t].append(artefact)
+
+        # Resolve the canonical Ref for this artefact (propagates to all holders)
+        canonical = self._canonical_ref(urn)
+        canonical._resolved = artefact  # noqa: SLF001
+
+        # Walk outgoing Refs on the artefact and intern them
+        self._walk_refs(artefact, set())
+
+    def add_all(self, artefacts: Iterable[Any]) -> None:
+        """Add multiple artefacts in any order."""
+        for artefact in artefacts:
+            self.add(artefact)
+
+    def get[T](self, urn: "SdmxUrn[T]") -> "T | None":
+        """Look up an artefact by exact URN. Returns ``None`` if absent."""
+        return self._store.get(str(urn))  # type: ignore[return-value]
+
+    def get_all[T](self, artefact_type: "type[T]") -> "list[T]":
+        """All artefacts of the given Python type (exact match, not subclasses)."""
+        return list(self._by_type.get(artefact_type, []))  # type: ignore[return-value]
+
+    def ref[T](self, urn: "SdmxUrn[T]") -> "Ref[T]":
+        """Return the canonical interned Ref for this URN.
+
+        Creates an unresolved Ref if this URN has not been seen before.
+        If the target artefact is already in the registry, the returned
+        Ref will be resolved.
+        """
+        return self._canonical_ref(urn)  # type: ignore[return-value]
+
+    def __contains__(self, urn: object) -> bool:
+        """True if an artefact with this URN is stored."""
+        if isinstance(urn, SdmxUrn):
+            return str(urn) in self._store
+        return False
+
+    def __len__(self) -> int:
+        """Number of artefacts stored."""
+        return len(self._store)
+
+    def __repr__(self) -> str:
+        counts = ", ".join(f"{t.__name__}={len(v)}" for t, v in self._by_type.items())
+        return f"Registry({counts or 'empty'})"
+
+    # ── Internals ─────────────────────────────────────────────────────────
+
+    def _canonical_ref(self, urn: "SdmxUrn[Any]") -> AnyRef:
+        """Get or create the canonical (interned) Ref for a URN."""
+        urn_str = str(urn)
+        if urn_str not in self._refs:
+            new_ref: AnyRef = Ref.unresolved(urn)
+            self._refs[urn_str] = new_ref
+            # Resolve immediately if the target is already stored
+            artefact = self._store.get(urn_str)
+            if artefact is not None:
+                new_ref._resolved = artefact  # noqa: SLF001
+        return self._refs[urn_str]
+
+    def _walk_refs(self, obj: Any, visited: set[int]) -> None:
+        """Walk dataclass fields of *obj*, interning every ``Ref`` found.
+
+        Recurses into ``ItemList`` items and nested dataclass fields.
+        The *visited* set prevents cycles.
+        """
+        if not attrs.has(type(obj)) or isinstance(obj, type):
+            return
+        oid = id(obj)
+        if oid in visited:
+            return
+        visited.add(oid)
+
+        for f in attrs.fields(type(obj)):
+            self._process_field(obj, f.name, getattr(obj, f.name, None), visited)
+
+    def _process_field(self, obj: Any, name: str, value: Any, visited: set[int]) -> None:
+        """Intern a single field value; recurse if it contains more Refs."""
+        if value is None:
+            return
+        if isinstance(value, Ref):
+            self._intern_ref_field(obj, name, value)
+        elif isinstance(value, ItemList):
+            for item in value:
+                self._walk_refs(item, visited)
+        elif attrs.has(type(value)) and not isinstance(value, type):
+            self._walk_refs(value, visited)
+
+    def _intern_ref_field(self, obj: Any, name: str, ref: AnyRef) -> None:
+        """Replace *ref* on *obj.name* with the canonical interned Ref."""
+        interned = self._canonical_ref(ref.urn)
+        # Transfer resolution from incoming ref to canonical if needed
+        if ref._resolved is not None and interned._resolved is None:  # noqa: SLF001
+            interned._resolved = ref._resolved  # noqa: SLF001
+        if interned is not ref:
+            setattr(obj, name, interned)
+
+
+# ── Module-level helper ────────────────────────────────────────────────────
+
+
+def _artefact_urn(artefact: Any) -> "SdmxUrn[Any]":
+    """Build the canonical SdmxUrn for a HasUrn artefact."""
+    return SdmxUrn.make(
+        type(artefact),
+        package=artefact.sdmx_package,
+        artefact_class=artefact.sdmx_class,
+        agency=artefact.agency_id,
+        id=artefact.id,
+        version=artefact.version,
+    )

sdmxlib/model/representation.py

@@ -0,0 +1,99 @@
+"""Representation types — DataType, Facet, Representation alias."""
+
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from attrs import frozen
+
+if TYPE_CHECKING:
+    from sdmxlib.model.codelist import Codelist
+    from sdmxlib.model.ref import Ref
+
+
+class DataType(StrEnum):
+    """SDMX data types for non-enumerated representations.
+
+    Values match the SDMX-ML ``textType`` attribute strings exactly, so
+    ``DataType.String == "String"`` and existing string-passing code continues
+    to work unchanged.
+
+    Example:
+        Facet(type=DataType.String, max_length=100)
+        Facet(type=DataType.ObservationalTimePeriod)
+        Facet(type="String")  # str also accepted
+    """
+
+    String = "String"
+    Alpha = "Alpha"
+    AlphaNumeric = "AlphaNumeric"
+    Numeric = "Numeric"
+    BigInteger = "BigInteger"
+    Integer = "Integer"
+    Long = "Long"
+    Short = "Short"
+    Decimal = "Decimal"
+    Float = "Float"
+    Double = "Double"
+    Boolean = "Boolean"
+    URI = "URI"
+    URL = "URL"
+    Count = "Count"
+    InclusiveValueRange = "InclusiveValueRange"
+    ExclusiveValueRange = "ExclusiveValueRange"
+    Incremental = "Incremental"
+    ObservationalTimePeriod = "ObservationalTimePeriod"
+    StandardTimePeriod = "StandardTimePeriod"
+    BasicTimePeriod = "BasicTimePeriod"
+    GregorianTimePeriod = "GregorianTimePeriod"
+    GregorianYear = "GregorianYear"
+    GregorianYearMonth = "GregorianYearMonth"
+    GregorianDay = "GregorianDay"
+    ReportingTimePeriod = "ReportingTimePeriod"
+    ReportingYear = "ReportingYear"
+    ReportingSemester = "ReportingSemester"
+    ReportingTrimester = "ReportingTrimester"
+    ReportingQuarter = "ReportingQuarter"
+    ReportingMonth = "ReportingMonth"
+    ReportingWeek = "ReportingWeek"
+    ReportingDay = "ReportingDay"
+    ReportingHour = "ReportingHour"
+    DateTime = "DateTime"
+    Time = "Time"
+    Duration = "Duration"
+    Month = "Month"
+    MonthDay = "MonthDay"
+    Day = "Day"
+    Year = "Year"
+    XHTML = "XHTML"
+    Attachment = "Attachment"
+
+
+@frozen
+class Facet:
+    """Non-enumerated representation with optional constraints.
+
+    ``type`` accepts a :class:`DataType` member or a raw string (for
+    non-standard values from registry responses).
+
+    Example:
+        Facet(type=DataType.String, max_length=100)
+        Facet(type=DataType.ObservationalTimePeriod)
+        Facet(type="String")  # str accepted; DataType.String preferred
+    """
+
+    type: DataType | str | None = None
+    max_length: int | None = None
+    min_length: int | None = None
+    max_value: float | None = None
+    min_value: float | None = None
+    decimals: int | None = None
+    pattern: str | None = None
+    start_value: float | None = None
+    end_value: float | None = None
+    is_sequence: bool | None = None
+    is_multi_lingual: bool | None = None
+
+
+# Type alias — a component's representation is a codelist ref (enumerated)
+# or a facet (free text with optional constraints), or absent.
+type Representation = "Ref[Codelist] | Facet | None"

sdmxlib/model/urn.py

@@ -0,0 +1,130 @@
+"""SdmxUrn[T] — typed artefact identity.
+
+T is a phantom type parameter — no field stores it. It exists so the type
+checker can carry the target type through ``reg.fetch(urn) -> T``.
+"""
+
+import re
+from typing import Any, ClassVar
+
+from attrs import frozen
+
+# urn:sdmx:org.sdmx.infomodel.<package>.<Class>=<AGENCY>:<ID>(<version>)
+# optional item suffix: .<item_id>
+_URN_RE = re.compile(
+    r"urn:sdmx:org\.sdmx\.infomodel\.(?P<package>[^.]+)\.(?P<artefact_class>[^=]+)"
+    r"=(?P<agency>[^:]+):(?P<id>[^.(]+)(?:\((?P<version>[^)]+)\))?(?:\.(?P<item_id>.+))?$"
+)
+
+# SDMX 2.1 / 3.0 formal type patterns from SDMXCommonReferences.xsd
+# IDType:       [A-Za-z0-9_@$-]+
+# NestedIDType: [A-Za-z0-9_@$-]+(\.[A-Za-z0-9_@$-]+)*   (dots for agency hierarchy)
+_PACKAGE_RE = re.compile(r"^[a-z][a-z_]*$")
+_CLASS_RE = re.compile(r"^[A-Z][A-Za-z]+$")
+_AGENCY_RE = re.compile(r"^[A-Za-z0-9_@$-]+(\.[A-Za-z0-9_@$-]+)*$")
+_ID_RE = re.compile(r"^[A-Za-z0-9_@$-]+$")
+
+
+@frozen
+class SdmxUrn[T]:
+    """Globally unique identifier for an SDMX artefact.
+
+    ``T`` is a phantom type — not stored at runtime, used by the type
+    checker to propagate the target type through
+    ``reg.fetch(urn: SdmxUrn[T]) -> T``.
+
+    Example:
+        SdmxUrn.parse("urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_FREQ(1.0)")
+        SdmxUrn.make(
+            Codelist,
+            package="codelist",
+            artefact_class="Codelist",
+            agency="SDMX",
+            id="CL_FREQ",
+            version="1.0",
+        )
+    """
+
+    _PACKAGE_PREFIX: ClassVar[str] = "urn:sdmx:org.sdmx.infomodel"
+
+    package: str
+    artefact_class: str
+    agency: str
+    id: str
+    version: str = "latest"
+    item_id: str | None = None
+
+    # ── Factories ─────────────────────────────────────────────────────────
+
+    @classmethod
+    def parse(cls, urn: str) -> "SdmxUrn[Any]":
+        """Parse a full URN string. Returns unparameterised SdmxUrn."""
+        m = _URN_RE.match(urn)
+        if not m:
+            msg = f"Invalid SDMX URN: {urn!r}"
+            raise ValueError(msg)
+        return cls(
+            package=m.group("package"),
+            artefact_class=m.group("artefact_class"),
+            agency=m.group("agency"),
+            id=m.group("id"),
+            version=m.group("version") or "latest",
+            item_id=m.group("item_id"),
+        )
+
+    @classmethod
+    def make[U](
+        cls,
+        artefact_type: type[U],  # noqa: ARG003  # phantom type witness; unused at runtime
+        /,
+        *,
+        package: str,
+        artefact_class: str,
+        agency: str,
+        id: str,  # noqa: A002
+        version: str = "latest",
+        item_id: str | None = None,
+    ) -> "SdmxUrn[U]":
+        """Low-level factory with basic validation.
+
+        ``artefact_type`` is a phantom type witness — unused at runtime,
+        used by the type checker to bind ``U`` and propagate the artefact
+        type through ``session.get`` and ``session.extract``.
+        """
+        if not _AGENCY_RE.match(agency):
+            msg = f"Invalid agency id: {agency!r}"
+            raise ValueError(msg)
+        if not _ID_RE.match(id):
+            msg = f"Invalid artefact id: {id!r}"
+            raise ValueError(msg)
+        return cls(  # type: ignore[return-value]
+            package=package,
+            artefact_class=artefact_class,
+            agency=agency,
+            id=id,
+            version=version,
+            item_id=item_id,
+        )
+
+    # ── String representation ──────────────────────────────────────────────
+
+    def __str__(self) -> str:
+        """Round-trip to full URN string."""
+        base = f"{self._PACKAGE_PREFIX}.{self.package}.{self.artefact_class}={self.agency}:{self.id}"
+        if self.version and self.version != "latest":
+            base = f"{base}({self.version})"
+        if self.item_id:
+            base = f"{base}.{self.item_id}"
+        return base
+
+    # ── Properties ────────────────────────────────────────────────────────
+
+    @property
+    def is_latest(self) -> bool:
+        """True if version is the sentinel "latest"."""
+        return self.version == "latest"
+
+    @property
+    def is_item_urn(self) -> bool:
+        """True if this URN points to an item within a scheme (e.g. a Code)."""
+        return self.item_id is not None