Plpygis PDF

plpygis Documentation
Release 0.1.0
Benjamin Trigona-Harany
Feb 14, 2018

Contents:
1 Installation 3
1.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Python Package Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Basic usage 5
2.1 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Geometry subclasses 9
3.1 Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.4 SRIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5 Dimensionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.6 Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4 PL/Python 13
4.1 Enabling PL/Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Function declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Type mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.4 Arrays and sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.5 Shared data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6 plpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.7 Aggregate functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5 Examples 19
5.1 Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2 External services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.3 Rendering output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.4 Spatial aggregate function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
6 plpygis package 23
Python Module Index 33
i
ii
plpygis Documentation, Release 0.1.0
plpygis is a Python conveter to and from the PostGIS geometry type, WKB, EWKB, GeoJSON and Shapely
geometries and additionally supports __geo_interface__. plpygis is intended for use in PL/Python functions.
Contents: 1
2 Contents:
CHAPTER 1
Installation
1.1 Requirements
plpygis has no dependencies beyond an installation of Python 2.7.x or 3.6.x. Additionally, plpygis can use
Shapely (version 1.6 or greater) if available. Without it, conversion to and from Shapely geometries will be impossible.
1.2 Python Package Index
plpygis may be installed from PyPI.
$ pip install plpygis
It is recommended that plpygis is installed into the system installation of Python or it may not be available in
PL/Python functions.
1.3 Source
The package sources are available at https://github.com/bosth/plpygis. Building and installing plpygis from source
can be done with setuptools:
$ python setup.py install
1.3.1 Tests
Tests require nose:
$ python setup.py test
3
1.3.2 Documentation
Building the documentation from source requires Sphinx. By default, the documentation will be rendered in HTML:
$ python setup.py build_sphinx
For other documentation output formats, see the options in the docs subdirectory:
$ cd docs
$ make
4 Chapter 1. Installation
CHAPTER 2
Basic usage
plpygis is a Python conveter to and from the PostGIS geometry type, WKB, EWKB, GeoJSON, Shapely geome-
tries 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.
2.1 Geometry
New Geometry instances can be created using a Well-Known Binary (WKB) representation of the geometry.
>>> from plpygis import Geometry

>>> geom = Geometry("01010000000000000000004AC00000000000000000")
2.1.1 Creation
Geometry instances may also be created from different representations of a geometry.

Geometry instances can be converted using the following methods:
• from_geojson()
• from_shapely()

>>> geom = Geometry.from_geojson({'type': 'Point', 'coordinates': [-52.0, 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 represen-
tation 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.
5
2.1.2 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
2.1.3 Conversion
Geometry instances can also be converted to other representations using the following properties:
• geojson
• shapely
• wkb

>>> geom = Geometry("01010000000000000000004AC00000000000000000")
>>> print geom.shapely
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).
2.2 Exceptions
All plpygis exceptions inherit from the PlpygisError class. The specific exceptions that may be raised are:
6 Chapter 2. Basic usage

• DependencyError: missing dependency required for an optional feature, such as shapely

• DimensionalityError: error pertaining to the Z or M coordinates of a Geometry
• SridError: error pertaining to a Geometry’s SRIDs
• WkbError: error reading or writing a WKB
2.2. Exceptions 7
8 Chapter 2. Basic usage

CHAPTER 3
Geometry subclasses
Creating a new plpygis geometry from a WKB, GeoJSON or Shapely instance, will produce a new subclass of the
base Geometry class:
• Point
• LineString
• Polygon
• MultiPoint
• LineString
• MultiPolygon
• GeometryCollection
3.1 Creation
New instances of the three base shapes (points, lines and polygons) may be created by passing in coordinates:
>>> point = Point((0, 0))

>>> line = LineString([(0, 0), (0, 1)])
>>> poly = Polygon([[(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)], [(4, 4), (4, 6), (6,
˓→ 6), (6, 4), (4, 4)]])
3.2 Editing
Coordinates may be accessed and modified after creation.
9
>>> point = Point((0, 0))

>>> print point.x
0
>>> point.x = 10
>>> print point.x
10
3.3 Composition
Individual LineString instances are composed of a list of Point instances that each represent a vertex in the line.
Similarly, Polygon instances are composed of a list of LineString instances that each represent linear rings.
The lists of vertices or linear rings can be modified, for example by adding a new Point to the end of a LineString.
Note: The first linear ring in a polygon should represent the exterior ring, while subsequent linear rings are internal
boundaries. plpygis will not validate geometries when they are created.
The four collection types, MultiPoint, LineString, MultiPolygon and GeometryCollection, are each
composed of a list of other geometries of the appropriate type. At creation time, the collection types are created by
passing in a list of existing instances:
>>> p1 = Point((0, 0))

>>> p2 = Point((1, 1))
>>> mp = MultiPoint([p1, p2])
3.4 SRIDs
An SRID may be added at creation time with an optional SRID parameter:
>>> point = Point((0, 0), srid=4326)
plpygis will detect conflicts when multigeometries or collections are created with mixed SRIDs.
Warning: Changing the SRID of an instance that is part of another geometry (such as a Point that is a vertex in
a LineString or a vertex in the linear ring of a Polygon) will not be detected. When converted to a WKB or
Shapely instance, only the SRID of the “parent” geometry will be used.
3.5 Dimensionality
The dimz and dimm boolean parameters will indicate whether the geometry will have Z and M dimensions.
plpygis will attempt to match provided coordinates with the requested dimensions or will set them to an initial
value of 0 if they have not been provided:
>>> p1 = Point((0, 0, 1), dimz=True, dimm=True)

>>> print "p1", p1.x, p1.y, p1.z, p1.m
p1 0 0 1 0
>>> p2 = Point((0, 0, 1), dimm=True)
10 Chapter 3. Geometry subclasses

>>> print "p2", p2.x, p2.y, p2.z, p2.m

p2 0 0 None 1
>>> p3 = Point((0, 0, 1, 2))
>>> print "p3", p3.x, p3.y, p3.z, p3.m
p3 0 0 1 2
The dimensionality of an existing instance may be altered after creation, by setting dimz or dimm. Adding a dimen-
sion will add a Z or M coordinate with an initial value of 0 to the geometry and all geometries encompassed within it
(e.g., each vertex in a LineString or each Point in a MultiPoint will gain the new dimension).
A new dimension may also be added to a single Point by assigning to the z or m properties.
Adding a new dimension to a Point that is a vertex in a LineString or a vertex in the linear ring of a Polygon
will not change the dimensionality of the LineString or the Polygon. The dimensionality of “parent” instance
must also be changed for the new coordinates to be reflected when converting to other representations.
>>> p1 = Point((0, 0))

>>> p2 = Point((1, 1))
>>> mp = MultiPoint([p1, p2])
>>> print mp.dimz
False
>>> p1.z = 2
>>> print p1.miz
True
>>> print mp.dimz
False
>>> mp.dimz = True
>>> print mp.dimz
True
>>> print "p1.z", p1.z, "p2.z", p2.z
p1.z 2 p2.z 0
3.6 Performance considerations
3.6.1 Lazy evaluation
plpygis uses native WKB parsing to extract header information that indicates the geometry type, SRID and the
presence of a Z or M dimension. Full parsing of the entire geometry only occurs when needed. It is therefore possible
to test the type and dimensionality of a Geometry with only the first few bytes of data having been read. Perform
these checks before performing any action that will require reading the remainder of the WKB.
3.6.2 Caching
plpygis will cache the initial WKB it was created from. As soon as any coordinates or composite geometries are
referenced, the cached WKB is lost and a subsequent request that requires the WKB will necessitate it being generated
from scratch. For sets of large geometries, this can have a noticeable affect on performance. Therefore, if doing a
conversion to a Shapely geometry - an action which relies on the availability of the WKB - it is recommended that this
conversion be done before any other operations on the plpygis geometry.
Note: Getting type, srid, dimz and dimm are considered “safe” operations. However writing a new SRID or
changing the dimensionality will also result in the cached WKB being lost. A geometry’s type may never be changed.
3.6. Performance considerations 11

As a summary, getting the following properties will not affect performance:

• type
• srid
• dimz
• dimm
Setting the following properties will cause any cached WKB to be cleared:
• srid
• dimz
• dimm
Getting the following property relies on the presence of the WKB (cached or generated):
• shapely
If the Geometry was created from a WKB, the follwing actions will trigger a full parse and will clear the cached
copy of the WKB:
• getting geojson and __geo_interface__
• getting shapely
• getting any Point coordinate
• getting bounds
• getting vertices, rings
• getting any component geometry from MultiPoint, MultiLineString, MultiPolygon or
GeometryCollection
12 Chapter 3. Geometry subclasses

CHAPTER 4
PL/Python
The PostgreSQL documentation has a complete reference on authoring PL/Python functions.

This section will cover uses of PL/Python with plpygis.
4.1 Enabling PL/Python
Prior to using PL/Python, it must be loaded in the current database:
# CREATE LANGUAGE plpythonu;
Warning: PL/Python is an “untrusted” language, meaning that Python code will have unrestricted access to the
system at the same level as the database administrator.
4.1.1 Python 2 and Python 3
plpygis is compatible with both Python 2 and Python 3. plpythonu, however, always refers to Python 2 in
PostgreSQL. For Python 3, the language is plpython3u (Python 2 can also explicitly be used with plpython2u).
4.2 Function declarations
PL/Python function declarations follow the following template:
CREATE FUNCTION funcname (argument-list)

RETURNS return-type
AS $$
# PL/Python function body
$$ LANGUAGE plpythonu;
13
Named arguments are provided as a comma-separated list, with the argument name preceding the argument type:
CREATE OR REPLACE FUNCTION make_point(x FLOAT, y FLOAT)

RETURNS geometry
AS $$
# PL/Python function body
Warning: Variables passed as arguments should never be assigned to in a PL/Python function.
4.3 Type mappings
The mapping between types in PL/Python and is PostgreSQL is covered in the Data Values section of the documenta-
tion; it is the role of plpygis to assist in mapping between PL/Python and PostGIS types.
4.3.1 PostGIS types
When authoring a Postgres function that takes a PostGIS geometry as an input parameter or returns a geometry as
output, Geometry objects will provide the automatic conversion between types.

RETURNS geometry
AS $$
from plpygis import Point
p = Point(x, y)
return p
Input parameter
A PostGIS geometry passed as the argument to Geometry() will initialize the instance.
CREATE OR REPLACE FUNCTION find_hemisphere(geom geometry)

RETURNS TEXT
AS $$
from plpygis import Geometry
point = Geometry(geom)
if point.type != "Point":
return None
gj = point.geojson
lon = gj["coordinates"][0]
lat = gj["coordinates"][1]
if lon < 0:
return "West"
elif lon > 0:
return "East"
else:
return "Meridian"
14 Chapter 4. PL/Python
db=# SELECT name, find_hemisphere(ST_Centroid(geom)) FROM countries LIMIT 10;

name | find_hemisphere
-------------------------+-----------------
Aruba | West
Afghanistan | East
Angola | East
Anguilla | West
Albania | East
American Samoa | West
Andorra | East
Argentina | West
Armenia | East
Bulgaria | East
(10 rows)
Return value
A Geometry can be returned directly from a PL/Python function.

RETURNS geometry
AS $$
from plpygis import Point
return Point((x, y))
db=# SELECT make_point(-52, 0);

make_point
--------------------------------------------
01010000000000000000004AC00000000000000000
(1 row)
This custom make_point(x, y) functions identically to PostGIS’s native ST_MakePoint(x, y).
db=# SELECT ST_MakePoint(-52, 0);

st_makepoint
--------------------------------------------
01010000000000000000004AC00000000000000000
(1 row)
4.3.2 geometry and geography
Both PostGIS geometry and geography types may be used as arguments or return types. plpygis does not
support box2d, box3d, raster or any topology types.
geometry and geography arguments will be treated identically by plpygis, as they share an common WKB
format.
However, a PL/Python function that has a return value of geography must not have an SRID of any value except
4326. It will also be treated differently by certain PostGIS functions.
Imagine two PL/Python functions that both create a polygon with lower-left coordinates at (0, 0) and upper-right
coordinates at (50, 50). If box_geom has a return type of geometry and box_geog has a return type of
geography, area calculations will be evaluated as follows:
4.3. Type mappings 15

db=# SELECT ST_Area(box_geom());

st_area
------------------
2500
(1 row)
db=# SELECT ST_Area(box_geog());

st_area
------------------
27805712533424.3
(1 row)
4.4 Arrays and sets
In addition to returning single values, plpygis functions may return a list of geometries that can be either interpreted
as a PostgreSQL array or set.
db=# CREATE OR REPLACE FUNCTION make_points(x FLOAT, y FLOAT)

RETURNS SETOF geometry
AS $$
from shapely.geometry import Point
p1 = Point(x, y)
p2 = Point(y, x)
return [Geometry.shape(p1), Geometry.shape(p2)]
db=# SELECT ST_AsText(make_points(10,20));

st_astext
--------------
POINT(10 20)
POINT(20 10)
Python’s yield keyword may also be used to return elements in a set rather than returning them as elements in a list.
4.5 Shared data
Each PL/Python function has access to a shared dictionary SD that can be used to store data between function calls.
As with other data, plpygis.Geometry instances may be stored in the SD dictionary for future reference in later
function calls.
4.6 plpy
The plpy module provides access to helper functions, notably around logging to PostgreSQL’s standard log files.
See Utility Functions in the PostgreSQL documentation.
4.7 Aggregate functions
PostGIS includes several spatial aggregate functions that accept a set of geometries as input parameters. An aggregate
function definition requires different syntax from a normal PL/Python function:
CREATE AGGREGATE agg_fn (

SFUNC = _state_function,
STYPE = geometry,
BASETYPE = geometry, -- optional
FINALFUNC = wrapup_func, -- optional
INITCOND = 'POINT(0 0)' -- optional
);
An aggregate will accept individual inputs of the type defined by BASETYPE and incrementally producing a single
type defined by STYPE. If many geometries will be collapsed down to a single geometry, then both BASETYPE
and STYPE will be geometry. If many geometries will produce more than one geometry, then the types will be
geometry and geometry[] respectively.
An example aggregate function would be point_cluster, which takes n input geometries and outputs m geome-
tries, where m < n.
CREATE AGGREGATE point_cluster (

SFUNC = _point_cluster,
BASETYPE = geometry,
STYPE = geometry[],
INITCOND = '{}'
);
The function indicated by SFUNC must accept the STYPE as the first parameter and BASETYPE as the second pa-
rameter, returning another instance of STYPE. If INITCOND is provided, this will be the value of the first argument
passed to the first call of SFUNC. If it is omitted, the value will be initially set to None.
CREATE FUNCTION _point_cluster(geoms geometry[], newgeom geometry)

RETURNS geometry[]
AS $$
# incremental clustering algorithm here
Alternatively, the SFUNC can simply collect all the individual geometries into a list and then rely on a single
FINALFUNC to create a new list of geometries that represents the clustered points.
CREATE AGGREGATE point_cluster (

SFUNC = array_append,
BASETYPE = geometry,
STYPE = geometry[],
INITCOND = '{}',
FINALFUNC = _point_cluster
);
The parameter of the FINALFUNC will be a single geometry[], representing the collection of individual points.
CREATE FUNCTION _point_cluster(geoms geometry[])

RETURNS geometry[]
AS $$
# clustering algorithm here
4.7. Aggregate functions 17

CHAPTER 5
Examples
5.1 Conversion
Some functions that analyze or manipulate geometries are possible in SQL but are easier to model in a procedural
language. The following example will use Shapely to find the largest component polygon of a multipolygon.
CREATE OR REPLACE FUNCTION largest_poly(geom geometry)

RETURNS geometry
AS $$
polygons = Geometry(geom)
if polygons.type == 'Polygon':
return polygons
elif polygons.type == 'MultiPolygon':
largest = max(polygons.shapely, key=lambda polygon: polygon.area)
return Geometry.from_shapely(largest)
else:
return None
A pure PL/pgSQL function will have significantly better performance:
CREATE OR REPLACE FUNCTION largest_poly_fast(polygons geometry)

RETURNS geometry
AS $$
WITH geoms AS (
SELECT (ST_Dump(polygons)).geom AS geom
)
SELECT geom
FROM geoms
ORDER BY ST_Area(geom) DESC LIMIT 1;
$$ LANGUAGE sql;
19
5.2 External services
Another application of plpygis is accessing external services or commands directly from PostgreSQL.
CREATE OR REPLACE FUNCTION geocode(geom geometry)

RETURNS text
AS $$
from geopy import Nominatim
shape = Geometry(geom).shapely
centroid = shape.centroid
lon = centroid.x
lat = centroid.y
nominatim = Nominatim()
location = nominatim.reverse((lat, lon))
return location.address
db=# SELECT name, geocode(geom) FROM countries LIMIT 5;

name | geocode
-------------------------+-----------------------------------------------------------
Angola | Ringoma, Bié, Angola
Anguilla | Eric Reid Road, The Valley, Anguilla
Albania | Bradashesh, Elbasan, Qarku i Elbasanit, 3001, Shqipëria
American Samoa | Aunu u, Sa'Ole County, Eastern District, American Samoa
Andorra | Bordes de Rigoder, les Bons, Encamp, AD200, Andorra
(5 rows)
5.3 Rendering output
The gj2ascii project allows geometries to be easily rendered with a PL/Python function.
CREATE FUNCTION show(geom geometry)

RETURNS text
AS $$
from gj2ascii import render
g = Geometry(geom)
return render(g)
$$ LANGUAGE plpythonu
db=# SELECT show(geom) FROM countries WHERE name = 'Malta';

show
-------------------------------------------------------------
+ + + + + +
+ + + + + + + + + +
+ + + + + + + + + + + +
+ + + + + + + + + + +
+ + + + + +
+
+ +
+ + +
+ + + + + + + +
20 Chapter 5. Examples
+ + + + + + + + + +
+ + + + + + + + + + + +
+ + + + + + + + + + + + + +
+ + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + ++
+ + + + + + + + + + + + + + ++
+ + + + + + + + + + + + + ++
+ + + + + + + + + + +
+ + + + +
(1 row)
5.4 Spatial aggregate function
Normally, the function show as defined above would print the geometries of individual rows, one each per line.
db=# SELECT show(geom) FROM countries WHERE continent = 'Africa';
An aggregate version of show would take all the geometries and print them as a single map.
db=# SELECT showall(geom) FROM countries WHERE continent = 'Africa';

showall
-------------------------------------------------------------
1 1 1 Q +
= = 1 1 1 1 Q +
= = = 1 1 1 1 1 ; ; ; ; ; - - - +
= = 1 1 1 1 1 1 1 ; ; ; ; ; ; - - - +
= @ @ 1 1 1 1 1 1 1 ; ; ; ; ; ; - - - +
G @ @ > > 1 1 1 1 1 C ; ; ; ; ; - - - - +
@ @ @ @ @ > > 1 1 1 C C C O O ; ; H H H H +
@ @ @ @ > > > > C C C C O O O H H H H H H +
F F @ @ @ > > > C C C C O O O O H H H H H . +
F F > > > $ $ C C D C D ( O O H H H H H H 2 2 . +
0 0 0 > $ 4 # D D D D ( O O & H H H I 2 2 2 2 K L+
J 0 ' ' 4 P D D D D ( O & & & I I I 2 2 2 2 2 2 +
: ' ' 4 D ( ( ( & & & & & I I I 2 2 2 2 L +
( ( * ) ) ) ) ) S 8 8 8 L L +
M 3 * * ) ) ) ) ) S 8 8 8 L +
3 * ) ) ) ) ) E R R 8 8 +
) ) ) ) ) ) R R R R +
! ! ) ) ) ) ) R R R +
! ! ! ! ) ) U U R R +
! ! ! ! U U ) U ? ? ? +
! ! ! U U U U ? A ? ? 9 9+
B B B ! ! B U V V ? 9 9 +
B B B % % % V V 9 9 +
B B % % % T ? ? 9 9 +
B B % % T T ? 9 +
B B T T T T T +
T T T T T +
T T T T +
+
+
5.4. Spatial aggregate function 21

(1 row)
The aggregate function is defined with the following properties:
CREATE AGGREGATE showall(geometry) (

STYPE=geometry[],
INITCOND='{}',
SFUNC=array_append,
FINALFUNC=_final_geom_show
);
The STYPE of geometry[] indicates that after each individual geometry has been processed, there will be a
PostgreSQL list of individual geometry objects as a result. INITCOND is used to ensure that list starts empty and
can be added to incrementally by the native PostgreSQL function array_append.
The function _final_geom_show will take the STYPE as the single parameter:
CREATE OR REPLACE FUNCTION _final_geom_show(geoms geometry[])

RETURNS text
AS $$
from gj2ascii import render_multiple
from itertools import cycle
# assign an ascii character sequentially to each geometry
chars = [chr(i) for i in range(33,126)]
geojsons = [Geometry(g) for g in geoms]
layers = zip(geojsons, chars)
return render_multiple(layers, width)
$$ LANGUAGE plpythonu
PL/Python automatically maps lists to Python arrays, so plpygis is only responsible for converting each elment of
the list (in the example, above this is done using list comprehension: [Geometry(g) for g in geoms]).
22 Chapter 5. Examples
CHAPTER 6
plpygis package
class plpygis.geometry.Geometry
Bases: object
A representation of a PostGIS geometry.
PostGIS geometries are either an OpenGIS Consortium Simple Features for SQL specification type or a PostGIS
extended type. The object’s canonical form is stored in WKB or EWKB format along with an SRID and flags
indicating whether the coordinates are 3DZ, 3DM or 4D.
Geometry objects can be created in a number of ways. In all cases, a subclass for the particular geometry type
will be instantiated.
From an (E)WKB:
>>> Geometry("0101000080000000000000000000000000000000000000000000000000")
<Point: 'geometry(PointZ)'>
The response above indicates an instance of the Point class has been created and that it represents a PostGIS
geometry(PointZ) type.
From a GeoJSON:
>>> Geometry.from_geojson({'type': 'Point', 'coordinates': (0.0, 0.0)})

