sdmxlib 0.70.0__tar.gz → 0.71.0__tar.gz

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

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

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

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

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

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

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

@@ -49,6 +49,7 @@ from sdmxlib.rest import ComponentFilter, parse_components, widen_key
 from sdmxlib.query._common import Descending
 from sdmxlib.model.convert import from_dict, to_dict
 from sdmxlib.model.errors import ImRuleWarning, ReadAssumption, ReadGap, SdmxWarning
+from sdmxlib.storage.schema import StoreSchemaError
 from sdmxlib.model.validation import (
     LossyReadError,
     ReferenceIssue,
@@ -395,6 +396,7 @@ __all__ = [
     "SliceError",
     "SourceValue",
     "SqlRelation",
+    "StoreSchemaError",
     "Str",
     "StructureMap",
     "StructureMessage",

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/api/client.py

@@ -216,6 +216,33 @@ def _check_content_type(response: httpx.Response, fmt: DataFormat, *, url: str)
     raise ValueError(msg)
 
 
+def _require_csv(response: httpx.Response, *, accept: str, url: str) -> None:
+    """Refuse an observation fetch's response that is not CSV (GH-50).
+
+    The data plane hands the body to DuckDB's CSV reader, which reads an
+    SDMX-ML document as a CSV of one malformed column. BIS answers
+    ``text/csv`` with SDMX-ML and a 200, and ECB and ESTAT answer an
+    ``Accept`` listing two types the same way. Either SDMX-CSV version, or
+    plain ``text/csv``, is fine: the reader takes both envelopes. As in
+    `_check_content_type`, a response with no ``Content-Type`` passes.
+
+    Raises:
+        ValueError: If the response says it is something other than CSV.
+    """
+    header = response.headers.get("content-type")
+    if not header:
+        return
+    media_type = header.partition(";")[0].strip().lower()
+    if media_type == "text/csv" or media_type.endswith("+csv"):
+        return
+    msg = (
+        f"Asked for {accept!r} but the response is {header!r}, not CSV, so it was not read. "
+        "Pass the media type this provider serves CSV under as `csv_media_type=` "
+        f"(see `sl.Provider` for the ones checked). URL: {url}"
+    )
+    raise ValueError(msg)
+
+
 def _raise_for_status(response: httpx.Response, *, url: str) -> None:
     """`raise_for_status`, with the two size refusals named.
 
@@ -277,6 +304,8 @@ class SdmxClient:
             obey the provider exactly.
         freshness_size: How many URLs to remember freshness for. Bounded,
             per `docs/design/caching.md`; eviction only costs a request.
+        csv_media_type: The ``Accept`` an observation fetch sends. Defaults to
+            the SDMX-CSV the API version defines: 1.0 for 2.1, 2.0 for 3.0.
     """
 
     def __init__(
@@ -288,6 +317,7 @@ class SdmxClient:
         headers: dict[str, str] | None = None,
         latest_ttl: int = 0,
         freshness_size: int = 256,
+        csv_media_type: str | None = None,
         **httpx_kwargs: Unpack[HttpxOptions],
     ) -> None:
         self._endpoint = endpoint.rstrip("/")
@@ -300,6 +330,11 @@ class SdmxClient:
         self._freshness_lock = threading.Lock()
         self._api = api
         self._v3 = api.startswith(("3", "2.0"))
+        #: What an observation fetch asks for (GH-50): the provider's, else
+        #: the SDMX-CSV the API version defines.
+        self._csv_media_type = (
+            csv_media_type or (DataFormat.SDMX_CSV_2_0_0 if self._v3 else DataFormat.SDMX_CSV_1_0_0).media_type
+        )
         default_headers: dict[str, str]
         if self._v3:
             default_headers = {"Accept": "application/vnd.sdmx.structure+xml;version=3.0"}
@@ -566,8 +601,9 @@ class SdmxClient:
         """
         url = f"{self._endpoint}/{path}"
         with self._reaching(url):
-            response = self._client.get(url, params=dict(params), headers={"Accept": "text/csv"})
+            response = self._client.get(url, params=dict(params), headers={"Accept": self._csv_media_type})
         _raise_for_status(response, url=url)
+        _require_csv(response, accept=self._csv_media_type, url=url)
         return response.content
 
     def stream_data_at(self, path: str, params: Mapping[str, str], *, to: Path) -> None:
@@ -587,9 +623,10 @@ class SdmxClient:
         url = f"{self._endpoint}/{path}"
         with (
             self._reaching(url),
-            self._client.stream("GET", url, params=dict(params), headers={"Accept": "text/csv"}) as response,
+            self._client.stream("GET", url, params=dict(params), headers={"Accept": self._csv_media_type}) as response,
         ):
             _raise_for_status(response, url=url)
+            _require_csv(response, accept=self._csv_media_type, url=url)
             with to.open("wb") as handle:
                 for chunk in response.iter_bytes():
                     handle.write(chunk)
@@ -609,7 +646,7 @@ class SdmxClient:
         """Fetch a dataflow's data in `fmt`, unparsed.
 
         The byte-faithful counterpart to `get_data_at` / `stream_data_at`, which
-        hardcode ``Accept: text/csv`` because their caller is about to hand the
+        ask for CSV (`csv_media_type`) because their caller is about to hand the
         body to DuckDB's CSV reader. Here the caller wants what the provider
         sent, so the format is the caller's to choose and nothing inspects the
         body afterwards.

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/api/federated.py

@@ -10,7 +10,9 @@ sources cooperating to answer a single URN) is intentionally out of
 scope; see #46 for that conversation.
 
 Example:
-    local = sl.LocalRegistry("cache.duckdb", source_registry="local")
+    # rebuild=True: a cache can be fetched again, so a store schema change may
+    # empty it rather than refuse to open (GH-57).
+    local = sl.LocalRegistry("cache.duckdb", source_registry="local", rebuild=True).open()
     estat = sl.RestRegistry(sl.Provider.ESTAT, store=local)
     sdmx_global = sl.RestRegistry(sl.Provider.SDMX_GLOBAL, store=local)
 

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/api/providers.py

@@ -22,11 +22,18 @@ class ProviderInfo:
             tag when a `RestRegistry` materialises through to a
             local store. Required for federation; ``None`` for ad-hoc
             URLs without a known label.
+        csv_media_type: The ``Accept`` an observation fetch sends, when the
+            API version's SDMX-CSV media type is not what this provider
+            answers (GH-50). None means that default: SDMX-CSV 1.0 for a
+            2.1 API, 2.0 for a 3.0 one. Set per provider because two 2.1
+            providers want opposite headers, and a header listing both gets
+            SDMX-ML back from each.
     """
 
     url: str
     api: str = "2.1"
     id: str | None = None
+    csv_media_type: str | None = None
 
 
 class Provider:
@@ -48,8 +55,13 @@ class Provider:
         sl.Provider.ECB.api  # "2.1"
     """
 
+    # The data `Accept` each answers, checked live 2026-10-22 (GH-50): ECB
+    # serves CSV for `text/csv` alone (406 for either SDMX-CSV type); ESTAT
+    # the reverse (406 for `text/csv`); BIS answers `text/csv` with SDMX-ML;
+    # OECD serves all three. IMF's is unchecked, so it takes the default.
+
     #: European Central Bank
-    ECB = ProviderInfo("https://data-api.ecb.europa.eu/service", api="2.1", id="ECB")
+    ECB = ProviderInfo("https://data-api.ecb.europa.eu/service", api="2.1", id="ECB", csv_media_type="text/csv")
     #: Bank for International Settlements
     BIS = ProviderInfo("https://stats.bis.org/api/v1", api="2.1", id="BIS")
     #: Eurostat

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/api/registry.py

@@ -178,6 +178,11 @@ class RestRegistry:
             whose `no-store` is appliance boilerplate, and cannot shorten a
             generous one. Defaults to 0 — obey the provider exactly. Wanting
             *less* is spelled with a pinned URN, which is not a pointer.
+        csv_media_type: The ``Accept`` `obs` fetches observations with
+            (GH-50). Defaults to the `ProviderInfo`'s, else the SDMX-CSV the
+            API version defines: 1.0 for 2.1, 2.0 for 3.0. Providers differ —
+            ECB serves CSV only for ``text/csv``, Eurostat only for SDMX-CSV
+            1.0 — so pass one when a bare URL's provider refuses the default.
 
     **Thread safety: concurrent reads are safe and do not duplicate work.**
 
@@ -202,9 +207,13 @@ class RestRegistry:
     store — inherit the local `LocalRegistry`'s rule and remain single-threaded.
 
     Example:
-        # Cache-mode federation: structural reads cached locally.
-        local = sl.LocalRegistry("cache.duckdb")
-        with sl.RestRegistry(sl.Provider.ECB, store=local) as reg:
+        # Cache-mode federation: structural reads cached locally. A cache can
+        # be fetched again, so it may be rebuilt when sdmxlib's store schema
+        # moves; any other store on an old schema is refused instead (GH-57).
+        with (
+            sl.LocalRegistry("cache.duckdb", rebuild=True) as local,
+            sl.RestRegistry(sl.Provider.ECB, store=local) as reg,
+        ):
             dsd = reg.get(sl.DataStructure.urn_for(agency="ECB", id="ECB_EXR1"), resolve=True)
 
         # Single-source ad-hoc.
@@ -226,6 +235,7 @@ class RestRegistry:
         store: LocalRegistry | None = None,
         fetch_cache_size: int = 256,
         latest_ttl: int = 0,
+        csv_media_type: str | None = None,
         **httpx_kwargs: Unpack[HttpxOptions],
     ) -> None:
         if isinstance(endpoint, ProviderInfo):
@@ -233,6 +243,8 @@ class RestRegistry:
             api = endpoint.api
             if id is None:
                 id = endpoint.id
+            if csv_media_type is None:
+                csv_media_type = endpoint.csv_media_type
         else:
             url = endpoint
 
@@ -278,6 +290,7 @@ class RestRegistry:
             timeout=timeout,
             headers=headers,
             latest_ttl=latest_ttl,
+            csv_media_type=csv_media_type,
             **httpx_kwargs,
         )
         self._session = Session()
@@ -1001,8 +1014,11 @@ class RestRegistry:
                 without a DSD there is no key order, and a key built on a guess
                 queries a different slice silently.
         """
-        urn = _flow_urn(flow)
-        dsd = self._resolve_data_structure(urn)
+        # Bound to the dataflow as fetched, not as asked for: the data URL names
+        # its version, and BIS and OECD refuse `latest` there with a 400 that
+        # ECB and Eurostat let pass (GH-51).
+        resolved, dsd = self._resolve_data_structure(_flow_urn(flow))
+        urn = resolved.urn
         store = DuckDBDataStore.from_registry(self._query_store())
         binding = DataflowBinding.from_dsd(
             dsd,
@@ -1036,8 +1052,8 @@ class RestRegistry:
             raise RuntimeError(msg)
         return str(rows[0][0])
 
-    def _resolve_data_structure(self, urn: SdmxUrn[Dataflow]) -> DataStructure:
-        """The dataflow's structure, resolved, or a refusal naming what is missing."""
+    def _resolve_data_structure(self, urn: SdmxUrn[Dataflow]) -> tuple[Dataflow, DataStructure]:
+        """The dataflow as fetched, and its structure resolved, or a refusal naming what is missing."""
         flow = self._fetch_one(
             Dataflow, urn.agency, urn.id, urn.version, detail="referencepartial", references="descendants"
         )
