29.7. USING FINISHED CALLBACKS

29.7 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:

7log.debug(’Request is finished.’)

8 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).

325

29. USING HOOKS

29.8 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.

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

1 class Traverser(object):

2def __init__(self, root):

3""" Accept the root object returned from the root factory """

4

5def __call__(self, request):

6""" Return a dictionary with (at least) the keys ‘‘root‘‘,

7‘‘context‘‘, ‘‘view_name‘‘, ‘‘subpath‘‘, ‘‘traversed‘‘,

9typically the result of a resource tree traversal. ‘‘root‘‘

10is the physical root object, ‘‘context‘‘ will be a resource

11object, ‘‘view_name‘‘ will be the view name used (a Unicode

12name), ‘‘subpath‘‘ will be a sequence of Unicode names that

13followed the view name but were not traversed, ‘‘traversed‘‘

14will be a sequence of Unicode names that were traversed

15(including the virtual root path, if any) ‘‘virtual_root‘‘

16will be a resource object representing the virtual root (or the

17physical root if traversal was not performed), and

18‘‘virtual_root_path‘‘ will be a sequence representing the

19virtual root path (a sequence of Unicode names) or None if

20traversal was not performed.

21

22Extra keys for special purpose functionality can be added as

23necessary.

24

25All values returned in the dictionary will be made available

26as attributes of the ‘‘request‘‘ object.

27"""

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

326

29.9. CHANGING HOW PYRAMID.REQUEST.REQUEST.RESOURCE_URL() GENERATES A URL

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:

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.

29.9Changing 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:

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:

327

29. USING HOOKS

1 class MyResourceURL(object):

2""" An adapter which provides the virtual and physical paths of a

3resource

4"""

5def __init__(self, resource, request):

6""" Accept the resource and request and set self.physical_path and

7self.virtual_path"""

8self.virtual_path = some_function_of(resource, request)

9self.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.

29.10 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.

latex-note.png

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.

328

29.10. CHANGING HOW PYRAMID TREATS VIEW RESPONSES

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

1 from pyramid.response import Response

2

3 def string_response_adapter(s):

4 response = Response(s)

5return response

6

7 # config is an instance of pyramid.config.Configurator

8

9 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 from pyramid.response import Response

2

3 class SimpleResponse(object):

4 def __init__(self, body):

5self.body = body

6

7 def simple_response_adapter(simple_response): 8 response = Response(simple_response.body)

9return response

10

11 # config is an instance of pyramid.config.Configurator

12

13 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.

329