CherryPy - A Minimalist Python Web Framework¶

Why CherryPy?¶

CherryPy is among the oldest web framework available for Python, yet many people aren’t aware of its existence. One of the reason for this is that CherryPy is not a complete stack with built-in support for a multi-tier architecture. It doesn’t provide frontend utilities nor will it tell you how to speak with your storage. Instead, CherryPy’s take is to let the developer make those decisions. This is a contrasting position compared to other well-known frameworks.

CherryPy has a clean interface and does its best to stay out of your way whilst providing a reliable scaffolding for you to build from.

Typical use-cases for CherryPy go from regular web application with user frontends (think blogging, CMS, portals, ecommerce) to web-services only.

Here are some reasons you would want to choose CherryPy:

1. Simplicity

   Developing with CherryPy is a simple task. “Hello, world” is only a few lines long, and does not require the developer to learn the entire (albeit very manageable) framework all at once. The framework is very pythonic; that is, it follows Python’s conventions very nicely (code is sparse and clean).

   Contrast this with J2EE and Python’s most popular and visible web frameworks: Django, Zope, Pylons, and Turbogears. In all of them, the learning curve is massive. In these frameworks, “Hello, world” requires the programmer to set up a large scaffold which spans multiple files and to type a lot of boilerplate code. CherryPy succeeds because it does not include the bloat of other frameworks, allowing the programmer to write their web application quickly while still maintaining a high level of organization and scalability.

   CherryPy is also very modular. The core is fast and clean, and extension features are easy to write and plug in using code or the elegant config system. The primary components (server, engine, request, response, etc.) are all extendable (even replaceable) and well-managed.

   In short, CherryPy empowers the developer to work with the framework, not against or around it.

2. Power

   CherryPy leverages all of the power of Python. Python is a dynamic language which allows for rapid development of applications. Python also has an extensive built-in API which simplifies web app development. Even more extensive, however, are the third-party libraries available for Python. These range from object-relational mappers to form libraries, to an automatic Python optimizer, a Windows exe generator, imaging libraries, email support, HTML templating engines, etc. CherryPy applications are just like regular Python applications. CherryPy does not stand in your way if you want to use these brilliant tools.

   CherryPy also provides tools and plugins, which are powerful extension points needed to develop world-class web applications.

3. Maturity

   Maturity is extremely important when developing a real-world application. Unlike many other web frameworks, CherryPy has had many final, stable releases. It is fully bugtested, optimized, and proven reliable for real-world use. The API will not suddenly change and break backwards compatibility, so your applications are assured to continue working even through subsequent updates in the current version series.

   CherryPy is also a “3.0” project: the first edition of CherryPy set the tone, the second edition made it work, and the third edition makes it beautiful. Each version built on lessons learned from the previous, bringing the developer a superior tool for the job.

