gispulse 2.2.0__tar.gz → 2.2.1__tar.gz

{gispulse-2.2.0/src/gispulse.egg-info → gispulse-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gispulse
-Version: 2.2.0
+Version: 2.2.1
 Summary: Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)
 Author-email: ImagoData <contact@imagodata.com>
 License-Expression: AGPL-3.0-or-later

{gispulse-2.2.0 → gispulse-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gispulse"
-version = "2.2.0"
+version = "2.2.1"
 description = "Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)"
 license = "AGPL-3.0-or-later"
 requires-python = ">=3.10"

{gispulse-2.2.0 → gispulse-2.2.1}/src/gispulse/persistence/datamart.py

@@ -19,8 +19,14 @@ from the ``GISPULSE_DATAMARTS`` environment variable (a JSON object), e.g.::
 
     GISPULSE_DATAMARTS='{
       "referentiel": {"location": "s3://bucket/marts/referentiel"},
-      "local": {"location": "/data/marts/local", "table_pattern": "{table}.parquet"}
+      "local": {"location": "/data/marts/local", "table_pattern": "{table}.parquet"},
+      "warehouse": {"location": "/data/marts/warehouse.duckdb", "kind": "duckdb"}
     }'
+
+A ``kind: "duckdb"`` mart points :attr:`Datamart.location` at a single
+DuckDB database file; ``datamart://warehouse/<table>`` then reads the table
+of that name from inside the file (attached read-only, bbox push-down still
+applies via an ``ST_Intersects`` predicate on a ``geom`` column).
 """
 
 from __future__ import annotations
@@ -42,17 +48,33 @@ DATAMARTS_ENV = "GISPULSE_DATAMARTS"
 DATAMART_SCHEME = "datamart"
 
 
+#: Supported datamart backends.
+DATAMART_KINDS = ("parquet", "duckdb")
+
+
 @dataclass(frozen=True)
 class Datamart:
     """Declaration of one curated table store.
 
+    Two backends are supported, selected by :attr:`kind`:
+
+    * ``"parquet"`` (default) — *location* is a directory / ``s3://`` /
+      ``https://`` prefix holding **one file per table**; the file is
+      addressed by joining *location* with *table_pattern* and read as an
+      ordinary source (DuckDB-scannable, bbox push-down applies).
+    * ``"duckdb"`` — *location* is the path to a **single DuckDB database
+      file** (``.duckdb``); a table is a relation *inside* that file, read by
+      attaching the database read-only and selecting the table.
+
     Args:
         name:          Logical mart name used in ``datamart://<name>/…``.
-        location:      Base location of the tables — a directory path or
-                       an ``s3://`` / ``https://`` prefix. Joined with
-                       ``table_pattern`` to address a single table.
-        table_pattern: Filename pattern for a table, ``{table}`` being the
-                       table name. Defaults to ``"{table}.parquet"``.
+        location:      Base location: a directory / ``s3://`` / ``https://``
+                       prefix (``parquet``), or the path to a ``.duckdb``
+                       file (``duckdb``).
+        table_pattern: Filename pattern for a ``parquet`` table, ``{table}``
+                       being the table name. Defaults to ``"{table}.parquet"``.
+                       Ignored for ``duckdb`` marts.
+        kind:          Backend, ``"parquet"`` (default) or ``"duckdb"``.
         crs:           Optional CRS to force on tables that declare none.
         metadata:      Free-form descriptive metadata.
     """
@@ -60,13 +82,31 @@ class Datamart:
     name: str
     location: str
     table_pattern: str = "{table}.parquet"
+    kind: str = "parquet"
     crs: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
 
+    def __post_init__(self) -> None:
+        if self.kind not in DATAMART_KINDS:
+            raise ValueError(
+                f"datamart '{self.name}': unknown kind {self.kind!r} "
+                f"(expected one of {DATAMART_KINDS})"
+            )
+
     def uri_for(self, table: str) -> str:
-        """Return the concrete source URI for *table* in this mart."""
+        """Return the concrete source URI for *table* (``parquet`` marts).
+
+        Raises:
+            ValueError: for a ``duckdb`` mart — a table there is not a file
+                URI; resolve it via the loader's DuckDB-table path instead.
+        """
         if not table:
             raise ValueError(f"datamart '{self.name}': empty table name")
+        if self.kind != "parquet":
+            raise ValueError(
+                f"datamart '{self.name}': uri_for is only valid for parquet "
+                f"marts, not kind={self.kind!r}"
+            )
         filename = self.table_pattern.format(table=table)
         base = self.location.rstrip("/")
         return f"{base}/{filename}"
@@ -141,13 +181,19 @@ class DatamartRegistry:
                 if not isinstance(spec, dict) or "location" not in spec:
                     log.warning("datamart_env_bad_decl", name=name)
                     continue
-                self._marts[name] = Datamart(
-                    name=name,
-                    location=str(spec["location"]),
-                    table_pattern=str(spec.get("table_pattern", "{table}.parquet")),
-                    crs=spec.get("crs"),
-                    metadata=dict(spec.get("metadata") or {}),
-                )
+                try:
+                    self._marts[name] = Datamart(
+                        name=name,
+                        location=str(spec["location"]),
+                        table_pattern=str(
+                            spec.get("table_pattern", "{table}.parquet")
+                        ),
+                        kind=str(spec.get("kind", "parquet")),
+                        crs=spec.get("crs"),
+                        metadata=dict(spec.get("metadata") or {}),
+                    )
+                except ValueError as exc:
+                    log.warning("datamart_env_bad_decl", name=name, error=str(exc))
 
 
 def parse_datamart_uri(uri: str) -> tuple[str, str]:
@@ -177,6 +223,7 @@ DATAMARTS = DatamartRegistry()
 __all__ = [
     "DATAMARTS",
     "DATAMARTS_ENV",
+    "DATAMART_KINDS",
     "DATAMART_SCHEME",
     "Datamart",
     "DatamartRegistry",

{gispulse-2.2.0 → gispulse-2.2.1}/src/gispulse/persistence/loader.py

@@ -119,12 +119,30 @@ class LazyDataset:
         return _scan_to_gdf(self.scan_sql, crs=self.crs, bbox=bbox)
 
 
+@dataclass(frozen=True)
+class _DuckDBTableRef:
+    """Reference to a table living inside a single DuckDB database file.
+
+    Produced by :func:`resolve_source` for a ``duckdb``-kind datamart
+    (``datamart://<mart>/<table>`` where the mart's location is a
+    ``.duckdb`` file). Unlike a Parquet table it is not a file URI the
+    loader can hand to ``read_vector`` / a remote-table scan, so the loader
+    reads it via :func:`_duckdb_table_to_gdf` (attach read-only, select).
+    """
+
+    db_path: str
+    table: str
+    crs: str | None = None
+
+
 # ---------------------------------------------------------------------------
 # Source resolution
 # ---------------------------------------------------------------------------
 
 
-def resolve_source(source: "str | Path | AccessSpec | dict[str, Any]") -> "Path | AccessSpec":
+def resolve_source(
+    source: "str | Path | AccessSpec | dict[str, Any]",
+) -> "Path | AccessSpec | _DuckDBTableRef":
     """Resolve a user-supplied source into a local path or an access spec.
 
     Accepted forms:
@@ -162,12 +180,19 @@ def resolve_source(source: "str | Path | AccessSpec | dict[str, Any]") -> "Path
     scheme = head.lower()
 
     # Datamart indirection: resolve datamart://<mart>/<table> to its
-    # concrete source URI, then resolve that recursively.
+    # concrete source. A "parquet" mart yields a file URI resolved
+    # recursively; a "duckdb" mart yields a table reference inside a
+    # database file, read via _duckdb_table_to_gdf.
     if scheme == DATAMART_SCHEME:
         from gispulse.persistence.datamart import DATAMARTS, parse_datamart_uri
 
-        mart, table = parse_datamart_uri(raw)
-        return resolve_source(DATAMARTS.resolve(mart, table))
+        mart_name, table = parse_datamart_uri(raw)
+        mart = DATAMARTS.get(mart_name)
+        if mart.kind == "duckdb":
+            if not table:
+                raise ValueError(f"datamart '{mart_name}': empty table name")
+            return _DuckDBTableRef(db_path=mart.location, table=table, crs=mart.crs)
+        return resolve_source(mart.uri_for(table))
 
     # GeoNode: geonode://<instance>/<dataset> reads via the instance's
     # GeoServer WFS endpoint (reuses the OGC fetcher).
@@ -330,6 +355,52 @@ def _scan_to_gdf(
     return gdf
 
 
+def _duckdb_table_to_gdf(
+    db_path: str, table: str, *, crs: str | None, bbox: BBox | None
+) -> gpd.GeoDataFrame:
+    """Read a table from a DuckDB database file into a GeoDataFrame.
+
+    Attaches *db_path* **read-only** (so concurrent readers don't contend on
+    a write lock) onto an ephemeral in-memory session, then selects *table*.
+    When *bbox* is given an ``ST_Intersects`` envelope predicate is pushed
+    into the query against a ``geom`` column (matching the convention of
+    :func:`_scan_to_gdf`).
+    """
+    from gispulse.persistence.duckdb_engine import DuckDBSession
+
+    # ATTACH cannot be wrapped in the SELECT sub-query DuckDBSession.sql
+    # builds, so run it separately on the connection, then SELECT the table
+    # — that SELECT *is* wrappable, so geometry/CRS decoding still works.
+    db_lit = db_path.replace("'", "''")
+    rel = f"_mart.{_quote_ident(table)}"
+    query = f"SELECT * FROM {rel}"
+    if bbox is not None:
+        minx, miny, maxx, maxy = bbox
+        query = (
+            f"SELECT * FROM {rel} "
+            f"WHERE ST_Intersects(geom, ST_MakeEnvelope("
+            f"{minx}, {miny}, {maxx}, {maxy}))"
+        )
+
+    session = DuckDBSession()
+    session.open()
+    try:
+        session.conn.execute(f"ATTACH '{db_lit}' AS _mart (READ_ONLY)")
+        gdf = session.sql(query)
+    finally:
+        session.close()
+
+    if crs and gdf.crs is None:
+        gdf = gdf.set_crs(crs)
+    return gdf
+
+
+def _quote_ident(identifier: str) -> str:
+    """Quote a SQL identifier (double-quote, doubling embedded quotes)."""
+    escaped = identifier.replace('"', '""')
+    return f'"{escaped}"'
+
+
 # ---------------------------------------------------------------------------
 # Public entry point
 # ---------------------------------------------------------------------------
@@ -380,6 +451,15 @@ def load(
 
     resolved = resolve_source(source)
 
+    # --- DuckDB-file datamart table ---------------------------------------
+    if isinstance(resolved, _DuckDBTableRef):
+        if lazy:
+            log.debug("loader_lazy_ignored_for_duckdb_table", table=resolved.table)
+        gdf = _duckdb_table_to_gdf(
+            resolved.db_path, resolved.table, crs=crs or resolved.crs, bbox=bbox
+        )
+        return gdf
+
     # --- Local file path ---------------------------------------------------
     if isinstance(resolved, Path):
         if lazy:

{gispulse-2.2.0 → gispulse-2.2.1/src/gispulse.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gispulse
-Version: 2.2.0
+Version: 2.2.1
 Summary: Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)
 Author-email: ImagoData <contact@imagodata.com>
 License-Expression: AGPL-3.0-or-later