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 object 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
.authenticated_userid
1.5
A property which returns the
userid
of the currently authenticated user orNone
if there is noauthentication policy
in effect or there is no currently authenticated user. This differs from~pyramid.request.Request.unauthenticated_userid
, because the effective authentication policy will have ensured that a record associated with theuserid
exists in persistent storage; if it has not, this value will beNone
.unauthenticated_userid
1.5
A property which returns a value which represents the claimed (not verified)
userid
of the credentials present in the request.None
if there is noauthentication policy
in effect or there is no user data associated with the current request. This differs from~pyramid.request.Request.authenticated_userid
, because the effective authentication policy will not ensure that a record associated with theuserid
exists in persistent storage. Even if theuserid
does not exist in persistent storage, this value will be the value of theuserid
claimed by the request data.effective_principals
1.5
A property which returns the list of 'effective'
principal
identifiers for this request. This list typically includes theuserid
of the currently authenticated user if a user is currently authenticated, but this depends on theauthentication policy
in effect. If noauthentication policy
is in effect, this will return a sequence containing only thepyramid.security.Everyone
principal.invoke_subrequest(request, use_tweens=False)
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
) on the request it's passed.- causes a
~pyramid.events.NewRequest
event to be sent at the beginning of request processing.- causes a
~pyramid.events.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.
- Calls any
response callback
functions defined within the request's lifetime if a response is obtained from the Pyramid application.- causes a
~pyramid.events.NewResponse
event to be sent if a response is obtained.- 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.See also
subrequest_chapter
.invoke_exception_view
has_permission
add_response_callback
add_finished_callback
route_url
route_path
current_route_url
current_route_path
static_url
static_path
resource_url
resource_path
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(request): # since version 1.5, request.exception is no # longer eagerly cleared if request.exception is not None: conn.rollback() else: conn.commit() 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
localizer
A
localizer
which will use the current locale name to translate values.1.5
locale_name
The locale name of the current request as computed by the
locale negotiator
.1.5
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
.
apply_request_extensions(request)