4. Community

   CherryPy has an devoted community that develops deployed CherryPy applications and are willing and ready to assist you on the CherryPy mailing list or IRC (#cherrypy on OFTC). The developers also frequent the list and often answer questions and implement features requested by the end-users.

5. Deployability

   Unlike many other Python web frameworks, there are cost-effective ways to deploy your CherryPy application.

   Out of the box, CherryPy includes its own production-ready HTTP server to host your application. CherryPy can also be deployed on any WSGI-compliant gateway (a technology for interfacing numerous types of web servers): mod_wsgi, FastCGI, SCGI, IIS, uwsgi, tornado, etc. Reverse proxying is also a common and easy way to set it up.

   In addition, CherryPy is pure-python and is compatible with Python 2.3. This means that CherryPy will run on all major platforms that Python will run on (Windows, MacOSX, Linux, BSD, etc).

   webfaction.com, run by the inventor of CherryPy, is a commercial web host that offers CherryPy hosting packages (in addition to several others).

6. It’s free!

   All of CherryPy is licensed under the open-source BSD license, which means CherryPy can be used commercially for ZERO cost.

7. Where to go from here?

   Check out the tutorials to start enjoying the fun!

Success Stories¶

You are interested in CherryPy but you would like to hear more from people using it, or simply check out products or application running it.

If you would like to have your CherryPy powered website or product listed here, contact us via our mailing list or IRC (#cherrypy on OFTC).

Requirements¶

CherryPy does not have any mandatory requirements. However certain features it comes with will require you install certain packages. To simplify installing additional dependencies CherryPy enables you to specify extras in your requirements (e.g. cherrypy[json,routes_dispatcher,ssl]): - doc – for documentation related stuff - json – for custom JSON processing library - routes_dispatcher – routes for declarative URL mapping dispatcher - ssl – for OpenSSL bindings, useful in Python environments not having the builtin ssl module - testing - memcached_session – enables memcached backend session - xcgi

Supported python version¶

CherryPy supports Python 2.7 through to 3.5.

Installing¶

CherryPy can be easily installed via common Python package managers such as setuptools or pip.

$ easy_install cherrypy

$ pip install cherrypy

You may also get the latest CherryPy version by grabbing the source code from Github:

$ git clone https://github.com/cherrypy/cherrypy
$ cd cherrypy
$ python setup.py install

$ python -m cherrypy.tutorial.tut01_helloworld

[15/Feb/2014:21:51:22] ENGINE Listening for SIGHUP.
[15/Feb/2014:21:51:22] ENGINE Listening for SIGTERM.
[15/Feb/2014:21:51:22] ENGINE Listening for SIGUSR1.
[15/Feb/2014:21:51:22] ENGINE Bus STARTING
[15/Feb/2014:21:51:22] ENGINE Started monitor thread 'Autoreloader'.
[15/Feb/2014:21:51:22] ENGINE Started monitor thread '_TimeoutMonitor'.
[15/Feb/2014:21:51:22] ENGINE Serving on http://127.0.0.1:8080
[15/Feb/2014:21:51:23] ENGINE Bus STARTED

Run it¶

During development, the easiest path is to run your application as follow:

$ python myapp.py

As long as myapp.py defines a “__main__” section, it will run just fine.

Tutorial 1: A basic web application¶

The following example demonstrates the most basic application you could write with CherryPy. It starts a server and hosts an application that will be served at request reaching http://127.0.0.1:8080/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

import cherrypy


class HelloWorld(object):
    @cherrypy.expose
    def index(self):
        return "Hello world!"


if __name__ == '__main__':
    cherrypy.quickstart(HelloWorld())

Store this code snippet into a file named tut01.py and execute it as follows:

$ python tut01.py

This will display something along the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[24/Feb/2014:21:01:46] ENGINE Listening for SIGHUP.
[24/Feb/2014:21:01:46] ENGINE Listening for SIGTERM.
[24/Feb/2014:21:01:46] ENGINE Listening for SIGUSR1.
[24/Feb/2014:21:01:46] ENGINE Bus STARTING
CherryPy Checker:
The Application mounted at '' has an empty config.

[24/Feb/2014:21:01:46] ENGINE Started monitor thread 'Autoreloader'.
[24/Feb/2014:21:01:46] ENGINE Started monitor thread '_TimeoutMonitor'.
[24/Feb/2014:21:01:46] ENGINE Serving on http://127.0.0.1:8080
[24/Feb/2014:21:01:46] ENGINE Bus STARTED

This tells you several things. The first three lines indicate the server will handle signal for you. The next line tells you the current state of the server, as that point it is in STARTING stage. Then, you are notified your application has no specific configuration set to it. Next, the server starts a couple of internal utilities that we will explain later. Finally, the server indicates it is now ready to accept incoming communications as it listens on the address 127.0.0.1:8080. In other words, at that stage your application is ready to be used.

Before moving on, let’s discuss the message regarding the lack of configuration. By default, CherryPy has a feature which will review the syntax correctness of settings you could provide to configure the application. When none are provided, a warning message is thus displayed in the logs. That log is harmless and will not prevent CherryPy from working. You can refer to the documentation above to understand how to set the configuration.

Tutorial 2: Different URLs lead to different functions¶

Your applications will obviously handle more than a single URL. Let’s imagine you have an application that generates a random string each time it is called:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

import random
import string

import cherrypy


class StringGenerator(object):
    @cherrypy.expose
    def index(self):
        return "Hello world!"

    @cherrypy.expose
    def generate(self):
        return ''.join(random.sample(string.hexdigits, 8))


if __name__ == '__main__':
    cherrypy.quickstart(StringGenerator())

Save this into a file named tut02.py and run it as follows:

$ python tut02.py

Go now to http://localhost:8080/generate and your browser will display a random string.

Let’s take a minute to decompose what’s happening here. This is the URL that you have typed into your browser: http://localhost:8080/generate

This URL contains various parts:

• http:// which roughly indicates it’s a URL using the HTTP protocol (see RFC 2616).
• localhost:8080 is the server’s address. It’s made of a hostname and a port.
• /generate which is the path segment of the URL. This is what CherryPy uses to locate an exposed function or method to respond.

Here CherryPy uses the index() method to handle / and the generate() method to handle /generate

Tutorial 3: My URLs have parameters¶

In the previous tutorial, we have seen how to create an application that could generate a random string. Let’s now assume you wish to indicate the length of that string dynamically.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

import random
import string

import cherrypy


class StringGenerator(object):
    @cherrypy.expose
    def index(self):
        return "Hello world!"

    @cherrypy.expose
    def generate(self, length=8):
        return ''.join(random.sample(string.hexdigits, int(length)))


if __name__ == '__main__':
    cherrypy.quickstart(StringGenerator())

Save this into a file named tut03.py and run it as follows:

$ python tut03.py

Go now to http://localhost:8080/generate?length=16 and your browser will display a generated string of length 16. Notice how we benefit from Python’s default arguments’ values to support URLs such as http://localhost:8080/generate still.

In a URL such as this one, the section after ? is called a query-string. Traditionally, the query-string is used to contextualize the URL by passing a set of (key, value) pairs. The format for those pairs is key=value. Each pair being separated by a & character.

Notice how we have to convert the given length value to an integer. Indeed, values are sent out from the client to our server as strings.

Much like CherryPy maps URL path segments to exposed functions, query-string keys are mapped to those exposed function parameters.

Tutorial 4: Submit this form¶

CherryPy is a web framework upon which you build web applications. The most traditional shape taken by applications is through an HTML user-interface speaking to your CherryPy server.

Let’s see how to handle HTML forms via the following example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

import random
import string

import cherrypy


class StringGenerator(object):
    @cherrypy.expose
    def index(self):
        return """<html>
          <head></head>
          <body>
            <form method="get" action="generate">
              <input type="text" value="8" name="length" />
              <button type="submit">Give it now!</button>
            </form>
          </body>
        </html>"""

    @cherrypy.expose
    def generate(self, length=8):
        return ''.join(random.sample(string.hexdigits, int(length)))


if __name__ == '__main__':
    cherrypy.quickstart(StringGenerator())

Save this into a file named tut04.py and run it as follows:

$ python tut04.py

Go now to http://localhost:8080/ and your browser and this will display a simple input field to indicate the length of the string you want to generate.

Notice that in this example, the form uses the GET method and when you pressed the Give it now! button, the form is sent using the same URL as in the previous tutorial. HTML forms also support the POST method, in that case the query-string is not appended to the URL but it sent as the body of the client’s request to the server. However, this would not change your application’s exposed method because CherryPy handles both the same way and uses the exposed’s handler parameters to deal with the query-string (key, value) pairs.

Tutorial 5: Track my end-user’s activity¶

It’s not uncommon that an application needs to follow the user’s activity for a while. The usual mechanism is to use a session identifier that is carried during the conversation between the user and your application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import random
import string

import cherrypy


class StringGenerator(object):
    @cherrypy.expose
    def index(self):
        return """<html>
          <head></head>
          <body>
            <form method="get" action="generate">
              <input type="text" value="8" name="length" />
              <button type="submit">Give it now!</button>
            </form>
          </body>
        </html>"""

    @cherrypy.expose
    def generate(self, length=8):
        some_string = ''.join(random.sample(string.hexdigits, int(length)))
        cherrypy.session['mystring'] = some_string
        return some_string

    @cherrypy.expose
    def display(self):
        return cherrypy.session['mystring']


if __name__ == '__main__':
    conf = {
        '/': {
            'tools.sessions.on': True
        }
    }
    cherrypy.quickstart(StringGenerator(), '/', conf)

Save this into a file named tut05.py and run it as follows:

$ python tut05.py

In this example, we generate the string as in the previous tutorial but also store it in the current session. If you go to http://localhost:8080/, generate a random string, then go to http://localhost:8080/display, you will see the string you just generated.

The lines 30-34 show you how to enable the session support in your CherryPy application. By default, CherryPy will save sessions in the process’s memory. It supports more persistent backends as well.

Tutorial 6: What about my javascripts, CSS and images?¶

Web applications are usually also made of static content such as javascript, CSS files or images. CherryPy provides support to serve static content to end-users.

Let’s assume, you want to associate a stylesheet with your application to display a blue background color (why not?).

First, save the following stylesheet into a file named style.css and stored into a local directory public/css.

1
2
3

body {
  background-color: blue;
}

Now let’s update the HTML code so that we link to the stylesheet using the http://localhost:8080/static/css/style.css URL.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

import os, os.path
import random
import string

import cherrypy


class StringGenerator(object):
    @cherrypy.expose
    def index(self):
        return """<html>
          <head>
            <link href="/static/css/style.css" rel="stylesheet">
          </head>
          <body>
            <form method="get" action="generate">
              <input type="text" value="8" name="length" />
              <button type="submit">Give it now!</button>
            </form>
          </body>
        </html>"""

    @cherrypy.expose
    def generate(self, length=8):
        some_string = ''.join(random.sample(string.hexdigits, int(length)))
        cherrypy.session['mystring'] = some_string
        return some_string

    @cherrypy.expose
    def display(self):
        return cherrypy.session['mystring']


if __name__ == '__main__':
    conf = {
        '/': {
            'tools.sessions.on': True,
            'tools.staticdir.root': os.path.abspath(os.getcwd())
        },
        '/static': {
            'tools.staticdir.on': True,
            'tools.staticdir.dir': './public'
        }
    }
    cherrypy.quickstart(StringGenerator(), '/', conf)

Save this into a file named tut06.py and run it as follows:

$ python tut06.py

Going to http://localhost:8080/, you should be greeted by a flashy blue color.

CherryPy provides support to serve a single file or a complete directory structure. Most of the time, this is what you’ll end up doing so this is what the code above demonstrates. First, we indicate the root directory of all of our static content. This must be an absolute path for security reason. CherryPy will complain if you provide only relative paths when looking for a match to your URLs.

Then we indicate that all URLs which path segment starts with /static will be served as static content. We map that URL to the public directory, a direct child of the root directory. The entire sub-tree of the public directory will be served as static content. CherryPy will map URLs to path within that directory. This is why /static/css/style.css is found in public/css/style.css.

Tutorial 7: Give us a REST¶

It’s not unusual nowadays that web applications expose some sort of datamodel or computation functions. Without going into its details, one strategy is to follow the REST principles edicted by Roy T. Fielding.

Roughly speaking, it assumes that you can identify a resource and that you can address that resource through that identifier.

“What for?” you may ask. Well, mostly, these principles are there to ensure that you decouple, as best as you can, the entities your application expose from the way they are manipulated or consumed. To embrace this point of view, developers will usually design a web API that expose pairs of (URL, HTTP method, data, constraints).

Lets go through a small example of a very basic web API mildly following REST principles.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

import random
import string

import cherrypy


@cherrypy.expose
class StringGeneratorWebService(object):

    @cherrypy.tools.accept(media='text/plain')
    def GET(self):
        return cherrypy.session['mystring']

    def POST(self, length=8):
        some_string = ''.join(random.sample(string.hexdigits, int(length)))
        cherrypy.session['mystring'] = some_string
        return some_string

    def PUT(self, another_string):
        cherrypy.session['mystring'] = another_string

    def DELETE(self):
        cherrypy.session.pop('mystring', None)


if __name__ == '__main__':
    conf = {
        '/': {
            'request.dispatch': cherrypy.dispatch.MethodDispatcher(),
            'tools.sessions.on': True,
            'tools.response_headers.on': True,
            'tools.response_headers.headers': [('Content-Type', 'text/plain')],
        }
    }
    cherrypy.quickstart(StringGeneratorWebService(), '/', conf)

Save this into a file named tut07.py and run it as follows:

$ python tut07.py

Before we see it in action, let’s explain a few things. Until now, CherryPy was creating a tree of exposed methods that were used to match URLs. In the case of our web API, we want to stress the role played by the actual requests’ HTTP methods. So we created methods that are named after them and they are all exposed at once by decorating the class itself with cherrypy.expose.

However, we must then switch from the default mechanism of matching URLs to method for one that is aware of the whole HTTP method shenanigan. This is what goes on line 27 where we create a MethodDispatcher instance.

Then we force the responses content-type to be text/plain and we finally ensure that GET requests will only be responded to clients that accept that content-type by having a Accept: text/plain header set in their request. However, we do this only for that HTTP method as it wouldn’t have much meaning on the other methods.

For the purpose of this tutorial, we will be using a Python client rather than your browser as we wouldn’t be able to actually try our web API otherwise.

Please install requests through the following command:

$ pip install requests

Then fire up a Python terminal and try the following commands:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

>>> import requests
>>> s = requests.Session()
>>> r = s.get('http://127.0.0.1:8080/')
>>> r.status_code
500
>>> r = s.post('http://127.0.0.1:8080/')
>>> r.status_code, r.text
(200, u'04A92138')
>>> r = s.get('http://127.0.0.1:8080/')
>>> r.status_code, r.text
(200, u'04A92138')
>>> r = s.get('http://127.0.0.1:8080/', headers={'Accept': 'application/json'})
>>> r.status_code
406
>>> r = s.put('http://127.0.0.1:8080/', params={'another_string': 'hello'})
>>> r = s.get('http://127.0.0.1:8080/')
>>> r.status_code, r.text
(200, u'hello')
>>> r = s.delete('http://127.0.0.1:8080/')
>>> r = s.get('http://127.0.0.1:8080/')
>>> r.status_code
500

The first and last 500 responses stem from the fact that, in the first case, we haven’t yet generated a string through POST and, on the latter case, that it doesn’t exist after we’ve deleted it.

Lines 12-14 show you how the application reacted when our client requested the generated string as a JSON format. Since we configured the web API to only support plain text, it returns the appropriate HTTP error code.

Tutorial 8: Make it smoother with Ajax¶

In the recent years, web applications have moved away from the simple pattern of “HTML forms + refresh the whole page”. This traditional scheme still works very well but users have become used to web applications that don’t refresh the entire page. Broadly speaking, web applications carry code performed client-side that can speak with the backend without having to refresh the whole page.

This tutorial will involve a little more code this time around. First, let’s see our CSS stylesheet located in public/css/style.css.

1
2
3
4
5
6
7

body {
  background-color: blue;
}

#the-string {
  display: none;
}

We’re adding a simple rule about the element that will display the generated string. By default, let’s not show it up. Save the following HTML code into a file named index.html.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

<!DOCTYPE html>
<html>
  <head>
    <link href="/static/css/style.css" rel="stylesheet">
    <script src="http://code.jquery.com/jquery-2.0.3.min.js"></script>
    <script type="text/javascript">
      $(document).ready(function() {

        $("#generate-string").click(function(e) {
          $.post("/generator", {"length": $("input[name='length']").val()})
           .done(function(string) {
            $("#the-string").show();
            $("#the-string input").val(string);
          });
          e.preventDefault();
        });

        $("#replace-string").click(function(e) {
          $.ajax({
            type: "PUT",
            url: "/generator",
            data: {"another_string": $("#the-string input").val()}
          })
          .done(function() {
            alert("Replaced!");
          });
          e.preventDefault();
        });

        $("#delete-string").click(function(e) {
          $.ajax({
            type: "DELETE",
            url: "/generator"
          })
          .done(function() {
            $("#the-string").hide();
          });
          e.preventDefault();
        });

      });
    </script>
  </head>
  <body>
    <input type="text" value="8" name="length"/>
    <button id="generate-string">Give it now!</button>
    <div id="the-string">
      <input type="text" />
      <button id="replace-string">Replace</button>
      <button id="delete-string">Delete it</button>
    </div>
  </body>
</html>

We’ll be using the jQuery framework out of simplicity but feel free to replace it with your favourite tool. The page is composed of simple HTML elements to get user input and display the generated string. It also contains client-side code to talk to the backend API that actually performs the hard work.

Finally, here’s the application’s code that serves the HTML page above and responds to requests to generate strings. Both are hosted by the same application server.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

import os, os.path
import random
import string

import cherrypy


class StringGenerator(object):
    @cherrypy.expose
    def index(self):
        return open('index.html')


@cherrypy.expose
class StringGeneratorWebService(object):

    @cherrypy.tools.accept(media='text/plain')
    def GET(self):
        return cherrypy.session['mystring']

    def POST(self, length=8):
        some_string = ''.join(random.sample(string.hexdigits, int(length)))
        cherrypy.session['mystring'] = some_string
        return some_string

    def PUT(self, another_string):
        cherrypy.session['mystring'] = another_string

    def DELETE(self):
        cherrypy.session.pop('mystring', None)


if __name__ == '__main__':
    conf = {
        '/': {
            'tools.sessions.on': True,
            'tools.staticdir.root': os.path.abspath(os.getcwd())
        },
        '/generator': {
            'request.dispatch': cherrypy.dispatch.MethodDispatcher(),
            'tools.response_headers.on': True,
            'tools.response_headers.headers': [('Content-Type', 'text/plain')],
        },
        '/static': {
            'tools.staticdir.on': True,
            'tools.staticdir.dir': './public'
        }
    }
    webapp = StringGenerator()
    webapp.generator = StringGeneratorWebService()
    cherrypy.quickstart(webapp, '/', conf)

Save this into a file named tut08.py and run it as follows:

$ python tut08.py

Go to http://127.0.0.1:8080/ and play with the input and buttons to generate, replace or delete the strings. Notice how the page isn’t refreshed, simply part of its content.

Notice as well how your frontend converses with the backend using a straightfoward, yet clean, web service API. That same API could easily be used by non-HTML clients.

Tutorial 9: Data is all my life¶

Until now, all the generated strings were saved in the session, which by default is stored in the process memory. Though, you can persist sessions on disk or in a distributed memory store, this is not the right way of keeping your data on the long run. Sessions are there to identify your user and carry as little amount of data as necessary for the operation carried by the user.

To store, persist and query data you need a proper database server. There exist many to choose from with various paradigm support:

• relational: PostgreSQL, SQLite, MariaDB, Firebird
• column-oriented: HBase, Cassandra
• key-store: redis, memcached
• document oriented: Couchdb, MongoDB
• graph-oriented: neo4j

Let’s focus on the relational ones since they are the most common and probably what you will want to learn first.

For the sake of reducing the number of dependencies for these tutorials, we will go for the sqlite database which is directly supported by Python.

Our application will replace the storage of the generated string from the session to a SQLite database. The application will have the same HTML code as tutorial 08. So let’s simply focus on the application code itself:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

import os, os.path
import random
import sqlite3
import string
import time

import cherrypy

DB_STRING = "my.db"


class StringGenerator(object):
    @cherrypy.expose
    def index(self):
        return open('index.html')


@cherrypy.expose
class StringGeneratorWebService(object):

    @cherrypy.tools.accept(media='text/plain')
    def GET(self):
        with sqlite3.connect(DB_STRING) as c:
            cherrypy.session['ts'] = time.time()
            r = c.execute("SELECT value FROM user_string WHERE session_id=?",
                          [cherrypy.session.id])
            return r.fetchone()

    def POST(self, length=8):
        some_string = ''.join(random.sample(string.hexdigits, int(length)))
        with sqlite3.connect(DB_STRING) as c:
            cherrypy.session['ts'] = time.time()
            c.execute("INSERT INTO user_string VALUES (?, ?)",
                      [cherrypy.session.id, some_string])
        return some_string

    def PUT(self, another_string):
        with sqlite3.connect(DB_STRING) as c:
            cherrypy.session['ts'] = time.time()
            c.execute("UPDATE user_string SET value=? WHERE session_id=?",
                      [another_string, cherrypy.session.id])

    def DELETE(self):
        cherrypy.session.pop('ts', None)
        with sqlite3.connect(DB_STRING) as c:
            c.execute("DELETE FROM user_string WHERE session_id=?",
                      [cherrypy.session.id])


def setup_database():
    """
    Create the `user_string` table in the database
    on server startup
    """
    with sqlite3.connect(DB_STRING) as con:
        con.execute("CREATE TABLE user_string (session_id, value)")


def cleanup_database():
    """
    Destroy the `user_string` table from the database
    on server shutdown.
    """
    with sqlite3.connect(DB_STRING) as con:
        con.execute("DROP TABLE user_string")


if __name__ == '__main__':
    conf = {
        '/': {
            'tools.sessions.on': True,
            'tools.staticdir.root': os.path.abspath(os.getcwd())
        },
        '/generator': {
            'request.dispatch': cherrypy.dispatch.MethodDispatcher(),
            'tools.response_headers.on': True,
            'tools.response_headers.headers': [('Content-Type', 'text/plain')],
        },
        '/static': {
            'tools.staticdir.on': True,
            'tools.staticdir.dir': './public'
        }
    }

    cherrypy.engine.subscribe('start', setup_database)
    cherrypy.engine.subscribe('stop', cleanup_database)

    webapp = StringGenerator()
    webapp.generator = StringGeneratorWebService()
    cherrypy.quickstart(webapp, '/', conf)

Save this into a file named tut09.py and run it as follows:

$ python tut09.py

Let’s first see how we create two functions that create and destroy the table within our database. These functions are registered to the CherryPy’s server on lines 85-86, so that they are called when the server starts and stops.

Next, notice how we replaced all the session code with calls to the database. We use the session id to identify the user’s string within our database. Since the session will go away after a while, it’s probably not the right approach. A better idea would be to associate the user’s login or more resilient unique identifier. For the sake of our demo, this should do.

Tutorial 10: Make it a modern single-page application with React.js¶

In the recent years, client-side single-page applications (SPA) have gradually eaten server-side generated content web applications’s lunch.

This tutorial demonstrates how to integrate with React.js, a Javascript library for SPA released by Facebook in 2013. Please refer to React.js documentation to learn more about it.

To demonstrate it, let’s use the code from tutorial 09. However, we will be replacing the HTML and Javascript code.

First, let’s see how our HTML code has changed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

 <!DOCTYPE html>
 <html>
    <head>
      <link href="/static/css/style.css" rel="stylesheet">
      <script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.13.3/react.js"></script>
      <script src="http://code.jquery.com/jquery-2.1.1.min.js"></script>
      <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.23/browser.min.js"></script>
    </head>
    <body>
      <div id="generator"></div>
      <script type="text/babel" src="static/js/gen.js"></script>
    </body>
 </html>

Basically, we have removed the entire Javascript code that was using jQuery. Instead, we load the React.js library as well as a new, local, Javascript module, named gen.js and located in the public/js directory:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

var StringGeneratorBox = React.createClass({
  handleGenerate: function() {
    var length = this.state.length;
    this.setState(function() {
      $.ajax({
        url: this.props.url,
        dataType: 'text',
        type: 'POST',
        data: {
          "length": length
        },
        success: function(data) {
          this.setState({
            length: length,
            string: data,
            mode: "edit"
          });
        }.bind(this),
        error: function(xhr, status, err) {
          console.error(this.props.url,
            status, err.toString()
          );
        }.bind(this)
      });
    });
  },
  handleEdit: function() {
    var new_string = this.state.string;
    this.setState(function() {
      $.ajax({
        url: this.props.url,
        type: 'PUT',
        data: {
          "another_string": new_string
        },
        success: function() {
          this.setState({
            length: new_string.length,
            string: new_string,
            mode: "edit"
          });
        }.bind(this),
        error: function(xhr, status, err) {
          console.error(this.props.url,
            status, err.toString()
          );
        }.bind(this)
      });
    });
  },
  handleDelete: function() {
    this.setState(function() {
      $.ajax({
        url: this.props.url,
        type: 'DELETE',
        success: function() {
          this.setState({
            length: "8",
            string: "",
            mode: "create"
          });
        }.bind(this),
        error: function(xhr, status, err) {
          console.error(this.props.url,
            status, err.toString()
          );
        }.bind(this)
      });
    });
  },
  handleLengthChange: function(length) {
    this.setState({
      length: length,
      string: "",
      mode: "create"
    });
  },
  handleStringChange: function(new_string) {
    this.setState({
      length: new_string.length,
      string: new_string,
      mode: "edit"
    });
  },
  getInitialState: function() {
    return {
      length: "8",
      string: "",
      mode: "create"
    };
  },
  render: function() {
    return (
      <div className="stringGenBox">
            <StringGeneratorForm onCreateString={this.handleGenerate}
                                 onReplaceString={this.handleEdit}
                                 onDeleteString={this.handleDelete}
                                 onLengthChange={this.handleLengthChange}
                                 onStringChange={this.handleStringChange}
                                 mode={this.state.mode}
                                 length={this.state.length}
                                 string={this.state.string}/>
      </div>
    );
  }
});

var StringGeneratorForm = React.createClass({
  handleCreate: function(e) {
    e.preventDefault();
    this.props.onCreateString();
  },
  handleReplace: function(e) {
    e.preventDefault();
    this.props.onReplaceString();
  },
  handleDelete: function(e) {
    e.preventDefault();
    this.props.onDeleteString();
  },
  handleLengthChange: function(e) {
    e.preventDefault();
    var length = React.findDOMNode(this.refs.length).value.trim();
    this.props.onLengthChange(length);
  },
  handleStringChange: function(e) {
    e.preventDefault();
    var string = React.findDOMNode(this.refs.string).value.trim();
    this.props.onStringChange(string);
  },
  render: function() {
    if (this.props.mode == "create") {
      return (
        <div>
           <input  type="text" ref="length" defaultValue="8" value={this.props.length} onChange={this.handleLengthChange} />
           <button onClick={this.handleCreate}>Give it now!</button>
        </div>
      );
    } else if (this.props.mode == "edit") {
      return (
        <div>
           <input type="text" ref="string" value={this.props.string} onChange={this.handleStringChange} />
           <button onClick={this.handleReplace}>Replace</button>
           <button onClick={this.handleDelete}>Delete it</button>
        </div>
      );
    }

    return null;
  }
});

React.render(
  <StringGeneratorBox url="/generator" />,
  document.getElementById('generator')
);

Wow! What a lot of code for something so simple, isn’t it? The entry point is the last few lines where we indicate that we want to render the HTML code of the StringGeneratorBox React.js class inside the generator div.

When the page is rendered, so is that component. Notice how it is also made of another component that renders the form itself.

This might be a little over the top for such a simple example but hopefully will get you started with React.js in the process.

There is not much to say and, hopefully, the meaning of that code is rather clear. The component has an internal state in which we store the current string as generated/modified by the user.

When the user changes the content of the input boxes, the state is updated on the client side. Then, when a button is clicked, that state is sent out to the backend server using the API endpoint and the appropriate action takes places. Then, the state is updated and so is the view.

Tutorial 11: Organize my code¶

CherryPy comes with a powerful architecture that helps you organizing your code in a way that should make it easier to maintain and more flexible.

Several mechanisms are at your disposal, this tutorial will focus on the three main ones:

• dispatchers
• tools
• plugins

In order to understand them, let’s imagine you are at a superstore:

• You have several tills and people queuing for each of them (those are your requests)
• You have various sections with food and other stuff (these are your data)
• Finally you have the superstore people and their daily tasks to make sure sections are always in order (this is your backend)

In spite of being really simplistic, this is not far from how your application behaves. CherryPy helps you structure your application in a way that mirrors these high-level ideas.

The one-minute application example¶

The most basic application you can write with CherryPy involves almost all its core concepts.

1
2
3
4
5
6
7
8
9

import cherrypy

class Root(object):
    @cherrypy.expose
    def index(self):
        return "Hello World!"

if __name__ == '__main__':
   cherrypy.quickstart(Root(), '/')

First and foremost, for most tasks, you will never need more than a single import statement as demonstrated in line 1.

Before discussing the meat, let’s jump to line 9 which shows, how to host your application with the CherryPy application server and serve it with its builtin HTTP server at the ‘/’ path. All in one single line. Not bad.

Let’s now step back to the actual application. Even though CherryPy does not mandate it, most of the time your applications will be written as Python classes. Methods of those classes will be called by CherryPy to respond to client requests. However, CherryPy needs to be aware that a method can be used that way, we say the method needs to be exposed. This is precisely what the cherrypy.expose() decorator does in line 4.

Save the snippet in a file named myapp.py and run your first CherryPy application:

$ python myapp.py

Then point your browser at http://127.0.0.1:8080. Tada!

CherryPy is a minimal framework but not a bare one, it comes with a few basic tools to cover common usages that you would expect.

Hosting one or more applications¶

A web application needs an HTTP server to be accessed to. CherryPy provides its own, production ready, HTTP server. There are two ways to host an application with it. The simple one and the almost-as-simple one.

cherrypy.quickstart(Blog())
cherrypy.quickstart(Blog(), '/blog')
cherrypy.quickstart(Blog(), '/blog', {'/': {'tools.gzip.on': True}})

cherrypy.tree.mount(Blog(), '/blog', blog_conf)
cherrypy.tree.mount(Forum(), '/forum', forum_conf)

cherrypy.engine.start()
cherrypy.engine.block()

cherrypy.tree.mount(Blog(), '/blog', blog_conf)
cherrypy.quickstart(Forum(), '/forum', forum_conf)

Logging¶

Logging is an important task in any application. CherryPy will log all incoming requests as well as protocol errors.

To do so, CherryPy manages two loggers:

• an access one that logs every incoming requests
• an application/error log that traces errors or other application-level messages

Your application may leverage that second logger by calling cherrypy.log().

cherrypy.log("hello there")

You can also log an exception:

try:
   ...
except:
   cherrypy.log("kaboom!", traceback=True)

Both logs are writing to files identified by the following keys in your configuration:

• log.access_file for incoming requests using the common log format
• log.error_file for the other log

cherrypy.config.update({'log.screen': False,
                        'log.access_file': '',
                        'log.error_file': ''})

import logging
import logging.config

import cherrypy

logger = logging.getLogger()
db_logger = logging.getLogger('db')

LOG_CONF = {
    'version': 1,

    'formatters': {
        'void': {
            'format': ''
        },
        'standard': {
            'format': '%(asctime)s [%(levelname)s] %(name)s: %(message)s'
        },
    },
    'handlers': {
        'default': {
            'level':'INFO',
            'class':'logging.StreamHandler',
            'formatter': 'standard',
            'stream': 'ext://sys.stdout'
        },
        'cherrypy_console': {
            'level':'INFO',
            'class':'logging.StreamHandler',
            'formatter': 'void',
            'stream': 'ext://sys.stdout'
        },
        'cherrypy_access': {
            'level':'INFO',
            'class': 'logging.handlers.RotatingFileHandler',
            'formatter': 'void',
            'filename': 'access.log',
            'maxBytes': 10485760,
            'backupCount': 20,
            'encoding': 'utf8'
        },
        'cherrypy_error': {
            'level':'INFO',
            'class': 'logging.handlers.RotatingFileHandler',
            'formatter': 'void',
            'filename': 'errors.log',
            'maxBytes': 10485760,
            'backupCount': 20,
            'encoding': 'utf8'
        },
    },
    'loggers': {
        '': {
            'handlers': ['default'],
            'level': 'INFO'
        },
        'db': {
            'handlers': ['default'],
            'level': 'INFO' ,
            'propagate': False
        },
        'cherrypy.access': {
            'handlers': ['cherrypy_access'],
            'level': 'INFO',
            'propagate': False
        },
        'cherrypy.error': {
            'handlers': ['cherrypy_console', 'cherrypy_error'],
            'level': 'INFO',
            'propagate': False
        },
    }
}

class Root(object):
    @cherrypy.expose
    def index(self):

        logger.info("boom")
        db_logger.info("bam")
        cherrypy.log("bang")

        return "hello world"

if __name__ == '__main__':
    cherrypy.config.update({'log.screen': False,
                            'log.access_file': '',
                            'log.error_file': ''})
cherrypy.engine.unsubscribe('graceful', cherrypy.log.reopen_files)
    logging.config.dictConfig(LOG_CONF)
    cherrypy.quickstart(Root())

Configuring¶

CherryPy comes with a fine-grained configuration mechanism and settings can be set at various levels.

cherrypy.config.update({'server.socket_port': 9090})

[global]
server.socket_port: 9090

cherrypy.config.update("server.conf")

cherrypy.quickstart(myapp, '/', {'/': {'tools.gzip.on': True}})

[/]
tools.gzip.on: True

cherrypy.quickstart(myapp, '/', "app.conf")

class Root(object):
    @cherrypy.expose
    @cherrypy.tools.gzip()
    def index(self):
        return "hello world!"

class Root(object):
    @cherrypy.expose
    def index(self):
        return "hello world!"
    index._cp_config = {'tools.gzip.on': True}

[/]
tools.gzip.on: True

[googleapi]
key = "..."
appid = "..."

class Root(object):
    @cherrypy.expose
    def index(self):
        google_appid = cherrypy.request.app.config['googleapi']['appid']
        return "hello world!"

cherrypy.quickstart(Root(), '/', "app.conf")

Cookies¶

CherryPy uses the Cookie module from python and in particular the Cookie.SimpleCookie object type to handle cookies.

• To send a cookie to a browser, set cherrypy.response.cookie[key] = value.
• To retrieve a cookie sent by a browser, use cherrypy.request.cookie[key].
• To delete a cookie (on the client side), you must send the cookie with its expiration time set to 0:

cherrypy.response.cookie[key] = value
cherrypy.response.cookie[key]['expires'] = 0

It’s important to understand that the request cookies are not automatically copied to the response cookies. Clients will send the same cookies on every request, and therefore cherrypy.request.cookie should be populated each time. But the server doesn’t need to send the same cookies with every response; therefore, cherrypy.response.cookie will usually be empty. When you wish to “delete” (expire) a cookie, therefore, you must set cherrypy.response.cookie[key] = value first, and then set its expires attribute to 0.

Extended example:

import cherrypy

class MyCookieApp(object):
    @cherrypy.expose
    def set(self):
        cookie = cherrypy.response.cookie
        cookie['cookieName'] = 'cookieValue'
        cookie['cookieName']['path'] = '/'
        cookie['cookieName']['max-age'] = 3600
        cookie['cookieName']['version'] = 1
        return "<html><body>Hello, I just sent you a cookie</body></html>"

    @cherrypy.expose
    def read(self):
        cookie = cherrypy.request.cookie
        res = """<html><body>Hi, you sent me %s cookies.<br />
                Here is a list of cookie names/values:<br />""" % len(cookie)
        for name in cookie.keys():
            res += "name: %s, value: %s<br>" % (name, cookie[name].value)
        return res + "</body></html>"

if __name__ == '__main__':
    cherrypy.quickstart(MyCookieApp(), '/cookie')

Using sessions¶

Sessions are one of the most common mechanism used by developers to identify users and synchronize their activity. By default, CherryPy does not activate sessions because it is not a mandatory feature to have, to enable it simply add the following settings in your configuration:

[/]
tools.sessions.on: True

cherrypy.quickstart(myapp, '/', "app.conf")

Sessions are, by default, stored in RAM so, if you restart your server all of your current sessions will be lost. You can store them in memcached or on the filesystem instead.

Using sessions in your applications is done as follows:

import cherrypy

@cherrypy.expose
def index(self):
    if 'count' not in cherrypy.session:
       cherrypy.session['count'] = 0
    cherrypy.session['count'] += 1

In this snippet, everytime the the index page handler is called, the current user’s session has its ‘count’ key incremented by 1.

CherryPy knows which session to use by inspecting the cookie sent alongside the request. This cookie contains the session identifier used by CherryPy to load the user’s session from the storage.

[/]
tools.sessions.on: True
tools.sessions.storage_class = cherrypy.lib.sessions.FileSession
tools.sessions.storage_path = "/some/directory"

[/]
tools.sessions.on: True
tools.sessions.storage_class = cherrypy.lib.sessions.MemcachedSession

Static content serving¶

CherryPy can serve your static content such as images, javascript and CSS resources, etc.

import mimetypes
mimetypes.types_map['.csv'] = 'text/csv'

[/style.css]
tools.staticfile.on = True
tools.staticfile.filename = "/home/site/style.css"

[/static]
tools.staticdir.on = True
tools.staticdir.dir = "/home/site/static"

[/]
tools.staticdir.root = "/home/site"

[/static]
tools.staticdir.on = True
tools.staticdir.dir = "static"

[/static]
tools.staticdir.on = True
tools.staticdir.dir = "/home/site/static"
tools.staticdir.index = "index.html"

from cherrypy.lib.static import serve_file

@cherrypy.expose
def download(self, filepath):
    return serve_file(filepath, "application/x-download", "attachment")

Dealing with JSON¶

CherryPy has built-in support for JSON encoding and decoding of the request and/or response.

class Root(object):
    @cherrypy.expose
    @cherrypy.tools.json_in()
    def index(self):
        data = cherrypy.request.json

class Root(object):
    @cherrypy.expose
    @cherrypy.tools.json_out()
    def index(self):
        return {'key': 'value'}

Authentication¶

CherryPy provides support for two very simple authentication mechanisms, both described in RFC 2617: Basic and Digest. They are most commonly known to trigger a browser’s popup asking users their name and password.

from cherrypy.lib import auth_basic

USERS = {'jon': 'secret'}

def validate_password(realm, username, password):
    if username in USERS and USERS[username] == password:
       return True
    return False

conf = {
   '/protected/area': {
       'tools.auth_basic.on': True,
       'tools.auth_basic.realm': 'localhost',
       'tools.auth_basic.checkpassword': validate_password
    }
}

cherrypy.quickstart(myapp, '/', conf)

from cherrypy.lib import auth_digest

USERS = {'jon': 'secret'}

conf = {
   '/protected/area': {
        'tools.auth_digest.on': True,
        'tools.auth_digest.realm': 'localhost',
        'tools.auth_digest.get_ha1': auth_digest.get_ha1_dict_plain(USERS),
        'tools.auth_digest.key': 'a565c27146791cfb'
   }
}

cherrypy.quickstart(myapp, '/', conf)

Favicon¶

CherryPy serves its own sweet red cherrypy as the default favicon using the static file tool. You can serve your own favicon as follows:

import cherrypy

class HelloWorld(object):
   @cherrypy.expose
   def index(self):
       return "Hello World!"

if __name__ == '__main__':
    cherrypy.quickstart(HelloWorld(), '/',
        {
            '/favicon.ico':
            {
                'tools.staticfile.on': True,
                'tools.staticfile.filename': '/path/to/myfavicon.ico'
            }
        }
    )

Please refer to the static serving section for more details.

You can also use a file to configure it:

[/favicon.ico]
tools.staticfile.on: True
tools.staticfile.filename: "/path/to/myfavicon.ico"

import cherrypy

class HelloWorld(object):
   @cherrypy.expose
   def index(self):
       return "Hello World!"

if __name__ == '__main__':
    cherrypy.quickstart(HelloWorld(), '/', app.conf)

Set aliases to page handlers¶

A fairly unknown, yet useful, feature provided by the cherrypy.expose() decorator is to support aliases.

Let’s use the template provided by tutorial 03:

import random
import string

import cherrypy

class StringGenerator(object):
    @cherrypy.expose(['generer', 'generar'])
    def generate(self, length=8):
        return ''.join(random.sample(string.hexdigits, int(length)))

if __name__ == '__main__':
    cherrypy.quickstart(StringGenerator())

In this example, we create localized aliases for the page handler. This means the page handler will be accessible via:

• /generate
• /generer (French)
• /generar (Spanish)

Obviously, your aliases may be whatever suits your needs.

RESTful-style dispatching¶

The term RESTful URL is sometimes used to talk about friendly URLs that nicely map to the entities an application exposes.

Let’s assume you wish to create an application that exposes music bands and their records. Your application will probably have the following URLs:

• http://hostname/<artist>/
• http://hostname/<artist>/albums/<album_title>/

It’s quite clear you would not create a page handler named after every possible band in the world. This means you will need a page handler that acts as a proxy for all of them.

The default dispatcher cannot deal with that scenario on its own because it expects page handlers to be explicitely declared in your source code. Luckily, CherryPy provides ways to support those use cases.

import cherrypy

class Band(object):
    def __init__(self):
        self.albums = Album()

    def _cp_dispatch(self, vpath):
        if len(vpath) == 1:
            cherrypy.request.params['name'] = vpath.pop()
            return self

        if len(vpath) == 3:
            cherrypy.request.params['artist'] = vpath.pop(0)  # /band name/
            vpath.pop(0) # /albums/
            cherrypy.request.params['title'] = vpath.pop(0) # /album title/
            return self.albums

        return vpath

    @cherrypy.expose
    def index(self, name):
        return 'About %s...' % name

class Album(object):
    @cherrypy.expose
    def index(self, artist, title):
        return 'About %s by %s...' % (title, artist)

if __name__ == '__main__':
    cherrypy.quickstart(Band())

import cherrypy

@cherrypy.popargs('band_name')
class Band(object):
    def __init__(self):
        self.albums = Album()

    @cherrypy.expose
    def index(self, band_name):
        return 'About %s...' % band_name

@cherrypy.popargs('album_title')
class Album(object):
    @cherrypy.expose
    def index(self, band_name, album_title):
        return 'About %s by %s...' % (album_title, band_name)

if __name__ == '__main__':
    cherrypy.quickstart(Band())

@cherrypy.popargs('album_title')
class Album(object):
    def __init__(self):
        self.tracks = Track()

@cherrypy.popargs('track_num', 'track_title')
class Track(object):
    @cherrypy.expose
    def index(self, band_name, album_title, track_num, track_title):
        ...

Error handling¶

CherryPy’s HTTPError class supports raising immediate responses in the case of errors.

class Root:
    @cherrypy.expose
    def thing(self, path):
        if not authorized():
            raise cherrypy.HTTPError(401, 'Unauthorized')
        try:
            file = open(path)
        except FileNotFoundError:
            raise cherrypy.HTTPError(404)

HTTPError.handle is a context manager which supports translating exceptions raised in the app into an appropriate HTTP response, as in the second example.

class Root:
    @cherrypy.expose
    def thing(self, path):
        with cherrypy.HTTPError.handle(FileNotFoundError, 404):
            file = open(path)

Streaming the response body¶

CherryPy handles HTTP requests, packing and unpacking the low-level details, then passing control to your application’s page handler, which produce the body of the response. CherryPy allows you to return body content in a variety of types: a string, a list of strings, a file. CherryPy also allows you to yield content, rather than return content. When you use “yield”, you also have the option of streaming the output.

In general, it is safer and easier to not stream output. Therefore, streaming output is off by default. Streaming output and also using sessions requires a good understanding of how session locks work.

The “normal” CherryPy response process¶

When you provide content from your page handler, CherryPy manages the conversation between the HTTP server and your code like this:

Notice that the HTTP server gathers all output first and then writes everything to the client at once: status, headers, and body. This works well for static or simple pages, since the entire response can be changed at any time, either in your application code, or by the CherryPy framework.

How “streaming output” works with CherryPy¶

When you set the config entry “response.stream” to True (and use “yield”), CherryPy manages the conversation between the HTTP server and your code like this:

When you stream, your application doesn’t immediately pass raw body content back to CherryPy or to the HTTP server. Instead, it passes back a generator. At that point, CherryPy finalizes the status and headers, before the generator has been consumed, or has produced any output. This is necessary to allow the HTTP server to send the headers and pieces of the body as they become available.

Once CherryPy has set the status and headers, it sends them to the HTTP server, which then writes them out to the client. From that point on, the CherryPy framework mostly steps out of the way, and the HTTP server essentially requests content directly from your application code (your page handler method).

Therefore, when streaming, if an error occurs within your page handler, CherryPy will not catch it–the HTTP server will catch it. Because the headers (and potentially some of the body) have already been written to the client, the server cannot know a safe means of handling the error, and will therefore simply close the connection (the current, builtin servers actually write out a short error message in the body, but this may be changed, and is not guaranteed behavior for all HTTP servers you might use with CherryPy).

In addition, you cannot manually modify the status or headers within your page handler if that handler method is a streaming generator, because the method will not be iterated over until after the headers have been written to the client. This includes raising exceptions like HTTPError, NotFound, InternalRedirect and HTTPRedirect. To use a streaming generator while modifying headers, you would have to return a generator that is separate from (or embedded in) your page handler. For example:

class Root:
    @cherrypy.expose
    def thing(self):
        cherrypy.response.headers['Content-Type'] = 'text/plain'
        if not authorized():
            raise cherrypy.NotFound()
        def content():
            yield "Hello, "
            yield "world"
        return content()
    thing._cp_config = {'response.stream': True}

Streaming generators are sexy, but they play havoc with HTTP. CherryPy allows you to stream output for specific situations: pages which take many minutes to produce, or pages which need a portion of their content immediately output to the client. Because of the issues outlined above, it is usually better to flatten (buffer) content rather than stream content. Do otherwise only when the benefits of streaming outweigh the risks.

Response timeouts¶

CherryPy responses include 3 attributes related to time:

• response.time: the time.time() at which the response began
• response.timeout: the number of seconds to allow responses to run
• response.timed_out: a boolean indicating whether the response has timed out (default False).

The request processing logic inspects the value of response.timed_out at various stages; if it is ever True, then TimeoutError is raised. You are free to do the same within your own code.

Rather than calculate the difference by hand, you can call response.check_timeout to set timed_out for you.

[global]
engine.timeout_monitor.on: False

cherrypy.engine.timeout_monitor.unsubscribe()

[global]
engine.timeout_monitor.frequency: 60 * 60

Deal with signals¶

This engine plugin is instantiated automatically as cherrypy.engine.signal_handler. However, it is only subscribed automatically by cherrypy.quickstart(). So if you want signal handling and you’re calling:

tree.mount()
engine.start()
engine.block()

on your own, be sure to add before you start the engine:

engine.signals.subscribe()

Securing your server¶

There are several settings that can be enabled to make CherryPy pages more secure. These include:

Transmitting data:

1. Use Secure Cookies

Rendering pages:

1. Set HttpOnly cookies
2. Set XFrame options
3. Enable XSS Protection
4. Set the Content Security Policy

An easy way to accomplish this is to set headers with a tool and wrap your entire CherryPy application with it:

import cherrypy

# set the priority according to your needs if you are hooking something
# else on the 'before_finalize' hook point.
@cherrypy.tools.register('before_finalize', priority=60)
def secureheaders():
    headers = cherrypy.response.headers
    headers['X-Frame-Options'] = 'DENY'
    headers['X-XSS-Protection'] = '1; mode=block'
    headers['Content-Security-Policy'] = "default-src='self'"

Then, in the configuration file (or any other place that you want to enable the tool):

[/]
tools.secureheaders.on = True

If you use sessions you can also enable these settings:

[/]
tools.sessions.on = True
# increase security on sessions
tools.sessions.secure = True
tools.sessions.httponly = True

If you use SSL you can also enable Strict Transport Security:

 # add this to secureheaders():
 # only add Strict-Transport headers if we're actually using SSL; see the ietf spec
 # "An HSTS Host MUST NOT include the STS header field in HTTP responses
 # conveyed over non-secure transport"
 # http://tools.ietf.org/html/draft-ietf-websec-strict-transport-sec-14#section-7.2
 if (cherrypy.server.ssl_certificate != None and cherrypy.server.ssl_private_key != None):
headers['Strict-Transport-Security'] = 'max-age=31536000'  # one year

Next, you should probably use SSL.

Multiple HTTP servers support¶

CherryPy starts its own HTTP server whenever you start the engine. In some cases, you may wish to host your application on more than a single port. This is easily achieved:

from cherrypy._cpserver import Server
server = Server()
server.socket_port = 8090
server.subscribe()

You can create as many server server instances as you need, once subscribed, they will follow the CherryPy engine’s life-cycle.

WSGI support¶

CherryPy supports the WSGI interface defined in PEP 333 as well as its updates in PEP 3333. It means the following:

• You can host a foreign WSGI application with the CherryPy server
• A CherryPy application can be hosted by another WSGI server

import cherrypy
wsgiapp = cherrypy.Application(StringGenerator(), '/', config=myconf)

def raw_wsgi_app(environ, start_response):
    status = '200 OK'
    response_headers = [('Content-type','text/plain')]
    start_response(status, response_headers)
    return ['Hello world!']

cherrypy.tree.graft(raw_wsgi_app, '/')

import cherrypy

class Root(object):
    @cherrypy.expose
    def index(self):
        return "Hello World!"

if __name__ == '__main__':
    from cherrypy._cpnative_server import CPHTTPServer
    cherrypy.server.httpserver = CPHTTPServer(cherrypy.server)

    cherrypy.quickstart(Root(), '/')

WebSocket support¶

WebSocket is a recent application protocol that came to life from the HTML5 working-group in response to the needs for bi-directional communication. Various hacks had been proposed such as Comet, polling, etc.

WebSocket is a socket that starts its life from a HTTP upgrade request. Once the upgrade is performed, the underlying socket is kept opened but not used in a HTTP context any longer. Instead, both connected endpoints may use the socket to push data to the other end.

CherryPy itself does not support WebSocket, but the feature is provided by an external library called ws4py.

Database support¶

CherryPy does not bundle any database access but its architecture makes it easy to integrate common database interfaces such as the DB-API specified in PEP 249. Alternatively, you can also use an ORM such as SQLAlchemy or SQLObject.

You will find here a recipe on how integrating SQLAlchemy using a mix of plugins and tools.

HTML Templating support¶

CherryPy does not provide any HTML template but its architecture makes it easy to integrate one. Popular ones are Mako or Jinja2.

You will find here a recipe on how to integrate them using a mix plugins and tools.

Testing your application¶

Web applications, like any other kind of code, must be tested. CherryPy provides a helper class to ease writing functional tests.

Here is a simple example for a basic echo application:

import cherrypy
from cherrypy.test import helper

class SimpleCPTest(helper.CPWebCase):
    def setup_server():
        class Root(object):
            @cherrypy.expose
            def echo(self, message):
                return message

        cherrypy.tree.mount(Root())
    setup_server = staticmethod(setup_server)

    def test_message_should_be_returned_as_is(self):
        self.getPage("/echo?message=Hello%20world")
        self.assertStatus('200 OK')
        self.assertHeader('Content-Type', 'text/html;charset=utf-8')
        self.assertBody('Hello world')

    def test_non_utf8_message_will_fail(self):
        """
        CherryPy defaults to decode the query-string
        using UTF-8, trying to send a query-string with
        a different encoding will raise a 404 since
        it considers it's a different URL.
        """
        self.getPage("/echo?message=A+bient%F4t",
                     headers=[
                         ('Accept-Charset', 'ISO-8859-1,utf-8'),
                         ('Content-Type', 'text/html;charset=ISO-8859-1')
                     ]
        )
        self.assertStatus('404 Not Found')

As you can see the, test inherits from that helper class. You should setup your application and mount it as per-usual. Then, define your various tests and call the helper getPage() method to perform a request. Simply use the various specialized assert* methods to validate your workflow and data.

You can then run the test using py.test as follows:

$ py.test -s test_echo_app.py

The -s is necessary because the CherryPy class also wraps stdin and stdout.

Architecture¶

The first thing you need to know about CherryPy 3’s configuration is that it separates global config from application config. If you’re deploying multiple applications at the same site (and more and more people are, as Python web apps are tending to decentralize), you need to be careful to separate the configurations, as well. There’s only ever one “global config”, but there is a separate “app config” for each app you deploy.

CherryPy Requests are part of an Application, which runs in a global context, and configuration data may apply to any of those three scopes. Let’s look at each of those scopes in turn.

cherrypy.config.update({'server.socket_host': '64.72.221.48',
                        'server.socket_port': 80,
                       })

[/]
tools.trailing_slash.on = False
request.dispatch: cherrypy.dispatch.MethodDispatcher()

config = {'/':
    {
        'request.dispatch': cherrypy.dispatch.MethodDispatcher(),
        'tools.trailing_slash.on': False,
    }
}
cherrypy.tree.mount(Root(), config=config)

[global]
server.socket_host: "0.0.0.0"

[Databases]
driver: "postgres"
host: "localhost"
port: 5432

[/path]
response.timeout: 6000

Declaration¶

Configuration data may be supplied as a Python dictionary, as a filename, or as an open file object.

[/path/to/my/page]
response.stream: True
tools.trailing_slash.extra = False

# global config
cherrypy.config.update({'environment': 'production',
                        'log.error_file': 'site.log',
                        # ...
                        })

# Mount each app and pass it its own config
cherrypy.tree.mount(root1, "", appconf1)
cherrypy.tree.mount(root2, "/forum", appconf2)
cherrypy.tree.mount(root3, "/blog", appconf3)

if hasattr(cherrypy.engine, 'block'):
    # 3.1 syntax
    cherrypy.engine.start()
    cherrypy.engine.block()
else:
    # 3.0 syntax
    cherrypy.server.quickstart()
    cherrypy.engine.start()

[global]
log.error_file: "/home/fumanchu/myapp.log"
environment = 'production'
server.max_request_body_size: 1200

[/myapp]
tools.trailing_slash.on = False
request.dispatch: cherrypy.dispatch.MethodDispatcher()

[/path/to/page]
methods_with_bodies = ("POST", "PUT", "PROPPATCH")

@cherrypy.expose
def page(self):
    return "Hello, world!"
page._cp_config = {"request.methods_with_bodies": ("POST", "PUT", "PROPPATCH")}

class SetOPages:

    _cp_config = {"request.methods_with_bodies": ("POST", "PUT", "PROPPATCH")}

    @cherrypy.expose
    def page(self):
        return "Hullo, Werld!"

Namespaces¶

Because config entries usually just set attributes on objects, they’re almost all of the form: object.attribute. A few are of the form: object.subobject.attribute. They look like normal Python attribute chains, because they work like them. We call the first name in the chain the “config namespace”. When you provide a config entry, it is bound as early as possible to the actual object referenced by the namespace; for example, the entry response.stream actually sets the stream attribute of cherrypy.response! In this way, you can easily determine the default value by firing up a python interpreter and typing:

>>> import cherrypy
>>> cherrypy.response.stream
False

Each config namespace has its own handler; for example, the “request” namespace has a handler which takes your config entry and sets that value on the appropriate “request” attribute. There are a few namespaces, however, which don’t work like normal attributes behind the scenes; however, they still use dotted keys and are considered to “have a namespace”.

[/]
hooks.before_handler = myapp.my_hook_func

def db_namespace(k, v):
    if k == 'connstring':
        orm.connect(v)
cherrypy.config.namespaces['db'] = db_namespace

Config.environments = environments = {
    'staging': {
        'engine.autoreload.on': False,
        'checker.on': False,
        'tools.log_headers.on': False,
        'request.show_tracebacks': False,
        'request.show_mismatched_params': False,
    },
    'production': {
        'engine.autoreload.on': False,
        'checker.on': False,
        'tools.log_headers.on': False,
        'request.show_tracebacks': False,
        'request.show_mismatched_params': False,
        'log.screen': False,
    },
    'embedded': {
        # For use with CherryPy embedded in another deployment stack.
        'engine.autoreload.on': False,
        'checker.on': False,
        'tools.log_headers.on': False,
        'request.show_tracebacks': False,
        'request.show_mismatched_params': False,
        'log.screen': False,
        'engine.SIGHUP': None,
        'engine.SIGTERM': None,
    },
    'test_suite': {
        'engine.autoreload.on': False,
        'checker.on': False,
        'tools.log_headers.on': False,
        'request.show_tracebacks': True,
        'request.show_mismatched_params': True,
        'log.screen': False,
    },
}

cherrypy._cpconfig.environments['staging']['log.screen'] = False

cherrypy._cpconfig.environments['Greek'] = {
    'tools.encode.encoding': 'ISO-8859-7',
    'tools.decode.encoding': 'ISO-8859-7',
    }

Server-wide functions¶

CherryPy can be considered both as a HTTP library as much as a web application framework. In that latter case, its architecture provides mechanisms to support operations accross the whole server instance. This offers a powerful canvas to perform persistent operations as server-wide functions live outside the request processing itself. They are available to the whole process as long as the bus lives.

Typical use cases:

• Keeping a pool of connection to an external server so that your need not to re-open them on each request (database connections for instance).
• Background processing (say you need work to be done without blocking the whole request itself).

Publish/Subscribe pattern¶

CherryPy’s backbone consists of a bus system implementing a simple publish/subscribe messaging pattern. Simply put, in CherryPy everything is controlled via that bus. One can easily picture the bus as a sushi restaurant’s belt as in the picture below.

You can subscribe and publish to channels on a bus. A channel is bit like a unique identifier within the bus. When a message is published to a channel, the bus will dispatch the message to all subscribers for that channel.

One interesting aspect of a pubsub pattern is that it promotes decoupling between a caller and the callee. A published message will eventually generate a response but the publisher does not know where that response came from.

Thanks to that decoupling, a CherryPy application can easily access functionalities without having to hold a reference to the entity providing that functionality. Instead, the application simply publishes onto the bus and will receive the appropriate response, which is all that matter.

Typical pattern¶

Let’s take the following dummy application:

import cherrypy

class ECommerce(object):
    def __init__(self, db):
        self.mydb = db

    @cherrypy.expose
    def save_kart(self, cart_data):
        cart = Cart(cart_data)
        self.mydb.save(cart)

if __name__ == '__main__':
   cherrypy.quickstart(ECommerce(), '/')

The application has a reference to the database but this creates a fairly strong coupling between the database provider and the application.

Another approach to work around the coupling is by using a pubsub workflow:

import cherrypy

class ECommerce(object):
    @cherrypy.expose
    def save_kart(self, cart_data):
        cart = Cart(cart_data)
        cherrypy.engine.publish('db-save', cart)

if __name__ == '__main__':
   cherrypy.quickstart(ECommerce(), '/')

In this example, we publish a cart instance to db-save channel. One or many subscribers can then react to that message and the application doesn’t have to know about them.

Note

This approach is not mandatory and it’s up to you to decide how to design your entities interaction.

Implementation details¶

CherryPy’s bus implementation is simplistic as it registers functions to channels. Whenever a message is published to a channel, each registered function is applied with that message passed as a parameter.

The whole behaviour happens synchronously and, in that sense, if a subscriber takes too long to process a message, the remaining subscribers will be delayed.

CherryPy’s bus is not an advanced pubsub messaging broker system such as provided by zeromq or RabbitMQ. Use it with the understanding that it may have a cost.

Engine as a pubsub bus¶

As said earlier, CherryPy is built around a pubsub bus. All entities that the framework manages at runtime are working on top of a single bus instance, which is named the engine.

The bus implementation therefore provides a set of common channels which describe the application’s lifecycle:

                 O
                 |
                 V
STOPPING --> STOPPED --> EXITING -> X
   A   A         |
   |    \___     |
   |        \    |
   |         V   V
 STARTED <-- STARTING

The states’ transitions trigger channels to be published to so that subscribers can react to them.

One good example is the HTTP server which will tranisition from a “STOPPED” stated to a “STARTED” state whenever a message is published to the start channel.

Built-in channels¶

In order to support its life-cycle, CherryPy defines a set of common channels that will be published to at various states:

• “start”: When the bus is in the “STARTING” state
• “main”: Periodically from the CherryPy’s mainloop
• “stop”: When the bus is in the “STOPPING” state
• “graceful”: When the bus requests a reload of subscribers
• “exit”: When the bus is in the “EXITING” state

This channel will be published to by the engine automatically. Register therefore any subscribers that would need to react to the transition changes of the engine.

In addition, a few other channels are also published to during the request processing.

• `“before_request”: right before the request is processed by CherryPy
• “after_request”: right after it has been processed

Also, from the cherrypy.process.plugins.ThreadManager plugin:

• “acquire_thread”
• “start_thread”
• “stop_thread”
• “release_thread”

Bus API¶

In order to work with the bus, the implementation provides the following simple API:

• cherrypy.engine.publish(channel, *args):

• The channel parameter is a string identifying the channel to which the message should be sent to
• *args is the message and may contain any valid Python values or objects.

• cherrypy.engine.subscribe(channel, callable):

• The channel parameter is a string identifying the channel the callable will be registered to.
• callable is a Python function or method which signature must match what will be published.

• cherrypy.engine.unsubscribe(channel, callable):

• The channel parameter is a string identifying the channel the callable was registered to.
• callable is the Python function or method which was registered.

import cherrypy
from cherrypy.process import wspbus, plugins

class DatabasePlugin(plugins.SimplePlugin):
    def __init__(self, bus, db_klass):
        plugins.SimplePlugin.__init__(self, bus)
        self.db = db_klass()

    def start(self):
        self.bus.log('Starting up DB access')
        self.bus.subscribe("db-save", self.save_it)

    def stop(self):
        self.bus.log('Stopping down DB access')
        self.bus.unsubscribe("db-save", self.save_it)

    def save_it(self, entity):
        self.db.save(entity)

DatabasePlugin(cherrypy.engine, SQLiteDB).subscribe()

someplugin.unsubscribe()

cherrypy.server.unsubscribe()

import cherrypy

class Root(object):
    @cherrypy.expose
    def index(self):
        return "hello world"

if __name__ == '__main__':
    cherrypy.quickstart(Root())

[27/Apr/2014:13:04:07] ENGINE Listening for SIGHUP.
[27/Apr/2014:13:04:07] ENGINE Listening for SIGTERM.
[27/Apr/2014:13:04:07] ENGINE Listening for SIGUSR1.
[27/Apr/2014:13:04:07] ENGINE Bus STARTING
[27/Apr/2014:13:04:07] ENGINE Started monitor thread 'Autoreloader'.
[27/Apr/2014:13:04:07] ENGINE Started monitor thread '_TimeoutMonitor'.
[27/Apr/2014:13:04:08] ENGINE Serving on http://127.0.0.1:8080
[27/Apr/2014:13:04:08] ENGINE Bus STARTED

import cherrypy

class Root(object):
    @cherrypy.expose
    def index(self):
        return "hello world"

if __name__ == '__main__':
    cherrypy.server.unsubscribe()
    cherrypy.quickstart(Root())

[27/Apr/2014:13:08:06] ENGINE Listening for SIGHUP.
[27/Apr/2014:13:08:06] ENGINE Listening for SIGTERM.
[27/Apr/2014:13:08:06] ENGINE Listening for SIGUSR1.
[27/Apr/2014:13:08:06] ENGINE Bus STARTING
[27/Apr/2014:13:08:06] ENGINE Started monitor thread 'Autoreloader'.
[27/Apr/2014:13:08:06] ENGINE Started monitor thread '_TimeoutMonitor'.
[27/Apr/2014:13:08:06] ENGINE Bus STARTED

[27/Apr/2014:13:04:08] ENGINE Serving on http://127.0.0.1:8080

Per-request functions¶

One of the most common task in a web application development is to tailor the request’s processing to the runtime context.

Within CherryPy, this is performed via what are called tools. If you are familiar with Django or WSGI middlewares, CherryPy tools are similar in spirit. They add functions that are applied during the request/response processing.

@cherrypy.tools.register('before_finalize')
def logit():
   print(cherrypy.request.remote.ip)

cherrypy.tools.logit = cherrypy.Tool('before_finalize', logit)

class Root(object):
    @cherrypy.expose
    @cherrypy.tools.logit()
    def index(self):
        return "hello world"

import time

import cherrypy

class TimingTool(cherrypy.Tool):
    def __init__(self):
        cherrypy.Tool.__init__(self, 'before_handler',
                               self.start_timer,
                               priority=95)

    def _setup(self):
        cherrypy.Tool._setup(self)
        cherrypy.request.hooks.attach('before_finalize',
                                      self.end_timer,
                                      priority=5)

    def start_timer(self):
        cherrypy.request._time = time.time()

    def end_timer(self):
        duration = time.time() - cherrypy.request._time
        cherrypy.log("Page handler took %.4f" % duration)

cherrypy.tools.timeit = TimingTool()

class Root(object):
    @cherrypy.expose
    @cherrypy.tools.timeit()
    def index(self):
        return "hello world"

import cherrypy

# Create a new Toolbox.
newauthtools = cherrypy._cptools.Toolbox("newauth")

# Add a Tool to our new Toolbox.
@newauthtools.register('before_request_body')
def check_access(default=False):
    if not getattr(cherrypy.request, "userid", default):
        raise cherrypy.HTTPError(401)

import cherrypy

class Root(object):
    @cherrypy.expose
    def default(self):
        return "Hello"

conf = {
   '/demo': {
       'newauth.check_access.on': True,
       'newauth.check_access.default': True,
    }
}

app = cherrypy.tree.mount(Root(), config=conf)

import cherrypy

class UserManager(cherrypy.Tool):
    def __init__(self):
        cherrypy.Tool.__init__(self, 'before_handler',
                               self.load, priority=10)

    def load(self):
        req = cherrypy.request

        # let's assume we have a db session
        # attached to the request somehow
        db = req.db

        # retrieve the user id and remove it
        # from the request parameters
        user_id = req.params.pop('user_id')
        req.params['user'] = db.get(int(user_id))

cherrypy.tools.user = UserManager()


class Root(object):
    @cherrypy.expose
    @cherrypy.tools.user()
    def index(self, user):
        return "hello %s" % user.name

Tailored dispatchers¶

Dispatching is the art of locating the appropriate page handler for a given request. Usually, dispatching is based on the request’s URL, the query-string and, sometimes, the request’s method (GET, POST, etc.).

Based on this, CherryPy comes with various dispatchers already.

In some cases however, you will need a little more. Here is an example of dispatcher that will always ensure the incoming URL leads to a lower-case page handler.

import random
import string

import cherrypy
from cherrypy._cpdispatch import Dispatcher

class StringGenerator(object):
   @cherrypy.expose
   def generate(self, length=8):
       return ''.join(random.sample(string.hexdigits, int(length)))

class ForceLowerDispatcher(Dispatcher):
    def __call__(self, path_info):
        return Dispatcher.__call__(self, path_info.lower())

if __name__ == '__main__':
    conf = {
        '/': {
            'request.dispatch': ForceLowerDispatcher(),
        }
    }
    cherrypy.quickstart(StringGenerator(), '/', conf)

Once you run this snipper, go to:

• http://localhost:8080/generate?length=8
• http://localhost:8080/GENerAte?length=8

In both cases, you will be led to the generate page handler. Without our home-made dispatcher, the second one would fail and return a 404 error (RFC 2616#sec10.4.5).

Request body processors¶

Since its 3.2 release, CherryPy provides a really elegant and powerful mechanism to deal with a request’s body based on its mimetype. Refer to the cherrypy._cpreqbody module to understand how to implement your own processors.

Run as a daemon¶

CherryPy allows you to easily decouple the current process from the parent environment, using the traditional double-fork: