Source code for geoalchemy2.types

""" This module defines the :class:`geoalchemy2.types.Geometry`,
:class:`geoalchemy2.types.Geography`, and :class:`geoalchemy2.types.Raster`
classes, that are used when defining geometry, geography and raster
columns/properties in models.

Reference
---------
"""
import warnings

from sqlalchemy.types import UserDefinedType, Integer
from sqlalchemy.sql import func
from sqlalchemy.dialects import postgresql
from sqlalchemy.dialects.postgresql.base import ischema_names

from .comparator import BaseComparator, Comparator
from .elements import WKBElement, WKTElement, RasterElement, CompositeElement
from .exc import ArgumentError


[docs]class _GISType(UserDefinedType): """ The base class for :class:`geoalchemy2.types.Geometry` and :class:`geoalchemy2.types.Geography`. This class defines ``bind_expression`` and ``column_expression`` methods that wrap column expressions in ``ST_GeomFromEWKT``, ``ST_GeogFromText``, or ``ST_AsEWKB`` calls. This class also defines ``result_processor`` and ``bind_processor`` methods. The function returned by ``result_processor`` converts WKB values received from the database to :class:`geoalchemy2.elements.WKBElement` objects. The function returned by ``bind_processor`` converts :class:`geoalchemy2.elements.WKTElement` objects to EWKT strings. Constructor arguments: ``geometry_type`` The geometry type. Possible values are: * ``"GEOMETRY"``, * ``"POINT"``, * ``"LINESTRING"``, * ``"POLYGON"``, * ``"MULTIPOINT"``, * ``"MULTILINESTRING"``, * ``"MULTIPOLYGON"``, * ``"GEOMETRYCOLLECTION"`` * ``"CURVE"``, * ``None``. The latter is actually not supported with :class:`geoalchemy2.types.Geography`. When set to ``None`` then no "geometry type" constraints will be attached to the geometry type declaration. Using ``None`` here is not compatible with setting ``management`` to ``True``. Default is ``"GEOMETRY"``. ``srid`` The SRID for this column. E.g. 4326. Default is ``-1``. ``dimension`` The dimension of the geometry. Default is ``2``. When set to ``3`` then the "geometry_type" is constrained to terminate on either ``"Z"`` or ``"M"``. When set to ``4`` then the "geometry_type" must terminate with ``"ZM"``. ``spatial_index`` Indicate if a spatial index should be created. Default is ``True``. ``management`` Indicate if the ``AddGeometryColumn`` and ``DropGeometryColumn`` managements functions should be called when adding and dropping the geometry column. Should be set to ``True`` for PostGIS 1.x. Default is ``False``. Note that this option has no effect for :class:`geoalchemy2.types.Geography`. ``use_typmod`` By default PostgreSQL type modifiers are used to create the geometry column. To use check constraints instead set ``use_typmod`` to ``False``. By default this option is not included in the call to ``AddGeometryColumn``. Note that this option is only taken into account if ``management`` is set to ``True`` and is only available for PostGIS 2.x. ``use_st_prefix`` Whether to use the ``ST_`` versions of the from_text and as_binary functions. For example, for Geometry, ``GeomFromEWKT`` will be used if ``use_st_prefix`` is ``False``, otherwise ``ST_GeomFromEWKT`` will be used. Default is ``True``. """ name = None """ Name used for defining the main geo type (geometry or geography) in CREATE TABLE statements. Set in subclasses. """ from_text = None """ The name of "from text" function for this type. Set in subclasses. """ as_binary = None """ The name of the "as binary" function for this type. Set in subclasses. """ comparator_factory = Comparator """ This is the way by which spatial operators are defined for geometry/geography columns. """ def __init__(self, geometry_type='GEOMETRY', srid=-1, dimension=2, spatial_index=True, management=False, use_typmod=None, use_st_prefix=True): geometry_type, srid = self.check_ctor_args( geometry_type, srid, dimension, management, use_typmod) self.geometry_type = geometry_type self.srid = srid self.dimension = dimension self.spatial_index = spatial_index self.management = management self.use_typmod = use_typmod self.extended = self.as_binary == 'AsEWKB' self.use_st_prefix = use_st_prefix if use_st_prefix: self.from_text = 'ST_' + self.from_text self.as_binary = 'ST_' + self.as_binary def get_col_spec(self): if not self.geometry_type: return self.name return '%s(%s,%d)' % (self.name, self.geometry_type, self.srid)
[docs] def column_expression(self, col): return getattr(func, self.as_binary)(col, type_=self)
[docs] def result_processor(self, dialect, coltype): def process(value): if value is not None: return WKBElement(value, srid=self.srid, extended=self.extended, use_st_prefix=self.use_st_prefix) return process
[docs] def bind_expression(self, bindvalue): return getattr(func, self.from_text)(bindvalue, type_=self)
[docs] def bind_processor(self, dialect): def process(bindvalue): if isinstance(bindvalue, WKTElement): return 'SRID=%d;%s' % (bindvalue.srid, bindvalue.data) else: return bindvalue return process
@staticmethod def check_ctor_args(geometry_type, srid, dimension, management, use_typmod): try: srid = int(srid) except ValueError: raise ArgumentError('srid must be convertible to an integer') if geometry_type: geometry_type = geometry_type.upper() if ((dimension == 4 and not geometry_type.endswith('ZM')) or (dimension == 3 and not (geometry_type.endswith('Z') or (geometry_type.endswith('M') and not geometry_type.endswith('ZM')))) or (dimension == 2 and (geometry_type.endswith('ZM') or geometry_type.endswith('Z') or geometry_type.endswith('M')))): raise ArgumentError( 'invalid geometry_type {!r} for dimension {}'.format( geometry_type, dimension)) else: if management: raise ArgumentError('geometry_type set to None not compatible ' 'with management') if srid > 0: warnings.warn('srid not enforced when geometry_type is None') if dimension > 2: raise ArgumentError('geometry type set to None not compatible ' 'with dimension > 2') if use_typmod and not management: warnings.warn('use_typmod ignored when management is False') return geometry_type, srid
[docs]class Geometry(_GISType): """ The Geometry type. Creating a geometry column is done like this:: Column(Geometry(geometry_type='POINT', srid=4326)) See :class:`geoalchemy2.types._GISType` for the list of arguments that can be passed to the constructor. """ name = 'geometry' """ Type name used for defining geometry columns in ``CREATE TABLE``. """ from_text = 'GeomFromEWKT' """ The "from text" geometry constructor. Used by the parent class' ``bind_expression`` method. """ as_binary = 'AsEWKB' """ The "as binary" function to use. Used by the parent class' ``column_expression`` method. """
[docs]class Geography(_GISType): """ The Geography type. Creating a geography column is done like this:: Column(Geography(geometry_type='POINT', srid=4326)) See :class:`geoalchemy2.types._GISType` for the list of arguments that can be passed to the constructor. """ name = 'geography' """ Type name used for defining geography columns in ``CREATE TABLE``. """ from_text = 'GeogFromText' """ The ``FromText`` geography constructor. Used by the parent class' ``bind_expression`` method. """ as_binary = 'AsBinary' """ The "as binary" function to use. Used by the parent class' ``column_expression`` method. """
[docs]class Raster(UserDefinedType): """ The Raster column type. Creating a raster column is done like this:: Column(Raster) This class defines the ``result_processor`` method, so that raster values received from the database are converted to :class:`geoalchemy2.elements.RasterElement` objects. Constructor arguments: ``spatial_index`` Indicate if a spatial index should be created. Default is ``True``. """ comparator_factory = BaseComparator """ This is the way by which spatial operators and functions are defined for raster columns. """ def __init__(self, spatial_index=True): self.spatial_index = spatial_index def get_col_spec(self): return 'raster'
[docs] def result_processor(self, dialect, coltype): def process(value): if value is not None: return RasterElement(value) return process
[docs]class CompositeType(UserDefinedType): """ A wrapper for :class:`geoalchemy2.elements.CompositeElement`, that can be used as the return type in PostgreSQL functions that return composite values. This is used as the base class of :class:`geoalchemy2.types.GeometryDump`. """ typemap = {} """ Dictionary used for defining the content types and their corresponding keys. Set in subclasses. """
[docs] class comparator_factory(UserDefinedType.Comparator): def __getattr__(self, key): try: type_ = self.type.typemap[key] except KeyError: raise KeyError("Type '%s' doesn't have an attribute: '%s'" % (self.type, key)) return CompositeElement(self.expr, key, type_)
[docs]class GeometryDump(CompositeType): """ The return type for functions like ``ST_Dump``, consisting of a path and a geom field. You should normally never use this class directly. """ typemap = {'path': postgresql.ARRAY(Integer), 'geom': Geometry} """ Dictionary defining the contents of a ``geometry_dump``. """
# Register Geometry, Geography and Raster to SQLAlchemy's Postgres reflection # subsystem. ischema_names['geometry'] = Geometry ischema_names['geography'] = Geography ischema_names['raster'] = Raster