single: view lookup
View lookup
is the Pyramid
subsystem responsible for finding and invoking a view callable
. View configuration
controls how view lookup
operates in your application. During any given request, view configuration information is compared against request data by the view lookup subsystem in order to find the "best" view callable for that request.
In earlier chapters, you have been exposed to a few simple view configuration declarations without much explanation. In this chapter we will explore the subject in detail.
pair: resource; mapping to view callable pair: URL pattern; mapping to view callable
A developer makes a view callable
available for use within a Pyramid
application via view configuration
. A view configuration associates a view callable with a set of statements that determine the set of circumstances which must be true for the view callable to be invoked.
A view configuration statement is made about information present in the context
resource and the request
.
View configuration is performed in one of two ways:
- by running a
scan
against application source code which has apyramid.view.view_config
decorator attached to a Python object as permapping_views_using_a_decorator_section
. - by using the
pyramid.config.Configurator.add_view
method as permapping_views_using_imperative_config_section
.
single: view configuration parameters
All forms of view configuration accept the same general types of arguments.
Many arguments supplied during view configuration are view predicate
arguments. View predicate arguments used during view configuration are used to narrow the set of circumstances in which view lookup
will find a particular view callable.
View predicate
attributes are an important part of view configuration that enables the view lookup
subsystem to find and invoke the appropriate view. The greater number of predicate attributes possessed by a view's configuration, the more specific the circumstances need to be before the registered view callable will be invoked. The fewer number of predicates which are supplied to a particular view configuration, the more likely it is that the associated view callable will be invoked. A view with five predicates will always be found and evaluated before a view with two, for example. All predicates must match for the associated view to be called.
This does not mean however, that Pyramid
"stops looking" when it finds a view registration with predicates that don't match. If one set of view predicates does not match, the "next most specific" view (if any) is consulted for predicates, and so on, until a view is found, or no view can be matched up with the request. The first view with a set of predicates all of which match the request environment will be invoked.
If no view can be found with predicates which allow it to be matched up with the request, Pyramid
will return an error to the user's browser, representing a "not found" (404) page. See changing_the_notfound_view
for more information about changing the default notfound view.
Other view configuration arguments are non-predicate arguments. These tend to modify the response of the view callable or prevent the view callable from being invoked due to an authorization policy. The presence of non-predicate arguments in a view configuration does not narrow the circumstances in which the view callable will be invoked.
permission
The name of a
permission
that the user must possess in order to invoke theview callable
. Seeview_security_section
for more information about view security and permissions.If
permission
is not supplied, no permission is registered for this view (it's accessible by any caller).attr
The view machinery defaults to using the
__call__
method of theview callable
(or the function itself, if the view callable is a function) to obtain a response. Theattr
value allows you to vary the method attribute used to obtain the response. For example, if your view was a class, and the class has a method namedindex
and you wanted to use this method instead of the class'__call__
method to return the response, you'd sayattr="index"
in the view configuration for the view. This is most useful when the view definition is a class.If
attr
is not supplied,None
is used (implying the function itself if the view is a function, or the__call__
callable attribute if the view is a class).renderer
Denotes the
renderer
implementation which will be used to construct aresponse
from the associated view callable's return value. (see alsorenderers_chapter
).This is either a single string term (e.g.
json
) or a string implying a path orasset specification
(e.g.templates/views.pt
) naming arenderer
implementation. If therenderer
value does not contain a dot (.
), the specified string will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the view return value. If therenderer
value contains a dot (.
), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path.When the renderer is a path, although a path is usually just a simple relative pathname (e.g.
templates/foo.pt
, implying that a template named "foo.pt" is in the "templates" directory relative to the directory of the currentpackage
), a path can be absolute, starting with a slash on UNIX or a drive letter prefix on Windows. The path can alternately be aasset specification
in the formsome.dotted.package_name:relative/path
, making it possible to address template assets which live in a separate package.The
renderer
attribute is optional. If it is not defined, the "null" renderer is assumed (no rendering is performed and the value is passed back to the upstreamPyramid
machinery unchanged). Note that if the view callable itself returns aresponse
(seethe_response
), the specified renderer implementation is never called.http_cache
When you supply an
http_cache
value to a view configuration, theExpires
andCache-Control
headers of a response generated by the associated view callable are modified. The value forhttp_cache
may be one of the following:- A nonzero integer. If it's a nonzero integer, it's treated as a number of seconds. This number of seconds will be used to compute the
Expires
header and theCache-Control: max-age
parameter of responses to requests which call this view. For example:http_cache=3600
instructs the requesting browser to 'cache this response for an hour, please'. - A
datetime.timedelta
instance. If it's adatetime.timedelta
instance, it will be converted into a number of seconds, and that number of seconds will be used to compute theExpires
header and theCache-Control: max-age
parameter of responses to requests which call this view. For example:http_cache=datetime.timedelta(days=1)
instructs the requesting browser to 'cache this response for a day, please'. - Zero (
0
). If the value is zero, theCache-Control
andExpires
headers present in all responses from this view will be composed such that client browser cache (and any intermediate caches) are instructed to never cache the response. - A two-tuple. If it's a two tuple (e.g.
http_cache=(1, {'public':True})
), the first value in the tuple may be a nonzero integer or adatetime.timedelta
instance; in either case this value will be used as the number of seconds to cache the response. The second value in the tuple must be a dictionary. The values present in the dictionary will be used as input to theCache-Control
response header. For example:http_cache=(3600, {'public':True})
means 'cache for an hour, and addpublic
to the Cache-Control header of the response'. All keys and values supported by thewebob.cachecontrol.CacheControl
interface may be added to the dictionary. Supplying{'public':True}
is equivalent to callingresponse.cache_control.public = True
.
Providing a non-tuple value as
http_cache
is equivalent to callingresponse.cache_expires(value)
within your view's body.Providing a two-tuple value as
http_cache
is equivalent to callingresponse.cache_expires(value[0], **value[1])
within your view's body.If you wish to avoid influencing, the
Expires
header, and instead wish to only influenceCache-Control
headers, pass a tuple ashttp_cache
with the first element ofNone
, e.g.:(None, {'public':True})
.- A nonzero integer. If it's a nonzero integer, it's treated as a number of seconds. This number of seconds will be used to compute the
wrapper
The
view name
of a differentview configuration
which will receive the response body of this view as therequest.wrapped_body
attribute of its ownrequest
, and theresponse
returned by this view as therequest.wrapped_response
attribute of its own request. Using a wrapper makes it possible to "chain" views together to form a composite response. The response of the outermost wrapper view will be returned to the user. The wrapper view will be found as any view is found: seeview_lookup
. The "best" wrapper view will be found based on the lookup ordering: "under the hood" this wrapper view is looked up viapyramid.view.render_view_to_response(context, request, 'wrapper_viewname')
. The context and request of a wrapper view is the same context and request of the inner view.If
wrapper
is not supplied, no wrapper view is used.decorator
A
dotted Python name
to a function (or the function itself) which will be used to decorate the registeredview callable
. The decorator function will be called with the view callable as a single argument. The view callable it is passed will accept(context, request)
. The decorator must return a replacement view callable which also accepts(context, request)
.mapper
A Python object or
dotted Python name
which refers to aview mapper
, orNone
. By default it isNone
, which indicates that the view should use the default view mapper. This plug-point is useful for Pyramid extension developers, but it's not very useful for 'civilians' who are just developing stock Pyramid applications. Pay no attention to the man behind the curtain.
These arguments modify view lookup behavior. In general, the more predicate arguments that are supplied, the more specific, and narrower the usage of the configured view.
name
The
view name
required to match this view callable. Aname
argument is typically only used when your application usestraversal
. Readtraversal_chapter
to understand the concept of a view name.If
name
is not supplied, the empty string is used (implying the default view).context
An object representing a Python class that the
context
resource must be an instance of or theinterface
that thecontext
resource must provide in order for this view to be found and called. This predicate is true when thecontext
resource is an instance of the represented class or if thecontext
resource provides the represented interface; it is otherwise false.If
context
is not supplied, the valueNone
, which matches any resource, is used.route_name
If
route_name
is supplied, the view callable will be invoked only when the named route has matched.This value must match the
name
of aroute configuration
declaration (seeurldispatch_chapter
) that must match before this view will be called. Note that theroute
configuration referred to byroute_name
will usually have a*traverse
token in the value of itspattern
, representing a part of the path that will be used bytraversal
against the result of the route'sroot factory
.If
route_name
is not supplied, the view callable will only have a chance of being invoked if no other route was matched. This is when the request/context pair found viaresource location
does not indicate it matched any configured route.request_type
This value should be an
interface
that therequest
must provide in order for this view to be found and called.If
request_type
is not supplied, the valueNone
is used, implying any request type.This is an advanced feature, not often used by "civilians".
request_method
This value can be a string (typically
"GET"
,"POST"
,"PUT"
,"DELETE"
, or"HEAD"
) representing an HTTPREQUEST_METHOD
. A view declaration with this argument ensures that the view will only be called when the request'smethod
attribute (aka theREQUEST_METHOD
of the WSGI environment) string matches the supplied value.If
request_method
is not supplied, the view will be invoked regardless of theREQUEST_METHOD
of theWSGI
environment.request_param
This value can be any string or a sequence of strings. A view declaration with this argument ensures that the view will only be called when the
request
has a key in therequest.params
dictionary (an HTTPGET
orPOST
variable) that has a name which matches the a supplied value.If any value supplied has a
=
sign in it, e.g.request_param="foo=123"
, then the key (foo
) must both exist in therequest.params
dictionary, and the value must match the right hand side of the expression (123
) for the view to "match" the current request.If
request_param
is not supplied, the view will be invoked without consideration of keys and values in therequest.params
dictionary.match_param
Note
This feature is new as of
Pyramid
1.2.This param may be either a single string of the format "key=value" or a dict of key/value pairs.
This argument ensures that the view will only be called when the
request
has key/value pairs in itsmatchdict
that equal those supplied in the predicate. e.g.match_param="action=edit" would require the
actionparameter in the :term:`matchdict` match the right hande side of the expression (
edit) for the view to "match" the current request. If the
match_paramis a dict, every key/value pair must match for the predicate to pass. If
match_paramis not supplied, the view will be invoked without consideration of the keys and values in
request.matchdict``.containment
This value should be a reference to a Python class or
interface
that a parent object in the context resource'slineage
must provide in order for this view to be found and called. The resources in your resource tree must be "location-aware" to use this feature.If
containment
is not supplied, the interfaces and classes in the lineage are not considered when deciding whether or not to invoke the view callable.See
location_aware
for more information about location-awareness.xhr
This value should be either
True
orFalse
. If this value is specified and isTrue
, theWSGI
environment must possess anHTTP_X_REQUESTED_WITH
(akaX-Requested-With
) header that has the valueXMLHttpRequest
for the associated view callable to be found and called. This is useful for detecting AJAX requests issued from jQuery, Prototype and other Javascript libraries.If
xhr
is not specified, theHTTP_X_REQUESTED_WITH
HTTP header is not taken into consideration when deciding whether or not to invoke the associated view callable.accept
The value of this argument represents a match query for one or more mimetypes in the
Accept
HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the formtext/plain
, a wildcard mimetype match token in the formtext/*
or a match-all wildcard mimetype match token in the form*/*
. If any of the forms matches theAccept
header of the request, this predicate will be true.If
accept
is not specified, theHTTP_ACCEPT
HTTP header is not taken into consideration when deciding whether or not to invoke the associated view callable.header
This value represents an HTTP header name or a header name/value pair.
If
header
is specified, it must be a header name or aheadername:headervalue
pair.If
header
is specified without a value (a bare header name only, e.g.If-Modified-Since
), the view will only be invoked if the HTTP header exists with any value in the request.If
header
is specified, and possesses a name/value pair (e.g.User-Agent:Mozilla/.*
), the view will only be invoked if the HTTP header exists and the HTTP header matches the value requested. When theheadervalue
contains a:
(colon), it will be considered a name/value pair (e.g.User-Agent:Mozilla/.*
orHost:localhost
). The value portion should be a regular expression.Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant.
If
header
is not specified, the composition, presence or absence of HTTP headers is not taken into consideration when deciding whether or not to invoke the associated view callable.path_info
This value represents a regular expression pattern that will be tested against the
PATH_INFO
WSGI environment variable to decide whether or not to call the associated view callable. If the regex matches, this predicate will beTrue
.If
path_info
is not specified, the WSGIPATH_INFO
is not taken into consideration when deciding whether or not to invoke the associated view callable.check_csrf
If specified, this value should be one of
None
,True
,False
, or a string representing the 'check name'. If the value isTrue
or a string, CSRF checking will be performed. If the value isFalse
orNone
, CSRF checking will not be performed.If the value provided is a string, that string will be used as the 'check name'. If the value provided is
True
,csrf_token
will be used as the check name.If CSRF checking is performed, the checked value will be the value of
request.params[check_name]
. This value will be compared against the value ofrequest.session.get_csrf_token()
, and the check will pass if these two values are the same. If the check passes, the associated view will be permitted to execute. If the check fails, the associated view will not be permitted to execute.Note that using this feature requires a
session factory
to have been configured.1.4a2
physical_path
If specified, this value should be a string or a tuple representing the
physical path
of the context found via traversal for this predicate to match as true. For example:physical_path='/'
orphysical_path='/a/b/c'
orphysical_path=('', 'a', 'b', 'c')
. This is not a path prefix match or a regex, it's a whole-path match. It's useful when you want to always potentially show a view when some object is traversed to, but you can't be sure about what kind of object it will be, so you can't use thecontext
predicate. The individual path elements inbetween slash characters or in tuple elements should be the Unicode representation of the name of the resource and should not be encoded in any way.1.4a3
effective_principals
If specified, this value should be a
principal
identifier or a sequence of principal identifiers. If thepyramid.security.effective_principals
method indicates that every principal named in the argument list is present in the current request, this predicate will return True; otherwise it will return False. For example:effective_principals=pyramid.security.Authenticated
oreffective_principals=('fred', 'group:admins')
.1.4a4
custom_predicates
If
custom_predicates
is specified, it must be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates do what you need. Custom predicates can be combined with predefined predicates as necessary. Each custom predicate callable should accept two arguments:context
andrequest
and should return eitherTrue
orFalse
after doing arbitrary evaluation of the context resource and/or the request. If all callables returnTrue
, the associated view callable will be considered viable for a given request.If
custom_predicates
is not specified, no custom predicates are used.predicates
Pass a key/value pair here to use a third-party predicate registered via
pyramid.config.Configurator.add_view_predicate
. More than one key/value pair can be used at the same time. Seeview_and_route_predicates
for more information about third-party predicates.1.4a1
single: view_config decorator
Warning
Using this feature tends to slows down application startup slightly, as more work is performed at application startup to scan for view configuration declarations. For maximum startup performance, use the view configuration method described in mapping_views_using_imperative_config_section
instead.
The ~pyramid.view.view_config
decorator can be used to associate view configuration
information with a function, method, or class that acts as a Pyramid
view callable.
Here's an example of the ~pyramid.view.view_config
decorator that lives within a Pyramid
application module views.py
:
from resources import MyResource
from pyramid.view import view_config
from pyramid.response import Response
@view_config(route_name='ok', request_method='POST', permission='read')
def my_view(request):
return Response('OK')
Using this decorator as above replaces the need to add this imperative configuration stanza:
config.add_view('mypackage.views.my_view', route_name='ok',
request_method='POST', permission='read')
All arguments to view_config
may be omitted. For example:
from pyramid.response import Response
from pyramid.view import view_config
@view_config()
def my_view(request):
""" My view """
return Response()
Such a registration as the one directly above implies that the view name will be my_view
, registered with a context
argument that matches any resource type, using no permission, registered against requests with any request method, request type, request param, route name, or containment.
The mere existence of a @view_config
decorator doesn't suffice to perform view configuration. All that the decorator does is "annotate" the function with your configuration declarations, it doesn't process them. To make Pyramid
process your pyramid.view.view_config
declarations, you must use the scan
method of a pyramid.config.Configurator
:
# config is assumed to be an instance of the
# pyramid.config.Configurator class
config.scan()
Please see decorations_and_code_scanning
for detailed information about what happens when code is scanned for configuration declarations resulting from use of decorators like ~pyramid.view.view_config
.
See configuration_module
for additional API arguments to the ~pyramid.config.Configurator.scan
method. For example, the method allows you to supply a package
argument to better control exactly which code will be scanned.
All arguments to the ~pyramid.view.view_config
decorator mean precisely the same thing as they would if they were passed as arguments to the pyramid.config.Configurator.add_view
method save for the view
argument. Usage of the ~pyramid.view.view_config
decorator is a form of declarative configuration
, while pyramid.config.Configurator.add_view
is a form of imperative
configuration
. However, they both do the same thing.
single: view_config placement
A ~pyramid.view.view_config
decorator can be placed in various points in your application.
If your view callable is a function, it may be used as a function decorator:
from pyramid.view import view_config
from pyramid.response import Response
@view_config(route_name='edit')
def edit(request):
return Response('edited!')
If your view callable is a class, the decorator can also be used as a class decorator in Python 2.6 and better (Python 2.5 and below do not support class decorators). All the arguments to the decorator are the same when applied against a class as when they are applied against a function. For example:
from pyramid.response import Response
from pyramid.view import view_config
@view_config(route_name='hello')
class MyView(object):
def __init__(self, request):
self.request = request
def __call__(self):
return Response('hello')
You can use the ~pyramid.view.view_config
decorator as a simple callable to manually decorate classes in Python 2.5 and below without the decorator syntactic sugar, if you wish:
from pyramid.response import Response
from pyramid.view import view_config
class MyView(object):
def __init__(self, request):
self.request = request
def __call__(self):
return Response('hello')
my_view = view_config(route_name='hello')(MyView)
More than one ~pyramid.view.view_config
decorator can be stacked on top of any number of others. Each decorator creates a separate view registration. For example:
from pyramid.view import view_config
from pyramid.response import Response
@view_config(route_name='edit')
@view_config(route_name='change')
def edit(request):
return Response('edited!')
This registers the same view under two different names.
The decorator can also be used against a method of a class:
from pyramid.response import Response
from pyramid.view import view_config
class MyView(object):
def __init__(self, request):
self.request = request
@view_config(route_name='hello')
def amethod(self):
return Response('hello')
When the decorator is used against a method of a class, a view is registered for the class, so the class constructor must accept an argument list in one of two forms: either it must accept a single argument request
or it must accept two arguments, context, request
.
The method which is decorated must return a response
.
Using the decorator against a particular method of a class is equivalent to using the attr
parameter in a decorator attached to the class itself. For example, the above registration implied by the decorator being used against the amethod
method could be spelled equivalently as the below:
from pyramid.response import Response
from pyramid.view import view_config
@view_config(attr='amethod', route_name='hello')
class MyView(object):
def __init__(self, request):
self.request = request
def amethod(self):
return Response('hello')
single: add_view
The pyramid.config.Configurator.add_view
method within configuration_module
is used to configure a view "imperatively" (without a ~pyramid.view.view_config
decorator). The arguments to this method are very similar to the arguments that you provide to the ~pyramid.view.view_config
decorator. For example:
from pyramid.response import Response
def hello_world(request):
return Response('hello!')
# config is assumed to be an instance of the
# pyramid.config.Configurator class
config.add_view(hello_world, route_name='hello')
The first argument, view
, is required. It must either be a Python object which is the view itself or a dotted Python name
to such an object. In the above example, view
is the hello_world
function. All other arguments are optional. See pyramid.config.Configurator.add_view
for more information.
When you use only ~pyramid.config.Configurator.add_view
to add view configurations, you don't need to issue a scan
in order for the view configuration to take effect.
single: view_defaults class decorator
Note
This feature is new in Pyramid 1.3.
If you use a class as a view, you can use the pyramid.view.view_defaults
class decorator on the class to provide defaults to the view configuration information used by every @view_config
decorator that decorates a method of that class.
For instance, if you've got a class that has methods that represent "REST actions", all which are mapped to the same route, but different request methods, instead of this:
from pyramid.view import view_config
from pyramid.response import Response
class RESTView(object):
def __init__(self, request):
self.request = request
@view_config(route_name='rest', request_method='GET')
def get(self):
return Response('get')
@view_config(route_name='rest', request_method='POST')
def post(self):
return Response('post')
@view_config(route_name='rest', request_method='DELETE')
def delete(self):
return Response('delete')
You can do this:
from pyramid.view import view_defaults
from pyramid.view import view_config
from pyramid.response import Response
@view_defaults(route_name='rest')
class RESTView(object):
def __init__(self, request):
self.request = request
@view_config(request_method='GET')
def get(self):
return Response('get')
@view_config(request_method='POST')
def post(self):
return Response('post')
@view_config(request_method='DELETE')
def delete(self):
return Response('delete')
In the above example, we were able to take the route_name='rest'
argument out of the call to each individual @view_config
statement, because we used a @view_defaults
class decorator to provide the argument as a default to each view method it possessed.
Arguments passed to @view_config
will override any default passed to @view_defaults
.
The view_defaults
class decorator can also provide defaults to the pyramid.config.Configurator.add_view
directive when a decorated class is passed to that directive as its view
argument. For example, instead of this:
from pyramid.response import Response
from pyramid.config import Configurator
class RESTView(object):
def __init__(self, request):
self.request = request
def get(self):
return Response('get')
def post(self):
return Response('post')
def delete(self):
return Response('delete')
if __name__ == '__main__':
config = Configurator()
config.add_route('rest', '/rest')
config.add_view(
RESTView, route_name='rest', attr='get', request_method='GET')
config.add_view(
RESTView, route_name='rest', attr='post', request_method='POST')
config.add_view(
RESTView, route_name='rest', attr='delete', request_method='DELETE')
To reduce the amount of repetion in the config.add_view
statements, we can move the route_name='rest'
argument to a @view_default
class decorator on the RESTView class:
from pyramid.view import view_defaults
from pyramid.view import view_config
from pyramid.response import Response
from pyramid.config import Configurator
@view_defaults(route_name='rest')
class RESTView(object):
def __init__(self, request):
self.request = request
def get(self):
return Response('get')
def post(self):
return Response('post')
def delete(self):
return Response('delete')
if __name__ == '__main__':
config = Configurator()
config.add_route('rest', '/rest')
config.add_view(RESTView, attr='get', request_method='GET')
config.add_view(RESTView, attr='post', request_method='POST')
config.add_view(RESTView, attr='delete', request_method='DELETE')
pyramid.view.view_defaults
accepts the same set of arguments that pyramid.view.view_config
does, and they have the same meaning. Each argument passed to view_defaults
provides a default for the view configurations of methods of the class it's decorating.
Normal Python inheritance rules apply to defaults added via view_defaults
. For example:
@view_defaults(route_name='rest')
class Foo(object):
pass
class Bar(Foo):
pass
The Bar
class above will inherit its view defaults from the arguments passed to the view_defaults
decorator of the Foo
class. To prevent this from happening, use a view_defaults
decorator without any arguments on the subclass:
@view_defaults(route_name='rest')
class Foo(object):
pass
@view_defaults()
class Bar(Foo):
pass
The view_defaults
decorator only works as a class decorator; using it against a function or a method will produce nonsensical results.
single: view security pair: security; view
If an authorization policy
is active, any permission
attached to a view configuration
found during view lookup will be verified. This will ensure that the currently authenticated user possesses that permission against the context
resource before the view function is actually called. Here's an example of specifying a permission in a view configuration using ~pyramid.config.Configurator.add_view
:
# config is an instance of pyramid.config.Configurator
config.add_route('add', '/add.html', factory='mypackage.Blog')
config.add_view('myproject.views.add_entry', route_name='add',
permission='add')
When an authorization policy
is enabled, this view will be protected with the add
permission. The view will not be called if the user does not possess the add
permission relative to the current context
. Instead the forbidden view
result will be returned to the client as per protecting_views
.
single: debugging not found errors single: not found error (debugging)
It's useful to be able to debug NotFound
error responses when they occur unexpectedly due to an application registry misconfiguration. To debug these errors, use the PYRAMID_DEBUG_NOTFOUND
environment variable or the pyramid.debug_notfound
configuration file setting. Details of why a view was not found will be printed to stderr
, and the browser representation of the error will include the same information. See environment_chapter
for more information about how, and where to set these values.
single: HTTP caching
Note
This feature is new in Pyramid 1.1.
When a non-None
http_cache
argument is passed to a view configuration, Pyramid will set Expires
and Cache-Control
response headers in the resulting response, causing browsers to cache the response data for some time. See http_cache
in nonpredicate_view_args
for the allowable values and what they mean.
Sometimes it's undesirable to have these headers set as the result of returning a response from a view, even though you'd like to decorate the view with a view configuration decorator that has http_cache
. Perhaps there's an alternate branch in your view code that returns a response that should never be cacheable, while the "normal" branch returns something that should always be cacheable. If this is the case, set the prevent_auto
attribute of the response.cache_control
object to a non-False
value. For example, the below view callable is configured with a @view_config
decorator that indicates any response from the view should be cached for 3600 seconds. However, the view itself prevents caching from taking place unless there's a should_cache
GET or POST variable:
from pyramid.view import view_config
@view_config(http_cache=3600)
def view(request):
response = Response()
if not 'should_cache' in request.params:
response.cache_control.prevent_auto = True
return response
Note that the http_cache
machinery will overwrite or add to caching headers you set within the view itself unless you use prevent_auto
.
You can also turn off the effect of http_cache
entirely for the duration of a Pyramid application lifetime. To do so, set the PYRAMID_PREVENT_HTTP_CACHE
environment variable or the pyramid.prevent_http_cache
configuration value setting to a true value. For more information, see preventing_http_caching
.
Note that setting pyramid.prevent_http_cache
will have no effect on caching headers that your application code itself sets. It will only prevent caching headers that would have been set by the Pyramid HTTP caching machinery invoked as the result of the http_cache
argument to view configuration.
pair: view configuration; debugging
See displaying_matching_views
for information about how to display each of the view callables that might match for a given URL. This can be an effective way to figure out why a particular view callable is being called instead of the one you'd like to be called.