# API reference

## cherrypy.threadData

This attribute holds attributes that map to this thread only.

## cherrypy.request

### cherrypy.request.remoteAddr

This attribute is a string containing the IP address of the client. It will be an empty string if it is not available.

### cherrypy.request.remotePort

This attribute is an int containing the TCP port number of the client. It will be -1 if it is not available.

### cherrypy.request.remoteHost

This attribute is a string containing the remote hostname of the client.

### cherrypy.request.headerMap

This attribute is a dictionary containing the received HTTP headers, with automatically titled keys (e.g., "Content-Type"). As it's a dictionary, no duplicates are allowed.

### cherrypy.request.headers

This attribute is a list of (header, value) tuples containing the received HTTP headers. In general, you probably want to use headerMap instead; this is only here in case you need to inspect duplicates in the request headers.

### cherrypy.request.requestLine

This attribute is a string containing the first line of the raw HTTP request; for example, "GET /path/page HTTP/1.1".

### cherrypy.request.simpleCookie

This attribute is a SimpleCookie instance from the standard library's Cookie module which contains the incoming cookie values from the client.

### cherrypy.request.rfile

This attribute is the input stream to the client, if applicable. See cherrypy.request.processRequestBody for more information.

### cherrypy.request.body

This attribute is the request entity body, if applicable. See cherrypy.request.processRequestBody for more information.

### cherrypy.request.processRequestBody

This attribute specifies whether or not the request's body (request.rfile, which is POST or PUT data) will be handled by CherryPy. If True (the default for POST and PUT requests), 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.paramMap; otherwise, it will be available in request.body. If cherrypy.request.processRequestBody is False, then the rfile is not consumed, but will be readable by the exposed method.

### cherrypy.request.method

This attribute is a string containing the HTTP request method, such as GET or POST.

### cherrypy.request.protocol

This attribute is a string containing the HTTP protocol of the request in the form of HTTP/x.x

### cherrypy.request.version

This attribute is a Version object which represents the HTTP protocol. It's the same os request.protocol, but allows easy comparisons like `if cherrypy.request.version >= "1.1": do_http_1_1_thing`.

### cherrypy.request.queryString

This attribute is a string containing the query string of the request (the part of the URL following '?').

### cherrypy.request.path

This attribute is a string containing the path of the resource the client requested.

### cherrypy.request.paramMap

This attribute is a dictionary containing the query string and POST arguments of this request.

### cherrypy.request.base

This attribute is a string containing the root URL of the server. By default, it is equal to request.scheme://request.headerMap['Host'].

### cherrypy.request.browserUrl

This attribute is a string containing the URL the client requested. By default, it is equal to `request.base + request.path`.

### cherrypy.request.objectPath

This attribute is 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.

### cherrypy.request.originalPath

This attribute is a string containing the original value of cherrypy.request.path, in case it is modified by a filter during the request.

### cherrypy.request.originalParamMap

This attribute is a string containing the original value of cherrypy.request.paramMap, in case it is modified by a filter during the request.

### cherrypy.request.scheme

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

## cherrypy.response

### cherrypy.response.headerMap

This attribute is a dictionary with automatically titled keys (e.g., "Content-Length"). It holds all outgoing HTTP headers to the client.

### cherrypy.response.headers

This attribute is a list of (header, value) tuples. It's not available until the response has been finalized; it's really only there in the extremely rare cases when you need duplicate response headers. In general, you should use request.headerMap instead.

### cherrypy.response.simpleCookie

This attribute is a SimpleCookie instance from the standard library's Cookie module. It contains the outgoing cookie values.

### cherrypy.response.body

This attribute is originally just the return value of the exposed method, but by the end of the request it must be an iterable (usually a list or generator of strings) which will be the content of the HTTP response.

### cherrypy.response.status

This attribute is a string containing the HTTP response code in the form "### Reason-Phrase", i.e. "200 OK". You may also set it to an int, in which case the response finalization process will supply a Reason-Phrase for you.

### cherrypy.response.version

This attribute is a Version object, representing the HTTP protocol version of the response. This is not necessarily the value that will be written in the response! Instead, it should be used to determine which features are available for the response. For example, an HTTP server may send an HTTP/1.1 response even though the client is known to only understand HTTP/1.0—the response.version will be set to Version("1.0") to inform you of this, so that you (and CherryPy) can restrict the response to HTTP/1.0 features only.

