Using Hooks

“Hooks” can be used to influence the behavior of the Pyramid framework in various ways.

Changing the Not Found View

When Pyramid can’t map a URL to view code, it invokes a not found view, which is a view callable. A default notfound view exists. The default not found view can be overridden through application configuration.

If your application uses imperative configuration, you can replace the Not Found view by using the pyramid.config.Configurator.add_notfound_view() method:

1
2
from helloworld.views import notfound
config.add_notfound_view(notfound)

Replace helloworld.views.notfound with a reference to the view callable you want to use to represent the Not Found view. The not found view callable is a view callable like any other.

If your application instead uses pyramid.view.view_config decorators and a scan, you can replace the Not Found view by using the pyramid.view.notfound_view_config decorator:

1
2
3
4
5
6
7
8
9
from pyramid.view import notfound_view_config

@notfound_view_config()
def notfound(request):
    return Response('Not Found, dude', status='404 Not Found')

def main(globals, **settings):
   config = Configurator()
   config.scan()

This does exactly what the imperative example above showed.

Your application can define multiple not found views if necessary. Both pyramid.config.Configurator.add_notfound_view() and pyramid.view.notfound_view_config take most of the same arguments as pyramid.config.Configurator.add_view and pyramid.view.view_config, respectively. This means that not found views can carry predicates limiting their applicability. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from pyramid.view import notfound_view_config

@notfound_view_config(request_method='GET')
def notfound_get(request):
    return Response('Not Found during GET, dude', status='404 Not Found')

@notfound_view_config(request_method='POST')
def notfound_post(request):
    return Response('Not Found during POST, dude', status='404 Not Found')

def main(globals, **settings):
   config = Configurator()
   config.scan()

The notfound_get view will be called when a view could not be found and the request method was GET. The notfound_post view will be called when a view could not be found and the request method was POST.

Like any other view, the notfound view must accept at least a request parameter, or both context and request. The request is the current request representing the denied action. The context (if used in the call signature) will be the instance of the HTTPNotFound exception that caused the view to be called.

Both pyramid.config.Configurator.add_notfound_view() and pyramid.view.notfound_view_config can be used to automatically redirect requests to slash-appended routes. See Redirecting to Slash-Appended Routes for examples.

Here’s some sample code that implements a minimal NotFound view callable:

1
2
3
4
from pyramid.httpexceptions import HTTPNotFound

def notfound(request):
    return HTTPNotFound()

Note

When a NotFound view callable is invoked, it is passed a request. The exception attribute of the request will be an instance of the HTTPNotFound exception that caused the not found view to be called. The value of request.exception.message will be a value explaining why the not found error was raised. This message will be different when the pyramid.debug_notfound environment setting is true than it is when it is false.

Note

Both pyramid.config.Configurator.add_notfound_view() and pyramid.view.notfound_view_config are new as of Pyramid 1.3. Older Pyramid documentation instructed users to use add_view instead, with a context of HTTPNotFound. This still works; the convenience method and decorator are just wrappers around this functionality.

Warning

When a NotFound view callable accepts an argument list as described in Alternate View Callable Argument/Calling Conventions, the context passed as the first argument to the view callable will be the HTTPNotFound exception instance. If available, the resource context will still be available as request.context.

Changing the Forbidden View

When Pyramid can’t authorize execution of a view based on the authorization policy in use, it invokes a forbidden view. The default forbidden response has a 403 status code and is very plain, but the view which generates it can be overridden as necessary.

The forbidden view callable is a view callable like any other. The view configuration which causes it to be a “forbidden” view consists of using the pyramid.config.Configurator.add_forbidden_view() API or the pyramid.view.forbidden_view_config decorator.

For example, you can add a forbidden view by using the pyramid.config.Configurator.add_forbidden_view() method to register a forbidden view:

1
2
3
from helloworld.views import forbidden_view
from pyramid.httpexceptions import HTTPForbidden
config.add_forbidden_view(forbidden_view)

Replace helloworld.views.forbidden_view with a reference to the Python view callable you want to use to represent the Forbidden view.

If instead you prefer to use decorators and a scan, you can use the pyramid.view.forbidden_view_config decorator to mark a view callable as a forbidden view:

1
2
3
4
5
6
7
8
9
from pyramid.view import forbidden_view_config

@forbidden_view_config()
def forbidden(request):
    return Response('forbidden')

def main(globals, **settings):
   config = Configurator()
   config.scan()

Like any other view, the forbidden view must accept at least a request parameter, or both context and request. If a forbidden view callable accepts both context and request, the HTTP Exception is passed as context. The context as found by the router when view was denied (that you normally would expect) is available as request.context. The request is the current request representing the denied action.

Here’s some sample code that implements a minimal forbidden view:

1
2
3
4
5
from pyramid.view import view_config
from pyramid.response import Response

def forbidden_view(request):
    return Response('forbidden')

Note

When a forbidden view callable is invoked, it is passed a request. The exception attribute of the request will be an instance of the HTTPForbidden exception that caused the forbidden view to be called. The value of request.exception.message will be a value explaining why the forbidden was raised and request.exception.result will be extended information about the forbidden exception. These messages will be different when the pyramid.debug_authorization environment setting is true than it is when it is false.

Changing the Request Factory

Whenever Pyramid handles a request from a WSGI server, it creates a request object based on the WSGI environment it has been passed. By default, an instance of the pyramid.request.Request class is created to represent the request object.

The class (aka “factory”) that Pyramid uses to create a request object instance can be changed by passing a request_factory argument to the constructor of the configurator. This argument can be either a callable or a dotted Python name representing a callable.

1
2
3
4
5
6
from pyramid.request import Request

class MyRequest(Request):
    pass

config = Configurator(request_factory=MyRequest)

If you’re doing imperative configuration, and you’d rather do it after you’ve already constructed a configurator it can also be registered via the pyramid.config.Configurator.set_request_factory() method:

1
2
3
4
5
6
7
8
from pyramid.config import Configurator
from pyramid.request import Request

class MyRequest(Request):
    pass

config = Configurator()
config.set_request_factory(MyRequest)

Using The Before Render Event

Subscribers to the pyramid.events.BeforeRender event may introspect and modify the set of renderer globals before they are passed to a renderer. This event object iself has a dictionary-like interface that can be used for this purpose. For example:

1
2
3
4
5
6
 from pyramid.events import subscriber
 from pyramid.events import BeforeRender

 @subscriber(BeforeRender)
 def add_global(event):
     event['mykey'] = 'foo'

An object of this type is sent as an event just before a renderer is invoked (but after the application-level renderer globals factory added via set_renderer_globals_factory, if any, has injected its own keys into the renderer globals dictionary).

If a subscriber attempts to add a key that already exist in the renderer globals dictionary, a KeyError is raised. This limitation is enforced because event subscribers do not possess any relative ordering. The set of keys added to the renderer globals dictionary by all pyramid.events.BeforeRender subscribers and renderer globals factories must be unique.

The dictionary returned from the view is accessible through the rendering_val attribute of a BeforeRender event.

Suppose you return {'mykey': 'somevalue', 'mykey2': 'somevalue2'} from your view callable, like so:

1
2
3
4
5
from pyramid.view import view_config

@view_config(renderer='some_renderer')
def myview(request):
    return {'mykey': 'somevalue', 'mykey2': 'somevalue2'}

rendering_val can be used to access these values from the BeforeRender object:

1
2
3
4
5
6
7
from pyramid.events import subscriber
from pyramid.events import BeforeRender

@subscriber(BeforeRender)
def read_return(event):
    # {'mykey': 'somevalue'} is returned from the view
    print(event.rendering_val['mykey'])

See the API documentation for the BeforeRender event interface at pyramid.interfaces.IBeforeRender.

Another (deprecated) mechanism which allows event subscribers more control when adding renderer global values exists in Adding Renderer Globals (Deprecated).

Adding Renderer Globals (Deprecated)

Warning

this feature is deprecated as of Pyramid 1.1. A non-deprecated mechanism which allows event subscribers to add renderer global values is documented in Using The Before Render Event.

Whenever Pyramid handles a request to perform a rendering (after a view with a renderer= configuration attribute is invoked, or when any of the methods beginning with render within the pyramid.renderers module are called), renderer globals can be injected into the system values sent to the renderer. By default, no renderer globals are injected, and the “bare” system values (such as request, context, view, and renderer_name) are the only values present in the system dictionary passed to every renderer.

A callback that Pyramid will call every time a renderer is invoked can be added by passing a renderer_globals_factory argument to the constructor of the configurator. This callback can either be a callable object or a dotted Python name representing such a callable.

1
2
3
4
5
def renderer_globals_factory(system):
    return {'a': 1}

config = Configurator(
         renderer_globals_factory=renderer_globals_factory)

Such a callback must accept a single positional argument (notionally named system) which will contain the original system values. It must return a dictionary of values that will be merged into the system dictionary. See System Values Used During Rendering for description of the values present in the system dictionary.

If you’re doing imperative configuration, and you’d rather do it after you’ve already constructed a configurator it can also be registered via the pyramid.config.Configurator.set_renderer_globals_factory() method:

1
2
3
4
5
6
7
from pyramid.config import Configurator

def renderer_globals_factory(system):
    return {'a': 1}

config = Configurator()
config.set_renderer_globals_factory(renderer_globals_factory)

Using Response Callbacks

Unlike many other web frameworks, Pyramid does not eagerly create a global response object. Adding a response callback allows an application to register an action to be performed against whatever response object is returned by a view, usually in order to mutate the response.

The pyramid.request.Request.add_response_callback() method is used to register a response callback.

A response callback is a callable which accepts two positional parameters: request and response. For example:

1
2
3
4
5
def cache_callback(request, response):
    """Set the cache_control max_age for the response"""
    if request.exception is not None:
        response.cache_control.max_age = 360
request.add_response_callback(cache_callback)

No response callback is called if an unhandled exception happens in application code, or if the response object returned by a view callable is invalid. Response callbacks are, however, invoked when a exception view is rendered successfully: in such a case, the request.exception attribute of the request when it enters a response callback will be an exception object instead of its default value of None.

Response callbacks are called in the order they’re added (first-to-most-recently-added). All response callbacks are called after the NewResponse event is sent. Errors raised by response callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

A response callback has a lifetime of a single request. If you want a response callback to happen as the result of every request, you must re-register the callback into every new request (perhaps within a subscriber of a NewRequest event).

Using Finished Callbacks

A finished callback is a function that will be called unconditionally by the Pyramid router at the very end of request processing. A finished callback can be used to perform an action at the end of a request unconditionally.

The pyramid.request.Request.add_finished_callback() method is used to register a finished callback.

A finished callback is a callable which accepts a single positional parameter: request. For example:

1
2
3
4
5
6
7
8
import logging

log = logging.getLogger(__name__)

def log_callback(request):
    """Log information at the end of request"""
    log.debug('Request is finished.')
request.add_finished_callback(log_callback)

Finished callbacks are called in the order they’re added (first-to-most-recently-added). Finished callbacks (unlike a response callback) are always called, even if an exception happens in application code that prevents a response from being generated.

The set of finished callbacks associated with a request are called very late in the processing of that request; they are essentially the very last thing called by the router before a request “ends”. They are called after response processing has already occurred in a top-level finally: block within the router request processing code. As a result, mutations performed to the request provided to a finished callback will have no meaningful effect, because response processing will have already occurred, and the request’s scope will expire almost immediately after all finished callbacks have been processed.

Errors raised by finished callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

A finished callback has a lifetime of a single request. If you want a finished callback to happen as the result of every request, you must re-register the callback into every new request (perhaps within a subscriber of a NewRequest event).

Changing the Traverser

The default traversal algorithm that Pyramid uses is explained in The Traversal Algorithm. Though it is rarely necessary, this default algorithm can be swapped out selectively for a different traversal pattern via configuration.

1
2
3
4
from pyramid.config import Configurator
from myapp.traversal import Traverser
config = Configurator()
config.add_traverser(Traverser)

In the example above, myapp.traversal.Traverser is assumed to be a class that implements the following interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
class Traverser(object):
    def __init__(self, root):
        """ Accept the root object returned from the root factory """

    def __call__(self, request):
        """ Return a dictionary with (at least) the keys ``root``,
        ``context``, ``view_name``, ``subpath``, ``traversed``,
        ``virtual_root``, and ``virtual_root_path``.  These values are
        typically the result of a resource tree traversal.  ``root``
        is the physical root object, ``context`` will be a resource
        object, ``view_name`` will be the view name used (a Unicode
        name), ``subpath`` will be a sequence of Unicode names that
        followed the view name but were not traversed, ``traversed``
        will be a sequence of Unicode names that were traversed
        (including the virtual root path, if any) ``virtual_root``
        will be a resource object representing the virtual root (or the
        physical root if traversal was not performed), and
        ``virtual_root_path`` will be a sequence representing the
        virtual root path (a sequence of Unicode names) or None if
        traversal was not performed.

        Extra keys for special purpose functionality can be added as
        necessary.

        All values returned in the dictionary will be made available
        as attributes of the ``request`` object.
        """

More than one traversal algorithm can be active at the same time. For instance, if your root factory returns more than one type of object conditionally, you could claim that an alternate traverser adapter is “for” only one particular class or interface. When the root factory returned an object that implemented that class or interface, a custom traverser would be used. Otherwise, the default traverser would be used. For example:

1
2
3
4
5
from myapp.traversal import Traverser
from myapp.resources import MyRoot
from pyramid.config import Configurator
config = Configurator()
config.add_traverser(Traverser, MyRoot)

If the above stanza was added to a Pyramid __init__.py file’s main function, Pyramid would use the myapp.traversal.Traverser only when the application root factory returned an instance of the myapp.resources.MyRoot object. Otherwise it would use the default Pyramid traverser to do traversal.

