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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
|
Serving Static Content
**********************
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 :mod:`regular expression <re>` 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
::
cpapp \
__init__.py
data \
scripts \
dummy.js
css \
style.css
Here is our `cpapp/__init__.py`:
::
#!python
import os.path
current_dir = os.path.dirname(os.path.abspath(__file__))
import cherrypy
class Root:
@cherrypy.expose
def index(self):
return """<html>
<head>
<title>CherryPy static example</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>
<p>Static example</p>
</body>
</html>"""
...and a `prod.conf` configuration file:
::
[global]
environment: 'production'
log.error_file: 'site.log'
log.screen: True
tree.cpapp: cherrypy.Application(cpapp.Root())
[/css/style.css]
tools.staticfile.on: True
tools.staticfile.filename: cpapp.current_dir + '/data/css/style.css'
[/js/some.js]
tools.staticfile.on: True
tools.staticfile.filename: cpapp.current_dir + '/data/scripts/dummy.js'
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.
You can run the above with:
::
$ cherryd -i cpapp -c prod.conf
Serving files through the ``staticdir`` tool
--------------------------------------------
Keeping the same directory structure as above, we could have written our config file as follows:
::
[/]
tools.staticdir.root: cpapp.current_dir + 'data'
[/css]
tools.staticdir.on: True
tools.staticdir.dir: 'css'
[/js]
tools.staticdir.on: True
tools.staticdir.dir: 'scripts'
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 URI 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.
staticdir.index
^^^^^^^^^^^^^^^
If `tools.staticdir.index` is provided, it should be the (relative) name of a file to serve for directory requests. For example, if the `staticdir.dir` argument is '/home/me', the Request-URI is 'myapp', and the `.index` arg is 'index.html', the file '/home/me/myapp/index.html' will be served.
Specify the content-type of static resource
-------------------------------------------
Both the ``staticfile`` and ``staticdir`` tool allow you to specify the mime type of resources by their extension.
Although internally CherryPy will most of the time guess the correct mime type (using the Python :mod:`mimetypes` module),
there may be cases when you need to provide the content type values. You can do this via configuration arguments
``tools.staticdir.content_types`` and ``tools.staticfile.content_types``, as in the following example.
::
#!python
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 value of ``tools.staticdir.content_types`` and ``tools.staticfile.content_types``
is a dictionary whose keys are filename extensions, and values are the corresponding
media-type strings (for the ``Content-Type`` header). Note that the key must NOT include any leading '.'.
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.
::
#!python
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
|
