cherrypy.tutorial package

Submodules

cherrypy.tutorial.tut01_helloworld module

Tutorial - Hello World

The most basic (working) CherryPy application possible.

class cherrypy.tutorial.tut01_helloworld.HelloWorld

Sample request handler class.

index()

cherrypy.tutorial.tut02_expose_methods module

Tutorial - Multiple methods

This tutorial shows you how to link to other methods of your request handler.

class cherrypy.tutorial.tut02_expose_methods.HelloWorld
index()
show_msg()

cherrypy.tutorial.tut03_get_and_post module

Tutorial - Passing variables

This tutorial shows you how to pass GET/POST variables to methods.

class cherrypy.tutorial.tut03_get_and_post.WelcomePage
greetUser(name=None)
index()

cherrypy.tutorial.tut04_complex_site module

Tutorial - Multiple objects

This tutorial shows you how to create a site structure through multiple possibly nested request handler objects.

class cherrypy.tutorial.tut04_complex_site.ExtraLinksPage
index()
class cherrypy.tutorial.tut04_complex_site.HomePage
index()
class cherrypy.tutorial.tut04_complex_site.JokePage
index()
class cherrypy.tutorial.tut04_complex_site.LinksPage
index()

cherrypy.tutorial.tut05_derived_objects module

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

Bases: cherrypy.tutorial.tut05_derived_objects.Page

index()
title = 'Another Page'
class cherrypy.tutorial.tut05_derived_objects.HomePage

Bases: cherrypy.tutorial.tut05_derived_objects.Page

index()
title = 'Tutorial 5'
class cherrypy.tutorial.tut05_derived_objects.Page
footer()
header()
title = 'Untitled Page'

cherrypy.tutorial.tut06_default_method module

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.

class cherrypy.tutorial.tut06_default_method.UsersPage
default(user)
index()

cherrypy.tutorial.tut07_sessions module

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.

class cherrypy.tutorial.tut07_sessions.HitCounter
index()

cherrypy.tutorial.tut08_generators_and_yield module

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. ;-)

class cherrypy.tutorial.tut08_generators_and_yield.GeneratorDemo
footer()
header()
index()

cherrypy.tutorial.tut09_files module

Tutorial: File upload and download

Uploads

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.

Downloads

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.

class cherrypy.tutorial.tut09_files.FileDemo

Bases: object

download()
index()
upload(myFile)

cherrypy.tutorial.tut10_http_errors module

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.

class cherrypy.tutorial.tut10_http_errors.HTTPErrorDemo

Bases: object

error(code)
index()
messageArg()
toggleTracebacks()

Module contents