## cherrypy.server

### cherrypy.server.start(initOnly=False, serverClass=_missing)

Start the CherryPy Server. Simple websites may call this without any arguments, to run the default server. If initOnly is False (the default), this function will block until KeyboardInterrupt or SystemExit is raised, so that the process will persist. When using one of the built-in HTTP servers, you should leave this set to False. You should only set it to True if you're running CherryPy as an extension to another HTTP server (for example, when using Apache and mod_python with CherryPy), in which case the foreign HTTP server should do its own process-management.

Use the serverClass argument to specify that you wish to use an HTTP server other than the default, built-in WSGIServer. If missing, config.get("server.class") will be checked for an alternate value; otherwise, the default is used. Possible alternate values (you may pass the class names as a string if you wish):

- `cherrypy._cphttpserver.CherryHTTPServer`: this will load the old, single-threaded built-in HTTP server. This server is deprecated and will probably be removed in CherryPy 2.2.

- `cherrypy._cphttpserver.PooledThreadServer`: this will load the old, multi-threaded built-in HTTP server. This server is deprecated and will probably be removed in CherryPy 2.2.

- `cherrypy._cphttpserver.embedded_server`: use this to automatically select between the CherryHTTPServer and the PooledThreadServer based on the value of config.get("server.threadPool") and config.get("server.socketFile").

- `None`: this will not load any HTTP server. Note that this is not the default; the default (if serverClass is not given) is to load the WSGIServer.

- Any other class (or dotted-name string): load a custom HTTP server.

You must call this function from Python's main thread, and set initOnly to False, if you want CherryPy to shut down when KeyboardInterrupt or SystemExit are raised (including Ctrl-C). The only time you might want to do otherwise is if you run CherryPy as a Windows service, or as an extension to, say, mod_python, and even then, you might want to anyway.

### cherrypy.server.blocking

If the "initOnly" argument to server.start is True, this will be False, and vice-versa.

### cherrypy.server.httpserverclass

Whatever HTTP server class is set in server.start will be stuck in here.

### cherrypy.server.httpserver

Whatever HTTP server class is set in server.start will be instantiated and stuck in here.

### cherrypy.server.state

One of three values, indicating the state of the server:

- STOPPED = 0: The server hasn't been started, and will not accept requests.

- STARTING = None: The server is in the process of starting, or an error occured while trying to start the server.

- STARTED = 1: The server has started (including an HTTP server if requested), and is ready to receive requests.

### cherrypy.server.ready

True if the server is ready to receive requests, false otherwise. Read-only.

### cherrypy.server.wait()

Since server.start usually blocks, other threads need to be started before calling server.start; however, they often must wait for server.start to complete it's setup of the HTTP server. Use this function from other threads to make them wait for the HTTP server to be ready to receive requests.

### cherrypy.server.start_with_callback(func, args=(), kwargs={}, serverClass=_missing)

Since server.start usually blocks, use this to easily run another function in a new thread. It starts the new thread and then runs server.start. The new thread automatically waits for the server to finish its startup procedure.

### cherrypy.server.stop()

Stop the CherryPy Server. Well, "suspend" might be a better term—this doesn't terminate the process.

### cherrypy.server.interrupt

Usually None, set this to KeyboardInterrupt() or SystemExit() to shut down the entire process. That is, the new exception will be raised in the main thread.

### cherrypy.server.restart()

Restart the CherryPy Server.

### cherrypy.server.onStartServerList

A list of functions that will be called when the server starts.

### cherrypy.server.onStopServerList

A list of functions that will be called when the server stops.

### cherrypy.server.onStartThreadList

A list of functions that will be called when each request thread is started. Note that such threads do not need to be started or controlled by CherryPy; for example, when using CherryPy with mod_python, Apache will start and stop the request threads. Nevertheless, CherryPy will run the onStartThreadList functions upon the first request using each distinct thread.

### cherrypy.server.onStopThreadList

A list of functions that will be called when each request thread is stopped.

### cherrypy.server.request()

HTTP servers should call this function to hand off the HTTP request to the CherryPy core. There is no return value; instead, the core sets response content in the cherrypy.response object.

## cherrypy.config

### cherrypy.config.get(key, defaultValue = None, returnSection = False)

