gpkglite 0.1.0__py3-none-any.whl

gpkglite/__init__.py

@@ -0,0 +1,79 @@
+"""gpkglite: read and write OGC GeoPackage files with the Python standard library.
+
+No GDAL, no compiled dependencies: only :mod:`sqlite3`, :mod:`struct` and
+:mod:`json`. Geometries are GeoJSON-like dictionaries.
+
+Quick start::
+
+    import gpkglite
+
+    with gpkglite.create("cities.gpkg") as gpkg:
+        layer = gpkg.create_layer("cities", "POINT", 4326, {"name": "TEXT", "pop": "INTEGER"})
+        layer.insert({"type": "Point", "coordinates": [28.97, 41.01]}, {"name": "Istanbul", "pop": 15_600_000})
+
+    with gpkglite.open("cities.gpkg") as gpkg:
+        for feature in gpkg["cities"].features(where="pop > ?", params=[1_000_000]):
+            print(feature["properties"]["name"], feature["geometry"]["coordinates"])
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import binary, wkb, wkt
+from .binary import GeoPackageGeometry
+from .binary import decode as decode_geometry
+from .binary import encode as encode_geometry
+from .convert import (
+    from_csv,
+    from_geodataframe,
+    from_geojson,
+    infer_fields,
+    infer_geometry_type,
+    to_csv,
+    to_geodataframe,
+    to_geojson,
+)
+from .crs import SpatialRefSys
+from .errors import (
+    GeometryError,
+    GeoPackageError,
+    GpkgliteError,
+    LayerNotFoundError,
+    UnsupportedGeometryError,
+)
+from .geopackage import Column, GeoPackage, Layer, LayerInfo, create, open
+from .validate import Issue, ValidationReport, validate
+
+__all__ = [
+    "__version__",
+    "Column",
+    "GeoPackage",
+    "GeoPackageError",
+    "GeoPackageGeometry",
+    "GeometryError",
+    "GpkgliteError",
+    "Issue",
+    "Layer",
+    "LayerInfo",
+    "LayerNotFoundError",
+    "SpatialRefSys",
+    "UnsupportedGeometryError",
+    "ValidationReport",
+    "binary",
+    "create",
+    "decode_geometry",
+    "encode_geometry",
+    "from_csv",
+    "from_geodataframe",
+    "from_geojson",
+    "infer_fields",
+    "infer_geometry_type",
+    "open",
+    "to_csv",
+    "to_geodataframe",
+    "to_geojson",
+    "validate",
+    "wkb",
+    "wkt",
+]

gpkglite/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m gpkglite`` entry point."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

gpkglite/_sql.py

@@ -0,0 +1,187 @@
+"""SQL definitions from OGC 12-128r18 (Annex C) and the RTree extension (Annex F.3)."""
+
+from __future__ import annotations
+
+from typing import List
+
+#: ``PRAGMA application_id`` value: the ASCII bytes "GPKG".
+APPLICATION_ID = 0x47504B47
+#: ``PRAGMA user_version`` written by gpkglite: GeoPackage 1.3.1 (12-128r18).
+USER_VERSION = 10301
+
+TIMESTAMP_DEFAULT = "strftime('%Y-%m-%dT%H:%M:%fZ','now')"
+
+RTREE_EXTENSION = "http://www.geopackage.org/spec120/#extension_rtree"
+METADATA_EXTENSION = "http://www.geopackage.org/spec120/#extension_metadata"
+CRS_WKT_EXTENSION = "http://www.geopackage.org/spec120/#extension_crs_wkt"
+
+SPATIAL_REF_SYS = """
+CREATE TABLE gpkg_spatial_ref_sys (
+  srs_name TEXT NOT NULL,
+  srs_id INTEGER NOT NULL PRIMARY KEY,
+  organization TEXT NOT NULL,
+  organization_coordsys_id INTEGER NOT NULL,
+  definition TEXT NOT NULL,
+  description TEXT{extra}
+)"""
+
+CONTENTS = f"""
+CREATE TABLE gpkg_contents (
+  table_name TEXT NOT NULL PRIMARY KEY,
+  data_type TEXT NOT NULL,
+  identifier TEXT UNIQUE,
+  description TEXT DEFAULT '',
+  last_change DATETIME NOT NULL DEFAULT ({TIMESTAMP_DEFAULT}),
+  min_x DOUBLE,
+  min_y DOUBLE,
+  max_x DOUBLE,
+  max_y DOUBLE,
+  srs_id INTEGER,
+  CONSTRAINT fk_gc_r_srs_id FOREIGN KEY (srs_id) REFERENCES gpkg_spatial_ref_sys(srs_id)
+)"""
+
+GEOMETRY_COLUMNS = """
+CREATE TABLE gpkg_geometry_columns (
+  table_name TEXT NOT NULL,
+  column_name TEXT NOT NULL,
+  geometry_type_name TEXT NOT NULL,
+  srs_id INTEGER NOT NULL,
+  z TINYINT NOT NULL,
+  m TINYINT NOT NULL,
+  CONSTRAINT pk_geom_cols PRIMARY KEY (table_name, column_name),
+  CONSTRAINT uk_gc_table_name UNIQUE (table_name),
+  CONSTRAINT fk_gc_tn FOREIGN KEY (table_name) REFERENCES gpkg_contents(table_name),
+  CONSTRAINT fk_gc_srs FOREIGN KEY (srs_id) REFERENCES gpkg_spatial_ref_sys (srs_id)
+)"""
+
+EXTENSIONS = """
+CREATE TABLE gpkg_extensions (
+  table_name TEXT,
+  column_name TEXT,
+  extension_name TEXT NOT NULL,
+  definition TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  CONSTRAINT ge_tce UNIQUE (table_name, column_name, extension_name)
+)"""
+
+METADATA = """
+CREATE TABLE gpkg_metadata (
+  id INTEGER CONSTRAINT m_pk PRIMARY KEY ASC NOT NULL,
+  md_scope TEXT NOT NULL DEFAULT 'dataset',
+  md_standard_uri TEXT NOT NULL,
+  mime_type TEXT NOT NULL DEFAULT 'text/xml',
+  metadata TEXT NOT NULL DEFAULT ''
+)"""
+
+METADATA_REFERENCE = f"""
+CREATE TABLE gpkg_metadata_reference (
+  reference_scope TEXT NOT NULL,
+  table_name TEXT,
+  column_name TEXT,
+  row_id_value INTEGER,
+  timestamp DATETIME NOT NULL DEFAULT ({TIMESTAMP_DEFAULT}),
+  md_file_id INTEGER NOT NULL,
+  md_parent_id INTEGER,
+  CONSTRAINT crmr_mfi_fk FOREIGN KEY (md_file_id) REFERENCES gpkg_metadata(id),
+  CONSTRAINT crmr_mpi_fk FOREIGN KEY (md_parent_id) REFERENCES gpkg_metadata(id)
+)"""
+
+
+def quote_ident(name: str) -> str:
+    """Quote an SQL identifier (table or column name)."""
+    return '"' + str(name).replace('"', '""') + '"'
+
+
+def rtree_name(table: str, column: str) -> str:
+    return f"rtree_{table}_{column}"
+
+
+def _bbox_values(c: str) -> str:
+    return f"ST_MinX(NEW.{c}), ST_MaxX(NEW.{c}), ST_MinY(NEW.{c}), ST_MaxY(NEW.{c})"
+
+
+def rtree_triggers(table: str, column: str, fid: str, version: int = USER_VERSION) -> List[str]:
+    """``CREATE TRIGGER`` statements maintaining ``rtree_<table>_<column>``.
+
+    GeoPackage 1.4 (``user_version >= 10400``) replaced the ``update1`` trigger
+    with ``update6``/``update7`` and renamed ``update3`` to ``update5``; earlier
+    versions use ``insert``, ``update1``-``update4`` and ``delete``.
+    """
+    base = rtree_name(table, column)
+    rt = quote_ident(base)
+    t = quote_ident(table)
+    c = quote_ident(column)
+    i = quote_ident(fid)
+    vals = _bbox_values(c)
+
+    def name(suffix: str) -> str:
+        return quote_ident(f"{base}_{suffix}")
+
+    present = f"(NEW.{c} NOTNULL AND NOT ST_IsEmpty(NEW.{c}))"
+    absent = f"(NEW.{c} ISNULL OR ST_IsEmpty(NEW.{c}))"
+    insert = (
+        f"CREATE TRIGGER {name('insert')} AFTER INSERT ON {t} "
+        f"WHEN (new.{c} NOT NULL AND NOT ST_IsEmpty(NEW.{c})) "
+        f"BEGIN INSERT OR REPLACE INTO {rt} VALUES (NEW.{i}, {vals}); END"
+    )
+    same_id_absent = (
+        f"CREATE TRIGGER {name('update2')} AFTER UPDATE OF {c} ON {t} "
+        f"WHEN OLD.{i} = NEW.{i} AND {absent} "
+        f"BEGIN DELETE FROM {rt} WHERE id = OLD.{i}; END"
+    )
+    new_id_absent = (
+        f"CREATE TRIGGER {name('update4')} AFTER UPDATE ON {t} "
+        f"WHEN OLD.{i} != NEW.{i} AND {absent} "
+        f"BEGIN DELETE FROM {rt} WHERE id IN (OLD.{i}, NEW.{i}); END"
+    )
+    delete = (
+        f"CREATE TRIGGER {name('delete')} AFTER DELETE ON {t} "
+        f"WHEN old.{c} NOT NULL "
+        f"BEGIN DELETE FROM {rt} WHERE id = OLD.{i}; END"
+    )
+
+    def new_id_present(suffix: str) -> str:
+        return (
+            f"CREATE TRIGGER {name(suffix)} AFTER UPDATE ON {t} "
+            f"WHEN OLD.{i} != NEW.{i} AND {present} "
+            f"BEGIN DELETE FROM {rt} WHERE id = OLD.{i}; "
+            f"INSERT OR REPLACE INTO {rt} VALUES (NEW.{i}, {vals}); END"
+        )
+
+    if version < 10400:
+        update1 = (
+            f"CREATE TRIGGER {name('update1')} AFTER UPDATE OF {c} ON {t} "
+            f"WHEN OLD.{i} = NEW.{i} AND {present} "
+            f"BEGIN INSERT OR REPLACE INTO {rt} VALUES (NEW.{i}, {vals}); END"
+        )
+        return [insert, update1, same_id_absent, new_id_present("update3"), new_id_absent, delete]
+
+    old_present = f"(OLD.{c} NOTNULL AND NOT ST_IsEmpty(OLD.{c}))"
+    old_absent = f"(OLD.{c} ISNULL OR ST_IsEmpty(OLD.{c}))"
+    update6 = (
+        f"CREATE TRIGGER {name('update6')} AFTER UPDATE OF {c} ON {t} "
+        f"WHEN OLD.{i} = NEW.{i} AND {present} AND {old_present} "
+        f"BEGIN UPDATE {rt} SET minx = ST_MinX(NEW.{c}), maxx = ST_MaxX(NEW.{c}), "
+        f"miny = ST_MinY(NEW.{c}), maxy = ST_MaxY(NEW.{c}) WHERE id = NEW.{i}; END"
+    )
+    update7 = (
+        f"CREATE TRIGGER {name('update7')} AFTER UPDATE OF {c} ON {t} "
+        f"WHEN OLD.{i} = NEW.{i} AND {present} AND {old_absent} "
+        f"BEGIN INSERT INTO {rt} VALUES (NEW.{i}, {vals}); END"
+    )
+    return [
+        insert,
+        same_id_absent,
+        new_id_absent,
+        new_id_present("update5"),
+        update6,
+        update7,
+        delete,
+    ]
+
+
+#: Trigger name suffixes expected for a given GeoPackage version.
+def rtree_trigger_suffixes(version: int) -> List[str]:
+    if version < 10400:
+        return ["insert", "update1", "update2", "update3", "update4", "delete"]
+    return ["insert", "update2", "update4", "update5", "update6", "update7", "delete"]

gpkglite/binary.py

@@ -0,0 +1,219 @@
+"""StandardGeoPackageBinary encoding and decoding (OGC 12-128r18, clause 2.1.3).
+
+Layout of a geometry blob::
+
+    magic      2 bytes   "GP"
+    version    1 byte    0 (version 1)
+    flags      1 byte    bit 0: header byte order (1 = little endian)
+                         bits 1-3: envelope contents indicator (0-4)
+                         bit 4: empty geometry flag
+                         bit 5: 0 = StandardGeoPackageBinary, 1 = Extended
+    srs_id     int32
+    envelope   0/32/48/48/64 bytes of doubles
+    geometry   ISO WKB
+
+Envelope indicator codes: 0 = none, 1 = [minx, maxx, miny, maxy],
+2 = + [minz, maxz], 3 = + [minm, maxm], 4 = + [minz, maxz, minm, maxm].
+"""
+
+from __future__ import annotations
+
+import math
+import struct
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Tuple, Union
+
+from . import wkb as _wkb
+from .errors import GeometryError, UnsupportedGeometryError
+
+__all__ = [
+    "ENVELOPE_SIZES",
+    "ENVELOPE_NAMES",
+    "GeoPackageGeometry",
+    "Header",
+    "decode",
+    "decode_header",
+    "encode",
+]
+
+#: Number of doubles stored for each envelope indicator code.
+ENVELOPE_SIZES: Dict[int, int] = {0: 0, 1: 4, 2: 6, 3: 6, 4: 8}
+#: Accepted names for the ``envelope`` argument of :func:`encode`.
+ENVELOPE_NAMES: Dict[str, int] = {"none": 0, "xy": 1, "xyz": 2, "xym": 3, "xyzm": 4}
+
+MAGIC = b"GP"
+
+
+@dataclass(frozen=True)
+class Header:
+    """Parsed GeoPackage binary header."""
+
+    version: int
+    flags: int
+    byte_order: str  # "<" or ">"
+    envelope_type: int
+    empty: bool
+    extended: bool
+    srs_id: int
+    envelope: Tuple[float, ...]
+    size: int  # header length in bytes, i.e. offset of the WKB payload
+
+    @property
+    def envelope_dict(self) -> Dict[str, float]:
+        """The envelope as ``{"minx": ..., "maxx": ..., ...}``."""
+        keys = {
+            0: (),
+            1: ("minx", "maxx", "miny", "maxy"),
+            2: ("minx", "maxx", "miny", "maxy", "minz", "maxz"),
+            3: ("minx", "maxx", "miny", "maxy", "minm", "maxm"),
+            4: ("minx", "maxx", "miny", "maxy", "minz", "maxz", "minm", "maxm"),
+        }[self.envelope_type]
+        return dict(zip(keys, self.envelope))
+
+
+@dataclass(frozen=True)
+class GeoPackageGeometry:
+    """A decoded GeoPackage geometry blob."""
+
+    header: Header
+    wkb: bytes = field(repr=False)
+    geometry: Optional[Dict[str, Any]]  # None only when decode(..., parse_wkb=False)
+
+    @property
+    def srs_id(self) -> int:
+        return self.header.srs_id
+
+    @property
+    def empty(self) -> bool:
+        return self.header.empty
+
+    @property
+    def bounds(self) -> Optional[Tuple[float, float, float, float]]:
+        """2D bounds ``(minx, miny, maxx, maxy)`` from the header envelope or WKB."""
+        env = self.header.envelope
+        if self.header.envelope_type and not any(math.isnan(v) for v in env[:4]):
+            return (env[0], env[2], env[1], env[3])
+        if self.geometry is None:
+            return _wkb.bounds(_wkb.loads(self.wkb))
+        return _wkb.bounds(self.geometry)
+
+
+def decode_header(blob: Union[bytes, bytearray, memoryview]) -> Header:
+    """Parse only the header of a GeoPackage geometry blob."""
+    data = bytes(blob)
+    if len(data) < 8:
+        raise GeometryError(f"GeoPackage geometry blob too short ({len(data)} bytes)")
+    if data[:2] != MAGIC:
+        raise GeometryError(f"bad GeoPackage geometry magic {data[:2]!r}, expected b'GP'")
+    version = data[2]
+    if version != 0:
+        raise GeometryError(f"unsupported GeoPackage binary version {version}")
+    flags = data[3]
+    if flags & 0xC0:
+        raise GeometryError(f"reserved flag bits set in GeoPackage header flags {flags:#04x}")
+    bo = "<" if flags & 1 else ">"
+    env_type = (flags >> 1) & 0x07
+    if env_type not in ENVELOPE_SIZES:
+        raise GeometryError(f"invalid envelope contents indicator code {env_type}")
+    empty = bool(flags & 0x10)
+    extended = bool(flags & 0x20)
+    (srs_id,) = struct.unpack_from(bo + "i", data, 4)
+    n = ENVELOPE_SIZES[env_type]
+    size = 8 + 8 * n
+    if len(data) < size:
+        raise GeometryError("GeoPackage geometry blob truncated inside the envelope")
+    env = struct.unpack_from(f"{bo}{n}d", data, 8) if n else ()
+    return Header(version, flags, bo, env_type, empty, extended, int(srs_id), env, size)
+
+
+def decode(blob: Union[bytes, bytearray, memoryview], parse_wkb: bool = True) -> GeoPackageGeometry:
+    """Decode a GeoPackage geometry blob.
+
+    Args:
+        blob: the BLOB stored in a feature table geometry column.
+        parse_wkb: when ``False`` only the header is parsed and
+            :attr:`GeoPackageGeometry.geometry` is ``None``.
+
+    Raises:
+        GeometryError: malformed header or WKB.
+        UnsupportedGeometryError: ExtendedGeoPackageBinary or curve geometry.
+    """
+    data = bytes(blob)
+    header = decode_header(data)
+    if header.extended:
+        raise UnsupportedGeometryError(
+            "ExtendedGeoPackageBinary geometries (flag bit 5) carry extension-specific "
+            "encodings that gpkglite does not decode"
+        )
+    payload = data[header.size :]
+    geometry = _wkb.loads(payload) if parse_wkb else None
+    return GeoPackageGeometry(header=header, wkb=payload, geometry=geometry)
+
+
+def encode(
+    geom: Any,
+    srs_id: int = 0,
+    envelope: Union[str, int] = "auto",
+    byte_order: str = "<",
+    dims: Optional[str] = None,
+) -> bytes:
+    """Encode a geometry as a StandardGeoPackageBinary blob.
+
+    Args:
+        geom: geometry dictionary, ``__geo_interface__`` object, or raw WKB
+            ``bytes`` (re-wrapped without re-encoding).
+        srs_id: value of the header ``srs_id`` field.
+        envelope: ``"auto"`` (no envelope for points, which the spec
+            recommends, XY envelope otherwise), ``"none"``, ``"xy"``, ``"xyz"``,
+            ``"xym"``, ``"xyzm"`` or an indicator code 0-4. Empty geometries are
+            always written without an envelope and with the empty flag set.
+        byte_order: byte order of header and WKB, ``"<"`` or ``">"``.
+        dims: force the coordinate dimension of the WKB.
+    """
+    if byte_order not in ("<", ">"):
+        raise ValueError("byte_order must be '<' or '>'")
+    if isinstance(geom, (bytes, bytearray, memoryview)):
+        payload = bytes(geom)
+        g = _wkb.loads(payload)
+    else:
+        g = _wkb.normalize(geom)
+        if dims is not None:
+            g["dims"] = dims.upper()
+        payload = _wkb.dumps(g, byte_order=byte_order)
+    empty = _wkb.is_empty(g)
+    env_type = _envelope_code(envelope, g, empty)
+    env_values: Tuple[float, ...] = ()
+    if env_type:
+        full = _wkb.envelope(g)
+        assert full is not None  # non-empty
+        has_z, has_m = _wkb.geometry_dims(g)
+        if env_type in (2, 4) and not has_z:
+            raise GeometryError("a Z envelope was requested for a geometry without Z")
+        if env_type in (3, 4) and not has_m:
+            raise GeometryError("an M envelope was requested for a geometry without M")
+        xy = full[:4]
+        z = full[4:6] if has_z else ()
+        m = full[-2:] if has_m else ()
+        env_values = xy + {1: (), 2: z, 3: m, 4: z + m}[env_type]
+    flags = (1 if byte_order == "<" else 0) | (env_type << 1) | (0x10 if empty else 0)
+    head = MAGIC + struct.pack(byte_order + "BBi", 0, flags, int(srs_id))
+    if env_values:
+        head += struct.pack(f"{byte_order}{len(env_values)}d", *env_values)
+    return head + payload
+
+
+def _envelope_code(envelope: Union[str, int], g: Dict[str, Any], empty: bool) -> int:
+    if empty:
+        return 0
+    if isinstance(envelope, int) and not isinstance(envelope, bool):
+        if envelope not in ENVELOPE_SIZES:
+            raise ValueError(f"invalid envelope indicator code {envelope}")
+        return envelope
+    key = str(envelope).lower()
+    if key == "auto":
+        return 0 if g["type"] == "Point" else 1
+    if key not in ENVELOPE_NAMES:
+        raise ValueError(
+            f"invalid envelope {envelope!r}; expected auto, {', '.join(ENVELOPE_NAMES)}"
+        )
+    return ENVELOPE_NAMES[key]