Module usage

PPyGIS registers itself as an adapter for PostGIS types with Psycopg when loaded. It then allows PostGIS geometry types to be read and written as Python objects.

Installation

The easiest way to install PPyGIS is using pip:

$ pip install PPyGIS

Alternatively, you can download the package, extract it and run the following command from the package directory:

$ python setup.py install

Basic usage

An example interactive session illustrates the basic usage of the module:

>>> import psycopg2
>>> import ppygis

# Connect to an existing spatially enabled database
>>> connection = psycopg2.connect(database = 'test', user = 'test')
>>> cursor = connection.cursor()

# Create a table with a geometry column
>>> cursor.execute('CREATE TABLE test(geometry GEOMETRY)')

# Insert a point into the table
>>> cursor.execute('INSERT INTO test VALUES(%s)', (ppygis.Point(1.0, 2.0), ))

# Retrieve the point from the table and print it
>>> cursor.execute('SELECT * FROM test')
>>> point = cursor.fetchone()[0]
>>> print point
Point(X: 1.0, Y: 2.0)

# Modify the point and print it
>>> point.z = 3.0
>>> point.srid = 1234
>>> print point
Point(X: 1.0, Y: 2.0, Z: 3.0, SRID: 1234)

# Create a line and insert it into the table
>>> geometry = ppygis.LineString((point, ppygis.Point(4.0, 5.0, 6.0)))
>>> cursor.execute('INSERT INTO test VALUES(%s)', (geometry, ))

# Retrieve the table contents and print it
>>> cursor.execute('SELECT * FROM test')
>>> for row in cursor
>>>   print cursor
...
Point(X: 1.0, Y: 2.0)
LineString(Point(X: 1.0, Y: 2.0, Z: 3.0), Point(X: 4.0, Y: 5.0, Z: 6.0))

# Disconnect from the database
>>> cursor.close()
>>> connection.close()

COPY FROM/TO

The PostgreSQL COPY FROM and COPY TO commands allow for bulk uploads and downloads of data. PPyGIS may be used to transform geometry between EWKB representation and Python objects in these scenarios as well. An example interactive session demonstrates the usage:

>>> import StringIO
>>> import psycopg2
>>> import ppygis

# Connect to an existing spatially enabled database
>>> connection = psycopg2.connect(database = 'test', user = 'test')
>>> cursor = connection.cursor()

# Create a table with a geometry column
>>> cursor.execute('CREATE TABLE test(geometry GEOMETRY)')

# Prepare data for a bulk upload
>>> buffer = StringIO.StringIO()
>>> buffer.write(ppygis.Point(1.0, 2.0).write_ewkb() + '\n')
>>> buffer.write(ppygis.LineString((ppygis.Point(1.0, 2.0),
...     ppygis.Point(3.0, 4.0))).write_ewkb() + '\n')
>>> buffer.seek(0)

# Perform a bulk upload of data to the table
>>> cursor.copy_from(buffer, 'test')

# Retrieve the table contents and print it
>>> cursor.execute('SELECT * FROM test')
>>> for row in cursor:
>>>   print row[0]
...
Point(X: 1.0, Y: 2.0)
LineString(Point(X: 1.0, Y: 2.0), Point(X: 3.0, Y: 4.0))

# Perform a bulk download of data from the table
>>> buffer = StringIO.StringIO()
>>> cursor.copy_to(buffer, 'test')
>>> buffer.seek(0)

# Print the data
>>> for line in buffer:
>>>   print ppygis.Geometry.read_ewkb(line.strip())
...
Point(X: 1.0, Y: 2.0)
LineString(Point(X: 1.0, Y: 2.0), Point(X: 3.0, Y: 4.0))

# Disconnect from the database
>>> cursor.close()
>>> connection.close()

Caveats

PPyGIS is young and has several limitations:

• Only the geometry types Point, LineString, Polygon, GeometryCollection, MultiPoint, MultiLineString, MultiPolygon are supported.
• Error checking is rudimentary. This is partially by design as PostGIS checks the validity of EWKB representations and duplicate checks are unnecessary.
• Only EWKB representations are supported — the WKB, EWKT and WKT alternatives are not.