Navigation

One of the primary jobs of Pyramid is to find and invoke a view
callable when a request reaches your application. View callables
are bits of code which do something interesting in response to a request made
to your application. They are the "meat" of any interesting web application.

Note

A Pyramidview callable is often referred to in
conversational shorthand as a view. In this documentation,
however, we need to use less ambiguous terminology because there
are significant differences between view configuration, the code
that implements a view callable, and the process of view
lookup.

This chapter describes how view callables should be defined. We'll have to
wait until a following chapter (entitled View Configuration) to find
out how we actually tell Pyramid to wire up view callables to
particular URL patterns and other request circumstances.

View callables are, at the risk of sounding obvious, callable Python
objects. Specifically, view callables can be functions, classes, or instances
that implement a __call__ method (making the instance callable).

View callables must, at a minimum, accept a single argument named
request. This argument represents a PyramidRequest
object. A request object represents a WSGI environment provided to
Pyramid by the upstream WSGI server. As you might expect, the request
object contains everything your application needs to know about the specific
HTTP request being made.

A view callable's ultimate responsibility is to create a PyramidResponse object. This can be done by creating a Response
object in the view callable code and returning it directly or by raising
special kinds of exceptions from within the body of a view callable.

One of the easiest way to define a view callable is to create a function that
accepts a single argument named request, and which returns a
Response object. For example, this is a "hello world" view callable
implemented as a function:

A view callable may also be represented by a Python class instead of a
function. When a view callable is a class, the calling semantics are
slightly different than when it is a function or another non-class callable.
When a view callable is a class, the class' __init__ method is called with a
request parameter. As a result, an instance of the class is created.
Subsequently, that instance's __call__ method is invoked with no
parameters. Views defined as classes must have the following traits:

an __init__ method that accepts a request argument.

a __call__ (or other) method that accepts no parameters and which
returns a response.

If you'd like to use a different attribute than __call__ to represent the
method expected to return a response, you can use an attr value as part
of the configuration for the view. See View Configuration Parameters.
The same view callable class can be used in different view configuration
statements with different attr values, each pointing at a different
method of the class if you'd like the class to represent a collection of
related view callables.

A view callable may return an object that implements the PyramidResponse interface. The easiest way to return something that
implements the Response interface is to return a
pyramid.response.Response object instance directly. For example:

You can also return objects from view callables that aren't instances of
pyramid.response.Response in various circumstances. This can be
helpful when writing tests and when attempting to share code between view
callables. See Renderers for the common way to allow for
this. A much less common way to allow for view callables to return
non-Response objects is documented in Changing How Pyramid Treats View Responses.

Usually when a Python exception is raised within a view callable,
Pyramid allows the exception to propagate all the way out to the
WSGI server which invoked the application. It is usually caught and
logged there.

However, for convenience, a special set of exceptions exists. When one of
these exceptions is raised within a view callable, it will always cause
Pyramid to generate a response. These are known as HTTP
exception objects.

This is the case because 401 is the HTTP status code for "HTTP
Unauthorized". Therefore, raiseexception_response(401) is functionally
equivalent to raiseHTTPUnauthorized(). Documentation which maps each
HTTP response code to its purpose and its associated HTTP exception object is
provided within pyramid.httpexceptions.

The machinery which allows HTTP exceptions to be raised and caught by
specialized views as described in Using Special Exceptions In View Callables can
also be used by application developers to convert arbitrary exceptions to
responses.

To register a view that should be called whenever a particular exception is
raised from within Pyramid view code, use the exception class (or one of
its superclasses) as the context of a view configuration which points
at a view callable you'd like to generate a response for.

For example, given the following exception class in a module named
helloworld.exceptions:

1
2
3

classValidationFailure(Exception):def__init__(self,msg):self.msg=msg

You can wire a view callable to be called whenever any of your other code
raises a helloworld.exceptions.ValidationFailure exception:

Assuming that a scan was run to pick up this view registration, this
view callable will be invoked whenever a
helloworld.exceptions.ValidationFailure is raised by your application's
view code. The same exception raised by a custom root factory, a custom
traverser, or a custom view or route predicate is also caught and hooked.

Other normal view predicates can also be used in combination with an
exception view registration:

The above exception view names the route_name of home, meaning that
it will only be called when the route matched has a name of home. You
can therefore have more than one exception view for any given exception in
the system: the "most specific" one will be called when the set of request
circumstances match the view registration.

The only view predicate that cannot be used successfully when creating
an exception view configuration is name. The name used to look up
an exception view is always the empty string. Views registered as
exception views which have a name will be ignored.

Note

Normal (i.e., non-exception) views registered against a context resource
type which inherits from Exception will work normally. When an
exception view configuration is processed, two views are registered. One
as a "normal" view, the other as an "exception" view. This means that you
can use an exception as context for a normal view.

Exception views can be configured with any view registration mechanism:
@view_config decorator or imperative add_view styles.

When the instance is raised, it is caught by the default exception
response handler and turned into a response.

Handling Form Submissions in View Callables (Unicode and Character Set Issues)¶

Most web applications need to accept form submissions from web browsers and
various other clients. In Pyramid, form submission handling logic is
always part of a view. For a general overview of how to handle form
submission data using the WebOb API, see Request and Response Objects and
"Query and POST variables" within the WebOb documentation.
Pyramid defers to WebOb for its request and response implementations,
and handling form submission data is a property of the request
implementation. Understanding WebOb's request API is the key to
understanding how to process form submission data.

There are some defaults that you need to be aware of when trying to handle
form submission data in a Pyramid view. Having high-order (i.e.,
non-ASCII) characters in data contained within form submissions is
exceedingly common, and the UTF-8 encoding is the most common encoding used
on the web for character data. Since Unicode values are much saner than
working with and storing bytestrings, Pyramid configures the
WebOb request machinery to attempt to decode form submission values
into Unicode from UTF-8 implicitly. This implicit decoding happens when view
code obtains form field values via the request.params, request.GET,
or request.POST APIs (see pyramid.request for details about these
APIs).

Note

Many people find the difference between Unicode and UTF-8 confusing.
Unicode is a standard for representing text that supports most of the
world's writing systems. However, there are many ways that Unicode data
can be encoded into bytes for transit and storage. UTF-8 is a specific
encoding for Unicode, that is backwards-compatible with ASCII. This makes
UTF-8 very convenient for encoding data where a large subset of that data
is ASCII characters, which is largely true on the web. UTF-8 is also the
standard character encoding for URLs.

As an example, let's assume that the following form page is served up to a
browser client, and its action points at some Pyramid view code:

The myview view code in the Pyramid application must expect that
the values returned by request.params will be of type unicode, as
opposed to type str. The following will work to accept a form post from
the above form:

But the following myview view code may not work, as it tries to decode
already-decoded (unicode) values obtained from request.params:

1
2
3
4
5

defmyview(request):# the .decode('utf-8') will break below if there are any high-order# characters in the firstname or lastnamefirstname=request.params['firstname'].decode('utf-8')lastname=request.params['lastname'].decode('utf-8')

For implicit decoding to work reliably, you should ensure that every form you
render that posts to a Pyramid view explicitly defines a charset
encoding of UTF-8. This can be done via a response that has a
;charset=UTF-8 in its Content-Type header; or, as in the form above,
with a metahttp-equiv tag that implies that the charset is UTF-8 within
the HTML head of the page containing the form. This must be done
explicitly because all known browser clients assume that they should encode
form data in the same character set implied by Content-Type value of the
response containing the form when subsequently submitting that form. There is
no other generally accepted way to tell browser clients which charset to use
to encode form data. If you do not specify an encoding explicitly, the
browser client will choose to encode form data in its default character set
before submitting it, which may not be UTF-8 as the server expects. If a
request containing form data encoded in a non-UTF8 charset is handled by your
view code, eventually the request code accessed within your view will throw
an error when it can't decode some high-order character encoded in another
character set within form data, e.g., when request.params['somename'] is
accessed.

If you are using the Response class to generate a
response, or if you use the render_template_* templating APIs, the UTF-8
charset is set automatically as the default via the Content-Type header.
If you return a Content-Type header without an explicit charset, a
request will add a ;charset=utf-8 trailer to the Content-Type header
value for you, for response content types that are textual
(e.g. text/html, application/xml, etc) as it is rendered. If you are
using your own response object, you will need to ensure you do this yourself.

Note

Only the values of request params obtained via
request.params, request.GET or request.POST are decoded
to Unicode objects implicitly in the Pyramid default
configuration. The keys are still (byte) strings.

Usually, view callables are defined to accept only a single argument:
request. However, view callables may alternately be defined as classes,
functions, or any callable that accept two positional arguments: a
context resource as the first argument and a request as the
second argument.

The context and request arguments passed to a view function
defined in this style can be defined as follows:

A package named pyramid_handlers (available from PyPI) provides an
analogue of Pylons -style "controllers", which are a special kind of
view class which provides more automation when your application uses
URL dispatch solely.