Changing How pyramid.request.Request.resource_url() Generates a URL

When you add a traverser as described in Changing the Traverser, it’s often convenient to continue to use the pyramid.request.Request.resource_url() API. However, since the way traversal is done will have been modified, the URLs it generates by default may be incorrect when used against resources derived from your custom traverser.

If you’ve added a traverser, you can change how resource_url() generates a URL for a specific type of resource by adding a call to pyramid.config.add_resource_url_adapter().

For example:

1
2
3
4
from myapp.traversal import ResourceURLAdapter
from myapp.resources import MyRoot

config.add_resource_url_adapter(ResourceURLAdapter, MyRoot)

In the above example, the myapp.traversal.ResourceURLAdapter class will be used to provide services to resource_url() any time the resource passed to resource_url is of the class myapp.resources.MyRoot. The resource_iface argument MyRoot represents the type of interface that must be possessed by the resource for this resource url factory to be found. If the resource_iface argument is omitted, this resource url adapter will be used for all resources.

The API that must be implemented by your a class that provides IResourceURL is as follows:

1
2
3
4
5
6
7
8
9
class MyResourceURL(object):
    """ An adapter which provides the virtual and physical paths of a
        resource
    """
    def __init__(self, resource, request):
        """ Accept the resource and request and set self.physical_path and
        self.virtual_path"""
        self.virtual_path =  some_function_of(resource, request)
        self.physical_path =  some_other_function_of(resource, request)

The default context URL generator is available for perusal as the class pyramid.traversal.ResourceURL in the traversal module of the Pylons GitHub Pyramid repository.

See pyramid.config.add_resource_url_adapter() for more information.

Changing How Pyramid Treats View Responses

It is possible to control how Pyramid treats the result of calling a view callable on a per-type basis by using a hook involving pyramid.config.Configurator.add_response_adapter() or the response_adapter decorator.

Note

This feature is new as of Pyramid 1.1.

Pyramid, in various places, adapts the result of calling a view callable to the IResponse interface to ensure that the object returned by the view callable is a “true” response object. The vast majority of time, the result of this adaptation is the result object itself, as view callables written by “civilians” who read the narrative documentation contained in this manual will always return something that implements the IResponse interface. Most typically, this will be an instance of the pyramid.response.Response class or a subclass. If a civilian returns a non-Response object from a view callable that isn’t configured to use a renderer, he will typically expect the router to raise an error. However, you can hook Pyramid in such a way that users can return arbitrary values from a view callable by providing an adapter which converts the arbitrary return value into something that implements IResponse.

For example, if you’d like to allow view callables to return bare string objects (without requiring a renderer to convert a string to a response object), you can register an adapter which converts the string to a Response:

1
2
3
4
5
6
7
8
9
from pyramid.response import Response

def string_response_adapter(s):
    response = Response(s)
    return response

# config is an instance of pyramid.config.Configurator

config.add_response_adapter(string_response_adapter, str)

Likewise, if you want to be able to return a simplified kind of response object from view callables, you can use the IResponse hook to register an adapter to the more complex IResponse interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from pyramid.response import Response

class SimpleResponse(object):
    def __init__(self, body):
        self.body = body

def simple_response_adapter(simple_response):
    response = Response(simple_response.body)
    return response

# config is an instance of pyramid.config.Configurator

config.add_response_adapter(simple_response_adapter, SimpleResponse)

If you want to implement your own Response object instead of using the pyramid.response.Response object in any capacity at all, you’ll have to make sure the object implements every attribute and method outlined in pyramid.interfaces.IResponse and you’ll have to ensure that it uses zope.interface.implementer(IResponse) as a class decoratoror.

1
2
3
4
5
6
7
from pyramid.interfaces import IResponse
from zope.interface import implementer

@implementer(IResponse)
class MyResponse(object):
    # ... an implementation of every method and attribute
    # documented in IResponse should follow ...

When an alternate response object implementation is returned by a view callable, if that object asserts that it implements IResponse (via zope.interface.implementer(IResponse)) , an adapter needn’t be registered for the object; Pyramid will use it directly.

An IResponse adapter for webob.Response (as opposed to pyramid.response.Response) is registered by Pyramid by default at startup time, as by their nature, instances of this class (and instances of subclasses of the class) will natively provide IResponse. The adapter registered for webob.Response simply returns the response object.

Instead of using pyramid.config.Configurator.add_response_adapter(), you can use the pyramid.response.response_adapter decorator:

1
2
3
4
5
6
7
from pyramid.response import Response
from pyramid.response import response_adapter

@response_adapter(str)
def string_response_adapter(s):
    response = Response(s)
    return response

