The CherryPy Documentation

First we need to import the modules we will be using from this entry point.

Example 2.4. Blogging system - import modules

     import sys
    import time
            
      sys.path.append('src')
            
      import cherrypy
      from cherrytemplate import cherrytemplate, renderTemplate

    
    from entryManager import BlogEntryManager
    from commentManager import BlogCommentManager
    from comment import BlogComment
    from admin import BlogAdmin
    from cal import getCurrentCalendar
          

	We use the sys module to be able to add a directory to the search path where Python looks for modules.
	Here we add the sub-directory src to the Python search path.
	CherryPy requires only one import. In version 2.0 of CherryPy, it used to be from cherrypy import cpg but not any longer.
	Import two modules from CherryTemplate. The first one is used to modify some global variable of CherryTemplate as we will see later on. The second one is the actual function to parse a template file and fetch the output.
	The last modules imported are those we will write later on in this tutorial.

CherryPy does not force you to define any kind of methods but index and default are the ones CherryPy will look for by default. The index() method is the equivalent to the index.html page used by default by Apache. The default() method is called by CherryPy when all other lookup fail. If CherryPy doesn't find any matching callable object, it will issue an exception. index() is by far the most common one to be defined.

Before a method can be used to serve content it needs to be published and exposed. Publishing is the process of attaching an instance of a given callable to the main cherrypy object tree as we will see later. Exposing is done by setting the exposed attribute to the method that we want to be able to call from the client side.

Now we can define both methods as follow.

Example 2.6. 

 
    def index(self):
         entries = self.em.fetchLastEntries()
         cal = getCurrentCalendar()
         rssPath = cherrypy.request.base + '/media/feed/rss.xml'
         return renderTemplate(file = "Blog_show_entry.tmpl")
    index.exposed = True
           
 
    def default(self, *args):
         cal = getCurrentCalendar()
         rssPath = cherrypy.request.base + '/media/feed/rss.xml'
         if len(args) == 3:
             date = "%s-%s-%s" % (args[0], args[1], args[2])
             entries = self.em.fetchEntriesByDate(date)
         elif len(args) == 4:
             entry = self.em.fetchEntry(args[0], args[1], args[2], args[3])
         if not entry:
             return renderTemplate(file = "error404.tmpl")
             entries = [entry]
         else:
             return self.index()
         return renderTemplate(file = "Blog_show_entry.tmpl")
    default.exposed = True
          

When the index method is called we fetch the last entries added to the blog as well as the calendar of the current month (we will see later how to build it). Then we define the RSS feed path. Those three variables will be transparently passed to the CherryTemplate which is rendered through the renderTemplate() function. Since we have defined the templates directory as a global variable of CherryTemplate, we simply need to provide the name of the template itself to the method. We will then serve to the client the string resulting from the rendering, although CherryPy allows you to return a string, a list, a generator to serve the content index.exposed = True tells CherryPy that this method is exposed and available to serve content.

The default method is called when CherryPy failed to map the requested URL to an exposed object in the published objects tree, but you can also use it to slightly change CherryPy's behavior. In this particular context we will use default() allow URL with positional parameters such as : http://myhost/2005/06/18/78, which would be the equivalent to : http://myhost/?year=2005&month=06&day=18&entry=78. The former URL looks nicer and is more search engine friendly. This behavior is not automatically handled by CherryPy and using the default method is the most common workaround. First we get the current month calendar then we set the RSS feed path. Then we check what to do next by testing the number of passed arguments to the request. If this equals to three then the user asked to view a full day and all its entries. If it equals to four he specified the entry id as well. Otherwise we simply fallback to callback index().

We will define two more exposed methods to our Blog class.

Example 2.7. 

 
def comment(self, id):
    entryId = id
    entry = self.em.fetchEntryById(id)
    comments = self.cm.fetchCommentsByEntry(id)
    cal = getCurrentCalendar()
    rssPath = cherrypy.request.base + '/media/feed/rss.xml'
    return renderTemplate(file = "Blog_comment_add.tmpl")
comment.exposed = True
 
 
def addComment(self, entryId, title, author, message):
    rssPath = cherrypy.request.base + '/media/feed/rss.xml'
    self.cm.addComment(BlogComment(title, author, message, entryId))
    return self.comment(entryId)
addComment.exposed = True
          

	Called when an user wants to read the comments added to an entry.
	Called when an user submitted a new comment through the HTML form.

Finally we need to set up the CherryPy tree of published objects, specify what settings we need and finally start the server.

Example 2.8. 

    cherrypy.root = Blog()
    cherrypy.root.admin = BlogAdmin()


    cherrypy.config.update(file='media/conf/Blog.conf')

    cherrypy.server.start()
          

	Define the tree structure. Our blogging system only publish two objects.
	Our settings will be defined in a seperate file. We could have defined them inline as a Python dictionnary.
	Let's start the server.

We will define a file called backendManager.py located under the src directory. This file will define a class and its set of methods to facilitate access and queries to our backend. Basically we will follow the CRUD interface : Create, Retrieve, Update and Delete. Following is a snippet code from that module:

Example 2.9. 

          import shelve
          import threading
          import time
          
          _dbLocker = threading.Lock()
          
          class BlogBackendManager:
              
              def fetchAll(self):
                  data = []
                  try:
                    _dbLocker.acquire()
                    db = shelve.open('media/db/blob.db', 'r')
                    data = db.keys()
                    if db: db.close()
                  finally:
                    _dbLocker.release()
                  return data
        

We will hold a global lock to ensure the database access will be protected. This is needed since CherryPy is a multithreaded application, each thread handling one user agent request. As you can notice this lock is global to the entire application, therefore no more than one thread will be able to access the database at one given time. This is a very simplistic principle and not a usable one on a larger application, but as we already said, our purpose is to show how to build an application without too much complexity.

This method will simply connect to the database and fetch all entries. We make sure the lock is always released by calliong the release method within the finallystatement, thus whatever happens after the lock has been acquired it will be released.

At its most basic, CherryPy is designed to allow the production of simple websites without having to think about any of the details of HTTP. Notice we're saying HTTP (the transport), not HTML (the markup language)! In particular, developers should not have to concern themselves with:

For the most part, simple "page handlers" (functions attached to cherrypy.root), should never have to refer to cherrypy at all! They receive params via function arguments, and return content directly. Advanced functionality is most often enabled via the built-in filters, which encapsulate the particulars of HTTP, and can be completely controlled via the config file.

Simple apps are produced simply, but when a developer needs to step out of the mundane and provide real value, they should be able to leverage the complete power and flexibility of the HTTP specification. In general, the HTTP request and response messages are completely represented in the cherrypy.request and .response objects. At the lowest level, a developer should be able to generate any valid HTTP response message by modifying cherrypy.response.status, .headerMap, and/or .body.

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

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

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

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.

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.

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

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

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

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

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.

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

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

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.

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

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

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

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

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

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.

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

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

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

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

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.

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

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.

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.

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.

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):

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.

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

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

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

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

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

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.

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.

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

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.

Restart the CherryPy Server.

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

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

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.

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

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.

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.

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.

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.

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

This exception will force a HTTP redirect.

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

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.

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

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.

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:

Figure 3.2. The autoreload process

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

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.

The baseurlfilter changes the base url of a request. It is useful for running CherryPy behind Apache with mod_rewrite.

The baseurlfilter has the following configuration options

The decoding filter can be configured to automatically decode incoming requests.

The decodingfilter has the following configuration options:

The encodingfilter can be configured to automatically encode outgoing responses.

The encodingfilter has the following configuration options:

The gzipfilter will automatically gzip outgoing requests, if it is supported by the client.

The gzipfilter does not have any configuration options.

The logdebuinfofilter adds debug information to each page. The filter is automatically turned on when "server.environment" is set to "development".

The logdebuginfofilter has the following configuration options:

The static filter allows CherryPy to serve static files.

The staticfilter has the following configuration options:

The tidyfilter cleans up returned html by running the response through Tidy.

Note that we use the standalone Tidy tool rather than the python mxTidy module. This is because this module doesn't seem to be stable and it crashes on some HTML pages (which means that the server would also crash.)

The tidyfilter has the following configuration options:

The virtualhostfilter changes the ObjectPath based on the Host. Use this filter when running multiple sites within one CP server.

The virtualhostfilter has the following configuration options:

The xmlrpcfilter converts XMLRPC to the CherryPy2 object system and vice-versa.

PLEASE NOTE: beforeRequestBody: Unmarshalls the posted data to a methodname and parameters. - These are stored in cherrypy.request.rpcMethod and .rpcParams - The method is also stored in cherrypy.request.path, so CP2 will find the right method to call for you, based on the root's position. beforeFinalize: Marshalls cherrypy.response.body to xmlrpc. - Until resolved: cherrypy.response.body must be a python source string; this string is 'eval'ed to return the results. This will be resolved in the future. - Content-Type and Content-Length are set according to the new (marshalled) data

The xmlrpcfilter does not have any configuration options.