This function returns the configuration value for the given key. The function checks if the setting is defined for the current request path; it walks up the request path until the key is found, or it returns the default value. If returnSection is True, the function returns the configuration path where the key is defined instead.

### cherrypy.config.getAll(key)

The getAll function returns a list containing a (path, value) tuple for all occurences of the key within the request path. This function allows applications to inherit configuration data defined for parent paths.

### cherrypy.config.update(updateMap=None, file=None)

Function to update the configuration map. The "updateMap" argument is a dictionary of the form {'sectionPath' : { } }. The "file" argument is the path to the configuration file.

## cherrypy exceptions

### cherrypy.HTTPError

This exception can be used to automatically send a response using a http status code, with an appropriate error page.

#### cherrypy.NotFound

This exception is raised when CherryPy is unable to map a requested path to an internal method. It's a subclass of HTTPError.

### cherrypy.HTTPRedirect

This exception will force a HTTP redirect.

### cherrypy.InternalRedirect

This exception will redirect processing to another path within the site (without informing the client).

## The CherryPy library

### cherrypy.lib.cptools

#### ExposeItems

Utility class that exposes a getitem-aware object. It does not provide index() or default() methods, and it does not expose the individual item objects - just the list or dict that contains them. User-specific index() and default() methods can be implemented by inheriting from this class.

#### PositionalParametersAware

Utility class that restores positional parameters functionality that was found in 2.0.0-beta.

#### getRanges(content_length)

Returns a list of (start, stop) indices from a Range request header. Returns None if no such header is provided in the request. Each (start, stop) tuple will be composed of two ints, which are suitable for use in a slicing operation. That is, the header "Range: bytes=3-6", if applied against a Python string, is requesting resource[3:7]. This function will return the list [(3, 7)].

#### serveFile(path, contentType=None, disposition=None, name=None)

Set status, headers, and body in order to serve the file at the given path. The Content-Type header will be set to the contentType arg, if provided. If not provided, the Content-Type will be guessed by the extension of the file. If disposition is not None, the Content-Disposition header will be set to "<disposition>; filename=<name>". If name is None, it will be set to the basename of path. If disposition is None, no Content-Disposition header will be written.

### cherrypy.lib.covercp

This module both provides code-coverage tools, and may also be run as a script. To use this module, or the coverage tools in the test suite, you need to download 'coverage.py', either Gareth Rees' original implementation or Ned Batchelder's enhanced version.

Set cherrypy.codecoverage to True to turn on coverage tracing. Then, use the covercp.serve() function to browse the results in a web browser. If you run this module as a script (i.e., from the command line), it will call serve() for you.

### cherrypy.lib.profiler

You can profile any of your page handlers (exposed methods) as follows:

Profiling example

    from cherrypy.lib import profile

    class Root:
        p = profile.Profiler("/path/to/profile/dir")

        def index(self):
            self.p.run(self._index)
        index.exposed = True

        def _index(self):
            return "Hello, world!"

    cherrypy.root = Root()

Set the config entry: "profiling.on = True" if you'd rather turn on profiling for all requests. Then, use the serve() function to browse the results in a web browser. If you run this module as a script (i.e., from the command line), it will call serve() for you.

Developers: this module should be used whenever you make significant changes to CherryPy, to get a quick sanity-check on the performance of the request process. Basic requests should complete in about 5 milliseconds on a reasonably-fast machine running Python 2.4 (Python 2.3 will be much slower due to threadlocal being implemented in Python, not C). You can profile the test suite by supplying the --profile option to test.py.

### cherrypy.lib.autoreload

This module provides a brute-force method of reloading application files on the fly. When the config entry "autoreload.on" is True (or when "server.environment" is "development"), CherryPy uses the autoreload module to restart the current process whenever one of the files in use is changed. The mechanism by which it does so is pretty complicated:

The autoreload process

## Special functions and attributes

### _cpOnError

_cpOnError is a function for handling unanticipated exceptions, whether raised by CherryPy itself, or in user applications. The default simply raises HTTPError(500).

### _cpFilterList

User defined filters are enabled using the class attribute _cpFilterList. Any filter instances placed in _cpFilterList will be applied to all methods of the class.

## Filter API

### onStartResource

### beforeRequestBody

### beforeMain

### beforeFinalize

### onEndResource

### beforeErrorResponse

### afterErrorResponse