See ApplicationReference for other objects and interfaces.

Request Object

This page describes the attributes of the cherrypy request object; it also says when these attributes are set by the core, and what happens when you change them. The order of phases is as follows:

init
run
    try:
        process headers
        get resource (dispatch)
        configure
        - on_start_resource hook
        - before_request_body hook
        process_body
        - before_handler hook
        handler
        - before_finalize hook
        finalize
    except:
        - before_error_response hook
        error response
        - after_error_response hook
        finalize
- on_end_request hook
close

---

app

The Application object which is handling this request.

base

A string containing the "base URL" of the request, which consists of scheme://host:port/virtualhost (the port and virtualhost are optional). Set in the "process headers" phase.

body

This attribute is the request entity body, if applicable. See process_request_body, below.

close

Runs cleanup code. This method is automatically called by the core.

closed

A bool indicated whether the close method has been called. For application code, this should always be True.

config

A flat dict of all configuration entries which apply to the current request. Set in the "dispatch" phase. The dispatcher collects and merges entries from global config, application config (based on request.path_info), and from handler config. The collection of handler config is governed by the request.dispatch object in effect for this request; by default, handler config can be attached anywhere in the tree between request.app.root and the final handler, and inherits downward.

cookie

A instance of Cookie.SimpleCookie, containing the cookies sent in the request. Set in the "process_headers" phase.

dispatch

The object which looks up the 'page handler' callable and collects config for the current request based on the path_info, other request attributes, and the application architecture. The core calls the dispatcher as early as possible, passing it a 'path_info' argument.

