sdmxlib 0.69.0__tar.gz → 0.70.0__tar.gz

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.69.0
+Version: 0.70.0
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner
@@ -13,18 +13,18 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Dist: attrs>=26.1.0
-Requires-Dist: duckdb>=1.5.6
+Requires-Dist: duckdb>=2.0.0
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: lxml>=6.0.2
-Requires-Dist: msgspec>=0.19
-Requires-Dist: polars>=1.39.3
-Requires-Dist: pyarrow>=18.0.0
-Requires-Dist: typing-extensions>=4.13
+Requires-Dist: lxml>=6.1.3
+Requires-Dist: msgspec>=0.22.0
+Requires-Dist: polars>=2.0.0
+Requires-Dist: pyarrow>=26.0.0
+Requires-Dist: typing-extensions>=4.16.0
 Requires-Python: >=3.14
-Project-URL: Homepage, https://gitlab.com/pinax-suite/sdmxlib
-Project-URL: Repository, https://gitlab.com/pinax-suite/sdmxlib
-Project-URL: Documentation, https://pinax-suite.gitlab.io/sdmxlib
-Project-URL: Changelog, https://gitlab.com/pinax-suite/sdmxlib/-/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/StatCat-Suite/sdmxlib
+Project-URL: Repository, https://github.com/StatCat-Suite/sdmxlib
+Project-URL: Documentation, https://statcat-suite.github.io/sdmxlib
+Project-URL: Changelog, https://github.com/StatCat-Suite/sdmxlib/blob/main/CHANGELOG.md
 Description-Content-Type: text/markdown
 
 # sdmxlib
@@ -120,7 +120,7 @@ library's actual surface. Point your assistant at them.
 ## Upgrading
 
 sdmxlib is pre-stability and breaks cleanly rather than carrying two spellings
