pyramid.request
Request
context
The
context
will be available as thecontext
attribute of therequest
object. It will be the context object implied by the current request. Seetraversal_chapter
for information about context objects.registry
The
application registry
will be available as theregistry
attribute of therequest
object. Seezca_chapter
for more information about the application registry.root
The
root
object will be available as theroot
attribute of therequest
object. It will be the resource object at which traversal started (the root). Seetraversal_chapter
for information about root objects.subpath
The traversal
subpath
will be available as thesubpath
attribute of therequest
object. It will be a sequence containing zero or more elements (which will be Unicode objects). Seetraversal_chapter
for information about the subpath.traversed
The "traversal path" will be available as the
traversed
attribute of therequest
object. It will be a sequence representing the ordered set of names that were used to traverse to thecontext
, not including the view name or subpath. If there is a virtual root associated with the request, the virtual root path is included within the traversal path. Seetraversal_chapter
for more information.view_name
The
view name
will be available as theview_name
attribute of therequest
object. It will be a single string (possibly the empty string if we're rendering a default view). Seetraversal_chapter
for information about view names.virtual_root
The
virtual root
will be available as thevirtual_root
attribute of therequest
object. It will be the virtual root object implied by the current request. Seevhosting_chapter
for more information about virtual roots.virtual_root_path
The
virtual root
path will be available as thevirtual_root_path
attribute of therequest
object. It will be a sequence representing the ordered set of names that were used to traverse to the virtual root object. Seevhosting_chapter
for more information about virtual roots.exception
If an exception was raised by a
root factory
or aview callable
, or at various other points wherePyramid
executes user-defined code during the processing of a request, the exception object which was caught will be available as theexception
attribute of the request within aexception view
, aresponse callback
or afinished callback
. If no exception occurred, the value ofrequest.exception
will beNone
within response and finished callbacks.exc_info
If an exception was raised by a
root factory
or aview callable
, or at various other points wherePyramid
executes user-defined code during the processing of a request, result ofsys.exc_info()
will be available as theexc_info
attribute of the request within aexception view
, aresponse callback
or afinished callback
. If no exception occurred, the value ofrequest.exc_info
will beNone
within response and finished callbacks.response
This attribute is actually a "reified" property which returns an instance of the
pyramid.response.Response
class. The response object returned does not exist until this attribute is accessed. Once it is accessed, subsequent accesses to this request object will return the same~pyramid.response.Response
object.The
request.response
API can is used by renderers. A render obtains the response object it will return from a view that uses that renderer by accessingrequest.response
. Therefore, it's possible to use therequest.response
API to set up a response object with "the right" attributes (e.g. by callingrequest.response.set_cookie(...)
orrequest.response.content_type = 'text/plain'
, etc) within a view that uses a renderer. For example, within a view that uses arenderer
:response = request.response response.set_cookie('mycookie', 'mine, all mine!') return {'text':'Value that will be used by the renderer'}
Mutations to this response object will be preserved in the response sent to the client after rendering. For more information about using
request.response
in conjunction with a renderer, seerequest_response_attr
.Non-renderer code can also make use of request.response instead of creating a response "by hand". For example, in view code:
response = request.response response.body = 'Hello!' response.content_type = 'text/plain' return response
Note that the response in this circumstance is not "global"; it still must be returned from the view code if a renderer is not used.
session
If a
session factory
has been configured, this attribute will represent the current user'ssession
object. If a session factory has not been configured, requesting therequest.session
attribute will cause apyramid.exceptions.ConfigurationError
to be raised.matchdict
If a
route
has matched during this request, this attribute will be a dictionary containing the values matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will beNone
. Seematchdict
.matched_route
If a
route
has matched during this request, this attribute will be an obect representing the route matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will beNone
. Seematched_route
.invoke_subrequest(request, use_tweens=False)
Warning
This API was added in Pyramid 1.4a1.
Obtain a response object from the Pyramid application based on information in the
request
object provided. Therequest
object must be an object that implements the Pyramid request interface (such as apyramid.request.Request
instance). Ifuse_tweens
isTrue
, the request will be sent to thetween
in the tween stack closest to the request ingress. Ifuse_tweens
isFalse
, the request will be sent to the main router handler, and no tweens will be invoked.This function also:
- manages the threadlocal stack (so that
~pyramid.threadlocal.get_current_request
and~pyramid.threadlocal.get_current_registry
work during a request)- Adds a
registry
attribute (the current Pyramid registry) and ainvoke_subrequest
attribute (a callable) to the request object it's handed.- sets request extensions (such as those added via
~pyramid.config.Configurator.add_request_method
or~pyramid.config.Configurator.set_request_property
) on the request it's passed.- causes a
~pyramid.event.NewRequest
event to be sent at the beginning of request processing.- causes a
~pyramid.event.ContextFound
event to be sent when a context resource is found.- Ensures that the user implied by the request passed has the necessary authorization to invoke view callable before calling it.
- causes a
~pyramid.event.NewResponse
event to be sent when the Pyramid application returns a response.- Calls any
response callback
functions defined within the request's lifetime if a response is obtained from the Pyramid application.- Calls any
finished callback
functions defined within the request's lifetime.
invoke_subrequest
isn't actually a method of the Request object; it's a callable added when the Pyramid router is invoked, or when a subrequest is invoked. This means that it's not available for use on a request provided by e.g. thepshell
environment. For more information, seesubrequest_chapter
.add_response_callback
add_finished_callback
route_url
route_path
current_route_url
current_route_path
static_url
static_path
resource_url
resource_path
In Pyramid 1.0, you could set attributes on a
pyramid.request.Request
which influenced the behavor of rendered responses (views which use arenderer
and which don't directly return a response). These attributes began withresponse_
, such asresponse_headerlist
. If you needed to influence response values from a view that uses a renderer (such as the status code, a header, the content type, etc) you would set these attributes. Seeresponse_prefixed_attrs
for further discussion. As of Pyramid 1.1, assignment toresponse_*
attrs are deprecated. Assigning to one is still supported but will cause a deprecation warning to be emitted, and eventually the feature will be removed. For new code, instead of assigningresponse_*
attributes to the request, use API of the thepyramid.request.Request.response
object (exposed to view code asrequest.response
) to influence rendered response behavior.json_body
This property will return the JSON-decoded variant of the request body. If the request body is not well-formed JSON, or there is no body associated with this request, this property will raise an exception. See also
request_json_body
.set_property(callable, name=None, reify=False)
Add a callable or a property descriptor to the request instance.
Properties, unlike attributes, are lazily evaluated by executing an underlying callable when accessed. They can be useful for adding features to an object without any cost if those features go unused.
A property may also be reified via the
pyramid.decorator.reify
decorator by settingreify=True
, allowing the result of the evaluation to be cached. Thus the value of the property is only computed once for the lifetime of the object.
callable
can either be a callable that accepts the request as its single positional parameter, or it can be a property descriptor.If the
callable
is a property descriptor aValueError
will be raised ifname
isNone
orreify
isTrue
.If
name
is None, the name of the property will be computed from the name of thecallable
.def _connect(request): conn = request.registry.dbsession() def cleanup(_): conn.close() request.add_finished_callback(cleanup) return conn @subscriber(NewRequest) def new_request(event): request = event.request request.set_property(_connect, 'db', reify=True)The subscriber doesn't actually connect to the database, it just provides the API which, when accessed via
request.db
, will create the connection. Thanks to reify, only one connection is made per-request even ifrequest.db
is accessed many times.This pattern provides a way to augment the
request
object without having to subclass it, which can be useful for extension authors.1.3
Note
For information about the API of a multidict
structure (such as that used as request.GET
, request.POST
, and request.params
), see pyramid.interfaces.IMultiDict
.