tessl/pypi-geoalchemy2

Using SQLAlchemy with Spatial Databases

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Spatial Types

Name: tessl/pypi-geoalchemy2
Author: tessl

Spatial column types for defining geometry, geography, and raster columns in SQLAlchemy models. These types provide database-agnostic spatial column definitions with automatic spatial index creation and dialect-specific optimizations.

Capabilities

Geometry Type

Column type for geometric data using Cartesian coordinate systems. Supports all standard geometry types with flexible SRID and dimension configuration.

class Geometry:
    """
    Column type for geometric data in Cartesian coordinate systems.
    
    Parameters:
    - geometry_type: str, geometry type constraint ("GEOMETRY", "POINT", "LINESTRING", 
      "POLYGON", "MULTIPOINT", "MULTILINESTRING", "MULTIPOLYGON", "GEOMETRYCOLLECTION", "CURVE")
    - srid: int, spatial reference system identifier (default: -1)
    - dimension: int, coordinate dimension (2, 3, or 4, default: 2)
    - spatial_index: bool, create spatial index (default: True)
    - use_N_D_index: bool, use N-dimensional index for PostgreSQL (default: False)
    - use_typmod: bool, use type modifiers instead of constraints (default: None)
    - from_text: str, custom from-text function name (default: None)
    - name: str, custom type name (default: None) 
    - nullable: bool, allow NULL values (default: True)
    """
    
    def __init__(
        self,
        geometry_type: Optional[str] = "GEOMETRY",
        srid: int = -1, 
        dimension: Optional[int] = None,
        spatial_index: bool = True,
        use_N_D_index: bool = False,
        use_typmod: Optional[bool] = None,
        from_text: Optional[str] = None,
        name: Optional[str] = None,
        nullable: bool = True
    ): ...

Usage examples:

from sqlalchemy import Column, Integer, String
from geoalchemy2 import Geometry

class Building(Base):
    __tablename__ = 'building'
    
    id = Column(Integer, primary_key=True)
    name = Column(String)
    
    # Point geometry with specific SRID
    location = Column(Geometry('POINT', srid=4326))
    
    # Polygon geometry with 3D coordinates
    footprint = Column(Geometry('POLYGON', srid=3857, dimension=3))
    
    # Generic geometry without type constraint
    boundary = Column(Geometry(srid=4326))

Geography Type

Column type for geographic data using spheroidal coordinate systems. Optimized for global geographic calculations with automatic great-circle distance computations.

class Geography:
    """
    Column type for geographic data in spheroidal coordinate systems.
    
    Parameters:
    - geometry_type: str, geometry type constraint (same as Geometry)
    - srid: int, spatial reference system identifier (default: -1) 
    - dimension: int, coordinate dimension (2, 3, or 4, default: 2)
    - spatial_index: bool, create spatial index (default: True)
    - use_N_D_index: bool, use N-dimensional index for PostgreSQL (default: False)
    - use_typmod: bool, use type modifiers instead of constraints (default: None)
    - from_text: str, custom from-text function name (default: None)
    - name: str, custom type name (default: None)
    - nullable: bool, allow NULL values (default: True)
    """
    
    def __init__(
        self, 
        geometry_type: Optional[str] = "GEOMETRY",
        srid: int = -1,
        dimension: Optional[int] = None, 
        spatial_index: bool = True,
        use_N_D_index: bool = False,
        use_typmod: Optional[bool] = None,
        from_text: Optional[str] = None,
        name: Optional[str] = None,
        nullable: bool = True
    ): ...

Usage examples:

from geoalchemy2 import Geography

class Airport(Base):
    __tablename__ = 'airport'
    
    id = Column(Integer, primary_key=True)
    code = Column(String(3))
    
    # Geographic point for global positioning
    location = Column(Geography('POINT', srid=4326))
    
    # Flight path as geographic linestring
    runway = Column(Geography('LINESTRING', srid=4326))

Raster Type

Column type for raster data including satellite imagery, digital elevation models, and gridded datasets.

class Raster:
    """
    Column type for raster data.
    
    Parameters:
    - spatial_index: bool, create spatial index on raster convex hull (default: True)
    - nullable: bool, allow NULL values (default: True)
    """
    
    def __init__(
        self,
        spatial_index: bool = True,
        nullable: bool = True
    ): ...

Usage examples:

from geoalchemy2 import Raster

class Satellite(Base):
    __tablename__ = 'satellite_image'
    
    id = Column(Integer, primary_key=True)
    scene_id = Column(String)
    
    # Raster data with spatial indexing
    image_data = Column(Raster())
    
    # Elevation model without spatial index
    elevation = Column(Raster(spatial_index=False))

Composite Types

Specialized types for handling composite spatial values returned by certain spatial functions.

class GeometryDump:
    """
    Return type for functions like ST_Dump that return geometry components.
    
    Components:
    - path: array of integers indicating component path
    - geom: geometry component
    """
    
    typemap = {
        "path": postgresql.ARRAY(Integer),
        "geom": Geometry
    }

class SummaryStats: 
    """
    Return type for ST_SummaryStatsAgg function.
    
    Components:
    - count: number of values
    - sum: sum of values  
    - mean: mean value
    - stddev: standard deviation
    - min: minimum value
    - max: maximum value
    """
    
    typemap = {
        "count": Integer,
        "sum": Float,
        "mean": Float, 
        "stddev": Float,
        "min": Float,
        "max": Float
    }

Type Utilities

Helper functions for working with spatial types across different database dialects.

def select_dialect(dialect_name: str):
    """
    Select database dialect implementation for spatial operations.
    
    Parameters:
    - dialect_name: str, database dialect ("postgresql", "mysql", "mariadb", "sqlite", "geopackage")
    
    Returns:
    Dialect-specific implementation module
    """