Download Install Tutorial Docs FAQ Tools Wiki ∇ License Team IRC Planet Involvement Shop Book

Serving static content with CherryPy 3

  1. Serving static content with CherryPy 3
    1. Parameters
    2. Usage
      1. Serving files through the staticfile tool
      2. Serving files through the staticdir tool
      3. Specify the content-type of static resource
      4. Serve static content from a page handler bypassing the static tools
    3. Troubleshooting staticdir
    4. Forming URLs
      1. 2.0

For CherryPy 2, see at the bottom of this page.

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

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

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

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

Parameters

  • on: True or False (default). Enable or disable the filter.
  • match: a regular expression of files to match.
  • filename: path to the target file.
  • dir: path to the target directory.
  • root: absolute path to a "root"; joined with .dir or .filename if they are relative paths.

Usage

Serving files through the staticfile tool

Directory structure 

application \
   app.py
   data \
     scripts \
       dummy.js
     css \
       style.css

Here is our app.py 

import os.path
import cherrypy

class Root:
    @cherrypy.expose
    def index(self):
        return """<html>
<head>
        <title>CherryPy static tutorial</title>
        <link rel="stylesheet" type="text/css" href="css/style.css" type="text/css"></link>
        <script type="application/javascript" src="js/some.js"></script>
</head>
<html>
<body>
Hello world!
</body>
</html>"""

if __name__ == '__main__':
    current_dir = os.path.dirname(os.path.abspath(__file__))
    # Set up site-wide config first so we get a log if errors occur.
    cherrypy.config.update({'environment': 'production',
                            'log.error_file': 'site.log',
                            'log.screen': True})
        
    conf = {'/css/style.css': {'tools.staticfile.on': True,
                               'tools.staticfile.filename': os.path.join(current_dir, 'data', 'css', 'style.css')},
            '/js/some.js': {'tools.staticfile.on': True,
                            'tools.staticfile.filename': os.path.join(current_dir, 'data', 'scripts', 'dummy.js')}}
    cherrypy.quickstart(Root(), '/', config=conf)

Note how we use the absolute path to point at the static files. Note also that when using the staticfile tool, the logical URI path and the physical file do not need to be the same. Parts of their components can differ as in the case of the Javascript resource.

Serving files through the staticdir tool

Keeping the same directory structure as above we could have written our example as follow: 

# same Root class...

if __name__ == '__main__':
    current_dir = os.path.dirname(os.path.abspath(__file__))
    # Set up site-wide config first so we get a log if errors occur.
    cherrypy.config.update({'environment': 'production',
                            'log.error_file': 'site.log',
                            'log.screen': True})
        
    conf = {'/': {'tools.staticdir.root': os.path.join(current_dir, 'data')},
            '/css': {'tools.staticdir.on': True,
                     'tools.staticdir.dir': 'css'},
            '/js': {'tools.staticdir.on': True,
                    'tools.staticdir.dir': 'scripts'}}
    cherrypy.quickstart(Root(), '/', config=conf)

However in this case the GET /js/some.js request will fail with a 404 Not Found response because when using the staticdir tool the last segment of the URU must match exactly the path of the physical file underneath the directory defined by tools.staticdir.dir.

In our example we must either rename the physical file or change the HTML code accordingly.

Specify the content-type of static resource

Both the staticfile and staticdor tool allow you to specify the mime type of resources by their extension. Although internally CherryPy will set most of the time the correct mime type, there are specific cases when you need to provide yourself the content type value as follow. 

import os.path
import cherrypy

class Root:
    @cherrypy.expose
    def index(self):
        return """<html>
<head>
        <title>CherryPy static tutorial</title>
</head>
<html>
<body>
<a href="feed/notes.rss">RSS 2.0</a>
<br />
<a href="feed/notes.atom">Atom 1.0</a>
</body>
</html>"""

if __name__ == '__main__':
    current_dir = os.path.dirname(os.path.abspath(__file__))
    # Set up site-wide config first so we get a log if errors occur.
    cherrypy.config.update({'environment': 'production',
                            'log.error_file': 'site.log',
                            'log.screen': True})
        
    conf = {'/feed': {'tools.staticdir.on': True,
                      'tools.staticdir.dir': os.path.join(current_dir, 'feeds'),
                      'tools.staticdir.content_types': {'rss': 'application/xml',
                                                        'atom': 'application/atom+xml'}}}
    cherrypy.quickstart(Root(), '/', config=conf)

The dictionary provided is keyed by the extension of the files to serve.

Serve static content from a page handler bypassing the static tools

It may happen that you would need the static tools power but from a page handler itself so that you can add more processing. You can do so by calling the serve_file function. 

import os.path
import cherrypy
from cherrypy.lib.static import serve_file

class Root:
    @cherrypy.expose
    def feed(self, name):
        accepts = cherrypy.request.headers.elements('Accept')

        for accept in accepts:
            if accept.value == 'application/atom+xml':
                return serve_file(os.path.join(current_dir, 'feeds', '%s.atom' % name),
                                  content_type='application/atom+xml')

        return serve_file(os.path.join(current_dir, 'feeds', '%s.rss' % name),
                              content_type='application/xml')

