diff options
Diffstat (limited to 'vendor/CherryPy-3.2.0/sphinx/source/progguide/files')
5 files changed, 0 insertions, 453 deletions
diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/downloading.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/downloading.rst deleted file mode 100644 index d431134..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/downloading.rst +++ /dev/null @@ -1,50 +0,0 @@ -***************** -Downloading files -***************** - -CherryPy allows you to serve a file from your page handler. Here is a simple recipe to handle downloads:: - - - #!python - import glob - import os.path - - import cherrypy - from cherrypy.lib.static import serve_file - - - class Root: - def index(self, directory="."): - html = """<html><body><h2>Here are the files in the selected directory:</h2> - <a href="index?directory=%s">Up</a><br /> - """ % os.path.dirname(os.path.abspath(directory)) - - for filename in glob.glob(directory + '/*'): - absPath = os.path.abspath(filename) - if os.path.isdir(absPath): - html += '<a href="/index?directory=' + absPath + '">' + os.path.basename(filename) + "</a> <br />" - else: - html += '<a href="/download/?filepath=' + absPath + '">' + os.path.basename(filename) + "</a> <br />" - - html += """</body></html>""" - return html - index.exposed = True - - class Download: - - def index(self, filepath): - return serve_file(filepath, "application/x-download", "attachment") - index.exposed = True - - if __name__ == '__main__': - root = Root() - root.download = Download() - cherrypy.quickstart(root) - - -Note that `CherryPy <http://www.cherrypy.org/wiki/CherryPy>`_ is not the fastest for doing such things. If you think you'll have many and big downloads, put CP `BehindApache <http://www.cherrypy.org/wiki/BehindApache>`_ and let Apache serve those files. - - - - - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/favicon.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/favicon.rst deleted file mode 100644 index b5ffa98..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/favicon.rst +++ /dev/null @@ -1,18 +0,0 @@ -************************* -Serving the favorite icon -************************* - -By default, CherryPy 3 adds a "favicon_ico" handler method to any root object -which is mounted at "/". This is a staticfile handler, which grabs the -favicon.ico shipped in the CherryPy distribution. - -To configure CherryPy to look in another file location, you can, in your server -configuration, do the following:: - - [/favicon.ico] - tools.staticfile.on = True - tools.staticfile.filename = "/path/to/favicon.ico" - -If you want a favicon, but don't want CherryPy to serve it, you can point to an -HTTP URL via a link element in the HTML head. See http://www.w3.org/2005/10/howto-favicon -and http://en.wikipedia.org/wiki/Favicon for instructions. diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/index.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/index.rst deleted file mode 100644 index d6e39ab..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -************* -File Handling -************* - -.. toctree:: - :maxdepth: 2 - :glob: - - * - - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/static.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/static.rst deleted file mode 100644 index 597edc5..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/static.rst +++ /dev/null @@ -1,299 +0,0 @@ -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 - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/uploading.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/uploading.rst deleted file mode 100644 index 526bc51..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/files/uploading.rst +++ /dev/null @@ -1,75 +0,0 @@ -*************** -Uploading Files -*************** - -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. - - -Here is a simple example that shows how file uploads are handled by CherryPy:: - - import os - localDir = os.path.dirname(__file__) - absDir = os.path.join(os.getcwd(), localDir) - - import cherrypy - - class FileDemo(object): - - def index(self): - return """ - <html><body> - <h2>Upload a file</h2> - <form action="upload" method="post" enctype="multipart/form-data"> - filename: <input type="file" name="myFile" /><br /> - <input type="submit" /> - </form> - <h2>Download a file</h2> - <a href='download'>This one</a> - </body></html> - """ - index.exposed = True - - def upload(self, myFile): - out = """<html> - <body> - myFile length: %s<br /> - myFile filename: %s<br /> - myFile mime-type: %s - </body> - </html>""" - - # Although this just counts the file length, it demonstrates - # how to read large files in chunks instead of all at once. - # CherryPy reads the uploaded file into a temporary file; - # myFile.file.read reads from that. - size = 0 - while True: - data = myFile.file.read(8192) - if not data: - break - size += len(data) - - return out % (size, myFile.filename, myFile.content_type) - upload.exposed = True - - - - tutconf = os.path.join(os.path.dirname(__file__), 'tutorial.conf') - - if __name__ == '__main__': - # CherryPy always starts with app.root when trying to map request URIs - # to objects, so we need to mount a request handler root. A request - # to '/' will be mapped to HelloWorld().index(). - cherrypy.quickstart(FileDemo(), config=tutconf) - else: - # This branch is for the test suite; you can ignore it. - cherrypy.tree.mount(FileDemo(), config=tutconf) - |