<Point: 'geometry(Point,4326)'>
From a Shapely object:
>>> from shapely.geometry import Point

>>> Geometry.from_shapely(Point((0, 0)), 3857)
<Point: 'geometry(Point,3857)'>
From any object supporting __geo_interface__:
>>> from shapefile import Reader

>>> feature = Reader("lines.shp").shape(0)
23
>>> Geometry.shape(feature)
<LineString: 'geometry(LineString)'>
A Geometry can be read as long as it is one of the following types: Point, LineString, Polygon,
MultiPoint, MultiLineString, MultiPolygon or GeometryCollection. The M dimension will
be preserved.
static from_geojson(geojson, srid=4326)
Create a Geometry from a GeoJSON. The SRID can be overridden from the expected 4326.
static from_shapely(sgeom, srid=None)
Create a Geometry from a Shapely geometry and the specified SRID.
The Shapely geometry will not be modified.
static shape(shape, srid=None)
Create a Geometry using __geo_interface__ and the specified SRID.
type
The geometry type.
srid
The geometry SRID.
geojson
Get the geometry as a GeoJSON dict. There is no check that the GeoJSON is using an SRID of 4326.
wkb
Get the geometry as an (E)WKB.
shapely
Get the geometry as a Shapely geometry. If the geometry has an SRID, the Shapely object will be created
with it set.
bounds
Get the minimum and maximum extents of the geometry: (minx, miny, maxx, maxy).
postgis_type
Get the type of the geometry in PostGIS format, including additional dimensions and SRID if they exist.
class plpygis.geometry.Point(coordinates=None, srid=None, dimz=False, dimm=False)
Bases: plpygis.geometry.Geometry
A representation of a PostGIS Point.
Point objects can be created directly.
>>> Point((0, -52, 5), dimm=True, srid=4326)

<Point: 'geometry(PointM,4326)'>
The dimz and dimm parameters will indicate how to interpret the coordinates that have been passed as the first
argument. By default, the third coordinate will be interpreted as representing the Z dimension.
x
X coordinate.
y
M coordinate.
z
Z coordinate.
24 Chapter 6. plpygis package

m
M coordinate.
dimz
Whether the geometry has a Z dimension.
Getter True if the geometry has a Z dimension.
Setter Add or remove the Z dimension.
Return type bool
dimm
Whether the geometry has an M dimension.
Getter True if the geometry has an M dimension.
Setter Add or remove the M dimension.
Return type bool
bounds
from_geojson(geojson, srid=4326)
from_shapely(sgeom, srid=None)
geojson
postgis_type
shape(shape, srid=None)
shapely
with it set.
srid
The geometry SRID.
type
The geometry type.
wkb
class plpygis.geometry.LineString(vertices=None, srid=None, dimz=False, dimm=False)
A representation of a PostGIS Line.
LineString objects can be created directly.
>>> LineString([(0, 0, 0, 0), (1, 1, 0, 0), (2, 2, 0, 0)])

<LineString: 'geometry(LineStringZM)'>
25
vertices
List of vertices that comprise the line.
dimz
Setter Add or remove the Z dimension from this and all vertices in the line.
Return type bool
dimm
Whether the geometry has a M dimension.
Getter True if the geometry has a M dimension.
Setter Add or remove the M dimension from this and all vertices in the line.
Return type bool
bounds
geojson
postgis_type
shapely
with it set.
srid
The geometry SRID.
type
The geometry type.
wkb
class plpygis.geometry.Polygon(rings=None, srid=None, dimz=False, dimm=False)
A representation of a PostGIS Polygon.
Polygon objects can be created directly.

>>> Polygon([[(0, 0, 0), (1, 0, 0), (1, 1, 0), (0, 1, 0), (0, 0, 0)]])
<Polygon: 'geometry(PolygonZ)'>
The first polygon in the list of linear rings is the exterior ring, while any subsequent rings are interior boundaries.
rings
List of linearrings that comprise the polygon.
exterior
The exterior ring of the polygon.
interior
A list of interior rings of the polygon.
dimz
Setter Add or remove the Z dimension from this and all linear rings in the polygon.
Return type bool
dimm
Whether the geometry has a M dimension.
Getter True if the geometry has a M dimension.
Setter Add or remove the M dimension from this and all linear rings in the polygon.
Return type bool
bounds
geojson
postgis_type
shapely
with it set.
srid
The geometry SRID.
type
The geometry type.
27
wkb
class plpygis.geometry.MultiPoint(points=None, srid=None)
Bases: plpygis.geometry._MultiGeometry
A representation of a PostGIS MultiPoint.
MultiPoint objects can be created directly from a list of Point objects.
>>> p1 = Point((0, 0, 0))

>>> p2 = Point((1, 1, 0))
>>> MultiPoint([p1, p2])
<MultiPoint: 'geometry(MultiPointZ)'>
The dimensionality of all geometries in the collection must be identical.

bounds
dimm
Setter Add or remove the M dimension from this and all geometries in the collection.
Return type bool
dimz
Setter Add or remove the Z dimension from this and all geometries in the collection.
Return type bool
geojson
postgis_type
shapely
with it set.
srid
The geometry SRID.
type
The geometry type.

wkb
points
List of all component points.
geometries
List of all component points.
class plpygis.geometry.MultiLineString(linestrings=None, srid=None)
A representation of a PostGIS MultiLineString
MultiLineString objects can be created directly from a list of LineString objects.
>>> l1 = LineString([(1, 1, 0), (2, 2, 0)], dimm=True)

>>> l2 = LineString([(0, 0, 0), (0, 1, 0)], dimm=True)
>>> MultiLineString([l1, l2])
<MultiLineString: 'geometry(MultiLineStringM)'>

bounds
dimm
Return type bool
dimz
Return type bool
geojson
postgis_type
shapely
with it set.
29
srid
The geometry SRID.
type
The geometry type.
wkb
linestrings
List of all component lines.
geometries
List of all component lines.
class plpygis.geometry.MultiPolygon(polygons=None, srid=None, dimz=False, dimm=False)
A representation of a PostGIS MultiPolygon.
MultiPolygon objects can be created directly from a list of Polygon objects.
>>> p1 = Polygon([[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]], srid=4326)
>>> p2 = Polygon([[(2, 2), (3, 2), (3, 3), (2, 3), (2, 2)]], srid=4326)
>>> MultiPolygon([p1, p2])
<MultiPolygon: 'geometry(MultiPolygon,4326)'>

bounds
dimm
Return type bool
dimz
Return type bool
geojson
postgis_type

shapely
with it set.
srid
The geometry SRID.
type
The geometry type.
wkb
polygons
List of all component polygons.
geometries
List of all component polygons.
class plpygis.geometry.GeometryCollection(geometries=None, srid=None, dimz=False,
dimm=False)
A representation of a PostGIS GeometryCollection.
GeometryCollection objects can be created directly from a list of geometries, including other collections.
>>> p = Point((0, 0, 0))

>>> l = LineString([(1, 1, 0), (2, 2, 0)])
>>> GeometryCollection([p, l])
<GeometryCollection: 'geometry(GeometryCollectionZ)'>

bounds
dimm
Return type bool
dimz
Return type bool
31
geojson
postgis_type
shapely
with it set.
srid
The geometry SRID.
type
The geometry type.
wkb
geometries
List of all component geometries.
exception plpygis.exceptions.PlpygisError(msg)
Bases: exceptions.Exception
Basic exception for plpygis.
exception plpygis.exceptions.DependencyError(dep, msg=None)
Bases: plpygis.exceptions.PlpygisError, exceptions.ImportError
Exception for a missing dependency.
exception plpygis.exceptions.WkbError(msg=None)
Bases: plpygis.exceptions.PlpygisError
Exception for problems in parsing WKBs.
exception plpygis.exceptions.DimensionalityError(msg=None)
Exception for problems in dimensionality of geometries.
exception plpygis.exceptions.SridError(msg=None)
Exception for problems in dimensionality of geometries.

Python Module Index
p
plpygis.exceptions, 32
plpygis.geometry, 23
33
34 Python Module Index

Index
B from_geojson() (plpygis.geometry.LineString method),

