CHAPTER

TWENTYNINE

USING HOOKS

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

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

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:

317

29. USING HOOKS

1 from pyramid.view import notfound_view_config

2

3 @notfound_view_config()

4 def notfound(request):

5return Response(’Not Found, dude’, status=’404 Not Found’)

6

7 def main(globals, **settings):

8config = Configurator()

9config.scan()

This does exactly what the imperative example above showed.

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 from pyramid.view import notfound_view_config

2

3 @notfound_view_config(request_method=’GET’) 4 def notfound_get(request):

5return Response(’Not Found during GET, dude’, status=’404 Not Found’)

6

7 @notfound_view_config(request_method=’POST’) 8 def notfound_post(request):

9return Response(’Not Found during POST, dude’, status=’404 Not Found’)

10

11def main(globals, **settings):

12config = Configurator()

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

318

29.1. CHANGING THE NOT FOUND VIEW

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

latex-note.png

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.

latex-note.png

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.

latex-warning.png

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.

319

29. USING HOOKS

29.2 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 meth: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:

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 from pyramid.view import forbidden_view_config

2

3 forbidden_view_config()

4 def forbidden(request):

5return Response(’forbidden’)

6

7 def main(globals, **settings):

8config = Configurator()

9config.scan()

Like any other view, the forbidden view must accept at least a request parameter, or both context and request. The context (available as request.context if you’re using the request-only view argument pattern) is the context found by the router when the view invocation was denied. The request is the current request representing the denied action.

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

320