sdmxlib 0.24.0__tar.gz → 0.26.0__tar.gz

{sdmxlib-0.24.0 → sdmxlib-0.26.0}/PKG-INFO

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

{sdmxlib-0.24.0 → sdmxlib-0.26.0}/pyproject.toml

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

{sdmxlib-0.24.0 → sdmxlib-0.26.0}/src/sdmxlib/__init__.py

@@ -7,7 +7,8 @@ from sdmxlib.api.providers import Provider
 from sdmxlib.api.query import DataQuery
 from sdmxlib.api.registry import BearerToken, FmrRegistry, RestRegistry
 from sdmxlib.catalog import DataflowEntry, FederatedCatalog
-from sdmxlib.data_store import DataStore, SqlRelation
+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
@@ -113,6 +114,7 @@ __all__ = [
     "CodeQuery",
     "Codelist",
     "CodelistMap",
+    "CompileContext",
     "ComponentFilter",
     "ComponentMap",
     "Concept",
@@ -166,6 +168,7 @@ __all__ = [
     "MetadataSet",
     "MetadataStructure",
     "Metadataflow",
+    "Predicate",
     "Provider",
     "ProvisionAgreement",
     "Ref",

{sdmxlib-0.24.0 → sdmxlib-0.26.0}/src/sdmxlib/data_store.py

@@ -25,35 +25,17 @@ import polars as pl
 
 from sdmxlib.model.binding import DataflowBinding
 
+# SqlRelation lives in sdmxlib.sql now (suite-level public contract);
+# re-exported here for backwards compatibility with code that imports
+# ``from sdmxlib.data_store import SqlRelation``.
+from sdmxlib.sql import SqlRelation as SqlRelation  # noqa: PLC0414 — public re-export
+
 if TYPE_CHECKING:
     import pyarrow as pa
 
     from sdmxlib.rest import ComponentFilter
 
 
-@runtime_checkable
-class SqlRelation(Protocol):
-    """A lazy single-column relation usable inside ``WHERE col IN (...)``.
-
-    Producers (typically :class:`~sdmxlib.model.code_query.CodeQuery`)
-    expose their compiled SELECT as a ``(sql, params)`` pair. The
-    streaming-query SQL builder splices the SQL inline as a subquery
-    and concatenates the params with the outer query's binds, so a
-    50k-row hierarchy traversal becomes one ``IN (SELECT ...)`` clause
-    with no parameter explosion.
-
-    The subquery's tables must be visible on the data store's
-    connection. For :class:`~sdmxlib.local.DuckDBDataStore` (which
-    shares its connection with :class:`~sdmxlib.local.Registry`),
-    codelist relations compose automatically because both sides see
-    the same ``sdmx.code`` table.
-    """
-
-    def to_sql(self) -> tuple[str, list[object]]:
-        """Return ``(sql, params)`` — a SELECT producing a single column."""
-        ...
-
-
 @runtime_checkable
 class DataStore(Protocol):
     """Read-side contract for the data plane.

sdmxlib-0.26.0/src/sdmxlib/sql.py

@@ -0,0 +1,146 @@
+"""Shared SQL-composition primitives — used across pinax-suite.
+
+Lifted from internal helpers in ``sdmxlib.data_store`` and
+``sdmxlib.model.code_query`` so other libraries (pinaxlib, future
+catalog-style tools) can compose with sdmxlib's lazy SQL machinery
+without re-implementing the contracts.
+
+Three primitives:
+
+- :class:`SqlRelation` — a producer of ``(sql, params)`` for use as a
+  single-column subquery. Lets a 50k-row hierarchy traversal compile
+  to one ``IN (SELECT …)`` clause, with no parameter explosion. This
+  is the load-bearing pattern for cross-library lazy composition.
+- :class:`Predicate` — a typed query predicate that compiles to a SQL
+  fragment. Composes into a tree on a builder; the builder's
+  compilation walks the tree once and emits one SQL.
+- :class:`CompileContext` — state threaded through one compilation
+  pass: the row alias for the main table, accumulators for joins,
+  and a join-alias dedup map (so multiple predicates touching the
+  same bridge table or annotation type share one join).
+
+Topology B from ``bundle-architecture.md`` (single DuckDB file
+co-locating ``sdmx.*``, ``pinax.*``, and the DuckLake catalog tables)
+is what makes :class:`SqlRelation` composition routinely useful across
+sdmxlib + pinaxlib: subquery tables are always visible on the same
+connection.
+
+See ``predicate-and-sqlrelation.md`` in the statcan-catalog-builder
+design docs for the full design rationale and decisions D1-D10.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+__all__ = [
+    "CompileContext",
+    "Predicate",
+    "SqlRelation",
+]
+
+
+@runtime_checkable
+class SqlRelation(Protocol):
+    """A lazy single-column relation usable inside ``WHERE col IN (...)``.
+
+    Producers (typically :class:`~sdmxlib.model.code_query.CodeQuery`,
+    :class:`~sdmxlib.model.hierarchy_query.HierarchyNodeQuery`, and the
+    pinaxlib query builders) expose their compiled SELECT as a
+    ``(sql, params)`` pair. The streaming-query SQL builder splices the
+    SQL inline as a subquery and concatenates the params with the outer
+    query's binds, so an N-row traversal becomes one
+    ``IN (SELECT ...)`` clause with no parameter explosion.
+
+    The subquery's tables must be visible on the consumer's connection.
+    For :class:`~sdmxlib.local.DuckDBDataStore` (which shares its
+    connection with :class:`~sdmxlib.local.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 DuckLake catalog).
+    """
+
+    def to_sql(self) -> tuple[str, list[object]]:
+        """Return ``(sql, params)`` — a SELECT producing a single column."""
+        ...
+
+
+@dataclass
+class CompileContext:
+    """State threaded through one compilation pass.
+
+    Predicate compilers receive a context object so multiple predicates
+    in the same query can share state — most importantly, joins. The
+    ``join_aliases`` map records "did we already join the bridge table
+    for this query?"; a second predicate touching the same join reuses
+    the alias instead of adding a duplicate.
+
+    Attributes:
+        row_alias: The main table's alias in the outer query (e.g.
+            ``"d"`` for ``pinax.dataset d``, ``"c"`` for ``sdmx.code c``,
+            ``"o"`` for an observation-table scan).
+        join_aliases: Dedup map for repeated joins. Keyed by an
+            implementation-defined join id (e.g. annotation type,
+            bridge table name + dimension); value is the SQL alias
+            assigned the first time the join was added.
+        join_sqls: Accumulated JOIN fragments to splice between
+            ``FROM`` and ``WHERE`` in the outer query.
+        join_params: Parameters for the accumulated joins, in
+            insertion order.
+        schemas: Logical-to-physical schema name map. Default identity
+            (``"sdmx"`` → ``"sdmx"``, ``"pinax"`` → ``"pinax"``);
+            override for federation or alternate naming.
+    """
+
+    row_alias: str
+    join_aliases: dict[str, str] = field(default_factory=dict)
+    join_sqls: list[str] = field(default_factory=list)
+    join_params: list[object] = field(default_factory=list)
+    schemas: dict[str, str] = field(default_factory=dict)
+    _alias_counter: int = 0
+
+    def schema(self, logical: str) -> str:
+        """Resolve a logical schema name to its physical SQL identifier."""
+        return self.schemas.get(logical, logical)
+
+    def next_alias(self, prefix: str = "f") -> str:
+        """Generate a unique SQL alias for use in a subquery or join.
+
+        Each call returns a fresh ``{prefix}{n}`` identifier. Predicate
+        compilers use this to give correlated subqueries unique table
+        aliases when multiple predicates would otherwise collide.
+
+        The counter is per-context (per-compilation-pass), so aliases are
+        deterministic within a query and naturally re-numbered for the
+        next compilation. Use a prefix like ``"ef"`` (exists filter) or
+        ``"j"`` (join) to make the generated SQL self-documenting.
+        """
+        self._alias_counter += 1
+        return f"{prefix}{self._alias_counter}"
+
+
+@runtime_checkable
+class Predicate(Protocol):
+    """A query predicate that compiles to a SQL WHERE-clause fragment.
+
+    Implementations live in pinaxlib (e.g. ``has_code``, ``MapFilter``,
+    ``ExistsFilter``) and sdmxlib (e.g. ``code.id == "X"``,
+    ``dim("FREQ") == "M"``). Both library's compilers reuse the same
+    :class:`CompileContext`, so a single query containing predicates
+    from both libraries compiles into one SQL with shared joins.
+
+    The implementation may add to ``ctx.join_sqls`` / ``ctx.join_params``
+    via :func:`CompileContext.join_aliases` dedup as a side effect of
+    compilation.
+
+    Returns:
+        ``(fragment, params)`` — a SQL fragment safe to AND into a
+        WHERE clause, and the parameters for it. The fragment must
+        reference the main table via ``ctx.row_alias``.
+    """
+
+    def to_sql(self, ctx: CompileContext) -> tuple[str, list[object]]:
+        """Emit a SQL fragment + params for this predicate."""
+        ...