bounds (plpygis.geometry.Geometry attribute), 24 26
bounds (plpygis.geometry.GeometryCollection attribute), from_geojson() (plpygis.geometry.MultiLineString
31 method), 29
bounds (plpygis.geometry.LineString attribute), 26 from_geojson() (plpygis.geometry.MultiPoint method),
bounds (plpygis.geometry.MultiLineString attribute), 29 28
bounds (plpygis.geometry.MultiPoint attribute), 28 from_geojson() (plpygis.geometry.MultiPolygon
bounds (plpygis.geometry.MultiPolygon attribute), 30 method), 30
bounds (plpygis.geometry.Point attribute), 25 from_geojson() (plpygis.geometry.Point method), 25
bounds (plpygis.geometry.Polygon attribute), 27 from_geojson() (plpygis.geometry.Polygon method), 27
from_shapely() (plpygis.geometry.Geometry static
D method), 24
from_shapely() (plpygis.geometry.GeometryCollection
DependencyError, 32
method), 31
DimensionalityError, 32
from_shapely() (plpygis.geometry.LineString method),
dimm (plpygis.geometry.GeometryCollection attribute),
26
31
from_shapely() (plpygis.geometry.MultiLineString
dimm (plpygis.geometry.LineString attribute), 26
method), 29
dimm (plpygis.geometry.MultiLineString attribute), 29
from_shapely() (plpygis.geometry.MultiPoint method),
dimm (plpygis.geometry.MultiPoint attribute), 28
28
dimm (plpygis.geometry.MultiPolygon attribute), 30
from_shapely() (plpygis.geometry.MultiPolygon
dimm (plpygis.geometry.Point attribute), 25
method), 30
dimm (plpygis.geometry.Polygon attribute), 27
from_shapely() (plpygis.geometry.Point method), 25
dimz (plpygis.geometry.GeometryCollection attribute),
from_shapely() (plpygis.geometry.Polygon method), 27
31
dimz (plpygis.geometry.LineString attribute), 26 G
dimz (plpygis.geometry.MultiLineString attribute), 29
dimz (plpygis.geometry.MultiPoint attribute), 28 geojson (plpygis.geometry.Geometry attribute), 24
dimz (plpygis.geometry.MultiPolygon attribute), 30 geojson (plpygis.geometry.GeometryCollection at-
dimz (plpygis.geometry.Point attribute), 25 tribute), 31
dimz (plpygis.geometry.Polygon attribute), 27 geojson (plpygis.geometry.LineString attribute), 26
geojson (plpygis.geometry.MultiLineString attribute), 29
E geojson (plpygis.geometry.MultiPoint attribute), 28
geojson (plpygis.geometry.MultiPolygon attribute), 30
exterior (plpygis.geometry.Polygon attribute), 27
geojson (plpygis.geometry.Point attribute), 25
geojson (plpygis.geometry.Polygon attribute), 27
F geometries (plpygis.geometry.GeometryCollection
from_geojson() (plpygis.geometry.Geometry static attribute), 32
method), 24 geometries (plpygis.geometry.MultiLineString attribute),
from_geojson() (plpygis.geometry.GeometryCollection 30
method), 31 geometries (plpygis.geometry.MultiPoint attribute), 29
35
geometries (plpygis.geometry.MultiPolygon attribute), 31 shapely (plpygis.geometry.GeometryCollection attribute),

Geometry (class in plpygis.geometry), 23 32
GeometryCollection (class in plpygis.geometry), 31 shapely (plpygis.geometry.LineString attribute), 26
shapely (plpygis.geometry.MultiLineString attribute), 29
I shapely (plpygis.geometry.MultiPoint attribute), 28
interior (plpygis.geometry.Polygon attribute), 27 shapely (plpygis.geometry.MultiPolygon attribute), 31
shapely (plpygis.geometry.Point attribute), 25
L shapely (plpygis.geometry.Polygon attribute), 27
LineString (class in plpygis.geometry), 25 srid (plpygis.geometry.Geometry attribute), 24
linestrings (plpygis.geometry.MultiLineString attribute), srid (plpygis.geometry.GeometryCollection attribute), 32
30 srid (plpygis.geometry.LineString attribute), 26
srid (plpygis.geometry.MultiLineString attribute), 29
M srid (plpygis.geometry.MultiPoint attribute), 28
srid (plpygis.geometry.MultiPolygon attribute), 31
m (plpygis.geometry.Point attribute), 24
srid (plpygis.geometry.Point attribute), 25
MultiLineString (class in plpygis.geometry), 29
srid (plpygis.geometry.Polygon attribute), 27
MultiPoint (class in plpygis.geometry), 28
SridError, 32
MultiPolygon (class in plpygis.geometry), 30
P T
type (plpygis.geometry.Geometry attribute), 24
plpygis.exceptions (module), 32
type (plpygis.geometry.GeometryCollection attribute), 32
plpygis.geometry (module), 23
type (plpygis.geometry.LineString attribute), 26
PlpygisError, 32
type (plpygis.geometry.MultiLineString attribute), 30
Point (class in plpygis.geometry), 24
type (plpygis.geometry.MultiPoint attribute), 28
points (plpygis.geometry.MultiPoint attribute), 29
type (plpygis.geometry.MultiPolygon attribute), 31
Polygon (class in plpygis.geometry), 26
type (plpygis.geometry.Point attribute), 25
polygons (plpygis.geometry.MultiPolygon attribute), 31
type (plpygis.geometry.Polygon attribute), 27
postgis_type (plpygis.geometry.Geometry attribute), 24
postgis_type (plpygis.geometry.GeometryCollection at- V
tribute), 32
postgis_type (plpygis.geometry.LineString attribute), 26 vertices (plpygis.geometry.LineString attribute), 26
postgis_type (plpygis.geometry.MultiLineString at-
tribute), 29
W
postgis_type (plpygis.geometry.MultiPoint attribute), 28 wkb (plpygis.geometry.Geometry attribute), 24
postgis_type (plpygis.geometry.MultiPolygon attribute), wkb (plpygis.geometry.GeometryCollection attribute), 32
30 wkb (plpygis.geometry.LineString attribute), 26
postgis_type (plpygis.geometry.Point attribute), 25 wkb (plpygis.geometry.MultiLineString attribute), 30
postgis_type (plpygis.geometry.Polygon attribute), 27 wkb (plpygis.geometry.MultiPoint attribute), 28
wkb (plpygis.geometry.MultiPolygon attribute), 31
R wkb (plpygis.geometry.Point attribute), 25
rings (plpygis.geometry.Polygon attribute), 27 wkb (plpygis.geometry.Polygon attribute), 27
WkbError, 32
S X
shape() (plpygis.geometry.Geometry static method), 24
x (plpygis.geometry.Point attribute), 24
shape() (plpygis.geometry.GeometryCollection method),
32
shape() (plpygis.geometry.LineString method), 26
Y
shape() (plpygis.geometry.MultiLineString method), 29 y (plpygis.geometry.Point attribute), 24
shape() (plpygis.geometry.MultiPoint method), 28
shape() (plpygis.geometry.MultiPolygon method), 30 Z
shape() (plpygis.geometry.Point method), 25 z (plpygis.geometry.Point attribute), 24
shape() (plpygis.geometry.Polygon method), 27
shapely (plpygis.geometry.Geometry attribute), 24
36 Index

Plpygis PDF

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Plpygis PDF

Uploaded by

Copyright:

Available Formats

plpygis Documentation

Feb 14, 2018

Python Module Index 33

1.2 Python Package Index

plpygis may be installed from PyPI.

$ pip install plpygis

$ python setup.py install

Tests require nose:

$ python setup.py test

$ python setup.py build_sphinx

>>> from plpygis import Geometry

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

>>> from plpygis import Geometry

2.1.2 Geometry types

>>> from plpygis import Geometry

Geometry also implements __geo_interface__.

6 Chapter 2. Basic usage

• DependencyError: missing dependency required for an optional feature, such as shapely

8 Chapter 2. Basic usage

>>> point = Point((0, 0))

Coordinates may be accessed and modified after creation.

>>> point = Point((0, 0))

>>> p1 = Point((0, 0))

An SRID may be added at creation time with an optional SRID parameter:

>>> point = Point((0, 0), srid=4326)

>>> p1 = Point((0, 0, 1), dimz=True, dimm=True)

10 Chapter 3. Geometry subclasses

>>> print "p2", p2.x, p2.y, p2.z, p2.m

>>> p1 = Point((0, 0))

3.6 Performance considerations

3.6.1 Lazy evaluation

3.6. Performance considerations 11

As a summary, getting the following properties will not affect performance:

12 Chapter 3. Geometry subclasses

The PostgreSQL documentation has a complete reference on authoring PL/Python functions.

4.1 Enabling PL/Python

Prior to using PL/Python, it must be loaded in the current database:

# CREATE LANGUAGE plpythonu;

4.1.1 Python 2 and Python 3

4.2 Function declarations

PL/Python function declarations follow the following template:

CREATE FUNCTION funcname (argument-list)

CREATE OR REPLACE FUNCTION make_point(x FLOAT, y FLOAT)

Warning: Variables passed as arguments should never be assigned to in a PL/Python function.

4.3 Type mappings

4.3.1 PostGIS types

CREATE OR REPLACE FUNCTION make_point(x FLOAT, y FLOAT)

CREATE OR REPLACE FUNCTION find_hemisphere(geom geometry)

db=# SELECT name, find_hemisphere(ST_Centroid(geom)) FROM countries LIMIT 10;

A Geometry can be returned directly from a PL/Python function.

CREATE OR REPLACE FUNCTION make_point(x FLOAT, y FLOAT)

db=# SELECT make_point(-52, 0);

This custom make_point(x, y) functions identically to PostGIS’s native ST_MakePoint(x, y).

db=# SELECT ST_MakePoint(-52, 0);

4.3.2 geometry and geography

4.3. Type mappings 15

db=# SELECT ST_Area(box_geom());

db=# SELECT ST_Area(box_geog());

4.4 Arrays and sets

db=# CREATE OR REPLACE FUNCTION make_points(x FLOAT, y FLOAT)

db=# SELECT ST_AsText(make_points(10,20));

4.5 Shared data