request.rst

pyramid.request

pyramid.request

Request

context

The context will be available as the context attribute of the request object. It will be the context object implied by the current request. See traversal_chapter for information about context objects.

registry

The application registry will be available as the registry attribute of the request object. See zca_chapter for more information about the application registry.

root

The root object will be available as the root attribute of the request object. It will be the resource object at which traversal started (the root). See traversal_chapter for information about root objects.

subpath

The traversal subpath will be available as the subpath attribute of the request object. It will be a sequence containing zero or more elements (which will be Unicode objects). See traversal_chapter for information about the subpath.

traversed

The "traversal path" will be available as the traversed attribute of the request object. It will be a sequence representing the ordered set of names that were used to traverse to the context, 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. See traversal_chapter for more information.

view_name

The view name will be available as the view_name attribute of the request object. It will be a single string (possibly the empty string if we're rendering a default view). See traversal_chapter for information about view names.

virtual_root

The virtual root will be available as the virtual_root attribute of the request object. It will be the virtual root object implied by the current request. See vhosting_chapter for more information about virtual roots.

virtual_root_path

The virtual root path will be available as the virtual_root_path attribute of the request object. It will be a sequence representing the ordered set of names that were used to traverse to the virtual root object. See vhosting_chapter for more information about virtual roots.

exception

If an exception was raised by a root factory or a view callable, or at various other points where Pyramid executes user-defined code during the processing of a request, the exception object which was caught will be available as the exception attribute of the request within a exception view, a response callback or a finished callback. If no exception occurred, the value of request.exception will be None within response and finished callbacks.

exc_info

If an exception was raised by a root factory or a view callable, or at various other points where Pyramid executes user-defined code during the processing of a request, result of sys.exc_info() will be available as the exc_info attribute of the request within a exception view, a response callback or a finished callback. If no exception occurred, the value of request.exc_info will be None 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 accessing request.response. Therefore, it's possible to use the request.response API to set up a response object with "the right" attributes (e.g. by calling request.response.set_cookie(...) or request.response.content_type = 'text/plain', etc) within a view that uses a renderer. For example, within a view that uses a renderer:

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, see request_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's session object. If a session factory has not been configured, requesting the request.session attribute will cause a pyramid.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 be None. See matchdict.

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 be None. See matched_route.

authenticated_userid

A property which returns the userid of the currently authenticated user or None if there is no security policy in effect or there is no currently authenticated user.

unauthenticated_userid

2.0

unauthenticated_userid has been deprecated in version 2.0. Use authenticated_userid or authenticated_identity instead. See upgrading_auth for more information.

A property which returns a value which represents the claimed (not verified) userid of the credentials present in the request. None if there is no authentication 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 the userid exists in persistent storage. Even if the userid does not exist in persistent storage, this value will be the value of the userid claimed by the request data.

effective_principals

2.0

The new security policy has removed the concept of principals. See upgrading_auth for more information.

A property which returns the list of 'effective' principal identifiers for this request. This list typically includes the userid of the currently authenticated user if a user is currently authenticated, but this depends on the authentication policy in effect. If no authentication policy is in effect, this will return a sequence containing only the pyramid.authorization.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. The request object must be an object that implements the Pyramid request interface (such as a pyramid.request.Request instance). If use_tweens is True, the request will be sent to the tween in the tween stack closest to the request ingress. If use_tweens is False, 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 a invoke_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. the pshell 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

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 setting reify=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 a ValueError will be raised if name is None or reify is True.

If name is None, the name of the property will be computed from the name of the callable.

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 if request.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)

RequestLocalCache