Basic usage

plpygis is a Python conveter to and from the PostGIS geometry type, WKB, EWKB, GeoJSON, Shapely geometries and any object that supports __geo_interface__. plpygis is intended for use in PL/Python, allowing procedural Python code to complement PostGIS types and functions.

Geometry

New Geometry instances can be created using a Well-Known Binary (WKB) representation of the geometry in hexadecimal form.

>>> from plpygis import Geometry
>>> geom = Geometry("01010000000000000000004AC00000000000000000")

Creation

Geometry instances may also be created from different representations of a geometry.

Geometry instances can be converted using the following methods:

>>> from plpygis import Geometry
>>> point = Geometry.from_geojson({'type': 'Point', 'coordinates': [-52.0, 0.0]})
>>> polygon = Geometry.from_wkt("POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))")

The shape() method can convert from any instance that provides __geo_interface__ (see A Python Protocol for Geospatial Data).

An optional srid keyword argument may be used with any of the above to set the geometry’s SRID. If the representation already provides an SRID (such as with some Shapely geometries) or implies a particular SRID (GeoJSON), it will be overridden by the user-specified value.

Geometry types

Every Geometry has a type that can be accessed using the instance’s type property. The following geometry types are supported:

  • Point

  • LineString

  • Polygon

  • MultiPoint

  • MultiLineString

  • MultiPolygon

  • GeometryCollection

The following EWKB types are not supported:

  • Unknown

  • CircularString

  • CompoundCurve

  • CurvePolygon

  • MultiCurve

  • MultiSurface

  • PolyhedralSurface

  • Triangle

  • Tin

Conversion

Geometry instances can also be converted to other representations using the following properties:

>>> from plpygis import Geometry
>>> geom = Geometry("01010000000000000000004AC00000000000000000")
>>> print(geom.wkt)
POINT (-52 0)

Geometry also implements __geo_interface__.

Conversion to GeoJSON or Shapely will result in the M dimension being lost as these representation only support X, Y and Z coordinates (see RFC 7946).

Exceptions

All plpygis exceptions inherit from the PlpygisError class. The specific exceptions that may be raised are: