sdmxlib 0.28.2__tar.gz → 0.29.0__tar.gz

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/PKG-INFO

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

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.28.2"
+version = "0.29.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -45,7 +45,6 @@ markers = [
 
 [tool.coverage.run]
 source = ["src/sdmxlib"]
-omit = ["src/sdmxlib/contrib/*"]
 
 [tool.coverage.report]
 show_missing = true
@@ -63,7 +62,19 @@ pythonVersion = "3.13"
 pythonPlatform = "Linux"
 venvPath = "."
 venv = ".venv"
+# "standard" rather than "strict" because the strict-only rules
+# (reportUnknownMemberType, reportUnknownArgumentType,
+# reportUnknownVariableType) fire on every duckdb / lxml / pyarrow
+# touch — third-party stubs we don't control. Standard mode still
+# catches the bugs we care about (assignments, attribute access,
+# return types, missing arguments). Strict-mode rules that *are*
+# enforceable on this codebase are turned on manually via
+# `# pyright: ignore[...]` opt-outs at the call sites that need them.
 typeCheckingMode = "standard"
+# `pytest.raises(...)` doesn't bind a name — without this every
+# `with pytest.raises(...):` block would need `# pyright: ignore`.
+# Off project-wide since the only places that consume return values
+# we *don't* care about are tests.
 reportUnusedCallResult = false
 
 [dependency-groups]

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/src/sdmxlib/__init__.py

@@ -11,7 +11,7 @@ from sdmxlib.data_store import DataStore
 from sdmxlib.sql import CompileContext, Predicate, SqlRelation
 from sdmxlib.formats import parse, read, serialize, to_json, to_xml
 from sdmxlib.local import LazyCodelist, LazyHierarchy, Registry
-from sdmxlib.local._data_store import DuckDBDataStore
+from sdmxlib.local.data_store import DuckDBDataStore
 from sdmxlib.rest import ComponentFilter, parse_components
 from sdmxlib.model.convert import from_dict, to_dict
 from sdmxlib.model.validation import ReferenceIssue, ValidationIssue, validate, validate_references
@@ -20,27 +20,31 @@ from sdmxlib.model import (
     AgencyScheme,
     Annotation,
     Annotations,
+    AnyRef,
     ArtefactList,
     AttachmentLevel,
     Attribute,
+    AttributeUsage,
+    CascadeSelection,
     Categorisation,
     Category,
     CategoryScheme,
     Code,
     CodeQuery,
+    CodeSelection,
     Codelist,
+    CodelistExtension,
     Concept,
     ConceptScheme,
-    CategoryMap,
     CategorySchemeMap,
-    CodeMap,
-    CodelistMap,
     ComponentMap,
-    ConceptMap,
     ConceptSchemeMap,
+    AttachmentConstraint,
     ConstraintAttachment,
+    ConstraintType,
     Contact,
     DataConstraint,
+    DataKey,
     CubeRegion,
     ReferencePeriod,
     ReleaseCalendar,
@@ -48,26 +52,30 @@ from sdmxlib.model import (
     DataProviderScheme,
     DataStructure,
     Dataset,
-    DataStructureMap,
     Dataflow,
     DataflowBinding,
-    DataflowMap,
     Dimension,
     DriftIssue,
     Hierarchy,
     HierarchicalCode,
+    HierarchyAssociation,
     Group,
+    InclusionMode,
+    IndexValueMap,
     InMemoryRegistry,
     InternationalString,
     ItemExpr,
     ItemList,
+    ItemMap,
     ItemPredicate,
     KeyValue,
     Level,
+    LiteralValueMap,
     item,
     Maintainable,
     MaintainableArtefact,
     Measure,
+    MemberValue,
     MeasureDimension,
     MetadataAttribute,
     MetadataMessage,
@@ -80,14 +88,17 @@ from sdmxlib.model import (
     DataType,
     Facet,
     Ref,
+    RegexValueMap,
     RegistryReader,
     Representation,
+    RepresentationMap,
     SdmxRef,
     SdmxUrn,
+    StructureMap,
     StructureMessage,
-    StructureSet,
     TimeDimension,
     UnresolvedRef,
+    ValueMap,
     artefact_urn,
     code,
     node,
@@ -100,42 +111,44 @@ __all__ = [
     "AgencyScheme",
     "Annotation",
     "Annotations",
+    "AnyRef",
     "ArtefactList",
+    "AttachmentConstraint",
     "AttachmentLevel",
     "Attribute",
+    "AttributeUsage",
     "BearerToken",
+    "CascadeSelection",
     "Categorisation",
     "Category",
-    "CategoryMap",
     "CategoryScheme",
     "CategorySchemeMap",
     "Code",
-    "CodeMap",
     "CodeQuery",
+    "CodeSelection",
     "Codelist",
-    "CodelistMap",
+    "CodelistExtension",
     "CompileContext",
     "ComponentFilter",
     "ComponentMap",
     "Concept",
-    "ConceptMap",
     "ConceptScheme",
     "ConceptSchemeMap",
     "ConstraintAttachment",
+    "ConstraintType",
     "Contact",
     "CubeRegion",
     "DataConstraint",
+    "DataKey",
     "DataProvider",
     "DataProviderScheme",
     "DataQuery",
     "DataStore",
     "DataStructure",
-    "DataStructureMap",
     "DataType",
     "Dataflow",
     "DataflowBinding",
     "DataflowEntry",
-    "DataflowMap",
     "Dataset",
     "DimFilter",
     "Dimension",
@@ -149,20 +162,26 @@ __all__ = [
     "Group",
     "HierarchicalCode",
     "Hierarchy",
+    "HierarchyAssociation",
     "HierarchyNodeQuery",
     "InMemoryRegistry",
+    "InclusionMode",
+    "IndexValueMap",
     "InternationalString",
     "ItemExpr",
     "ItemList",
+    "ItemMap",
     "ItemPredicate",
     "KeyValue",
     "LazyCodelist",
     "LazyHierarchy",
     "Level",
+    "LiteralValueMap",
     "Maintainable",
     "MaintainableArtefact",
     "Measure",
     "MeasureDimension",
+    "MemberValue",
     "MetadataAttribute",
     "MetadataMessage",
     "MetadataSet",
@@ -174,6 +193,7 @@ __all__ = [
     "Ref",
     "ReferenceIssue",
     "ReferencePeriod",
+    "RegexValueMap",
     "Registry",
     "RegistryReader",
     "RegistryUnavailable",
@@ -181,15 +201,17 @@ __all__ = [
     "ReportedAttribute",
     "ReportedAttributeValue",
     "Representation",
+    "RepresentationMap",
     "RestRegistry",
     "SdmxRef",
     "SdmxUrn",
     "SqlRelation",
+    "StructureMap",
     "StructureMessage",
-    "StructureSet",
     "TimeDimension",
     "UnresolvedRef",
     "ValidationIssue",
+    "ValueMap",
     "artefact_urn",
     "code",
     "dim",

sdmxlib-0.29.0/src/sdmxlib/_duckdb.py

@@ -0,0 +1,18 @@
+"""Private DuckDB helpers shared by the storage layer and model query DSLs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import duckdb
+
+
+def scalar(cursor: duckdb.DuckDBPyConnection, default: Any = None) -> Any:
+    """Return the first column of the cursor's first row, or *default* if empty.
+
+    Centralises the ``row = cur.fetchone(); row[0] if row else default``
+    idiom so callers don't need to repeat the indexing dance or paper over
+    pyright with ``# type: ignore[index]``.
+    """
+    row = cursor.fetchone()
+    return row[0] if row is not None else default

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/src/sdmxlib/api/client.py

@@ -134,7 +134,9 @@ class SdmxClient:
         response = self._client.get(url, params=params)
         response.raise_for_status()
         msg = parse(response.content, version=self._parse_version)
-        assert isinstance(msg, StructureMessage)  # noqa: S101  # structure endpoint only
+        if not isinstance(msg, StructureMessage):
+            err = f"Expected StructureMessage from structure endpoint, got {type(msg).__name__}"
+            raise TypeError(err)
         return msg
 
     def get_all(
@@ -153,7 +155,9 @@ class SdmxClient:
         response = self._client.get(url, params=params)
         response.raise_for_status()
         msg = parse(response.content, version=self._parse_version)
-        assert isinstance(msg, StructureMessage)  # noqa: S101  # structure endpoint only
+        if not isinstance(msg, StructureMessage):
+            err = f"Expected StructureMessage from structure endpoint, got {type(msg).__name__}"
+            raise TypeError(err)
         return msg
 
     def _data_url(

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/src/sdmxlib/api/federated.py

@@ -1,6 +1,6 @@
 """FederatedRegistry — agency-routed dispatch across multiple sources.
 
-The headline of #46. Composes any number of :class:`~sdmxlib.model.registry.Registry`
+The headline of #46. Composes any number of `Registry`
 instances (in-memory, local DuckDB, REST) and dispatches each ``get(urn)``
 call to the source responsible for the URN's maintenance agency. The user
 sees a single registry that resolves URNs from many backends.
@@ -45,23 +45,23 @@ class FederatedRegistry:
     """Read-side dispatcher across multiple Registry sources.
 
     Routes each URN-keyed lookup by maintenance agency. Configure with a
-    ``routing`` map from agency id to a :class:`Registry` source, plus
+    ``routing`` map from agency id to a `Registry` source, plus
     an optional ``default`` source for agencies absent from the map.
 
-    Satisfies the :class:`~sdmxlib.model.registry.Registry` Protocol —
+    Satisfies the `Registry` Protocol —
     a ``FederatedRegistry`` can itself be a source in another
     ``FederatedRegistry`` (composition).
 
     Args:
         routing: Mapping of agency id (e.g. ``"ESTAT"``, ``"SDMX"``) to a
-            :class:`Registry` source. Lookup keys are matched against
+            `Registry` source. Lookup keys are matched against
             ``SdmxUrn.agency``.
         default: Optional fallback source for URNs whose agency is not
             in ``routing``. ``None`` (the default) means "no fallback":
-            unrouted URNs raise :class:`KeyError`.
+            unrouted URNs raise `KeyError`.
         failure: How to treat exceptions raised by a routed source.
-            Defaults to :attr:`FailurePolicy.HARD_FAIL` — propagate the
-            underlying error wrapped in :class:`RegistryUnavailable`.
+            Defaults to `HARD_FAIL` — propagate the
+            underlying error wrapped in `RegistryUnavailable`.
 
     Note:
         FederatedRegistry is a *router*, not a *store*. It has no
@@ -117,9 +117,9 @@ class FederatedRegistry:
         - URN agency absent and no default → raise ``KeyError``.
 
         Errors from the routed source are wrapped in
-        :class:`RegistryUnavailable` when ``failure`` is
-        :attr:`FailurePolicy.HARD_FAIL` (default), or swallowed (returning
-        ``None``) when ``failure`` is :attr:`FailurePolicy.RETURN_NONE`.
+        `RegistryUnavailable` when ``failure`` is
+        `HARD_FAIL` (default), or swallowed (returning
+        ``None``) when ``failure`` is `RETURN_NONE`.
         """
         source = self._route(urn)
         if source is None:

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/src/sdmxlib/api/filters.py

@@ -9,7 +9,7 @@ from attrs import frozen
 class DimFilter:
     """A resolved server-side filter on a single dimension.
 
-    Produced by :func:`dim` expressions — not constructed directly.
+    Produced by `dim` expressions — not constructed directly.
 
     Attributes:
         id: DSD dimension id.
@@ -21,7 +21,7 @@ class DimFilter:
 
 
 class _DimExpr:
-    """Builder returned by :func:`dim`. Produces a :class:`DimFilter` via ``==`` or ``.isin()``."""
+    """Builder returned by `dim`. Produces a `DimFilter` via ``==`` or ``.isin()``."""
 
     def __init__(self, id: str) -> None:  # noqa: A002
         self._id = id
@@ -50,7 +50,7 @@ class _DimExpr:
 
 
 def dim(id: str) -> _DimExpr:  # noqa: A002
-    """Create a server-side dimension filter expression for :meth:`DataQuery.slice`.
+    """Create a server-side dimension filter expression for `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.

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/src/sdmxlib/api/policy.py

@@ -4,7 +4,7 @@ Per #46's pitfall list ("Partial failure handling"), there are several
 valid behaviours when a routed source is unreachable: hard-fail, return
 ``None`` (treat as not-found), or fall through to a stale local cache.
 The policy is configurable per source or globally on
-:class:`~sdmxlib.api.federated.FederatedRegistry`.
+`FederatedRegistry`.
 """
 
 from enum import Enum

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/src/sdmxlib/api/providers.py

@@ -19,7 +19,7 @@ class ProviderInfo:
         url: Base REST endpoint URL.
         api: SDMX REST API version (``"2.1"`` or ``"3.0"``).
         id: Stable identifier used as the ``source_registry`` provenance
-            tag when a :class:`RestRegistry` materialises through to a
+            tag when a `RestRegistry` materialises through to a
             local store. Required for federation; ``None`` for ad-hoc
             URLs without a known label.
     """
@@ -32,7 +32,7 @@ class ProviderInfo:
 class Provider:
     """Built-in SDMX REST endpoint URLs.
 
-    Each entry is a :class:`ProviderInfo` carrying the endpoint URL and its
+    Each entry is a `ProviderInfo` carrying the endpoint URL and its
     REST API version. Pass directly to ``RestRegistry``::
 
         with sl.RestRegistry(sl.Provider.ECB) as reg:

{sdmxlib-0.28.2 → sdmxlib-0.29.0}/src/sdmxlib/api/query.py

@@ -252,15 +252,15 @@ class Query[T]:
 
 
 class DataQuery:
-    """Lazy data fetch — resolves to a :class:`~sdmxlib.model.dataset.Dataset`.
+    """Lazy data fetch — resolves to a `Dataset`.
 
-    Returned by :meth:`~sdmxlib.api.registry.RestRegistry.data`. Use
-    :meth:`fetch` for in-memory loading or :meth:`fetch_to` to stream
-    directly to a file for large datasets. Use :meth:`slice` and
-    :meth:`measures` to filter what comes over the wire.
+    Returned by `data`. Use
+    `fetch` for in-memory loading or `fetch_to` to stream
+    directly to a file for large datasets. Use `slice` and
+    `measures` to filter what comes over the wire.
 
     Example:
-        # Raw positional key string (backwards compatible)
+        # Raw SDMX REST positional key string
         ds = reg.data(flow, key="M.USD.EUR.SP00.A").fetch()
 
         # Named dimension filter — no positional knowledge needed
@@ -301,13 +301,13 @@ class DataQuery:
     def slice(self, *filters: DimFilter) -> Self:
         """Add server-side dimension filters to the SDMX key.
 
-        Each filter is a :class:`~sdmxlib.api.filters.DimFilter` produced by
-        :func:`~sdmxlib.dim`. Calling ``.slice()`` multiple times accumulates
+        Each filter is a `DimFilter` produced by
+        `dim`. Calling ``.slice()`` multiple times accumulates
         filters — each call is additive.
 
         Unspecified dimensions become wildcards. Raises ``ValueError`` if
         ``key=`` was also passed to
-        :meth:`~sdmxlib.api.registry.RestRegistry.data`.
+        `data`.
 
         Example:
             import sdmxlib as sl
@@ -337,7 +337,7 @@ class DataQuery:
 
         For SDMX 2.1 flows with a ``MeasureDimension`` (e.g. ``INDIC_EM``),
         this filters the indicator key segment — controlling which columns
-        appear after :meth:`pivot`. For SDMX 3.0 multi-measure flows this
+        appear after `pivot`. For SDMX 3.0 multi-measure flows this
         will become the ``measures=`` query parameter.
 
         ``codes`` is a single code string or a list of code strings.
@@ -412,8 +412,8 @@ class DataQuery:
 
         Uses httpx chunked streaming — the response is never fully loaded into
         memory. The returned ``Dataset.data`` is a genuine ``pl.LazyFrame``
-        backed by ``pl.scan_csv``, so :meth:`~sdmxlib.model.dataset.Dataset.sink_parquet`
-        and :meth:`~sdmxlib.model.dataset.Dataset.sink_csv` are truly streaming.
+        backed by ``pl.scan_csv``, so `sink_parquet`
+        and `sink_csv` are truly streaming.
 
         The caller owns the file — it is not deleted when the Dataset is
         garbage collected.