The above example, when scanned, has the same effect as:

config.add_response_adapter(string_response_adapter, str)

The response_adapter decorator will have no effect until activated by a scan.

Using a View Mapper

The default calling conventions for view callables are documented in the Views chapter. You can change the way users define view callables by employing a view mapper.

A view mapper is an object that accepts a set of keyword arguments and which returns a callable. The returned callable is called with the view callable object. The returned callable should itself return another callable which can be called with the “internal calling protocol” (context, request).

You can use a view mapper in a number of ways:

  • by setting a __view_mapper__ attribute (which is the view mapper object) on the view callable itself
  • by passing the mapper object to pyramid.config.Configurator.add_view() (or its declarative/decorator equivalents) as the mapper argument.
  • by registering a default view mapper.

Here’s an example of a view mapper that emulates (somewhat) a Pylons “controller”. The mapper is initialized with some keyword arguments. Its __call__ method accepts the view object (which will be a class). It uses the attr keyword argument it is passed to determine which attribute should be used as an action method. The wrapper method it returns accepts (context, request) and returns the result of calling the action method with keyword arguments implied by the matchdict after popping the action out of it. This somewhat emulates the Pylons style of calling action methods with routing parameters pulled out of the route matching dict as keyword arguments.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# framework

class PylonsControllerViewMapper(object):
    def __init__(self, **kw):
        self.kw = kw

    def __call__(self, view):
        attr = self.kw['attr']
        def wrapper(context, request):
            matchdict = request.matchdict.copy()
            matchdict.pop('action', None)
            inst = view(request)
            meth = getattr(inst, attr)
            return meth(**matchdict)
        return wrapper

class BaseController(object):
    __view_mapper__ = PylonsControllerViewMapper

A user might make use of these framework components like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# user application

from pyramid.response import Response
from pyramid.config import Configurator
import pyramid_handlers
from wsgiref.simple_server import make_server

class MyController(BaseController):
    def index(self, id):
        return Response(id)

if __name__ == '__main__':
    config = Configurator()
    config.include(pyramid_handlers)
    config.add_handler('one', '/{id}', MyController, action='index')
    config.add_handler('two', '/{action}/{id}', MyController)
    server.make_server('0.0.0.0', 8080, config.make_wsgi_app())
    server.serve_forever()

The pyramid.config.Configurator.set_view_mapper() method can be used to set a default view mapper (overriding the superdefault view mapper used by Pyramid itself).

A single view registration can use a view mapper by passing the mapper as the mapper argument to add_view().

Registering Configuration Decorators

Decorators such as view_config don’t change the behavior of the functions or classes they’re decorating. Instead, when a scan is performed, a modified version of the function or class is registered with Pyramid.

You may wish to have your own decorators that offer such behaviour. This is possible by using the Venusian package in the same way that it is used by Pyramid.

By way of example, let’s suppose you want to write a decorator that registers the function it wraps with a Zope Component Architecture “utility” within the application registry provided by Pyramid. The application registry and the utility inside the registry is likely only to be available once your application’s configuration is at least partially completed. A normal decorator would fail as it would be executed before the configuration had even begun.

However, using Venusian, the decorator could be written as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import venusian
from mypackage.interfaces import IMyUtility

class registerFunction(object):

    def __init__(self, path):
        self.path = path

    def register(self, scanner, name, wrapped):
        registry = scanner.config.registry
        registry.getUtility(IMyUtility).register(
            self.path, wrapped)

    def __call__(self, wrapped):
        venusian.attach(wrapped, self.register)
        return wrapped

This decorator could then be used to register functions throughout your code:

1
2
3
@registerFunction('/some/path')
def my_function():
   do_stuff()

However, the utility would only be looked up when a scan was performed, enabling you to set up the utility in advance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
from zope.interface import implementer

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from mypackage.interfaces import IMyUtility

@implementer(IMyUtility)
class UtilityImplementation:

    def __init__(self):
       self.registrations = {}

    def register(self, path, callable_):
       self.registrations[path] = callable_

if __name__ == '__main__':
    config = Configurator()
    config.registry.registerUtility(UtilityImplementation())
    config.scan()
    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

For full details, please read the Venusian documentation.

Registering “Tweens”

Note

Tweens are a feature which were added in Pyramid 1.2. They are not available in any previous version.

A tween (a contraction of the word “between”) is a bit of code that sits between the Pyramid router’s main request handling function and the upstream WSGI component that uses Pyramid as its “app”. This is a feature that may be used by Pyramid framework extensions, to provide, for example, Pyramid-specific view timing support bookkeeping code that examines exceptions before they are returned to the upstream WSGI application. Tweens behave a bit like WSGI middleware but they have the benefit of running in a context in which they have access to the Pyramid application registry as well as the Pyramid rendering machinery.

Creating a Tween Factory

To make use of tweens, you must construct a “tween factory”. A tween factory must be a globally importable callable which accepts two arguments: handler and registry. handler will be the either the main Pyramid request handling function or another tween. registry will be the Pyramid application registry represented by this Configurator. A tween factory must return a tween when it is called.

A tween is a callable which accepts a request object and returns a response object.

Here’s an example of a tween factory:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 # in a module named myapp.tweens

 import time
 from pyramid.settings import asbool
 import logging

 log = logging.getLogger(__name__)

 def timing_tween_factory(handler, registry):
     if asbool(registry.settings.get('do_timing')):
         # if timing support is enabled, return a wrapper
         def timing_tween(request):
             start = time.time()
             try:
                 response = handler(request)
             finally:
                 end = time.time()
                 log.debug('The request took %s seconds' %
                           (end - start))
             return response
         return timing_tween
     # if timing support is not enabled, return the original
     # handler
     return handler

If you remember, a tween is an object which accepts a request object and which returns a response argument. The request argument to a tween will be the request created by Pyramid’s router when it receives a WSGI request. The response object will be generated by the downstream Pyramid application and it should be returned by the tween.

In the above example, the tween factory defines a timing_tween tween and returns it if asbool(registry.settings.get('do_timing')) is true. It otherwise simply returns the handler it was given. The registry.settings attribute is a handle to the deployment settings provided by the user (usually in an .ini file). In this case, if the user has defined a do_timing setting, and that setting is True, the user has said she wants to do timing, so the tween factory returns the timing tween; it otherwise just returns the handler it has been provided, preventing any timing.

The example timing tween simply records the start time, calls the downstream handler, logs the number of seconds consumed by the downstream handler, and returns the response.

Registering an Implicit Tween Factory

Once you’ve created a tween factory, you can register it into the implicit tween chain using the pyramid.config.Configurator.add_tween() method using its dotted Python name.

Here’s an example of registering the a tween factory as an “implicit” tween in a Pyramid application:

1
2
3
 from pyramid.config import Configurator
 config = Configurator()
 config.add_tween('myapp.tweens.timing_tween_factory')

Note that you must use a dotted Python name as the first argument to pyramid.config.Configurator.add_tween(); this must point at a tween factory. You cannot pass the tween factory object itself to the method: it must be dotted Python name that points to a globally importable object. In the above example, we assume that a timing_tween_factory tween factory was defined in a module named myapp.tweens, so the tween factory is importable as myapp.tweens.timing_tween_factory.

When you use pyramid.config.Configurator.add_tween(), you’re instructing the system to use your tween factory at startup time unless the user has provided an explicit tween list in his configuration. This is what’s meant by an “implicit” tween. A user can always elect to supply an explicit tween list, reordering or disincluding implicitly added tweens. See Explicit Tween Ordering for more information about explicit tween ordering.

If more than one call to pyramid.config.Configurator.add_tween() is made within a single application configuration, the tweens will be chained together at application startup time. The first tween factory added via add_tween will be called with the Pyramid exception view tween factory as its handler argument, then the tween factory added directly after that one will be called with the result of the first tween factory as its handler argument, and so on, ad infinitum until all tween factories have been called. The Pyramid router will use the outermost tween produced by this chain (the tween generated by the very last tween factory added) as its request handler function. For example:

1
2
3
4
5
 from pyramid.config import Configurator

 config = Configurator()
 config.add_tween('myapp.tween_factory1')
 config.add_tween('myapp.tween_factory2')

The above example will generate an implicit tween chain that looks like this:

INGRESS (implicit)
myapp.tween_factory2
myapp.tween_factory1
pyramid.tweens.excview_tween_factory (implicit)
MAIN (implicit)

Suggesting Implicit Tween Ordering

By default, as described above, the ordering of the chain is controlled entirely by the relative ordering of calls to pyramid.config.Configurator.add_tween(). However, the caller of add_tween can provide an optional hint that can influence the implicit tween chain ordering by supplying under or over (or both) arguments to add_tween(). These hints are only used when an explicit tween ordering is not used. See Explicit Tween Ordering for a description of how to set an explicit tween ordering.

Allowable values for under or over (or both) are:

  • None (the default).
  • A dotted Python name to a tween factory: a string representing the predicted dotted name of a tween factory added in a call to add_tween in the same configuration session.
  • One of the constants pyramid.tweens.MAIN, pyramid.tweens.INGRESS, or pyramid.tweens.EXCVIEW.
  • An iterable of any combination of the above. This allows the user to specify fallbacks if the desired tween is not included, as well as compatibility with multiple other tweens.

Effectively, under means “closer to the main Pyramid application than”, over means “closer to the request ingress than”.

For example, the following call to add_tween() will attempt to place the tween factory represented by myapp.tween_factory directly ‘above’ (in ptweens order) the main Pyramid request handler.

1
2
3
import pyramid.tweens

config.add_tween('myapp.tween_factory', over=pyramid.tweens.MAIN)

The above example will generate an implicit tween chain that looks like this:

INGRESS (implicit)
pyramid.tweens.excview_tween_factory (implicit)
myapp.tween_factory
MAIN (implicit)

Likewise, calling the following call to add_tween() will attempt to place this tween factory ‘above’ the main handler but ‘below’ a separately added tween factory:

1
2
3
4
5
6
7
import pyramid.tweens

config.add_tween('myapp.tween_factory1',
                 over=pyramid.tweens.MAIN)
config.add_tween('myapp.tween_factory2',
                 over=pyramid.tweens.MAIN,
                 under='myapp.tween_factory1')

The above example will generate an implicit tween chain that looks like this:

INGRESS (implicit)
pyramid.tweens.excview_tween_factory (implicit)
myapp.tween_factory1
myapp.tween_factory2
MAIN (implicit)

Specifying neither over nor under is equivalent to specifying under=INGRESS.

If all options for under (or over) cannot be found in the current configuration, it is an error. If some options are specified purely for compatibilty with other tweens, just add a fallback of MAIN or INGRESS. For example, under=('someothertween', 'someothertween2', INGRESS). This constraint will require the tween to be located under both the ‘someothertween’ tween, the ‘someothertween2’ tween, and INGRESS. If any of these is not in the current configuration, this constraint will only organize itself based on the tweens that are present.

Explicit Tween Ordering

Implicit tween ordering is obviously only best-effort. Pyramid will attempt to provide an implicit order of tweens as best it can using hints provided by calls to add_tween(), but because it’s only best-effort, if very precise tween ordering is required, the only surefire way to get it is to use an explicit tween order. The deploying user can override the implicit tween inclusion and ordering implied by calls to add_tween() entirely by using the pyramid.tweens settings value. When used, this settings value must be a list of Python dotted names which will override the ordering (and inclusion) of tween factories in the implicit tween chain. For example:

1
2
3
4
5
6
7
8
9
[app:main]
use = egg:MyApp
pyramid.reload_templates = true
pyramid.debug_authorization = false
pyramid.debug_notfound = false
pyramid.debug_routematch = false
pyramid.debug_templates = true
pyramid.tweens = myapp.my_cool_tween_factory
                 pyramid.tweens.excview_tween_factory

In the above configuration, calls made during configuration to pyramid.config.Configurator.add_tween() are ignored, and the user is telling the system to use the tween factories he has listed in the pyramid.tweens configuration setting (each is a dotted Python name which points to a tween factory) instead of any tween factories added via pyramid.config.Configurator.add_tween(). The first tween factory in the pyramid.tweens list will be used as the producer of the effective Pyramid request handling function; it will wrap the tween factory declared directly “below” it, ad infinitum. The “main” Pyramid request handler is implicit, and always “at the bottom”.

Note

Pyramid’s own exception view handling logic is implemented as a tween factory function: pyramid.tweens.excview_tween_factory(). If Pyramid exception view handling is desired, and tween factories are specified via the pyramid.tweens configuration setting, the pyramid.tweens.excview_tween_factory() function must be added to the pyramid.tweens configuration setting list explicitly. If it is not present, Pyramid will not perform exception view handling.

Tween Conflicts and Ordering Cycles

Pyramid will prevent the same tween factory from being added to the tween chain more than once using configuration conflict detection. If you wish to add the same tween factory more than once in a configuration, you should either: a) use a tween factory that is a separate globally importable instance object from the factory that it conflicts with b) use a function or class as a tween factory with the same logic as the other tween factory it conflicts with but with a different __name__ attribute or c) call pyramid.config.Configurator.commit() between calls to pyramid.config.Configurator.add_tween().

If a cycle is detected in implicit tween ordering when over and under are used in any call to “add_tween”, an exception will be raised at startup time.

Displaying Tween Ordering

The ptweens command-line utility can be used to report the current implict and explicit tween chains used by an application. See Displaying “Tweens”.

Adding A Third Party View, Route, or Subscriber Predicate

Note

Third-party view, route, and subscriber predicates are a feature new as of Pyramid 1.4.

View and Route Predicates

View and route predicates used during configuration allow you to narrow the set of circumstances under which a view or route will match. For example, the request_method view predicate can be used to ensure a view callable is only invoked when the request’s method is POST:

@view_config(request_method='POST')
def someview(request):
    ...

Likewise, a similar predicate can be used as a route predicate:

config.add_route('name', '/foo', request_method='POST')

Many other built-in predicates exists (request_param, and others). You can add third-party predicates to the list of available predicates by using one of pyramid.config.Configurator.add_view_predicate() or pyramid.config.Configurator.add_route_predicate(). The former adds a view predicate, the latter a route predicate.

When using one of those APIs, you pass a name and a factory to add a predicate during Pyramid’s configuration stage. For example:

config.add_view_predicate('content_type', ContentTypePredicate)

The above example adds a new predicate named content_type to the list of available predicates for views. This will allow the following view configuration statement to work:

1
2
@view_config(content_type='File')
def aview(request): ...

The first argument to pyramid.config.Configurator.add_view_predicate(), the name, is a string representing the name that is expected to be passed to view_config (or its imperative analogue add_view).

The second argument is a view or route predicate factory. A view or route predicate factory is most often a class with a constructor (__init__), a text method, a phash method and a __call__ method. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 class ContentTypePredicate(object):
     def __init__(self, val, config):
         self.val = val

     def text(self):
         return 'content_type = %s' % (self.val,)

     phash = text

     def __call__(self, context, request):
         return getattr(context, 'content_type', None) == self.val

The constructor of a predicate factory takes two arguments: val and config. The val argument will be the argument passed to view_config (or add_view). In the example above, it will be the string File. The second arg, config will be the Configurator instance at the time of configuration.

The text method must return a string. It should be useful to describe the behavior of the predicate in error messages.

The phash method must return a string or a sequence of strings. It’s most often the same as text, as long as text uniquely describes the predicate’s name and the value passed to the constructor. If text is more general, or doesn’t describe things that way, phash should return a string with the name and the value serialized. The result of phash is not seen in output anywhere, it just informs the uniqueness constraints for view configuration.

The __call__ method of a predicate factory must accept a resource (context) and a request, and must return True or False. It is the “meat” of the predicate.

You can use the same predicate factory as both a view predicate and as a route predicate, but you’ll need to call add_view_predicate and add_route_predicate separately with the same factory.

Subscriber Predicates

Subscriber predicates work almost exactly like view and route predicates. They narrow the set of circumstances in which a subscriber will be called. There are several minor differences between a subscriber predicate and a view/route predicate:

  • There are no default subscriber predicates. You must register one to use one.
  • The __call__ method of a subscriber predicate accepts a single event object instead of a context and a request.
  • Not every subscriber predicate can be used with every event type. Some subscriber predicates will assume a certain event type.

Here’s an example of a subscriber predicate that can be used in conjunction with a subscriber that subscribes to the pyramid.events.NewReqest event type.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 class RequestPathStartsWith(object):
     def __init__(self, val, config):
         self.val = val

     def text(self):
         return 'path_startswith = %s' % (self.val,)

     phash = text

     def __call__(self, event):
         return event.request.path.startswith(self.val)

Once you’ve created a subscriber predicate, it may registered via pyramid.config.Configurator.add_subscriber_predicate(). For example:

config.add_subscriber_predicate(
    'request_path_startswith', RequestPathStartsWith)

Once a subscriber predicate is registered, you can use it in a call to pyramid.config.Configurator.add_subscriber() or to pyramid.events.subscriber. Here’s an example of using the previously registered request_path_startswith predicate in a call to add_subscriber():

1
2
3
4
5
6
7
8
9
 # define a subscriber in your code

 def yosubscriber(event):
     event.request.yo = 'YO!'

 # and at configuration time

 config.add_subscriber(yosubscriber, NewRequest,
        request_path_startswith='/add_yo')

Here’s the same subscriber/predicate/event-type combination used via subscriber.

1
2
3
4
5
 from pyramid.events import subscriber

 @subscriber(NewRequest, request_path_startswith='/add_yo')
 def yosubscriber(event):
     event.request.yo = 'YO!'

In either of the above configurations, the yosubscriber callable will only be called if the request path starts with /add_yo. Otherwise the event subscriber will not be called.

Note that the request_path_startswith subscriber you defined can be used with events that have a request attribute, but not ones that do not. So, for example, the predicate can be used with subscribers registered for pyramid.events.NewRequest and pyramid.events.ContextFound events, but it cannot be used with subscribers registered for pyramid.events.ApplicationCreated because the latter type of event has no request attribute. The point being: unlike route and view predicates, not every type of subscriber predicate will necessarily be applicable for use in every subscriber registration. It is not the responsibility of the predicate author to make every predicate make sense for every event type; it is the responsibility of the predicate consumer to use predicates that make sense for a particular event type registration.