@@ -1048,7 +1064,7 @@ class RestRegistry:
         if not isinstance(dsd, DataStructure):
             msg = f"{flow.structure.urn} did not resolve to a DataStructure."
             raise TypeError(msg)
-        return dsd
+        return flow, dsd
 
     def _fetch_data_for[R: "RowKind"](
         self, plan: Plan[R], _projection: frozenset[tuple[str, str]] | None = None

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/local/registry.py

@@ -20,7 +20,7 @@ stashes the URI; the DuckDB connection is opened by ``open()`` /
         dsd = local.get(dsd_urn)
         cm = local.code_map(codelist_urn, lang="en")
 
-    # Share an existing DuckDB connection (e.g. with cataloglib): use the
+    # Share an existing DuckDB connection (e.g. with statcatlib): use the
     # ``from_connection`` classmethod, which doesn't take ownership of the
     # connection's lifecycle.
     import duckdb
@@ -37,6 +37,7 @@ import threading
 import time
 from collections.abc import Callable, Generator, Iterable, Mapping, Sequence
 from contextlib import contextmanager
+from importlib import metadata
 from pathlib import Path
 from typing import Final, Literal, Self, cast, overload, override
 
@@ -94,9 +95,11 @@ from sdmxlib.storage.readers import make_lazy_codelist
 from sdmxlib.storage.schema import (
     SCHEMA_VERSION,
     ReadOnlySchemaError,
+    StoreSchemaError,
     check_scan_integrity,
     connection_is_read_only,
     get_schema_version,
+    holds_rows,
     migrate,
     schema_exists,
 )
@@ -104,6 +107,14 @@ from sdmxlib.storage.schema import (
 _SIBLING_INDEX = re.compile(r"\[\d+\]")
 
 
+def _sdmxlib_version() -> str:
+    """This sdmxlib's version, for a message; ``"unknown"`` when not installed as a package."""
+    try:
+        return metadata.version("sdmxlib")
+    except metadata.PackageNotFoundError:
+        return "unknown"
+
+
 def _declared_path(attribute_path: str) -> str:
     """The MSD path a reported ``attribute_path`` instantiates.
 
@@ -573,9 +584,17 @@ class LocalRegistry(SessionFactory):
         source_registry: str | None = None,
         resolve_cache_items: int = DEFAULT_RESOLVE_CACHE_ITEMS,
         target: str | None = None,
+        rebuild: bool = False,
     ) -> None:
         """Open or wrap a DuckDB-backed registry.
 
+        ``rebuild`` lets opening drop and rebuild a store that holds artefacts
+        on another schema version (GH-57). Without it such a store is refused
+        with `StoreSchemaError`, because the rebuild empties it: right for a
+        cache that `RestRegistry(store=...)` can fetch again, and wrong for a
+        bundle or a store filled with ``add``. An empty store, or a new file,
+        is created or migrated either way.
+
         ``target`` declares which SDMX-ML version this store's contents are
         meant to be written as — ``"2.1"``, ``"3.0"`` or ``"3.1"``. Adding an
         artefact carrying something that format cannot represent then **raises**
@@ -602,6 +621,8 @@ class LocalRegistry(SessionFactory):
         self._uri = store_path(uri, owner="LocalRegistry", wrap="sl.LocalRegistry.from_connection(conn)")
         self._source_registry = source_registry
         self._target = target
+        #: Whether opening may drop a populated store on another schema (GH-57).
+        self._rebuild = rebuild
         self._conn: duckdb.DuckDBPyConnection | None = None
         self._cursor: duckdb.DuckDBPyConnection | None = None
         self._owns_connection = True
@@ -697,6 +718,7 @@ class LocalRegistry(SessionFactory):
         source_registry: str | None = None,
         resolve_cache_items: int = DEFAULT_RESOLVE_CACHE_ITEMS,
         target: str | None = None,
+        rebuild: bool = False,
     ) -> Self:
         """Wrap an existing DuckDB connection.
 
@@ -705,9 +727,10 @@ class LocalRegistry(SessionFactory):
         is shared with another component (e.g. a co-located DuckLake catalog)
         that owns its lifecycle.
 
-        ``resolve_cache_items`` configures the resolver cache (FIFO), and ``target``
-        declares an SDMX-ML version to hold the contents to; both are
-        described on `__init__`.
+        ``resolve_cache_items`` configures the resolver cache (FIFO), ``target``
+        declares an SDMX-ML version to hold the contents to, and ``rebuild``
+        lets a populated store on another schema be dropped; all are described
+        on `__init__`.
         """
         # `Self`-annotated because `cls.__new__(cls)` is otherwise untyped: the
         # local would be `Self@__new__` with no field information. (It also
@@ -727,6 +750,7 @@ class LocalRegistry(SessionFactory):
         # raise `AttributeError` on any registry built this way. A comment was
         # not enough; `test_constructors_agree_on_fields` is the guard.
         instance._target = target
+        instance._rebuild = rebuild
         instance._conn = conn
         instance._cursor = None
         instance._owns_connection = False
@@ -744,19 +768,33 @@ class LocalRegistry(SessionFactory):
         return instance
 
     def _initialise_schema(self) -> None:
-        """Migrate or open a cursor on the ``sdmx`` schema."""
+        """Migrate or open a cursor on the ``sdmx`` schema.
+
+        Raises:
+            StoreSchemaError: If the store holds artefacts on another schema
+                version and ``rebuild`` was not asked for (GH-57).
+            ReadOnlySchemaError: If the schema must be created or rebuilt and
+                the connection is read-only.
+        """
         if self._conn is None:
             return
         version = get_schema_version(self._conn)
-        if not schema_exists(self._conn) or version != SCHEMA_VERSION:
+        exists = schema_exists(self._conn)
+        if not exists or version != SCHEMA_VERSION:
+            found = f"schema {version}" if exists else "no sdmx schema"
+            if exists and not self._rebuild and holds_rows(self._conn):
+                msg = (
+                    f"{self._uri} holds artefacts on store {found}, and this sdmxlib "
+                    f"({_sdmxlib_version()}) reads schema {SCHEMA_VERSION}, so it was not opened: "
+                    f"migrating means dropping them. A bundle: rebuild it from its source with this "
+                    f"sdmxlib, or read it with the one that built it. A cache that can be fetched "
+                    f"again: open it with rebuild=True."
+                )
+                raise StoreSchemaError(msg)
             if connection_is_read_only(self._conn):
-                found = version if schema_exists(self._conn) else "no sdmx schema"
                 msg = (
-                    f"this store is on {found}, and this build of sdmxlib uses "
-                    f"schema {SCHEMA_VERSION}. The store is a cache and migration "
-                    f"is drop-and-rebuild, which a read-only connection cannot do "
-                    f"— reopen it read-write to rebuild in place, or rebuild the "
-                    f"bundle from its source."
+                    f"this store has {found}, and this build of sdmxlib uses schema {SCHEMA_VERSION}. "
+                    f"Creating or rebuilding it needs a read-write connection."
                 )
                 raise ReadOnlySchemaError(msg)
             self._cursor = migrate(self._conn)
@@ -1540,6 +1578,10 @@ class LocalRegistry(SessionFactory):
         set — §9's rule. The lake is ATTACHed lazily, when something first asks
         for observations, so opening a bundle to read a codelist costs nothing.
 
+        **A bundle is never rebuilt.** Its ``meta.duckdb`` is the published
+        record, so one built on another schema version is refused with
+        `StoreSchemaError` rather than emptied (GH-57).
+
         Args:
             path: The bundle directory.
             source_registry: Provenance tag for artefacts added later.
@@ -1547,6 +1589,9 @@ class LocalRegistry(SessionFactory):
 
         Returns:
             An open registry over the bundle.
+
+        Raises:
+            StoreSchemaError: If the bundle was built on another schema version.
         """
         root = Path(path) if isinstance(path, str) else path
         registry = cls(

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/model/_label_match.py

@@ -3,7 +3,7 @@
 Package-internal: plain names in a private module, per CLAUDE.md rule 4. It is
 deliberately *not* in `sdmxlib.sql`, which is the public cross-library seam —
 these fragments are an implementation detail of `code_query` and
-`hierarchy_query`, not part of the contract pinaxlib composes against.
+`hierarchy_query`, not part of the contract statcatlib composes against.
 
 Four matching strengths, exposed on the DSLs as the plain string ops plus
 three namespaces:

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/query/_common.py

@@ -229,7 +229,7 @@ def canonical_key(value: object) -> tuple[object, ...]:
             ),
         )
     if isinstance(value, SqlRelation):
-        # A foreign relation — pinaxlib's, or anything else implementing the
+        # A foreign relation — statcatlib's, or anything else implementing the
         # protocol without being attrs. Its compiled SQL and binds are the only
         # stable description available, and are what a cache would key on.
         sql, params = value.to_sql()

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/query/observations.py

@@ -692,6 +692,12 @@ class ObsQuery(Query[ObsRow]):
         forms the index. One measure fills the cells; several give a column
         per measure per value. Attributes are not carried.
 
+        A `pl.DataFrame`, not a `LazyFrame` (#516), as every other terminal's
+        result is: the query has run by the time a pivot can start, so
+        laziness after it would push nothing back into the fetch, and when
+        the axis's enumeration is unresolved its columns can only be read
+        from the rows. ``.lazy()`` on the result costs nothing.
+
         Args:
             on: The dimension to spread into columns. Needed when the DSD
                 declares no measure dimension.

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/query/raw.py

@@ -25,7 +25,7 @@ back across.
 
 The protocol itself is untouched, because it is not the raw-SQL seam: `Query`
 satisfies it, which is how one structural query filters another, and external
-producers satisfy it, which is how pinaxlib composes. Both are compiled
+producers satisfy it, which is how statcatlib composes. Both are compiled
 relations the planner can still reason about. Raw text is not.
 """
 

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/sql.py

@@ -16,12 +16,12 @@ there is nothing for a foreign predicate to be assignable to.
 That is a real narrowing and worth naming rather than burying: a downstream
 library can no longer inject a *predicate*. It can still inject a *relation*,
 which is the composition that was actually used — `SqlRelation` has consumers
-in `rest.py`, `is_in`, and pinaxlib — and which works precisely because a
+in `rest.py`, `is_in`, and statcatlib — and which works precisely because a
 single-column subquery carries no row kind to disagree about.
 
 A bundle laid out as a single DuckDB file co-locating ``sdmx.*``,
-``pinax.*``, and the DuckLake catalog tables is what makes `SqlRelation`
-composition routinely useful across sdmxlib + pinaxlib: subquery tables are
+``statcat.*``, and the DuckLake catalog tables is what makes `SqlRelation`
+composition routinely useful across sdmxlib + statcatlib: subquery tables are
 always visible on the same connection.
 """
 
@@ -34,7 +34,7 @@ __all__ = ["HasSource", "SqlRelation"]
 class SqlRelation(Protocol):
     """A lazy relation usable inside ``WHERE col IN (...)`` or as a join input.
 
-    Producers — `sdmxlib.query.query.Select`, `AncestorMap`, and the pinaxlib
+    Producers — `sdmxlib.query.query.Select`, `AncestorMap`, and the statcatlib
     query builders — expose their compiled SELECT as a ``(sql, params)`` pair.
     The consumer splices the SQL inline as a subquery and concatenates the
     params with the outer query's binds, so an N-row traversal becomes one
@@ -43,8 +43,8 @@ class SqlRelation(Protocol):
     The subquery's tables must be visible on the consumer's connection. For
     `DuckDBDataStore` (which shares its connection with `Registry`), codelist
     relations compose automatically because both sides see the same
-    ``sdmx.code`` table. For pinaxlib's ``Catalog``, the same applies when the
-    bundle uses Topology B (one DuckDB file holding sdmx.*, pinax.*, and the
+    ``sdmx.code`` table. For statcatlib's ``Catalog``, the same applies when the
+    bundle uses Topology B (one DuckDB file holding sdmx.*, statcat.*, and the
     DuckLake catalog).
     """
 
@@ -79,7 +79,7 @@ class HasSource(Protocol):
     Optional by design, and deliberately not folded into `SqlRelation`. Making
     it required would break every existing producer, and a foreign relation
     that cannot answer is not necessarily wrong — Topology B puts ``sdmx.*``
-    and ``pinax.*`` on one connection precisely so cross-library composition is
+    and ``statcat.*`` on one connection precisely so cross-library composition is
     legitimate. So: a producer that *can* identify its source gets checked, and
     one that cannot is trusted, which is exactly the state before this existed.
     """

{sdmxlib-0.70.0 → sdmxlib-0.71.0}/src/sdmxlib/storage/schema.py

@@ -1571,12 +1571,25 @@ def check_scan_integrity(conn: duckdb.DuckDBPyConnection) -> None:
     raise ScanIntegrityError(msg)
 
 
-class ReadOnlySchemaError(Exception):
+class StoreSchemaError(Exception):
+    """A store holds artefacts on a schema version this build does not read (GH-57).
+
+    Migration is *drop and rebuild*, which is only right for a cache that can
+    be fetched again. A bundle's ``meta.duckdb`` is the published record, and a
+    store filled with ``add`` may have no source to fetch from, so a populated
+    store on another version is refused rather than emptied: sdmxlib 0.68 to
+    0.70 opened a 0.67 bundle read-write and deleted every artefact in it,
+    silently, for the reader and for the older sdmxlib that built it.
+    ``LocalRegistry(path, rebuild=True)`` asks for the rebuild.
+    """
+
+
+class ReadOnlySchemaError(StoreSchemaError):
     """A read-only store is not on this build's schema version.
 
-    Migration here is *drop and rebuild* — correct for a cache, impossible on
-    a connection opened read-only. Raised in place of DuckDB's own
-    ``Cannot execute statement of type "DROP" on database … read-only``,
+    Raised when a rebuild would otherwise run, but the connection is read-only:
+    an empty store to create, or ``rebuild=True``. Raised in place of DuckDB's
+    own ``Cannot execute statement of type "DROP" on database … read-only``,
     which names neither version and reads as a bug in the caller.
 
     First hit when 2.19 landed (#145): the bundle-assertion tier opens
@@ -1591,11 +1604,27 @@ def connection_is_read_only(conn: duckdb.DuckDBPyConnection) -> bool:
     return bool(row[0]) if row else False
 
 
+def holds_rows(conn: duckdb.DuckDBPyConnection) -> bool:
+    """Whether any ``sdmx`` table but ``_meta`` has a row — what a rebuild would lose.
+
+    Asks every table rather than ``artefact`` alone, because the store being
+    asked about is on *another* schema version, whose tables this build does
+    not know.
+    """
+    tables = conn.execute(
+        """
+        SELECT table_name FROM duckdb_tables()
+        WHERE database_name = current_database() AND schema_name = 'sdmx' AND table_name <> '_meta'
+        """
+    ).fetchall()
+    return any(conn.execute(f'SELECT EXISTS (SELECT 1 FROM sdmx."{name}")').fetchone() == (True,) for (name,) in tables)
+
+
 def migrate(conn: duckdb.DuckDBPyConnection) -> duckdb.DuckDBPyConnection:
     """Drop and rebuild the ``sdmx`` schema.
 
-    This is a cache — the migration strategy is *drop and rebuild*.
-    Users repopulate from remote registries.
+    Everything in it is lost. `LocalRegistry` calls this only for a store with
+    nothing in it, or when opened with ``rebuild=True`` (GH-57).
 
     Returns a fresh cursor with ``search_path = 'sdmx'``.
     """