The default dispatcher discovers the page handler by matching path_info to a hierarchical arrangement of objects, starting at request.app.root. Each hierarchical component in the path_info argument is matched to a corresponding nested attribute of the root object. Matching handlers must have an 'exposed' attribute which evaluates to True. The special method name "index" matches a URI which ends in a slash ("/"). The special method name "default" may match a portion of the path_info (but only when no longer substring of the path_info matches some other object.

error_page

A dict of {error code: response filename} pairs. The named response files should be Python string-formatting templates, and can expect by default to receive the format values with the mapping keys 'status', 'message', 'traceback', and 'version'. The set of format mappings can be extended by overriding HTTPError.set_response. See ErrorsAndExceptions.

error_response

The no-arg callable which will handle unexpected, untrapped errors during request processing. This is not used for expected exceptions (like NotFound?, HTTPError, or HTTPRedirect) which are raised in response to expected conditions (those should be customized either via request.error_page or by overriding HTTPError.set_response). By default, error_response uses HTTPError(500) to return a generic error response to the user-agent. See ErrorsAndExceptions.

get_resource

Internal method to find and call a dispatcher (which sets request.handler and request.config).

handle_error

Internal method which handles the most recent unanticipated exception.

handler

The function, method, or other callable which CherryPy will call to produce the response. The discovery of the handler and the arguments it will receive are determined by the request.dispatch object in the "dispatch" phase. By default, the handler is discovered by walking a tree of objects starting at request.app.root, and is then passed all HTTP params (from the query string and POST body) as keyword arguments.

This is called a "handler" after Fielding's usage: "The resource is a conceptual mapping -- the server receives the identifier (which identifies the mapping) and applies it to its current mapping implementation (usually a combination of collection-specific deep tree traversal and/or hash tables) to find the currently responsible handler implementation and the handler implementation then selects the appropriate action+response based on the request content."

header_list

A list containing the HTTP headers that were sent in the request. Set in the "run" phase.

headers

A dict containing the HTTP headers that were sent in the request. Set from header_list in the "process headers" phase. The keys of this dict are automatically title-cased (e.g., "Content-Type"), but you can use any case to interact with it (e.g. headers['content-type'] is just fine). Since it's a dictionary, no duplicates are allowed. If you encounter the extremely rare case where duplicate headers (or the case of header keys, or the order of headers) are important, use header_list instead.

hooks

A HookMap? (dict-like object) of the form: {hookpoint: [hook, ...]}. Each key is a str naming the hook point, and each value is a list of hooks which will be called at that hook point during this request. Each list of hooks is generally populated as early as possible (mostly from Tools specified in config), but may be extended at any time.

Framework authors are free to add keys in order to register new hook points.

local

An instance of http.Host, which has the following members:

• local.ip: a string containing the IP address of the server. This is not available when using WSGI (the default).
• local.port: an int containing the TCP port number of the server.
• local.name: a string containing the hostname of the server.

Set in the "init" phase.

method

A string containing the HTTP method, such as "GET" or "POST". Set in the "run" phase.

methods_with_bodies

A sequence of HTTP methods for which CherryPy will automatically attempt to read a body from the rfile. Defaults to ("POST", "PUT").

namespaces

A NamespaceSet?; a dict of config namespace names and handlers.

Each config entry should begin with a namespace name; the corresponding namespace handler will be called once for each config entry in that namespace, and will be passed two arguments: the config key (with the namespace removed) and the config value.

Namespace handlers may be any Python callable; they may also be Python 2.5-style 'context managers', in which case their enter method should return a callable to be used as the handler. See ConfigAPI.

params

A dict containing the parameters sent in the request, either in the query string or in the request body. Values from the query string are added in the "process headers" phase. Values from the request body are added in the "process body" phase.

path_info

A string containing the "path_info" portion of the requested URL. Set in the "run" phase. This value should always start with a forward slash ("/"). Changing this value in hooks and tools has no effect on dispatch.

process_body

Internal method which converts request.rfile into request.params (or request.body).

process_headers

Internal method which parses the HTTP header data into Python structures.

process_request_body

A boolean to tell CherryPy whether to parse the request rfile or not. Set it to False in a "before_request_body" hook to tell CherryPy not to parse the request rfile. The rfile will usually have data when the request method is POST or PUT; CherryPy usually sets process_request_body for you based on the request method.

If True, then request.rfile will be consumed by CherryPy (and unreadable after that). If the request Content-Type is "application/x-www-form-urlencoded", then the rfile will be parsed and placed into request.params; otherwise, it will be available in request.body.

If False, then the rfile is not consumed; other code (your page handler, or a tool) must read it.

protocol

The HTTP protocol version corresponding to the set of features which should be allowed in the response. If BOTH the client's request message AND the server's level of HTTP compliance is HTTP/1.1, this attribute will be the tuple (1, 1). If either is 1.0, this attribute will be the tuple (1, 0). Lower HTTP protocol versions are not explicitly supported.

The protocol version of the request can be found in request.request_line, but should rarely be used. See RFC 2145 for a detailed explanation. The protocol version of the server can be found in request.server_protocol.

query_string

A string containing the query string of the request (the part of the URL following '?').

remote

An instance of http.Host, which has the following members:

• remote.ip: a string containing the IP address of the client.
• remote.port: an int containing the TCP port number of the client.
• remote.name: a string containing the hostname of the client. If "reverse DNS" is not used, then remote.name is the same as remote.ip. In practice, this value is not reliable due to the rarity of reverse DNS, the unreliability of some proxies, and the ease of forgery.

Set in the "init" phase.

request_line

A string containing the first line of the request, of the form "GET /path/to/page HTTP/1.1". Set in the "run" phase.

respond

Internal method which generates a response for the resource at request.path_info.

rfile

The incoming request stream, a file-like object available for reading the request body. If process_request_body is True (the default), CherryPy will read the contents for you and place them in request.params or request.body (as appropriate) in the "process body" phase.

run

Internal method which processes the request.

scheme

A string containing the URL scheme used in this request. It is either "http" or "https".

script_name

The 'mount point' of the application which is handling this request. It MUST NOT end in a slash. If the script_name refers to the root of the URI, it MUST be an empty string (not "/").

server_protocol

A string containing the HTTP protocol of the server, in the form of "HTTP/1.1". The only other meaningful value will be "HTTP/1.0".

show_tracebacks

If True, unexpected errors encountered during request processing will include a traceback in the response body.

throw_errors

If True, Request.run will not trap any errors (except HTTPRedirect and HTTPError, which are more properly called 'exceptions', not errors).

throws

The sequence of exceptions which Request.run does not trap.

toolmaps

A nested dict of all Toolboxes and Tools in effect for this request, of the form: {Toolbox.namespace: {Tool.name: config dict}}.

wsgi_environ

A dictionary containing the WSGI environment for the request. In non-WSGI settings (i.e., custom HTTP servers), it is absent.

Older versions

2.2

replace this	with this
request.cookie	request.simple_cookie
request.process_request_body	request.processRequestBody

• request.browser_url: A string containing the URL the client requested. By default, it is equal to request.base + request.path, plus the querystring, if provided.
• request.object_path: A string containing the path of the exposed method that will be called to handle this request. This is usually the same as cherrypy.request.path, but can be changed in a filter to change which method is actually called.
• request.original_path: A string containing the original value of cherrypy.request.path, in case it is modified by a filter during the request.
• request.original_params: A string containing the original value of cherrypy.request.params, in case it is modified by a filter during the request.
• request.version: A Version object which represents the HTTP protocol. It's the same as request.protocol, but allows easy comparisons like if cherrypy.request.version >= "1.1": do_http_1_1_thing().