Filters are one of the most important features of CherryPy. The CherryPy core can call user-defined functions at specific points during request processing; a filter is a class which defines those functions. Filters are designed to be called at a low level—the HTTP request/response level—and therefore should only be used in that context.

CherryPy comes with a set of built-in filters, but they're turned off by default. To enable them, you must use the configuration system as follows:

        [/entries/view]
        tidyFilter.on = True
        tidyFilter.tmpDir = "/tmp"
        tidyFilter.strictXml = True
      

On the first line we define that the tidy filter will be used by the core whenever the path /entries/view (or one of its sub-paths) is called. On the two last lines we also define some parameters used by the filter.

CherryPy lets you write your own filters as we will see in the developer reference chapter. However, the way to use them is different from the default filters. You do not declare custom filters within the configuration file; instead, use the _cpFilterList attribute in your source code:

        import cherrypy
        from myfiltermodule import MyFilterClass
        
        class Entry:
          _cpFilterList = [ MyFilterClass() ]
          def view(self, id): 
            # do suff...
          view.exposed = True
        
        class Root: pass
        
        cherrypy.root = Root()
        cherrypy.root.entries = Entry()
        cherrypy.server.start()
      

As all objects below cherrypy.root.entries will inherit the filter, there is no need to re-specify it in each _cpFilterList underneath.

Keep in mind that the user-defined filters are called in the order you add them to the list.

The CherryPy configuration system provides fine-grained control over how each part of the application should react. You will use it for two reasons:

You will be able to declare the configuration settings either from a file or from a Python dictionary.

First of all, let's see how a typical configuration file is defined.

            # The configuration file called myconfigfile.conf
            [global]
            server.socketPort=8080
            server.socketHost=""
            server.socketFile=""
            server.socketQueueSize=5
            server.protocolVersion="HTTP/1.0"
            server.logToScreen=True
            server.logFile=""
            server.reverseDNS=False
            server.threadPool=10
            server.environment="development"
            
            [/service/xmlrpc]
            xmlRpcFilter.on = True
            
            [/admin]
            sessionAuthenticateFilter.on=True
            
            [/css/default.css]
            staticFilter.on = True
            staticFilter.file = "data/css/default.css"
            
            # From your script...
            cherrypy.config.update(file="myconfigfile.conf") 
        

The settings can also be defined using a python dictionary instead of a file as follows:

      settings = { 
         'global': {
            'server.socketPort' : 8080,
            'server.socketHost': "",
            'server.socketFile': "",
            'server.socketQueueSize': 5,
            'server.protocolVersion': "HTTP/1.0",
            'server.logToScreen': True,
            'server.logFile': "",
            'server.reverseDNS': False,
            'server.threadPool': 10,
            'server.environment': "development"
         },
         '/service/xmlrpc' : {
            'xmlRpcFilter.on': True
         },
         '/admin': {
            'sessionAuthenticateFilter.on' :True
         },
         '/css/default.css': {
            'staticFilter.on': True,
            'staticFilter.file': "data/css/default.css"
         }
      }
      cherrypy.config.update(settings)
        

Each section of the configuration refers to a URL path; each path is mapped to a published object of the tree handled by CherryPy. Therefore when the server receives a request for /css/default.css, the static filter will be called and the server will actually return the physical file name data/css/default.css.

Since the path /service/xmlrpc has the XML-RPC filter enabled, all the exposed methods of the object cherrypy.root.service.xmlrpc will be treated as XML-RPC methods.

The root entry, defined as global, is also responsible for defining the server settings such as the port, the protocol version to use by default, the number of threads to start with the server, etc.

All values in the configuration file must be valid Python values. Strings must be quoted, booleans must be True or False, etc.

The server.environment entry controls how CherryPy should run. Three values are legal:

CherryPy is a low-level framework for building web applications, and thus does not offer high-level features such as an integrated templating system. This is quite a different point of view from many other web frameworks. CherryPy does not force you to use a specific templating language; instead, it allows you to plug in your favourite one as you see fit.

CherryPy works with all the main templating systems:

You will find recipes on how to use them on the CherryPy website.

Static content is now handled by a filter called "staticFilter" that can easily be enabled and configured in your config file. For instance, if you wanted to serve /style.css from /home/site/style.css and /static/* from /home/site/static/*, you can use the following configuration:

            [global]
            staticFilter.root = "/home/site"
            
            [/style.css]
            staticFilter.on = True
            staticFilter.file = "style.css"
            
            [/static]
            staticFilter.on = True
            staticFilter.dir = "static"
        

The staticFilter.root entry can be either absolute or relative. If absolute, static content is sought within that absolute path. Since CherryPy cannot guess where your application root is located, relative paths are assumed to be relative to the directory where your cherrypy.root class is defined (if you do not provide a root, it defaults to "", and therefore to the directory of your cherrypy.root class).

As an application developer, the design of your application affects whether you choose to use absolute or relative paths. If you are creating a one-off application that will only be deployed once, you might as well use absolute paths. But you can make multiple deployments easier by using relative paths, letting CherryPy calculate the absolute path each time for you. Absolute paths, however, give deployers the ability to place static content on read-only filesystems, or on faster disks.

Before version 2.1, CherryPy handled file uploads by reading the entire file into memory, storing it in a string, and passing it to the page handler method. This worked well for small files, but not so well for large files.

CherryPy 2.1 uses the python cgi module to parse the POST data. When a file is being uploaded, the cgi module stores it in a temp file and returns a FieldStorage instance which contains information about this file. CherryPy then passes this FieldStorage instance to the method. The FieldStorage instance has the following attributes:

Unhandled exceptions raised inside CherryPy applications result in a call to the _cpOnError function. HTTPError and HTTPRedirect exceptions do not result in calls to _cpOnError. HTTPError exceptions force the server to set response status and return an error page.