if __name__ == '__main__':
    current_dir = os.path.dirname(os.path.abspath(__file__))
    # Set up site-wide config first so we get a log if errors occur.
    cherrypy.config.update({'environment': 'production',
                            'log.error_file': 'site.log',
                            'log.screen': True})
    cherrypy.quickstart(Root(), '/')

In this example we rely on the Accept header of the HTTP request to tell us which content type is supported by the client. If it can process the Atom content type then we serve the Atom resource, otherwise we serve the RSS one.

In any case by using the serve_file function we benefit from the CherryPy internal processing of the request in regards of HTTP headers such as If-Modified-Since. In fact the static tools use the serve_file function.

Troubleshooting staticdir

When using staticdir, "root" and "dir" are concatenated using os.path.join. So if you're having problems, try os.path.join(root, dir) in an interactive interpreter and make sure you at least get a valid, absolute path. Remember, you don't have to use "root" at all if you don't want to; just make "dir" an absolute path. If root + dir is not absolute, an error will be raised asking you to make it absolute. CherryPy doesn't make any assumptions about where your project files are, nor can it trust the current working directory, since that may change or not be under your control depending on your deployment environment.

Once root and dir are joined, the final file is found by os.path.join'ing a branch. The branch is pulled from the current request's URL like this: 

http://www2.mydomain.org/vhost /path/to/my/approot /path/to/section / path/to/actual/file.jpg
|                            | |                 | |              |   |                     |
+----------- base -----------+ +-- script_name --+ +-- section ---+   +------ branch -------+

The 'base' is the value of the 'Host' request header (unless changed by tools.proxy). The 'script_name' is where you mounted your app root. The 'section' is what part of the remaining URL to ignore; that is, none of its path atoms need to map to filesystem folders. It should exactly match the section header in your application config file where you defined 'tools.staticdir.dir'. In this example, your application config file should have: 

[/]
tools.staticdir.root = '/home/me/testproj'

[/path/to/section]
tools.staticdir.dir = 'images/jpegs'

Note that the section must start with a slash, but not end with one. And in order for os.path.join to work on root + dir, our 'images' value neither starts nor ends with a slash. Also note that the values of "root" and "dir" need not have anything to do with any part of the URL; they are OS path components only. Only the section header needs to match a portion of the URL.

Now we're finally ready to slice off the part of the URL that is our branch and add it to root + dir. So our final example will try to open the following file: 

                         root        +      dir      +          branch
>>> os.path.join('/home/me/testproj', 'images/jpegs', 'path/to/actual/file.jpg')
'/home/me/testproj/images/jpegs/path/to/actual/file.jpg'

Forming URLs

Creating links to static content is the inverse of the above. If you want to serve the file: 

/home/me/testproj/images/jpegs/path/to/actual/file.jpg

...you have a choice about where to split up the full path into root, dir, and branch. Remember, the 'root' value only exists to save typing; you could use absolute paths for all "dir" values. So if you're serving multiple static directories, find the common root to them all and use that for your "root" value. For example, instead of this: 

[/images]
tools.staticdir.dir = "/usr/home/me/app/static/images"

[/styles]
tools.staticdir.dir = "/usr/home/me/app/static/css"

[/scripts]
tools.staticdir.dir = "/usr/home/me/app/static/js"

...write: 

[/]
tools.staticdir.root = "/usr/home/me/app/static"

[/images]
tools.staticdir.dir = "images"

[/styles]
tools.staticdir.dir = "css"

[/scripts]
tools.staticdir.dir = "js"

Regardless of where you split "root" from "dir", the remainder of the OS path will be the "branch". Assuming the config above, our example branch would then be "jpegs/path/to/actual/file.jpg". Add the branch to the section name where you defined "dir", and use that for your URL. Even better, pass it to cherrypy.url() (which prepends base and script_name) and emit that. 

                  section     +                branch
>>> cherrypy.url('/images' + '/' + 'jpegs/path/to/actual/file.jpg')
http://www2.mydomain.org/vhost/path/to/my/approot/images/jpegs/path/to/actual/file.jpg

Older versions

replace this with this
2.2tools.staticdir static_filter.dir
tools.staticfilestatic_filter.file
cherrypy.url no equivalent
serve_file serveFile
2.1static_filter staticFilter

2.0

Edit your config file and place a section like this: 

[staticContent]
static=/home/dir/static
icons=/home/dir2/icons
favicon.ico=/home/icons/favicon.ico
robots.txt=/home/static/robots.txt
subobject/static=/home/dir/subdir/static

This will handle all files under static and icons directories as static files. Also, when the server recieves a request for /favicon.ico, it will serve the /home/icons/favicon.ico file; when it gets a request for /robots.txt, it will serve /home/static/robots.txt.

To use ConfigMap? instead of a config file for static files, you can use the keyname 'staticContentList', and you can put the directory names into pairs within an array, like this: 

cpg.server.start(configMap =
 {'staticContentList': [['example', r'C:\WINDOWS\Desktop\example'],
                        ['test', r'C:\WINDOWS\Desktop\test']],
  'socketPort': 9001 })

Hosted by WebFaction

Log in as guest/cpguest to create tickets