Tutorial - Hello World
The most basic (working) CherryPy application possible.
Tutorial - Multiple methods
This tutorial shows you how to link to other methods of your request handler.
Tutorial - Passing variables
This tutorial shows you how to pass GET/POST variables to methods.
Tutorial - Multiple objects
This tutorial shows you how to create a site structure through multiple possibly nested request handler objects.
Tutorial - Object inheritance
You are free to derive your request handler classes from any base class you wish. In most real-world applications, you will probably want to create a central base class used for all your pages, which takes care of things like printing a common page header and footer.
- class cherrypy.tutorial.tut05_derived_objects.AnotherPage¶
- title = 'Another Page'¶
- class cherrypy.tutorial.tut05_derived_objects.HomePage¶
- title = 'Tutorial 5'¶
Tutorial - The default method
Request handler objects can implement a method called “default” that is called when no other suitable method/object could be found. Essentially, if CherryPy2 can’t find a matching request handler object for the given request URI, it will use the default method of the object located deepest on the URI path.
Using this mechanism you can easily simulate virtual URI structures by parsing the extra URI string, which you can access through cherrypy.request.virtualPath.
The application in this tutorial simulates an URI structure looking like /users/<username>. Since the <username> bit will not be found (as there are no matching methods), it is handled by the default method.
Tutorial - Sessions
Storing session data in CherryPy applications is very easy: cherrypy provides a dictionary called “session” that represents the session data for the current user. If you use RAM based sessions, you can store any kind of object into that dictionary; otherwise, you are limited to objects that can be pickled.
Bonus Tutorial: Using generators to return result bodies
Instead of returning a complete result string, you can use the yield statement to return one result part after another. This may be convenient in situations where using a template package like CherryPy or Cheetah would be overkill, and messy string concatenation too uncool. ;-)
Tutorial: File upload and download
When a client uploads a file to a CherryPy application, it’s placed on disk immediately. CherryPy will pass it to your exposed method as an argument (see “myFile” below); that arg will have a “file” attribute, which is a handle to the temporary uploaded file. If you wish to permanently save the file, you need to read() from myFile.file and write() somewhere else.
Note the use of ‘enctype=”multipart/form-data”’ and ‘input type=”file”’ in the HTML which the client uses to upload the file.
If you wish to send a file to the client, you have two options: First, you can simply return a file-like object from your page handler. CherryPy will read the file and serve it as the content (HTTP body) of the response. However, that doesn’t tell the client that the response is a file to be saved, rather than displayed. Use cherrypy.lib.static.serve_file for that; it takes four arguments:
serve_file(path, content_type=None, disposition=None, name=None)
Set “name” to the filename that you expect clients to use when they save your file. Note that the “name” argument is ignored if you don’t also provide a “disposition” (usually “attachement”). You can manually set “content_type”, but be aware that if you also use the encoding tool, it may choke if the file extension is not recognized as belonging to a known Content-Type. Setting the content_type to “application/x-download” works in most cases, and should prompt the user with an Open/Save dialog in popular browsers.
Tutorial: HTTP errors
HTTPError is used to return an error response to the client. CherryPy has lots of options regarding how such errors are logged, displayed, and formatted.