sdmxlib 0.8.0__py3-none-any.whl

sdmxlib/__init__.py

@@ -0,0 +1,155 @@
+"""sdmxlib — SDMX structural metadata library for Python."""
+
+from sdmxlib.api.filters import DimFilter, dim
+from sdmxlib.api.providers import Provider
+from sdmxlib.api.query import DataQuery
+from sdmxlib.api.registry import BearerToken, FmrRegistry, RestRegistry
+from sdmxlib.formats import parse, read, serialize, to_json, to_xml
+from sdmxlib.local import LazyCodelist, LocalRegistry
+from sdmxlib.model.convert import from_dict, to_dict
+from sdmxlib.model.validation import ReferenceIssue, ValidationIssue, validate, validate_references
+from sdmxlib.model import (
+    Agency,
+    AgencyScheme,
+    Annotation,
+    Annotations,
+    ArtefactList,
+    AttachmentLevel,
+    Attribute,
+    Categorisation,
+    Category,
+    CategoryScheme,
+    Code,
+    Codelist,
+    Concept,
+    ConceptScheme,
+    CategoryMap,
+    CategorySchemeMap,
+    CodeMap,
+    CodelistMap,
+    ComponentMap,
+    ConceptMap,
+    ConceptSchemeMap,
+    ConstraintAttachment,
+    Contact,
+    ContentConstraint,
+    CubeRegion,
+    ReferencePeriod,
+    ReleaseCalendar,
+    DataProvider,
+    DataProviderScheme,
+    DataStructure,
+    Dataset,
+    DataStructureMap,
+    Dataflow,
+    DataflowMap,
+    Dimension,
+    Hierarchy,
+    HierarchicalCode,
+    Group,
+    InternationalString,
+    ItemExpr,
+    ItemList,
+    ItemPredicate,
+    KeyValue,
+    item,
+    Maintainable,
+    MaintainableArtefact,
+    Measure,
+    MeasureDimension,
+    ProvisionAgreement,
+    DataType,
+    Facet,
+    Ref,
+    Registry,
+    Representation,
+    SdmxRef,
+    SdmxUrn,
+    StructureMessage,
+    StructureSet,
+    TimeDimension,
+    UnresolvedRef,
+)
+
+__all__ = [
+    "Agency",
+    "AgencyScheme",
+    "Annotation",
+    "Annotations",
+    "ArtefactList",
+    "AttachmentLevel",
+    "Attribute",
+    "BearerToken",
+    "Categorisation",
+    "Category",
+    "CategoryMap",
+    "CategoryScheme",
+    "CategorySchemeMap",
+    "Code",
+    "CodeMap",
+    "Codelist",
+    "CodelistMap",
+    "ComponentMap",
+    "Concept",
+    "ConceptMap",
+    "ConceptScheme",
+    "ConceptSchemeMap",
+    "ConstraintAttachment",
+    "Contact",
+    "ContentConstraint",
+    "CubeRegion",
+    "DataProvider",
+    "DataProviderScheme",
+    "DataQuery",
+    "DataStructure",
+    "DataStructureMap",
+    "DataType",
+    "Dataflow",
+    "DataflowMap",
+    "Dataset",
+    "DimFilter",
+    "Dimension",
+    "Facet",
+    "FmrRegistry",
+    "Group",
+    "HierarchicalCode",
+    "Hierarchy",
+    "InternationalString",
+    "ItemExpr",
+    "ItemList",
+    "ItemPredicate",
+    "KeyValue",
+    "LazyCodelist",
+    "LocalRegistry",
+    "Maintainable",
+    "MaintainableArtefact",
+    "Measure",
+    "MeasureDimension",
+    "Provider",
+    "ProvisionAgreement",
+    "Ref",
+    "ReferenceIssue",
+    "ReferencePeriod",
+    "Registry",
+    "ReleaseCalendar",
+    "Representation",
+    "RestRegistry",
+    "SdmxRef",
+    "SdmxUrn",
+    "StructureMessage",
+    "StructureSet",
+    "TimeDimension",
+    "UnresolvedRef",
+    "ValidationIssue",
+    "dim",
+    "from_dict",
+    "item",
+    "parse",
+    "read",
+    "serialize",
+    "to_dict",
+    "to_json",
+    "to_xml",
+    "validate",
+    "validate_references",
+]

sdmxlib/api/__init__.py

@@ -0,0 +1,7 @@
+"""sdmxlib.api — HTTP client and registry."""
+
+from sdmxlib.api.providers import Provider
+from sdmxlib.api.query import GetQuery, Query
+from sdmxlib.api.registry import BearerToken, FmrRegistry, RestRegistry
+
+__all__ = ["BearerToken", "FmrRegistry", "GetQuery", "Provider", "Query", "RestRegistry"]

sdmxlib/api/client.py

@@ -0,0 +1,246 @@
+"""SdmxClient — thin httpx wrapper around the SDMX REST API."""
+
+from pathlib import Path
+from typing import Self
+
+import httpx
+
+from sdmxlib.formats import parse
+from sdmxlib.model.message import StructureMessage
+
+# SDMX REST resource path segments (lowercase endpoint name)
+_RESOURCE_PATH: dict[str, str] = {
+    "DataStructure": "datastructure",
+    "Codelist": "codelist",
+    "Dataflow": "dataflow",
+    "ConceptScheme": "conceptscheme",
+    "ProvisionAgreement": "provisionagreement",
+    "CategoryScheme": "categoryscheme",
+    "Categorisation": "categorisation",
+    "ContentConstraint": "contentconstraint",
+    "AgencyScheme": "agencyscheme",
+    "DataProviderScheme": "dataproviderorganisationscheme",
+    "Hierarchy": "hierarchy",
+    "StructureSet": "structureset",
+}
+
+# Wire parameter presets — (detail, references)
+_BROWSE_PARAMS = {"detail": "allstubs", "references": "none"}
+_FETCH_PARAMS = {"detail": "full", "references": "none"}
+_RESOLVE_PARAMS = {"detail": "referencepartial", "references": "descendants"}
+_RESOLVE_FULL = {"detail": "full", "references": "descendants"}
+
+
+class SdmxClient:
+    """Thin httpx wrapper that fetches SDMX REST resources and parses them.
+
+    Handles URL construction, Accept headers, and response parsing.
+    Does not cache — caching is the Session's responsibility.
+
+    Args:
+        endpoint: Base URL of the SDMX REST endpoint.
+        api: SDMX REST API version — ``"2.1"`` (default) or ``"3.0"``.
+             Controls URL scheme and response format.
+        timeout: HTTP request timeout in seconds.
+        headers: Extra HTTP headers merged with defaults.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        *,
+        api: str = "2.1",
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        **httpx_kwargs: object,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._api = api
+        self._v3 = api.startswith(("3", "2.0"))
+        default_headers: dict[str, str]
+        if self._v3:
+            default_headers = {"Accept": "application/vnd.sdmx.structure+xml;version=3.0"}
+        else:
+            default_headers = {"Accept": "application/xml"}
+        if headers:
+            default_headers.update(headers)
+        self._client = httpx.Client(
+            headers=default_headers,
+            timeout=timeout,
+            **httpx_kwargs,  # type: ignore[arg-type]
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # ── URL building ──────────────────────────────────────────────────────────
+
+    def _resource_url(
+        self,
+        resource: str,
+        agency: str,
+        id: str,  # noqa: A002
+        version: str,
+    ) -> str:
+        """Build the resource URL for the given API version."""
+        path = _RESOURCE_PATH.get(resource, resource.lower())
+        if self._v3:
+            # v2.x: /structure/{resource}/{agency}/{id}/{version}
+            # "latest" sentinel becomes "~" on the wire
+            ver = "~" if version == "latest" else version
+            return f"{self._endpoint}/structure/{path}/{agency}/{id}/{ver}"
+        # v1.5: /{resource}/{agency}/{id}/{version}
+        return f"{self._endpoint}/{path}/{agency}/{id}/{version}"
+
+    def _collection_url(self, resource: str, agency: str | None) -> str:
+        """Build the collection URL (all artefacts of a type)."""
+        path = _RESOURCE_PATH.get(resource, resource.lower())
+        agency_seg = agency or ("*" if self._v3 else "all")
+        if self._v3:
+            return f"{self._endpoint}/structure/{path}/{agency_seg}"
+        return f"{self._endpoint}/{path}/{agency_seg}"
+
+    # ── Parse version ─────────────────────────────────────────────────────────
+
+    @property
+    def _parse_version(self) -> str:
+        """Format version string passed to the parser."""
+        return "3.0" if self._v3 else "2.1"
+
+    # ── HTTP methods ──────────────────────────────────────────────────────────
+
+    def get_artefact(
+        self,
+        resource: str,
+        agency: str,
+        id: str,  # noqa: A002
+        version: str = "latest",
+        *,
+        detail: str = "full",
+        references: str = "none",
+    ) -> StructureMessage:
+        """Fetch a single maintainable artefact."""
+        url = self._resource_url(resource, agency, id, version)
+        params: dict[str, str] = {"detail": detail}
+        if references != "none":
+            params["references"] = references
+        response = self._client.get(url, params=params)
+        response.raise_for_status()
+        return parse(response.content, version=self._parse_version)
+
+    def get_all(
+        self,
+        resource: str,
+        agency: str | None = None,
+        *,
+        detail: str = "full",
+        references: str = "none",
+    ) -> StructureMessage:
+        """Fetch all artefacts of a type, optionally filtered by agency."""
+        url = self._collection_url(resource, agency)
+        params: dict[str, str] = {"detail": detail}
+        if references != "none":
+            params["references"] = references
+        response = self._client.get(url, params=params)
+        response.raise_for_status()
+        return parse(response.content, version=self._parse_version)
+
+    def _data_url(
+        self,
+        agency: str,
+        id: str,  # noqa: A002
+        version: str,
+        key: str,
+    ) -> str:
+        """Build the data URL for the given API version."""
+        if self._v3:
+            ver = "~" if version == "latest" else version
+            return f"{self._endpoint}/data/dataflow/{agency}/{id}/{ver}/{key}"
+        return f"{self._endpoint}/data/{agency},{id},{version}/{key}"
+
+    def get_data(
+        self,
+        agency: str,
+        id: str,  # noqa: A002
+        version: str = "latest",
+        *,
+        key: str = "all",
+        start_period: str | None = None,
+        end_period: str | None = None,
+    ) -> bytes:
+        """Fetch observation data as SDMX-CSV bytes.
+
+        Args:
+            agency: Dataflow maintainer agency id.
+            id: Dataflow id.
+            version: Dataflow version. Defaults to ``"latest"``.
+            key: SDMX key filter string, e.g. ``"M.AT+DE.INDPRO"``.
+                 Defaults to ``"all"`` (all observations).
+            start_period: ISO period start, e.g. ``"2020-01"``.
+            end_period: ISO period end.
+
+        Returns:
+            Raw SDMX-CSV bytes.
+        """
+        url = self._data_url(agency, id, version, key)
+        params: dict[str, str] = {}
+        if start_period is not None:
+            params["startPeriod"] = start_period
+        if end_period is not None:
+            params["endPeriod"] = end_period
+        response = self._client.get(
+            url,
+            params=params,
+            headers={"Accept": "text/csv"},
+        )
+        response.raise_for_status()
+        return response.content
+
+    def stream_data_to(
+        self,
+        agency: str,
+        id: str,  # noqa: A002
+        version: str = "latest",
+        *,
+        path: Path,
+        key: str = "all",
+        start_period: str | None = None,
+        end_period: str | None = None,
+    ) -> None:
+        """Stream observation data directly to a file.
+
+        Uses httpx chunked streaming — the response is never fully loaded into
+        memory. Suitable for multi-GB datasets.
+
+        Args:
+            agency: Dataflow maintainer agency id.
+            id: Dataflow id.
+            version: Dataflow version.
+            path: Destination file path.
+            key: SDMX key filter string.
+            start_period: ISO period start.
+            end_period: ISO period end.
+        """
+        url = self._data_url(agency, id, version, key)
+        params: dict[str, str] = {}
+        if start_period is not None:
+            params["startPeriod"] = start_period
+        if end_period is not None:
+            params["endPeriod"] = end_period
+        with self._client.stream(
+            "GET",
+            url,
+            params=params,
+            headers={"Accept": "text/csv"},
+        ) as response:
+            response.raise_for_status()
+            with path.open("wb") as f:
+                for chunk in response.iter_bytes():
+                    f.write(chunk)

sdmxlib/api/filters.py

@@ -0,0 +1,67 @@
+"""Server-side dimension filter expressions for DataQuery.slice()."""
+
+from __future__ import annotations
+
+from attrs import frozen
+
+
+@frozen
+class DimFilter:
+    """A resolved server-side filter on a single dimension.
+
+    Produced by :func:`dim` expressions — not constructed directly.
+
+    Attributes:
+        id: DSD dimension id.
+        codes: One or more codes to match (OR semantics, ``+``-joined on the wire).
+    """
+
+    id: str
+    codes: list[str]
+
+
+class _DimExpr:
+    """Builder returned by :func:`dim`. Produces a :class:`DimFilter` via ``==`` or ``.isin()``."""
+
+    def __init__(self, id: str) -> None:  # noqa: A002
+        self._id = id
+
+    def __eq__(self, other: object) -> DimFilter:  # type: ignore[override]
+        if not isinstance(other, str):
+            msg = f"Expected a code string, got {type(other).__name__!r}"
+            raise TypeError(msg)
+        return DimFilter(id=self._id, codes=[other])
+
+    def isin(self, codes: list[str]) -> DimFilter:
+        """Match any of the given codes (server-side OR — ``+``-joined in the key).
+
+        Codes are sorted for stable, deterministic URLs.
+
+        Example:
+            sl.dim("REF_AREA").isin(["AT", "DE", "FR"])
+        """
+        return DimFilter(id=self._id, codes=sorted(codes))
+
+    def __hash__(self) -> int:
+        return hash(self._id)
+
+    def __repr__(self) -> str:
+        return f"dim({self._id!r})"
+
+
+def dim(id: str) -> _DimExpr:  # noqa: A002
+    """Create a server-side dimension filter expression for :meth:`DataQuery.slice`.
+
+    Use ``==`` for a single code or ``.isin()`` for multiple codes (OR semantics).
+    Dimensions not mentioned in any filter become wildcards in the SDMX REST key.
+
+    Example:
+        sl.dim("FREQ") == "M"
+        sl.dim("REF_AREA").isin(["AT", "DE", "FR"])
+
+        reg.data(flow).slice(
+            sl.dim("FREQ") == "M",
+            sl.dim("REF_AREA").isin(["AT", "DE"]),
+        ).fetch()
+    """
+    return _DimExpr(id)

sdmxlib/api/providers.py

@@ -0,0 +1,66 @@
+"""Known SDMX REST endpoint URLs and API versions.
+
+Use as a shortcut when constructing a RestRegistry::
+
+    with sl.RestRegistry(sl.Provider.ECB) as reg:
+        ...
+    with sl.RestRegistry(sl.Provider["ECB"]) as reg:
+        ...
+"""
+
+from attrs import frozen
+
+
+@frozen
+class ProviderInfo:
+    """URL and REST API version for a known SDMX endpoint."""
+
+    url: str
+    api: str = "2.1"
+
+
+class Provider:
+    """Built-in SDMX REST endpoint URLs.
+
+    Each entry is a :class:`ProviderInfo` carrying the endpoint URL and its
+    REST API version. Pass directly to ``RestRegistry``::
+
+        with sl.RestRegistry(sl.Provider.ECB) as reg:
+            ...
+        with sl.RestRegistry(sl.Provider.BIS) as reg:
+            ...
+
+    Supports both attribute and subscript access::
+
+        sl.Provider.ECB  # ProviderInfo(url="...", api="2.1")
+        sl.Provider["ECB"]  # same
+        sl.Provider.ECB.url  # "https://data-api.ecb.europa.eu/service"
+        sl.Provider.ECB.api  # "2.1"
+    """
+
+    #: European Central Bank
+    ECB = ProviderInfo("https://data-api.ecb.europa.eu/service", api="2.1")
+    #: Bank for International Settlements
+    BIS = ProviderInfo("https://stats.bis.org/api/v1", api="2.1")
+    #: Eurostat
+    ESTAT = ProviderInfo("https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1", api="2.1")
+    #: International Monetary Fund
+    IMF = ProviderInfo("https://sdmxcentral.imf.org/ws/public/sdmxapi/rest", api="2.1")
+    #: OECD
+    OECD = ProviderInfo("https://sdmx.oecd.org/public/rest", api="2.1")
+    #: SDMX Global Registry (FMR — SDMX 3.0 endpoint)
+    SDMX_GLOBAL = ProviderInfo("https://registry.sdmx.org/sdmx/v2", api="3.0")
+
+    def __class_getitem__(cls, key: str) -> ProviderInfo:
+        val = getattr(cls, key, None)
+        if not isinstance(val, ProviderInfo):
+            available = ", ".join(
+                k for k in vars(cls) if not k.startswith("_") and isinstance(getattr(cls, k), ProviderInfo)
+            )
+            msg = f"{key!r} — available: {available}"
+            raise KeyError(msg)
+        return val
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        msg = "Provider cannot be subclassed"
+        raise TypeError(msg)