repoze.bfg.request

class Request(environ=None, environ_getter=None, charset=(No Default), unicode_errors=(No Default), decode_param_names=(No Default), **kw)

A subclass of the WebOb Request class. An instance of this class is created by the router and is provided to a view callable (and to other subsystems) as the request argument.

The documentation below (save for the add_response_callback and ‘’add_finished_callback`` methods, which are defined in this subclass itself, and the attributes context, registry, root, subpath, traversed, view_name, virtual_root , and virtual_root_path, each of which is added to the request at by the router at request ingress time) are autogenerated from the WebOb source code used when this documentation was generated.

Due to technical constraints, we can’t yet display the WebOb version number from which this documentation is autogenerated, but it will be the ‘prevailing WebOb version’ at the time of the release of this repoze.bfg version. See http://http://pythonpaste.org/webob/ for further information.

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 for information about context objects.

registry

The application registry will be available as the registry attribute of the request object. See Using the Zope Component Architecture in repoze.bfg 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 model object at which traversal started (the root). See Traversal 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 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 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 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 Virtual Hosting 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 Virtual Hosting 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 repoze.bfg 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.

Note

The exception attribute is new in repoze.bfg 1.3.

GET

Like .str_GET, but may decode values and keys

POST

Like .str_POST, but may decode values and keys

ResponseClass

alias of Response

accept

Gets and sets and deletes the ‘HTTP_ACCEPT’ key from the environment. For more information on Accept see section 14.1. Converts it as a MIME Accept.

accept_charset

Gets and sets and deletes the ‘HTTP_ACCEPT_CHARSET’ key from the environment. For more information on Accept-Charset see section 14.2. Converts it as a accept header.

accept_encoding

Gets and sets and deletes the ‘HTTP_ACCEPT_ENCODING’ key from the environment. For more information on Accept-Encoding see section 14.3. Converts it as a accept header.

accept_language

Gets and sets and deletes the ‘HTTP_ACCEPT_LANGUAGE’ key from the environment. For more information on Accept-Language see section 14.4. Converts it as a accept header.

add_finished_callback(callback)

Add a callback to the set of callbacks to be called unconditionally by the router at the very end of request processing.

callback is a callable which accepts a single positional parameter: request. For example:

import transaction

def commit_callback(request):
    '''commit or abort the transaction associated with request'''
    if request.exception is not None:
        transaction.abort()
    else:
        transaction.commit()
request.add_finished_callback(commit_callback)

Finished callbacks are called in the order they’re added ( first- to most-recently- added). Finished callbacks (unlike response callbacks) are always called, even if an exception happens in application code that prevents a response from being generated.

The set of finished callbacks associated with a request are called very late in the processing of that request; they are essentially the last thing called by the router. They are called after response processing has already occurred in a top-level finally: block within the router request processing code. As a result, mutations performed to the request provided to a finished callback will have no meaningful effect, because response processing will have already occurred, and the request’s scope will expire almost immediately after all finished callbacks have been processed.

Errors raised by finished callbacks are not handled specially. They will be propagated to the caller of the repoze.bfg router application.

See also: Using Finished Callbacks.

add_response_callback(callback)

Add a callback to the set of callbacks to be called by the router at a point after a response object is successfully created. repoze.bfg does not have a global response object: this functionality allows an application to register an action to be performed against the response once one is created.

A ‘callback’ is a callable which accepts two positional parameters: request and response. For example:

def cache_callback(request, response):
    'Set the cache_control max_age for the response'
    response.cache_control.max_age = 360
request.add_response_callback(cache_callback)

Response callbacks are called in the order they’re added (first-to-most-recently-added). No response callback is called if an exception happens in application code, or if the response object returned by view code is invalid.

All response callbacks are called after the repoze.bfg.interfaces.INewResponse event is sent.

Errors raised by callbacks are not handled specially. They will be propagated to the caller of the repoze.bfg router application.

See also: Using Response Callbacks.

application_url

The URL including SCRIPT_NAME (no PATH_INFO or query string)

classmethod blank(path, environ=None, base_url=None, headers=None, **kw)

Create a blank request environ (and Request wrapper) with the given path (path should be urlencoded), and any keys from environ.

The path will become path_info, with any query string split off and used.

All necessary keys will be added to the environ, but the values you pass in will take precedence. If you pass in base_url then wsgi.url_scheme, HTTP_HOST, and SCRIPT_NAME will be filled in from that value.

Any extra keyword will be passed to __init__ (e.g., decode_param_names).

body

Return the content of the request body.

body_file

Access the body of the request (wsgi.input) as a file-like object.

If you set this value, CONTENT_LENGTH will also be updated (either set to -1, 0 if you delete the attribute, or if you set the attribute to a string then the length of the string).

cache_control

Get/set/modify the Cache-Control header (section 14.9)

call_application(application, catch_exc_info=False)

Call the given WSGI application, returning (status_string, headerlist, app_iter)

Be sure to call app_iter.close() if it’s there.

If catch_exc_info is true, then returns (status_string, headerlist, app_iter, exc_info), where the fourth item may be None, but won’t be if there was an exception. If you don’t do this and there was an exception, the exception will be raised directly.

content_length

Gets and sets and deletes the ‘CONTENT_LENGTH’ key from the environment. For more information on CONTENT_LENGTH see section 14.13. Converts it as a int.

content_type

Gets and sets and deletes the ‘CONTENT_TYPE’ key from the environment. For more information on CONTENT_TYPE see section 14.17.

cookies

Like .str_cookies, but may decode values and keys

copy()

Copy the request and environment object.

This only does a shallow copy, except of wsgi.input

copy_body()

Copies the body, in cases where it might be shared with another request object and that is not desired.

This copies the body in-place, either into a StringIO object or a temporary file.

