CherryPy Documentation Release 3.3.0 CherryPy Team August 05, 2016 Contents 1 What is CherryPy? 1 2 What CherryPy is NOT? 3 3 Contents 5 3.1 Why choose CherryPy?.........................................5 3.2 Installation................................................6 3.3 CherryPy License (BSD).........................................8 4 Tutorial 9 4.1 What is this tutorial about?........................................9 4.2 Start the Tutorial.............................................9 5 Programmer’s Guide 35 5.1 Features.................................................. 35 5.2 HTTP details............................................... 66 6 Deployment Guide 79 6.1 Applications............................................... 79 6.2 Servers.................................................. 79 6.3 Environment............................................... 87 7 Reference Manual 91 7.1 cherrypy._cpchecker ....................................... 91 7.2 cherrypy._cpconfig ........................................ 92 7.3 cherrypy._cpdispatch – Mapping URI’s to handlers...................... 94 7.4 cherrypy._cprequest ....................................... 96 7.5 cherrypy._cpserver ........................................ 101 7.6 cherrypy._cptools ........................................ 103 7.7 cherrypy._cptree ......................................... 105 7.8 cherrypy._cpwsgi ......................................... 107 7.9 cherrypy ................................................ 108 7.10 cherrypy.lib................................................ 112 7.11 cherrypy.process............................................. 131 7.12 cherrypy.wsgiserver........................................... 135 8 Appendix 139 8.1 How fast is CherryPy?.......................................... 139 8.2 Frequently Asked Questions....................................... 148 i 8.3 Success Stories.............................................. 150 9 CherryPy 3.3.0 Documentation 153 9.1 Introduction ............................................... 153 9.2 Tutorial .................................................. 153 9.3 Programmer’s Guide ........................................... 153 9.4 Deployment Guide ............................................ 153 9.5 Reference Manual ............................................ 153 9.6 Appendix ................................................. 153 9.7 Other................................................... 153 Python Module Index 155 ii CHAPTER 1 What is CherryPy? CherryPy is a pythonic, object-oriented HTTP framework. CherryPy allows developers to build web applications in much the same way they would build any other object-oriented Python program. This results in smaller source code developed in less time. CherryPy does its best to stay out of the way between the programmer and the problem. It works out of the box; default behavior is sensible enough to allow use without extensive setup or customization. However, its configuration and plugin systems are more than enough to easily build and deploy complex sites. You are free to use any kind of templating, data access etc. technology you want. CherryPy also has built-in tools for sessions, static files, cookies, file uploads, caching, encoding, authorization, compression, and many more. The production-ready, HTTP/1.1-compliant web server allows you to deploy web applications anywhere Python is installed. It also supports any other WSGI-enabled webserver or adapter, including Apache, IIS, lighttpd, mod_python, FastCGI, SCGI, and mod_wsgi, even multiple ones. And it’s fast; typically, CherryPy itself takes only 1-2ms per request! It is being used in production by many sites, from the simplest to the most demanding. CherryPy applications run on Windows, Linux, Mac OS X and any other platform supporting Python 2.3 or higher. CherryPy is now more than eight years old and it is has proven very fast and stable. It is well tested, and includes tools for testing, profiling, and coverage of your own applications. Oh, and most importantly: CherryPy is fun to work with :-) Here’s how easy it is to write “Hello World” in CherryPy: import cherrypy class HelloWorld(object): def index(self): return "Hello World!" index.exposed= True cherrypy.quickstart(HelloWorld()) 1 CherryPy Documentation, Release 3.3.0 2 Chapter 1. What is CherryPy? CHAPTER 2 What CherryPy is NOT? As an HTTP framework, CherryPy does all that is necessary to allow Python code to be executed when some resource (URL) is requested by the user. However: • CherryPy is not a templating language, such as PHP. CherryPy can work with several Python templating pack- ages (see Choosing a templating language), but does not ship one by default. • CherryPy does not fill out HTML forms for you. You’re free to use formencode or any other solution, or none at all if you’re not using HTML ;) • CherryPy is not a database or ORM. Rather than dictate or bless a persistence layer to you, CherryPy allows you to choose your own. 3 CherryPy Documentation, Release 3.3.0 4 Chapter 2. What CherryPy is NOT? CHAPTER 3 Contents 3.1 Why choose CherryPy? Let’s face it: there are dozens of different Python web frameworks. Why would you want to choose CherryPy for your next dynamic Web project? 3.1.1 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 Turbo- gears. 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. 3.1.2 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 ex- tensive, 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. 5 CherryPy Documentation, Release 3.3.0 3.1.3 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. 3.1.4 4. Community CherryPy has an active 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. 3.1.5 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. If the application needs to be deployed on Apache, there is copious documentation discussing how to connect the two. CherryPy can also be deployed on any WSGI-compliant gateway (a technology for interfacing numerous types of web servers): mod_wsgi, FastCGI, SCGI, IIS, etc. 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). 3.1.6 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. 3.1.7 7. Where to go from here? Check out the Tutorial and Programmer’s Guide for more complete documentation. 3.2 Installation Prerequisites Download Stable Versions Development versions 6 Chapter 3. Contents CherryPy Documentation, Release 3.3.0 3.2.1 Prerequisites All you need is a working version of Python-2.3 or later on your