papyrus 0.5

With GeoInterface

Papyrus provides a mixin to help create SQLAlchemy/GeoAlchemy mapped classes that implement the Python Geo Interface, and define __init__ and __update__ as expected by the MapFish protocol. The mixin is named GeoInterface, and is provided by the papyrus.geo_interface module.

Using GeoInterface our Spot class looks like this:

from papyrus.geo_interface import GeoInterface

class Spot(GeoInterface, Base):
    __tablename__ = 'spots'
    id = Column(Integer, primary_key=True)
    name = Column(Unicode, nullable=False)
    geom = GeometryColumn('the_geom', Point(srid=4326))

GeoInterface represents a convenience method. Often, implementing one’s own __geo_interface__, __init__, and __update__ definitions is a better choice than relying on GeoInterface.

When using GeoInterface understanding its code can be useful. It can also be a source of inspiration for those who don’t use it.

Without GeoInterface

Without using GeoInterface our Spot class could look like this:

class Spot(Base):
    __tablename__ = 'spots'
    id = Column(Integer, primary_key=True)
    name = Column(Unicode, nullable=False)
    geom = GeometryColumn('the_geom', Point(srid=4326))

    def __init__(self, feature):
        self.id = feature.id
        self.__update__(feature)

    def __update__(self, feature):
        geometry = feature.geometry
        if geometry is not None and \
           not isinstance(geometry, geojson.geometry.Default):
            shape = asShape(geometry)
            self.geom = WKBSpatialElement(buffer(shape.wkb), srid=4326)
            self._shape = shape
        self.name = feature.properties.get('name', None)

    @property
    def __geo_interface__(self):
        id = self.id
        if hasattr(self, '_shape') and self._shape is not None:
            geometry = self_shape
        else:
            geometry = loads(str(self.geom.geom_wkb))
        properties = dict(name=self.name)
        return geojson.Feature(id=id, geometry=geometry, properties=properties)

Notes:

• the pyramid_routesalchemy template, provided by Pyramid, places SQLAlchemy models in a models.py file located at the root of the application’s main module (myapp.models).

• the akhet template, provided by the Akhet package, places SQLAlchemy models in the __init__.py file of the models module.

With view callables

Using view functions here’s how our web service implementation would look like:

from myproject.models import Session, Spot
from papyrus.protocol import Protocol

# 'geom' is the name of the mapped class' geometry property
proto = Protocol(Session, Spot, 'geom')

@view_config(route_name='spots_read_many', renderer='geojson')
def read_many(request):
    return proto.read(request)

@view_config(route_name='spots_read_one', renderer='geojson')
def read_one(request):
    id = request.matchdict.get('id', None)
    return proto.read(request, id=id)

@view_config(route_name='spots_count', renderer='string')
def count(request):
    return proto.count(request)

@view_config(route_name='spots_create', renderer='geojson')
def create(request):
    return proto.create(request)

@view_config(route_name='spots_update', renderer='geojson')
def update(request):
    id = request.matchdict['id']
    return proto.update(request, id)

@view_config(route_name='spots_delete')
def delete(request):
    id = request.matchdict['id']
    return proto.delete(request, id)

These six view functions, typically defined in views.py, entirely define our MapFish web service.

We now need to provide routes to these actions. This is done by calling add_papyrus_routes() on the Configurator (in __init__.py):

import papyrus
from papyrus.renderers import GeoJSON
config.include(papyrus.includeme)
config.add_renderer('geojson', GeoJSON())
config.add_papyrus_routes('spots', '/spots')
config.scan()

add_papyrus_routes is a convenience method, here’s what it basically does:

config.add_route('spots_read_many', '/spots', request_method='GET')
config.add_route('spots_read_one', '/spots/{id}', request_method='GET')
config.add_route('spots_count', '/spots/count', request_method='GET')
config.add_route('spots_create', '/spots', request_method='POST')
config.add_route('spots_update', '/spots/{id}', request_method='PUT')
config.add_route('spots_delete', '/spots/{id}', request_method='DELETE')

With a handler

Using a handler here’s what our web service implementation would look like:

from pyramid_handlers import action

from myproject.models import Session, Spot
from papyrus.protocol import Protocol

# create the protocol object. 'geom' is the name
# of the geometry attribute in the Spot model class
proto = Protocol(Session, Spot, 'geom')

class SpotHandler(object):
    def __init__(self, request):
        self.request = request

    @action(renderer='geojson')
    def read_many(self):
        return proto.read(self.request)

    @action(renderer='geojson')
    def read_one(self):
        id = self.request.matchdict.get('id', None)
        return proto.read(self.request, id=id)

    @action(renderer='string')
    def count(self):
        return proto.count(self.request)

    @action(renderer='geojson')
    def create(self):
        return proto.create(self.request)

    @action(renderer='geojson')
    def update(self):
        id = self.request.matchdict['id']
        return proto.update(self.request, id)

    @action()
    def delete(self):
        id = self.request.matchdict['id']
        return proto.delete(self.request, id)

The six actions of the SpotHandler class entirely define our MapFish web service.

We now need to provide routes to these actions. This is done by calling add_papyrus_handler() on the Configurator:

import papyrus
from papyrus.renderers import GeoJSON
config.include(papyrus)
config.add_renderer('geojson', GeoJSON())
config.add_papyrus_handler('spots', '/spots',
                           'myproject.handlers:SpotHandler')

Likewise add_papyrus_routes add_papyrus_handler is a convenience method. Here’s what it basically does:

config.add_handler('spots_read_many', '/spots',
                   'myproject.handlers:SpotHandler',
                   action='read_many', request_method='GET')
config.add_handler('spots_read_one', '/spots/{id}',
                   'myproject.handlers:SpotHandler',
                   action='read_one', request_method='GET')
config.add_handler('spots_count', '/spots/count',
                   'myproject.handlers:SpotHandler',
                   action='count', request_method='GET')
config.add_handler('spots_create', '/spots',
                   'myproject.handlers:SpotHandler',
                   action='create', request_method='POST')
config.add_handler('spots_update', '/spots/{id}',
                   'myproject.handlers:SpotHandler',
                   action='update', request_method='PUT')
config.add_handler('spots_delete', '/spots/{id}',
                   'myproject.handlers:SpotHandler',
                   action='delete', request_method='DELETE')

Note: when using handlers the pyramid_handlers package must be set as an application’s dependency.