-of the same idea. [Upgrading](https://pinax-suite.gitlab.io/sdmxlib/upgrading/)
+of the same idea. [Upgrading](https://statcat-suite.github.io/sdmxlib/upgrading/)
 lists every breaking change since 0.48, with the old and new spelling of each —
 `sl.Registry` is now `sl.LocalRegistry`, `get()` takes a URN and a resolution
 depth, the four query DSLs are one path language, and every model class is
@@ -128,7 +128,7 @@ frozen.
 
 ## Documentation
 
-See the [docs](https://pinax-suite.gitlab.io/sdmxlib/) for the full cookbook,
+See the [docs](https://statcat-suite.github.io/sdmxlib/) for the full cookbook,
 including:
 
 - Connecting to registries and choosing a resolution depth
@@ -148,3 +148,8 @@ just test            # unit tests
 just test-integration  # end-to-end tests, replayed from recorded cassettes
 just ci              # the full gate: lint, typecheck, unit, docs, integration
 ```
+
+Issues are tracked on [GitHub](https://github.com/StatCat-Suite/sdmxlib/issues).
+The project started on GitLab, so a bare `#492` in code, comments or docs means
+an issue in the [GitLab tracker](https://gitlab.com/pinax-suite/sdmxlib/-/issues),
+which stays readable as an archive. GitHub issues are written `GH-12`.

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/README.md

@@ -91,7 +91,7 @@ library's actual surface. Point your assistant at them.
 ## Upgrading
 
 sdmxlib is pre-stability and breaks cleanly rather than carrying two spellings
-of the same idea. [Upgrading](https://pinax-suite.gitlab.io/sdmxlib/upgrading/)
+of the same idea. [Upgrading](https://statcat-suite.github.io/sdmxlib/upgrading/)
 lists every breaking change since 0.48, with the old and new spelling of each —
 `sl.Registry` is now `sl.LocalRegistry`, `get()` takes a URN and a resolution
 depth, the four query DSLs are one path language, and every model class is
@@ -99,7 +99,7 @@ frozen.
 
 ## Documentation
 
-See the [docs](https://pinax-suite.gitlab.io/sdmxlib/) for the full cookbook,
+See the [docs](https://statcat-suite.github.io/sdmxlib/) for the full cookbook,
 including:
 
 - Connecting to registries and choosing a resolution depth
@@ -119,3 +119,8 @@ just test            # unit tests
 just test-integration  # end-to-end tests, replayed from recorded cassettes
 just ci              # the full gate: lint, typecheck, unit, docs, integration
 ```
+
+Issues are tracked on [GitHub](https://github.com/StatCat-Suite/sdmxlib/issues).
+The project started on GitLab, so a bare `#492` in code, comments or docs means
+an issue in the [GitLab tracker](https://gitlab.com/pinax-suite/sdmxlib/-/issues),
+which stays readable as an archive. GitHub issues are written `GH-12`.

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.69.0"
+version = "0.70.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -20,13 +20,13 @@ classifiers = [
 ]
 dependencies = [
     "attrs>=26.1.0",
-    "duckdb>=1.5.6",
+    "duckdb>=2.0.0",
     "httpx>=0.28.1",
-    "lxml>=6.0.2",
-    "msgspec>=0.19",
-    "polars>=1.39.3",
-    "pyarrow>=18.0.0",
-    "typing-extensions>=4.13",
+    "lxml>=6.1.3",
+    "msgspec>=0.22.0",
+    "polars>=2.0.0",
+    "pyarrow>=26.0.0",
+    "typing-extensions>=4.16.0",
 ]
 
 [project.license]
@@ -37,10 +37,10 @@ name = "gabrielgellner"
 email = "gabrielgellner@gmail.com"
 
 [project.urls]
-Homepage = "https://gitlab.com/pinax-suite/sdmxlib"
-Repository = "https://gitlab.com/pinax-suite/sdmxlib"
-Documentation = "https://pinax-suite.gitlab.io/sdmxlib"
-Changelog = "https://gitlab.com/pinax-suite/sdmxlib/-/blob/main/CHANGELOG.md"
+Homepage = "https://github.com/StatCat-Suite/sdmxlib"
+Repository = "https://github.com/StatCat-Suite/sdmxlib"
+Documentation = "https://statcat-suite.github.io/sdmxlib"
+Changelog = "https://github.com/StatCat-Suite/sdmxlib/blob/main/CHANGELOG.md"
 
 [build-system]
 requires = ["uv_build>=0.13.0,<0.14.0"]
@@ -105,7 +105,7 @@ dev = [
     "types-PyYAML>=6.0.12",
     "mkdocs-material>=9.7.6",
     "mkdocstrings[python]>=1.0.3",
-    "polars>=1.39.3",
+    "polars>=2.0.0",
     "pytest>=9.0.2",
     "jsonschema[format-nongpl]>=4.21.0",
     "pytest-benchmark>=4.0.0",

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.69.0"
+version = "0.70.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -17,37 +17,36 @@ classifiers = [
 ]
 dependencies = [
     "attrs>=26.1.0",
-    # >=1.5.3: ducklake extension must support DuckLake catalog format 1.0,
-    # which is what a bundle built with duckdb 1.5.3 carries. duckdb 1.5.1's
-    # ducklake tops out at format 0.4 and fails to ATTACH such bundles with "DuckLake catalog version mismatch".
-    #
-    # Moved to >=1.5.5 while investigating #400 — two patch releases of fixes,
-    # taken on their own merits. It is **not** a fix for #400: 1.5.0, 1.5.1,
-    # 1.5.2, 1.5.3, 1.5.4, 1.5.5 and 1.6.0.dev379 all read the affected bundle
-    # identically, so that defect is in the file rather than in the reader.
-    #
-    # >=1.5.6: test_annotation_subtree_read (#426) asserts the annotation
-    # subtree read uses the owner index. 1.5.5's planner chooses a SEQ_SCAN
-    # over `owner_artefact_urn = ?` (502 rows read) and 1.5.6 uses the index,
-    # so on 1.5.5 the read scans every annotation row.
-    "duckdb>=1.5.6",
+    # >=2.0: an `execute()` result has no `pl()` any more, so frames come from
+    # a relation (`sql().pl()`), and a relation call on a handle holding an
+    # unfinished result raises rather than clobbering it (`session.completed`).
+    # The tests assert 2.0's profile JSON, error text and sort costs.
+    "duckdb>=2.0.0",
     "httpx>=0.28.1",
-    "lxml>=6.0.2",
-    "msgspec>=0.19",
-    "polars>=1.39.3",
-    "pyarrow>=18.0.0",
+    # >=6.1: `resolve_entities` defaults to 'internal' (CVE-2026-41066), so no
+    # parse expands an external entity.
+    "lxml>=6.1.3",
+    # >=0.22: on 3.14 an older msgspec cannot resolve a Struct field's forward
+    # reference (`list[SentinelValueJson]` in `_structure_dto`), and importing
+    # sdmxlib raises NameError.
+    "msgspec>=0.22.0",
+    # >=2.0: a cast no longer parses text into a date, so `_typed` parses it
+    # (`query._converted`); and `collect()` streams, so an order is sorted for.
+    "polars>=2.0.0",
+    # >=22 is the first with Python 3.14 wheels; 26 is what the suite runs.
+    "pyarrow>=26.0.0",
     # PEP 728's `closed=True` TypedDict, which `typing` gains only in 3.15: a
     # TypedDict unpacked into a constructor (`**read_reference_attrs(el)`) must
     # be closed for a checker to know it holds no other key. httpx already
     # brings it in, through anyio; declared because we now import it.
-    "typing-extensions>=4.13",
+    "typing-extensions>=4.16.0",
 ]
 
 [project.urls]
-Homepage      = "https://gitlab.com/pinax-suite/sdmxlib"
-Repository    = "https://gitlab.com/pinax-suite/sdmxlib"
-Documentation = "https://pinax-suite.gitlab.io/sdmxlib"
-Changelog     = "https://gitlab.com/pinax-suite/sdmxlib/-/blob/main/CHANGELOG.md"
+Homepage      = "https://github.com/StatCat-Suite/sdmxlib"
+Repository    = "https://github.com/StatCat-Suite/sdmxlib"
+Documentation = "https://statcat-suite.github.io/sdmxlib"
+Changelog     = "https://github.com/StatCat-Suite/sdmxlib/blob/main/CHANGELOG.md"
 
 [build-system]
 requires = ["uv_build>=0.13.0,<0.14.0"]
@@ -119,7 +118,7 @@ dev = [
   "types-PyYAML>=6.0.12",
   "mkdocs-material>=9.7.6",
   "mkdocstrings[python]>=1.0.3",
-  "polars>=1.39.3",
+  "polars>=2.0.0",
   "pytest>=9.0.2",
   "jsonschema[format-nongpl]>=4.21.0",
   "pytest-benchmark>=4.0.0",

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/__init__.py

@@ -54,6 +54,7 @@ from sdmxlib.model.validation import (
     ReferenceIssue,
     ReferenceValidationError,
     SdmxConformanceError,
+    SdmxErrorMessage,
     SdmxParseError,
     ValidationError,
     ValidationIssue,
@@ -380,6 +381,7 @@ __all__ = [
     "RowKind",
     "SchemaInspector",
     "SdmxConformanceError",
+    "SdmxErrorMessage",
     "SdmxParseError",
     "SdmxRef",
     "SdmxUrn",

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/formats/__init__.py

@@ -58,6 +58,7 @@ from sdmxlib.model.registry import SupportsAddAll
 from sdmxlib.model.validation import (
     LossyReadError,
     SdmxConformanceError,
+    SdmxErrorMessage,
     SdmxParseError,
     ValidationError,
     check_metadata_serialisable,
@@ -163,6 +164,9 @@ def parse(
             refusals and carries them as ``.refused``, with everything that
             was read as ``.message``. When ``lossless`` and anything was
             lost, `LossyReadError`, carrying ``.lost`` and ``.message``.
+            When the document is an SDMX error message (``<mes:Error>``,
+            ``{"errors": [...]}``), `SdmxErrorMessage`, carrying each
+            error's code and text as ``.errors``.
     """
     try:
         # Read straight into an in-memory registry: its references are bound
@@ -201,6 +205,7 @@ def parse(
 def _dispatch(data: bytes, *, version: str | None) -> StructureMessage | MetadataMessage:
     """Detect format and message kind, then hand off to the matching reader."""
     detected = version or _detect_version(data)
+    _refuse_error_message(data, detected)
     kind = _detect_message_kind(data, detected)
 
     if kind == "metadata":
@@ -334,6 +339,69 @@ _MESSAGE_NS_VERSION = {_MES_21: "2.1", _MES_30: "3.0", _MES_31: "3.1"}
 #: Local name of the SDMX-ML root element that carries reported metadata.
 _METADATA_ROOT = "GenericMetadata"
 
+#: Local name of the SDMX-ML root element of an error message, and of each error in it.
+_ERROR_ROOT = "Error"
+_ERROR_ENTRY = "ErrorMessage"
+
+
+class _ErrorProbeEntry(msgspec.Struct):
+    """One SDMX-JSON error. ``message`` is not in the schema; FMR 12.4 writes it."""
+
+    code: int | float | str
+    title: str | None = None
+    detail: str | None = None
+    message: str | None = None
+
+
+class _ErrorProbe(msgspec.Struct):
+    """Just enough of an SDMX-JSON document to tell an error message from the rest."""
+
+    errors: list[_ErrorProbeEntry] | None = None
+    data: msgspec.Raw | None = None
+
+
+def _refuse_error_message(data: bytes, version: str) -> None:
+    """Raise `SdmxErrorMessage` if *data* is an SDMX error message (GH-31).
+
+    SDMX-ML: the root is ``<mes:Error>``. SDMX-JSON: ``errors`` is non-empty
+    and there is no ``data``, since a message may also carry errors beside
+    what it answers. A JSON payload this probe cannot decode is left to the
+    reader, so the reader's own error is the one raised.
+
+    Raises:
+        SdmxErrorMessage: Carrying each error's code and text.
+    """
+    if version == "json":
+        try:
+            probe = msgspec.json.decode(data, type=_ErrorProbe)
+        except msgspec.MsgspecError:
+            return
+        if probe.errors and probe.data is None:
+            raise SdmxErrorMessage(tuple((_code(e.code), e.title or e.detail or e.message or "") for e in probe.errors))
+        return
+    root = _xml_root(data)
+    if root is None or root.localname != _ERROR_ROOT or root.namespace not in _MESSAGE_NS_VERSION:
+        return
+    entries = [
+        el for el in etree.fromstring(data) if isinstance(el.tag, str) and etree.QName(el).localname == _ERROR_ENTRY
+    ]
+    raise SdmxErrorMessage(tuple((el.get("code", ""), _first_text(el)) for el in entries))
+
+
+def _code(code: float | str) -> str:
+    """An SDMX-JSON error code as SDMX-ML writes it: ``404``, not ``404.0``."""
+    if isinstance(code, float) and code.is_integer():
+        return str(int(code))
+    return str(code)
+
+
+def _first_text(entry: etree._Element) -> str:
+    """The first ``<com:Text>`` of an ``<ErrorMessage>``; a message may give several languages."""
+    for child in entry:
+        if isinstance(child.tag, str) and etree.QName(child).localname == "Text":
+            return (child.text or "").strip()
+    return ""
+
 
 def _xml_root(data: bytes) -> etree.QName | None:
     """The qualified name of the XML root element, or None if *data* is not XML.

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/formats/sdmx_json/_structure_dto.py

@@ -367,6 +367,14 @@ class Format(WireStruct, rename=_camel_rename):
     end_time: str | None = None
     #: Values with a special meaning (#422) — a text format's alone.
     sentinel_values: list[SentinelValueJson] | None = None
+    #: Read tolerance: SDMX-JSON 1.0's name for `data_type` (GH-30), moved
+    #: there as it is read so nothing downstream sees two spellings.
+    text_type: str | None = None
+
+    def __post_init__(self) -> None:
+        """Read 1.0's `text_type` as `data_type`."""
+        if self.text_type is not None and self.data_type is None:
+            self.data_type, self.text_type = self.text_type, None
 
 
 class SentinelValueJson(WireStruct, rename=_camel_rename):
@@ -404,6 +412,9 @@ class Representation(WireStruct, rename=_camel_rename):
     #: or ``"unbounded"``.
     min_occurs: int | None = None
     max_occurs: int | str | None = None
+    #: Read tolerance: SDMX-JSON 1.0's name for `format` (GH-30), moved there
+    #: as it is read, before the ``oneOf`` below counts it.
+    text_format: Format | None = None
 
     def __post_init__(self) -> None:
         """Every representation type's ``oneOf``: an enumeration or a format (#474).
@@ -411,6 +422,8 @@ class Representation(WireStruct, rename=_camel_rename):
         Raises:
             ValueError: If it has neither, or both.
         """
+        if self.text_format is not None and self.format is None:
+            self.format, self.text_format = self.text_format, None
         # Tested inline before `one_of` builds its arguments: this runs for
         # every component and concept, and the call alone was 2-5% of a read.
         if (self.enumeration is None) == (self.format is None):
@@ -871,6 +884,11 @@ class AttributeRelationship(WireStruct, rename=_camel_rename):
     are_dimensions_optional: list[bool] | None = None
     group: str | None = None
     dataflow: EmptyObject | None = None
+    #: Read tolerance, SDMX-JSON 1.0's two spellings (GH-30): ``none`` is
+    #: `dataflow` (2.1's ``<str:None/>``, a dataset-level attribute), and
+    #: ``primaryMeasure`` is `observation`, naming the measure 2.1 relates it to.
+    none: EmptyObject | None = None
+    primary_measure: str | None = None
 
     def __post_init__(self) -> None:
         """The schema's ``oneOf`` (#474).
@@ -884,6 +902,8 @@ class AttributeRelationship(WireStruct, rename=_camel_rename):
             dimensions=self.dimensions,
             group=self.group,
             observation=self.observation,
+            none=self.none,
+            primaryMeasure=self.primary_measure,
         )
 
 

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/formats/sdmx_json/_structure_ingest.py

@@ -540,9 +540,9 @@ def from_attachment(
         # Required by the schema; one a document omits varies with nothing,
         # read as dataset-level as the SDMX-ML readers read it (#421).
         return AttachmentLevel.DATASET, None, frozenset(), None
-    if ar.observation is not None:
+    if ar.observation is not None or ar.primary_measure is not None:
         return AttachmentLevel.OBSERVATION, None, frozenset(), None
-    if ar.dataflow is not None:
+    if ar.dataflow is not None or ar.none is not None:
         return AttachmentLevel.DATASET, None, frozenset(), None
     if ar.dimensions:
         # `areDimensionsOptional` is parallel to `dimensions` (#422).

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/local/_scan.py

@@ -38,6 +38,7 @@ from sdmxlib.model.datastructure import DataStructure
 from sdmxlib.model.ref import Ref
 from sdmxlib.model.urn import SdmxUrn
 from sdmxlib.query.observations import ObsQuery
+from sdmxlib.session import completed
 
 #: The catalog every scan's relation lives in — see the module docstring.
 SCANS = "sdmx_scans"
@@ -99,11 +100,11 @@ def scan_frame_into(
         if column in frame.columns
     )
     name = relation.rpartition(".")[2]
-    plane.connection.register(name, typed.to_arrow())
+    completed(plane.connection).register(name, typed.to_arrow())
     try:
         plane.connection.execute(f"CREATE TABLE {relation} AS SELECT * FROM {name}")
     finally:
-        plane.connection.unregister(name)
+        completed(plane.connection).unregister(name)
     return plane.obs(binding, dsd=dsd)
 
 

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/local/data_store.py

@@ -31,7 +31,7 @@ from sdmxlib.model.ref import Ref
 from sdmxlib.model.representation import Facet
 from sdmxlib.query.observations import Observations, ObsQuery, Sidecar
 from sdmxlib.query.query import build
-from sdmxlib.session import SessionFactory
+from sdmxlib.session import SessionFactory, completed
 
 if TYPE_CHECKING:
     # `local.registry` imports this module at runtime: a cycle.
@@ -676,10 +676,10 @@ class DuckDBDataStore(SessionFactory):
             raise ValueError(msg)
 
         conn = self.connection
-        # Register the source as a temporary view the CTAS can scan.
+        # Registered for this session, not created as a view: a view is
+        # catalog state, and DuckDB refuses one over a Python object.
         view_name = f"__sdmxlib_write_obs_{id(source):x}"
-        rel = _as_relation(conn, source)
-        rel.create_view(view_name, replace=True)
+        completed(conn).register(view_name, _as_relation(conn, source))
         try:
             target = f"{lake_alias}.{schema}.{table}"
             conn.execute(f"CREATE SCHEMA IF NOT EXISTS {lake_alias}.{schema}")
@@ -696,7 +696,7 @@ class DuckDBDataStore(SessionFactory):
                 msg = f"Unknown mode: {mode!r} (expected 'overwrite' or 'append')"
                 raise ValueError(msg)
         finally:
-            conn.execute(f"DROP VIEW IF EXISTS {view_name}")
+            completed(conn).unregister(view_name)
         # A rewrite can change the target table's schema; drop cached column
         # lists so the inspector (internal query path + custom SQL) re-reflects.
         # The target may be cached under a differently-qualified name than the

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/local/sql.py

@@ -52,6 +52,7 @@ import duckdb
 from attrs import frozen
 
 from sdmxlib.model.binding import DataflowBinding
+from sdmxlib.session import cursor_for
 
 
 class SidecarNotUniqueError(ValueError):
@@ -152,7 +153,9 @@ class SchemaInspector:
             cached = self._columns_cache.get(table)
             if cached is not None:
                 return cached
-            rows = self._conn.execute(f"DESCRIBE {table}").fetchall()
+            # On this thread's handle, never `_conn` itself: concurrent
+            # `execute()` on one handle overwrite each other's rows (#75).
+            rows = cursor_for(self._conn).execute(f"DESCRIBE {table}").fetchall()
             described = tuple((str(r[0]), str(r[1])) for r in rows)
             self._columns_cache[table] = described
             return described
@@ -190,9 +193,11 @@ class SchemaInspector:
                 return cached
             tuple_sql = ", ".join(keys)
             not_null = " AND ".join(f"{k} IS NOT NULL" for k in keys)
-            row = self._conn.execute(
-                f"SELECT count(*), count(DISTINCT ({tuple_sql})) FROM {table} WHERE {not_null}"
-            ).fetchone()
+            row = (
+                cursor_for(self._conn)
+                .execute(f"SELECT count(*), count(DISTINCT ({tuple_sql})) FROM {table} WHERE {not_null}")
+                .fetchone()
+            )
             counts = (int(row[0]), int(row[1])) if row else (0, 0)
             self._key_counts_cache[cache_key] = counts
             return counts

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/model/rollup.py

@@ -16,7 +16,7 @@ import attrs
 import duckdb
 import polars as pl
 
-from sdmxlib.session import cursor_for
+from sdmxlib.session import completed, cursor_for, frame_of
 from sdmxlib.sql import SqlRelation
 
 
@@ -105,7 +105,7 @@ class AncestorMap:
     def collect(self) -> pl.DataFrame:
         """Execute and return the mapping as a Polars frame."""
         sql, params = self.to_sql()
-        return cursor_for(self._conn).execute(sql, params).pl()
+        return frame_of(completed(cursor_for(self._conn)).sql(sql, params=params))
 
     def to_dict(self) -> dict[str, str]:
         """Execute and return ``{path: rollup_path}``.

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/model/validation.py

@@ -222,6 +222,33 @@ class SdmxConformanceError(SdmxParseError):
         return cls("Structure", detail, refused=refused, message=message)
 
 
+class SdmxErrorMessage(SdmxParseError):  # noqa: N818 - SDMX's own element name, `ErrorMessage`
+    """Raised by `parse` when the document is an SDMX error message (GH-31).
+
+    A registry answers a query it cannot serve with an error message —
+    ``<mes:Error>`` in SDMX-ML, ``{"errors": [...]}`` in SDMX-JSON — rather
+    than a structure or metadata message. `parse` used to read one as an empty
+    `StructureMessage`, so a saved "100 No Results Found" was indistinguishable
+    from a query that matched nothing. The REST client never gets this far: it
+    raises on the HTTP status first. This is for bytes read from a file.
+
+    A `SdmxParseError`, because the payload is still not the message asked
+    for; catching the base handles it with every other unusable document.
+
+    Attributes:
+        errors: One ``(code, text)`` pair per error the message reports, in
+            document order. The code is text, as SDMX-ML types it; the text
+            is the first one given, or empty when there is none.
+    """
+
+    errors: tuple[tuple[str, str], ...]
+
+    def __init__(self, errors: tuple[tuple[str, str], ...]) -> None:
+        self.errors = errors
+        reported = "; ".join(f"{code} {text}".strip() for code, text in errors) or "no error given"
+        super().__init__(f"the document is an SDMX error message, not a structure or metadata message: {reported}")
+
+
 class LossyReadError(SdmxParseError):
     """Raised by ``parse(..., lossless=True)`` when the message is not exactly the document (#422, #474).
 

{sdmxlib-0.69.0 → sdmxlib-0.70.0}/src/sdmxlib/query/query.py

@@ -73,7 +73,7 @@ from sdmxlib.query._expr import (
 )
 from sdmxlib.query._plan import Plan, scanned
 from sdmxlib.query._pushdown import DUCKDB, Program, Push, plan_program
-from sdmxlib.session import cursor_for
+from sdmxlib.session import completed, cursor_for, frame_of
 
 
 def _partition_prefix(root: AnyCols, order: Sequence[OrderKey]) -> tuple[str, ...]:
@@ -127,7 +127,7 @@ def _stream_by_partition[R: RowKind, A](
             # does not pull the next partition until this one is finished — which
             # is exactly what keeps peak at one partition rather than their sum.
             cursor = query._cursor().cursor()
-            yield cursor.execute(compiled.sql, list(compiled.params)).to_arrow_reader(chunk_rows)
+            yield completed(cursor).sql(compiled.sql, params=list(compiled.params)).to_arrow_reader(chunk_rows)
 
     stream = readers()
     first = next(stream)
@@ -174,9 +174,9 @@ def _typed(frame: pl.DataFrame, root: AnyCols, columns: Mapping[str, str] | None
 
     Raises:
         ValueError: If a value cannot take its component's type — a code its
-            codelist does not list, text where the DSD declares a number. Fail
-            fast; the message names the way to the raw rows and to the report
-            of every bad value.
+            codelist does not list, text where the DSD declares a number or
+            a date. Fail fast; the message names the way to the raw rows and
+            to the report of every bad value.
     """
     dsd = getattr(root, "dsd", None)
     if not isinstance(dsd, DataStructure):
@@ -193,7 +193,7 @@ def _typed(frame: pl.DataFrame, root: AnyCols, columns: Mapping[str, str] | None
     if not casts:
         return frame
     try:
-        return frame.with_columns(pl.col(name).cast(dtype) for name, dtype in casts.items())
+        return frame.with_columns(_converted(name, frame.schema[name], dtype) for name, dtype in casts.items())
     except pl.exceptions.PolarsError as exc:
         msg = (
             f"an observation column does not fit its component's type in {dsd.id}: {exc}. Results are "
@@ -203,6 +203,35 @@ def _typed(frame: pl.DataFrame, root: AnyCols, columns: Mapping[str, str] | None
         raise ValueError(msg) from exc
 
 
+#: `xs:boolean`'s lexical forms.
+_BOOLEANS = {"true": True, "false": False, "1": True, "0": False}
+
+
+def _converted(name: str, stored: pl.DataType, dtype: pl.DataType) -> pl.Expr:
+    """Column `name`, stored as `stored`, as `dtype` — parsed when it is text.
+
+    A cast is not a parse: polars 2.0 casts no text to a date, a datetime or a
+    time (1.x did dates only), and no version casts text to a boolean. A value
+    stored as ``VARCHAR`` — every observation column is — is parsed instead. A
+    datetime with an offset lands in UTC, and every datetime is naive UTC, the
+    store's convention (`sdmxlib._time`).
+    """
+    column = pl.col(name)
+    if stored != pl.String():
+        return column.cast(dtype)
+    match dtype:
+        case pl.Date():
+            return column.str.to_date()
+        case pl.Datetime():
+            return column.str.to_datetime(time_unit=dtype.time_unit, time_zone="UTC").dt.replace_time_zone(None)
+        case pl.Time():
+            return column.str.to_time()
+        case pl.Boolean():
+            return column.replace_strict(_BOOLEANS, return_dtype=pl.Boolean)
+        case _:
+            return column.cast(dtype)
+
+
 def _declared_components(dsd: DataStructure) -> frozenset[str]:
     """The components whose type the DSD states — see `_typed`."""
     found = {
@@ -1613,7 +1642,7 @@ class Query[R: RowKind, A = object]:
         their `Facet` declares.
         """
         compiled = self.to_sql()
-        frame = _typed(self._cursor().execute(compiled.sql, list(compiled.params)).pl(), self.root)
+        frame = _typed(frame_of(completed(self._cursor()).sql(compiled.sql, params=list(compiled.params))), self.root)
         if not labels:
             return frame
         return _labelled(frame, self.root, labels, label_suffix)
@@ -1699,7 +1728,7 @@ class Query[R: RowKind, A = object]:
         # on one connection would overwrite each other's row buffer (#75), and
         # the reader holds this one until it is exhausted or closed.
         cursor = self._cursor().cursor()
-        return cursor.execute(compiled.sql, list(compiled.params)).to_arrow_reader(chunk_rows)
+        return completed(cursor).sql(compiled.sql, params=list(compiled.params)).to_arrow_reader(chunk_rows)
 
     def _partition_values(self, partitions: tuple[str, ...]) -> list[tuple[object, ...]]:
         """Every partition, in key order — one small query before the stream.
@@ -2355,7 +2384,7 @@ class Select[R: RowKind, A = object]:
         # component id -> the name it was projected under, so an aliased column
         # is typed and labelled under the alias.
         aliases = {item.projected_name: name for name, item in self.items if isinstance(item, AnyCol)}
-        frame = _as_utc(cursor.execute(compiled.sql, list(compiled.params)).pl(), self.items)
+        frame = _as_utc(frame_of(completed(cursor).sql(compiled.sql, params=list(compiled.params))), self.items)
         frame = _typed(frame, self._query.root, aliases)
         if not labels:
             return frame
@@ -2450,7 +2479,7 @@ class Select[R: RowKind, A = object]:
         # on one connection would overwrite each other's row buffer (#75), and
         # the reader holds this one until it is exhausted or closed.
         cursor = self._query._cursor(self._query._projection_columns(self.items)).cursor()
-        return cursor.execute(compiled.sql, list(compiled.params)).to_arrow_reader(chunk_rows)
+        return completed(cursor).sql(compiled.sql, params=list(compiled.params)).to_arrow_reader(chunk_rows)
 
     @override
     def __repr__(self) -> str: