Version 1 (modified by spascoe, 14 years ago) (diff)


NOTE: This document is work in progress and, in it's present form, is best understood in conjuction with the source.

A note about Pylons terminology

In Pylons

  • controllers are classes inherited from pylons.controllers.WSGIController that reside in the controllers package of your application. Requests are routed to particular controllers via the Routes configuration.
  • actions are methods of a controller. They are also selected using Routes.

OGC Web Services

Support for implementing OGC Web Services using Pylons is provided via:

  1. The ows_common package.
  2. The OwsController class
  3. The OWS Controller protocol defining standard attributes on Pylons controllers and actions
  4. Decorators on controller actions

The ows_common package

The ows_common package provides a library of objects modelling the OWS Common specification v1.1.0. Metadata required for a OWS should be represented using ows_common where ever possible to maximise code reuse. For instance, templates are provided to render ows_common objects into OWS 1.1.0 or WMS 1.3.0 compliant GetCapabilities? documents (ows_server.templates.ows.get_capabilities and ows_server.templates.ows.wms_capabilities. Implementations of other services can reuse parts of the core template.

Also ows_common.exceptions provides a set of exception classes that are caught by the framework and rendered as a standard OWS exception response.

The OwsController class

All OWS implementations should be implemented as a Pylons controller inheriting from ows_server.base.OwsController. The method OwsController._renderCapabilities() returns a response object containing a standard OWS common 1.1.0 Capabilities document. Populating this document with service-specific metadata can be done by overriding the {{{OwsController?._loadCapabilities() method.

OWS operations are created by defining a OwsController method of the same name wrapped in the @operation decorator. See below about decorators.


The ows_server.lib.decorators module provides a set of decorators for setting attributes of the OWS controller protocol. These are added to the beginning of operation definitions e.g.:

class WmsController(OwsController):

    # ...

    @parameter('Format', possibleValues=['text/xml'])
    @parameter('Service', possibleValues=['WMS'], required=True)
    @parameter('Version', possibleValues=['1.3.0'])
    def GetCapabilities(self, file, service=None, version=None):
        # ...
Should be the top-most decorator. It wraps the method in a function that performs request handling and type checking on the operation's arguments.
Add one of these for each operation parameter. This instructs the framework to perform several tasks.
  1. Add the parameter (from request.params) to the list of arguments send to the operation method.
  2. Populate ows_common objects to describe this parameter in the GetCapabilities? document.
  3. Do type-checking on the parameter's value during invocation. The possibleValues argument allows you to define a set of possible values, the require argument can declare an argument required and the validator argument allows you to provide a validation function.
OWS common 1.3.0 allows you to define constraints on operations. This decorator will populate the necessary ows_common objects for describing the constraint in the GetCapabilities? document.

The OWS controller Protocol

The OwsController class and decorators rely on as series of standard attributes being attached to the OwsController subclass implementing a OWS. All attribute names begin with _ows_

Defined in a method. The CamelCased? name of the operation. This is automatically set with the @operation decorator.
Definied in a controller or method. A dictionary mapping parameter names to ows_common.domain.Domain objects. Parameters are used to define operation arguments and operation-level parameters such as request format. As well as populating the Capabilities document, type checking is done on the request parameter based on the parameter's domain. See Decorators for details.
The same as _ows_parameters except for constraints. Constraints are defined in OWS Common 1.1.0. An example of use would be the MaximumLayerLevels? element in WMS 1.3.0.
Definied in a controller. Used to describe what version(s) of the OWS a controller supports.
Defined in a method. Describes which keys of _ows_parameters are required. The framework will automatically raise an OWS exception if a request doesn't contain this parameter.
Defined in a method. Provides a mechanism for adding custom type checking to an operation parameter. See Decorators.