copy_get()

Copies the request and environment object, but turning this request into a GET along the way. If this was a POST request (or any other verb) then it becomes GET, and the request body is thrown away.

date

Gets and sets and deletes the ‘HTTP_DATE’ key from the environment. For more information on Date see section 14.8. Converts it as a HTTP date.

get_response(application, catch_exc_info=False)

Like .call_application(application), except returns a response object with .status, .headers, and .body attributes.

This will use self.ResponseClass to figure out the class of the response object to return.

headers

All the request headers as a case-insensitive dictionary-like object.

host

Host name provided in HTTP_HOST, with fall-back to SERVER_NAME

host_url

The URL through the host (no path)

if_match

Gets and sets and deletes the ‘HTTP_IF_MATCH’ key from the environment. For more information on If-Match see section 14.24. Converts it as a ETag.

if_modified_since

Gets and sets and deletes the ‘HTTP_IF_MODIFIED_SINCE’ key from the environment. For more information on If-Modified-Since see section 14.25. Converts it as a HTTP date.

if_none_match

Gets and sets and deletes the ‘HTTP_IF_NONE_MATCH’ key from the environment. For more information on If-None-Match see section 14.26. Converts it as a ETag.

if_range

Gets and sets and deletes the ‘HTTP_IF_RANGE’ key from the environment. For more information on If-Range see section 14.27. Converts it as a IfRange object.

if_unmodified_since

Gets and sets and deletes the ‘HTTP_IF_UNMODIFIED_SINCE’ key from the environment. For more information on If-Unmodified-Since see section 14.28. Converts it as a HTTP date.

is_xhr

Returns a boolean if X-Requested-With is present and XMLHttpRequest

Note: this isn’t set by every XMLHttpRequest request, it is only set if you are using a Javascript library that sets it (or you set the header yourself manually). Currently Prototype and jQuery are known to set this header.

make_body_seekable()

This forces environ['wsgi.input'] to be seekable. That is, if it doesn’t have a seek method already, the content is copied into a StringIO or temporary file.

The choice to copy to StringIO is made from self.request_body_tempfile_limit

max_forwards

Gets and sets and deletes the ‘HTTP_MAX_FORWARDS’ key from the environment. For more information on Max-Forwards see section 14.31. Converts it as a int.

method

Gets and sets and deletes the ‘REQUEST_METHOD’ key from the environment.

params

Like .str_params, but may decode values and keys

path

The path of the request, without host or query string

path_info

Gets and sets and deletes the ‘PATH_INFO’ key from the environment.

path_info_peek()

Returns the next segment on PATH_INFO, or None if there is no next segment. Doesn’t modify the environment.

path_info_pop()

‘Pops’ off the next segment of PATH_INFO, pushing it onto SCRIPT_NAME, and returning the popped segment. Returns None if there is nothing left on PATH_INFO.

Does not return '' when there’s an empty segment (like /path//path); these segments are just ignored.

path_qs

The path of the request, without host but with query string

path_url

The URL including SCRIPT_NAME and PATH_INFO, but not QUERY_STRING

postvars

Wraps a decorator, with a deprecation warning or error

pragma

Gets and sets and deletes the ‘HTTP_PRAGMA’ key from the environment. For more information on Pragma see section 14.32.

query_string

Gets and sets and deletes the ‘QUERY_STRING’ key from the environment.

queryvars

Wraps a decorator, with a deprecation warning or error

range

Gets and sets and deletes the ‘HTTP_RANGE’ key from the environment. For more information on Range see section 14.35. Converts it as a Range object.

referer

Gets and sets and deletes the ‘HTTP_REFERER’ key from the environment. For more information on Referer see section 14.36.

referrer

Gets and sets and deletes the ‘HTTP_REFERER’ key from the environment. For more information on Referer see section 14.36.

relative_url(other_url, to_application=False)

Resolve other_url relative to the request URL.

If to_application is True, then resolve it relative to the URL with only SCRIPT_NAME

remote_addr

Gets and sets and deletes the ‘REMOTE_ADDR’ key from the environment.

remote_user

Gets and sets and deletes the ‘REMOTE_USER’ key from the environment.

remove_conditional_headers(remove_encoding=True, remove_range=True, remove_match=True, remove_modified=True)

Remove headers that make the request conditional.

These headers can cause the response to be 304 Not Modified, which in some cases you may not want to be possible.

This does not remove headers like If-Match, which are used for conflict detection.

scheme

Gets and sets and deletes the ‘wsgi.url_scheme’ key from the environment.

script_name

Gets and sets and deletes the ‘SCRIPT_NAME’ key from the environment.

server_name

Gets and sets and deletes the ‘SERVER_NAME’ key from the environment.

server_port

Gets and sets and deletes the ‘SERVER_PORT’ key from the environment. Converts it as a int.

str_GET

Return a MultiDict containing all the variables from the QUERY_STRING.

str_POST

Return a MultiDict containing all the variables from a form request. Returns an empty dict-like object for non-form requests.

Form requests are typically POST requests, however PUT requests with an appropriate Content-Type are also supported.

str_cookies

Return a plain dictionary of cookies as found in the request.

str_params

A dictionary-like object containing both the parameters from the query string and request body.

str_postvars

Wraps a decorator, with a deprecation warning or error

str_queryvars

Wraps a decorator, with a deprecation warning or error

url

The full request URL, including QUERY_STRING

urlargs

Return any positional variables matched in the URL.

Takes values from environ['wsgiorg.routing_args']. Systems like routes set this value.

urlvars

Return any named variables matched in the URL.

Takes values from environ['wsgiorg.routing_args']. Systems like routes set this value.

user_agent

Gets and sets and deletes the ‘HTTP_USER_AGENT’ key from the environment. For more information on User-Agent see section 14.43.