diff options
Diffstat (limited to 'vendor/CherryPy-3.2.0/sphinx/source/progguide')
17 files changed, 0 insertions, 1569 deletions
diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/REST.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/REST.rst deleted file mode 100644 index 2a2cf54..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/REST.rst +++ /dev/null @@ -1,255 +0,0 @@ -***************************************** -Creating RESTful applications in CherryPy -***************************************** - -Introduction -============ - -REST (Representational State Transfer) is an architectural style that -is well-suited to implementation in CherryPy. Both REST and CherryPy -heavily leverage the HTTP protocol but otherwise carry minimal -requisite overhead. This chapter briefly discusses the purpose of -REST and an example implementation in CherryPy. - -REST in a nutshell -================== - -The REST architectural style describes how domain models and their state -are referenced and transferred. The primary goal of REST is promote -certain advantageous qualities of a distributed system, namely high -visibility, scalability, extensibility. - -Terminology ------------ - - - "resources" are concepual objects represented by the system - any - information that can be named is a resource. - - "state" is data held by or associated with resources - - "representations" are information in state with a specific encoding - - "methods" are invoked to transfer or mutate state. - - an "identifier" is a URL or URI which uniquely and usually globally - references a resource. - -More information on REST can be found in abundance in Wikipedia and -other readily-available resources. - -Implementing REST in CherryPy -============================= - -From the canonical `Roy Fielding dissertation <http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5>`_ : - - REST is defined by four interface constraints: identification of resources; - manipulation of resources through representations; self-descriptive messages; - and, hypermedia as the engine of application state - -This section covers each of these four contstraints and demonstrates how each -is applied in a CherryPy implementation. - -Identification of Resources ---------------------------- - -As an HTTP service provider, resources represented in CherryPy are -referenced by HTTP URIs (Uniform Resource Identifiers). A URI consists -of four parts: scheme, hierarchical identifier, query, and fragment. -For HTTP, the scheme is always ``http`` or ``https``. The hierarchical -identifier consists of an authority (typically host/port) and a path -(similar to a file system path, but not necessarily representing an -actual path). - -A single CherryPy instance is typically bound to a single -server/port pair, such that the scheme://authority portion of the URI -references the server. This aspect is configured through the -``server.socket_host`` and ``server.socket_port`` options or via another -hosting server. - -Within the CherryPy server, the remainder of the hierarchical -identifier--the path--is mapped to Python objects -via the Dispatch mechanism. This behavior is highly -customizable and documented in :doc:`/concepts/dispatching`. - -Using the default dispatcher and page handlers, the path of the URI -maps to a hierarchy of Python identifiers in the CherryPy app. For -example, the URI path ``/container/objects/pencil`` will result in a -call to ``app.root.container.objects.pencil()`` where ``app`` is the -CherryPy app. - -Manipulation of Resources Through Representations -------------------------------------------------- - -REST defines the use of the HTTP protocol and HTTP methods to implement -the standard REST methods. - - - GET retrieves the state of a specific resource, - - PUT creates or replaces the state of a specific resource, - - POST passes information to a resource to use at it sees fit, - - DELETE removes resources. - -The default dispatcher in CherryPy stores the HTTP method name at -:attr:`cherrypy.request.method<cherrypy._cprequest.Request.method>`. - -Because HTTP defines these invocation methods, the most direct -way to implement REST using CherryPy is to utilize the -:class:`MethodDispatcher<cherrypy._cpdispatch.MethodDispatcher>` -instead of the default dispatcher. To enable -the method dispatcher, add the -following to your configuration for the root URI ("/"):: - - '/': { - 'request.dispatch': cherrypy.dispatch.MethodDispatcher(), - } - -Now, the REST methods will map directly to the same method names on -your resources. That is, a GET method on a CherryPy class implements -the HTTP GET on the resource represented by that class. - -For example:: - - class Resource(object): - - exposed = True - - def GET(self): - return """Some representation of self""" - - def PUT(self): - self.content = initialize_from_representation(cherrypy.request.body.read()) - -The concrete implementation of GET and PUT has been omitted, but the -basic concepts remain: GET returns some meaningful representation of -the resource and PUT stores an instance of an object represented by the -content in the body of the request. - -Self-Descriptive Messages -------------------------- - -REST enables powerful clients and intermediaries by requiring messages to be -self-descriptive; that is, everything you need to know about a message is -carried within the message itself, either in headers or within the definition -of the message's declared media type. - -CherryPy gives you easy access to the headers. It's as simple as -:attr:`cherrypy.request.headers<cherrypy._cprequest.Request.headers>` and -:attr:`cherrypy.response.headers<cherrypy._cprequest.Response.headers>`! -Each is a normal Python dictionary which you can read and write as you like. -They also have additional functions to help you parse complex values according -to the HTTP spec. - -CherryPy also allows you to set whatever response Content-Type you prefer, -just like any other response header. You have complete control. When reading -request entities, you can register :ref:`custombodyprocessors` for different -media types. - -Hypermedia as the Engine of Application State ---------------------------------------------- - -REST is designed as a stateless protocol--all application state is -maintained with the application at the client. Thus, concepts such as a -"session" need not be maintained by the server. CherryPy does not enable -sessions by default, so it is well-suited to the RESTful style. - -In order for the client to maintain meaningful state, however, the REST -server implementer must provide meaningful URIs which supply semantic -links between resources. - -For example, a CherryPy application might have a resource index, which -a client might retrieve to inspect the application for other resources:: - - class ResourceIndex(object): - def GET(self): - items = [item.get_href() for item in self.get_all_items()] - return ', '.join(items) - -This very simple example demonstrates how to create an index of -comma-separated hypertext references. This example assumes the client -can effectively interpret comma-separated references. In practice, -another representation such as HTML or JSON might be used. - -A Quick Example -=============== - -For example, consider the following contrived REST+HTML specification. - -1. Resources store arbitrary key/value pairs with unique keys - (represented as a Python dict). - -2. A GET request returns colon-separated key/value pairs in ``<div>`` - elements. - -3. A PUT request accepts colon-separated key/value pairs in ``<div>`` - elements. - -4. An index resource provides an HTML anchor tag (hypertext link) to objects - which it indexes (where the keys represent the names and the values - represent the link). - -A REST+HTML implementation was chosen for this example as HTML defines -relative links, which keeps the example simple yet functional. - -Complete Example ----------------- - -Brining the above code samples together and adding some basic -configuration results in the following program, which can be run -directly:: - - import cherrypy - - class Resource(object): - - def __init__(self, content): - self.content = content - - exposed = True - - def GET(self): - return self.to_html() - - def PUT(self): - self.content = self.from_html(cherrypy.request.body.read()) - - def to_html(self): - html_item = lambda (name,value): '<div>{name}:{value}</div>'.format(\*\*vars()) - items = map(html_item, self.content.items()) - items = ''.join(items) - return '<html>{items}</html>'.format(**vars()) - - @staticmethod - def from_html(data): - pattern = re.compile(r'\<div\>(?P<name>.*?)\:(?P<value>.*?)\</div\>') - items = [match.groups() for match in pattern.finditer(data)] - return dict(items) - - class ResourceIndex(Resource): - def to_html(self): - html_item = lambda (name,value): '<div><a href="{value}">{name}</a></div>'.format(\*\*vars()) - items = map(html_item, self.content.items()) - items = ''.join(items) - return '<html>{items}</html>'.format(**vars()) - - class Root(object): - pass - - root = Root() - - root.sidewinder = Resource({'color': 'red', 'weight': 176, 'type': 'stable'}) - root.teebird = Resource({'color': 'green', 'weight': 173, 'type': 'overstable'}) - root.blowfly = Resource({'color': 'purple', 'weight': 169, 'type': 'putter'}) - root.resource_index = ResourceIndex({'sidewinder': 'sidewinder', 'teebird': 'teebird', 'blowfly': 'blowfly'}) - - conf = { - 'global': { - 'server.socket_host': '0.0.0.0', - 'server.socket_port': 8000, - }, - '/': { - 'request.dispatch': cherrypy.dispatch.MethodDispatcher(), - } - } - - cherrypy.quickstart(root, '/', conf) - -Conclusion -========== - -CherryPy provides a straightforward interface for readily creating -RESTful interfaces. diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/choosingtemplate.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/choosingtemplate.rst deleted file mode 100644 index 8cfd563..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/choosingtemplate.rst +++ /dev/null @@ -1,151 +0,0 @@ -******************************
-Choosing a templating language
-******************************
-
-CherryPy is an open-ended HTTP framework that integrates with a wide variety of -templating systems. So the first point we want to make is that you should do -your own study *with your own data* to find out which one is best for you. - -That said, we recommend you start with one of these three:
- -`Mako <http://www.makotemplates.org/>`_ -======================================= - -Mako is a template library written in Python. It provides a familiar, non-XML -syntax which compiles into Python modules for maximum performance. Mako's syntax -and API borrows from the best ideas of many others, including Django templates, -Cheetah, Myghty, and Genshi. Conceptually, Mako is an embedded Python (i.e. -Python Server Page) language, which refines the familiar ideas of componentized -layout and inheritance to produce one of the most straightforward and flexible -models available, while also maintaining close ties to Python calling and -scoping semantics. - -Mako snippet:: - - <table> - % for row in rows: - ${makerow(row)} - % endfor - </table> - - -CherryPy integration example:: - - import cherrypy - from mako.template import Template - from mako.lookup import TemplateLookup - lookup = TemplateLookup(directories=['html']) - - class Root: - @cherrypy.expose - def index(self): - tmpl = lookup.get_template("index.html") - return tmpl.render(salutation="Hello", target="World") - -
-`Jinja2 <http://jinja.pocoo.org/2/>`_
-=====================================
- -Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible, -fast and secure. If you have any exposure to other text-based template languages, -such as Smarty or Django, you should feel right at home with Jinja2. It’s both -designer and developer friendly by sticking to Python’s principles and adding -functionality useful for templating environments. - -The key-features are... - - * ... configurable syntax. If you are generating LaTeX or other formats with - Jinja2 you can change the delimiters to something that integrates better - into the LaTeX markup. - * ... fast. While performance is not the primarily target of Jinja2 it’s - surprisingly fast. The overhead compared to regular Python code was reduced - to the very minimum. - * ... easy to debug. Jinja2 integrates directly into the python traceback - system which allows you to debug Jinja2 templates with regular python - debugging helpers. - * ... secure. It’s possible to evaluate untrusted template code if the optional - sandbox is enabled. This allows Jinja2 to be used as templating language for - applications where users may modify the template design. - -Jinja2 snippet:: - - <ul id="navigation"> - {% for item in navigation %} - <li><a href="{{ item.href }}">{{ item.caption }}</a></li> - {% endfor %} - </ul> - - -CherryPy integration example:: - - import cherrypy - from jinja2 import Environment, FileSystemLoader - env = Environment(loader=FileSystemLoader('templates')) - - class Root: - @cherrypy.expose - def index(self): - tmpl = env.get_template('index.html') - return tmpl.render(salutation='Hello', target='World') - - -`Genshi <http://genshi.edgewall.org>`_
-=======================================
-
-Genshi is a Python library that provides an integrated set of components for -parsing, generating, and processing HTML, XML or other textual content for -output generation on the web. - -The main feature is a template language that is smart about markup: unlike -conventional template languages that only deal with bytes and (if you're lucky) -characters, Genshi knows the difference between tags, attributes, and actual -text nodes, and uses that knowledge to your advantage. - -Plain XHTML templates make Genshi easy to use even for web designers who don't -know Python. Do you know XHTML? Then you're 75% of the way there! It's -considered by many to be the successor to Kid.
- -See the `Genshi tutorial <http://tools.cherrypy.org/wiki/Genshi>`_.
- -Because it parses HTML/XML, it can be slower than other solutions. -See `Genshi performance <http://genshi.edgewall.org/wiki/GenshiPerformance>`_ -for more information.
- -Genshi snippet:: - - <ol py:if="links"> - <li py:for="link in links"> - <a href="${link.url}">${link.title}</a> - posted by ${link.username} at ${link.time.strftime('%x %X')} - </li> - </ol> - -CherryPy integration example:: - - import cherrypy - from genshi.template import TemplateLoader - loader = TemplateLoader('/path/to/templates', auto_reload=True) - - class Root: - @cherrypy.expose - def index(self): - tmpl = loader.load('index.html') - page = tmpl.generate(salutation='Hello', target='World') - return page.render('html', doctype='html') - - -Others -====== - - * Cheetah - * ClearSilver - * Kid
- * HTMLTemplate
- * Nevow
- * PSP
- * PyMeld
- * py.xml
- * XSLT
- * Xyaptu - * ZPT
- diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/cookies.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/cookies.rst deleted file mode 100644 index afb218a..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/cookies.rst +++ /dev/null @@ -1,51 +0,0 @@ -******************************** -How to use cookies with CherryPy -******************************** - -CherryPy uses the :mod:`Cookie` module from python and in particular the -:class:`Cookie.SimpleCookie` object type to handle cookies. - -* To send a cookie to a browser, set ``cherrypy.response.cookie[key] = value``. -* To retrieve a cookie sent by a browser, use ``cherrypy.request.cookie[key]``. -* To delete a cookie (on the client side), you must *send* the cookie with its - expiration time set to 0:: - - - cherrypy.response.cookie[key] = value - cherrypy.response.cookie[key]['expires'] = 0 - - -It's important to understand that the request cookies are **not** automatically -copied to the response cookies. Clients will send the same cookies on every -request, and therefore ``cherrypy.request.cookie`` should be populated each -time. But the server doesn't need to send the same cookies with every response; -therefore, **``cherrypy.response.cookie`` will usually be empty**. When you wish -to "delete" (expire) a cookie, therefore, you must set -``cherrypy.response.cookie[key] = value`` first, and then set its ``expires`` -attribute to 0. - -Extended example:: - - import cherrypy - - class Root: - def setCookie(self): - cookie = cherrypy.response.cookie - cookie['cookieName'] = 'cookieValue' - cookie['cookieName']['path'] = '/' - cookie['cookieName']['max-age'] = 3600 - cookie['cookieName']['version'] = 1 - return "<html><body>Hello, I just sent you a cookie</body></html>" - setCookie.exposed = True - - def readCookie(self): - cookie = cherrypy.request.cookie - res = """<html><body>Hi, you sent me %s cookies.<br /> - Here is a list of cookie names/values:<br />""" % len(cookie) - for name in cookie.keys(): - res += "name: %s, value: %s<br>" % (name, cookie[name].value) - return res + "</body></html>" - readCookie.exposed = True - - cherrypy.quickstart(Root()) - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/cpreturn.gif b/vendor/CherryPy-3.2.0/sphinx/source/progguide/cpreturn.gif Binary files differdeleted file mode 100644 index 074ea3c..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/cpreturn.gif +++ /dev/null diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/cpyield.gif b/vendor/CherryPy-3.2.0/sphinx/source/progguide/cpyield.gif Binary files differdeleted file mode 100644 index e07c50a..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/cpyield.gif +++ /dev/null diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/customheaders.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/customheaders.rst deleted file mode 100644 index 51802dc..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/customheaders.rst +++ /dev/null @@ -1,74 +0,0 @@ -
-Custom Response Headers
-***********************
-
-Although the ``cherrypy.response.headers`` is usually adequate for
-supplying headers in a CherryPy response, it is sometimes desirable for
-the server application to customize the order of the resultant headers
-or provide multiple headers with duplicate keys. This section describes
-how one can accomplish these tasks within the CherryPy framework.
-
-Process
-=======
-
-The CherryPy Response object maintains a dictionary of headers until the
-finalize phase, after which the headers in the dictionary are converted
-into a list of (name, value) tuples. See
-``cherrypy._cprequest.Response`` for details.
-
-Therefore, since a dictionary discards order and duplicate keys,
-customizing the order or duplicity of keys must occur after the finalize
-phase.
-
-This end can be effected using a tool bound to the ``on_end_resource``
-hook.
-
-Multiple Headers
-================
-
-The following example illustrates the creation of a multiheaders tool to
-deliver multiple headers with the same key in the response.
-
-::
-
- #python
- import cherrypy
-
- def multi_headers():
- cherrypy.response.header_list.extend(cherrypy.response.multiheaders)
-
- cherrypy.tools.multiheaders = cherrypy.Tool('on_end_resource', multi_headers)
-
- class Root(object):
- @cherrypy.expose
- @cherrypy.tools.multiheaders()
- def index(self):
- cherrypy.response.multiheaders = [('foo', '1'), ('foo', '2')]
- return "Hello"
-
- cherrypy.quickstart(Root())
-
-Header Order
-============
-
-The following example illustrates the creation of a firstheaders tool to
-deliver headers in a specified order (at the beginning) in the response.
-
-::
-
- #python
- import cherrypy
-
- def first_headers():
- cherrypy.response.header_list[:0] = cherrypy.response.first_headers
-
- cherrypy.tools.firstheaders = cherrypy.Tool('on_end_resource', first_headers)
-
- class Root(object):
- @cherrypy.expose
- @cherrypy.tools.firstheaders()
- def index(self):
- cherrypy.response.first_headers = [('foo', '1'), ('foo', '2')]
- return "Hello"
-
- cherrypy.quickstart(Root())
diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/customplugins.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/customplugins.rst deleted file mode 100644 index 609f5c5..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/customplugins.rst +++ /dev/null @@ -1,131 +0,0 @@ -************** -Custom Plugins -************** - -CherryPy allows you to extend startup, shutdown, and other behavior outside the -request process via *Listeners* and *Plugins*. The -:class:`cherrypy.engine<cherrypy.process.wspbus.Bus>` object controls -these behaviors; to extend them, you subscribe listeners to the engine. -These allow you to run functions at a particular point in the -*site* process; for the *request* process, see :doc:`customtools` instead. - -Listeners -========= - -The engine is a publish-subscribe service; event handlers publish to various -*channels*, like "start", "stop", "exit", "graceful", or "log", and both -CherryPy and you can subscribe *listeners* for those messages:: - - engine.subscribe(channel, callback[, priority]) - -channel -------- - -The channel is an event name: - - * start: the Engine is starting for the first time, or has been stopped and is - now restarting; listeners here should start up sockets, files, or other - services and not return until they are ready to be used by clients or - other parts of the site. - * stop: the Engine is stopping; plugins should cleanly stop what they are - doing and not return until they have finished cleaning up. This is called - by :func:`cherrypy.engine.stop<cherrypy.process.wspbus.Bus.stop>`, and - plugins should make every effort to stop and clean up in a fashion that - permits them to be restarted via a "start" listener. - * graceful: advises all listeners to reload, e.g. by closing any open files - and reopening them. - * exit: this is called by - :func:`cherrypy.engine.exit<cherrypy.process.wspbus.Bus.exit>`, - and advises plugins to prepare for process termination. Note that - :func:`cherrypy.engine.exit<cherrypy.process.wspbus.Bus.exit>` first calls - :func:`cherrypy.engine.stop<cherrypy.process.wspbus.Bus.stop>`, so Plugins - may expect to stop first, then exit in a separate step. - * log(msg, level): in general, :class:`cherrypy.log<cherrypy._cplogging.LogManager>` - listens on this channel. Plugins, however, should make every effort to - publish to this channel verbosely to aid process event debugging. See the - builtin Plugins for good examples. - * main: New in 3.2. All Engine tasks run in threads other than the main thread; - the main thread usually calls - :func:`cherrypy.engine.block<cherrypy.process.wspbus.Bus.block>` to wait - for KeyboardInterrupt and other signals. While blocked, it loops - (every 1/10th of a second, by default), and publishes a message on the - "main" channel each time. Listeners subscribed to this channel, therefore, - are called at every interval. - -callback --------- - -The functionality you wish to run; this can be any function, class, or other -callable. Each channel defines the arguments; currently, however, only the "log" -channel defines any ('msg', the string message to log, and 'level', an int -following the levels defined in the stdlib's :mod:`logging <logging>` module). - -priority --------- - -The optional priority (0 - 100) allows multiple listeners to run in the correct -order. Lower numbers run first. The default is 50. - -If you omit the priority argument to engine.subscribe (or pass ``None``), -you can instead set it as an attribute on the callback function:: - - def setup_db(): - .... - setup_db.priority = 90 - engine.subscribe('start', setup_db) - - -Plugins -======= - -You can manually subscribe bus listeners, but you probably shouldn't. -*Plugins* allow your function to be subscribed and configured both -via the CherryPy config system and via the Plugin itself. Plugins also allow -you to write a single class that listens on multiple channels. - -Most of the built-in plugins have their own ``subscribe`` method, -so that instead of writing ``engine.subscribe``, you write: -``p = Plugin(engine).subscribe()``. If you want to turn off a plugin, -call ``p.unsubscribe()``. The plugin already knows the correct channel, -callback, and priority. - -You can run arbitrary code at any of the events by creating a -SimplePlugin object, with one method for each *channel* you wish to handle:: - - class ScratchDB(plugins.SimplePlugin): - - def start(self): - self.fname = 'myapp_%d.db' % os.getpid() - self.db = sqlite.connect(database=self.fname) - start.priority = 80 - - def stop(self): - self.db.close() - os.remove(self.fname) - cherrypy.engine.scratchdb = ScratchDB(cherrypy.engine) - -...then, once you've authored your Plugin, turn it on by calling its -``subscribe`` method:: - - cherrypy.engine.scratchdb.subscribe() - -...or, in CherryPy 3.2 and above, in site config:: - - [global] - engine.scratchdb.on = True - - -Priorities of the built-in "start" listeners: - -====================================================================== ================ - Listener Priority -====================================================================== ================ - default 50 - :doc:`Daemonizer </refman/process/plugins/daemonizer>` 65 - :doc:`Timeout Monitor </progguide/responsetimeouts>` 70 - :class:`Autoreloader <cherrypy.process.plugins.Autoreloader>` 70 - :doc:`PID File </refman/process/plugins/pidfile>` 70 - :doc:`HTTP Servers </refman/process/servers>` 75 - :doc:`Drop Privileges </refman/process/plugins/dropprivileges>` 77 -====================================================================== ================ - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/customtools.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/customtools.rst deleted file mode 100644 index 3d59a30..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/customtools.rst +++ /dev/null @@ -1,282 +0,0 @@ -************ -Custom Tools -************ - -CherryPy is an extremely capable platform for web application and framework -development. One of the strengths of CherryPy is its modular design; CherryPy -separates key-but-not-core functionality out into "tools". This provides two -benefits: a slimmer, faster core system and a supported means of tying -additional functionality into the framework. - -Tools can be enabled for any point of your CherryPy application: a certain -path, a certain class, or even individual methods using the -:ref:`_cp_config <cp_config>` dictionary. Tools can also be used as decorators -which provide syntactic sugar for configuring a tool for a specific callable. -See :doc:`/concepts/tools` for more information on how to use Tools. -This document will show you how to make your own. - -Your First Custom Tool -====================== - -Let's look at a very simple authorization tool:: - - import cherrypy - - def protect(users): - if cherrypy.request.login not in users: - raise cherrypy.HTTPError("401 Unauthorized") - - cherrypy.tools.protect = Tool('on_start_resource', protect) - -We can now enable it in the standard ways: a config file or dict passed to an -application, a :ref:`_cp_config<cp_config>` dict on a particular class or -callable or via use of the tool as a decorator. Here's how to turn it on in -a config file:: - - [/path/to/protected/resource] - tools.protect.on = True - tools.protect.users = ['me', 'myself', 'I'] - -Now let's look at the example tool a bit more closely. -Working from the bottom up, the :class:`cherrypy.Tool<cherrypy._cptools.Tool>` -constructor takes 2 required and 2 optional arguments. - -point ------ - -First, we need to declare the point in the CherryPy request/response -handling process where we want our tool to be triggered. Different request -attributes are obtained and set at different points in the request process. -In this example, we'll run at the first *hook point*, called "on_start_resource". - -.. _hooks: - -Hooks -^^^^^ - -Tools package up *hooks*. When we created a Tool instance above, the Tool -class registered our `protect` function to run at the 'on_start_resource' -*hookpoint*. You can write code that runs at hookpoints without using a Tool -to help you, but you probably shouldn't. The Tool system allows your function -to be turned on and configured both via the CherryPy config system and via the -Tool itself as a decorator. You can also write a Tool that runs code at multiple -hook points. - -Here is a quick rundown of the "hook points" that you can hang your tools on: - - * on_start_resource - The earliest hook; the Request-Line and request headers - have been processed and a dispatcher has set request.handler and request.config. - * before_request_body - Tools that are hooked up here run right before the - request body would be processed. - * before_handler - Right before the request.handler (the "exposed" callable - that was found by the dispatcher) is called. - * before_finalize - This hook is called right after the page handler has been - processed and before CherryPy formats the final response object. It helps - you for example to check for what could have been returned by your page - handler and change some headers if needed. - * on_end_resource - Processing is complete - the response is ready to be - returned. This doesn't always mean that the request.handler (the exposed - page handler) has executed! It may be a generator. If your tool absolutely - needs to run after the page handler has produced the response body, you - need to either use on_end_request instead, or wrap the response.body in a - generator which applies your tool as the response body is being generated - (what a mouthful--see - `caching tee.output <http://www.cherrypy.org/browser/trunk/cherrypy/lib/caching.py>`_ - for an example). - * before_error_response - Called right before an error response - (status code, body) is set. - * after_error_response - Called right after the error response - (status code, body) is set and just before the error response is finalized. - * on_end_request - The request/response conversation is over, all data has - been written to the client, nothing more to see here, move along. - - -callable --------- - -Second, we need to provide the function that will be called back at that -hook point. Here, we provide our ``protect`` callable. The Tool -class will find all config entries related to our tool and pass them as -keyword arguments to our callback. Thus, if:: - - 'tools.protect.on' = True - 'tools.protect.users' = ['me', 'myself', 'I'] - -is set in the config, the users list will get passed to the Tool's callable. -[The 'on' config entry is special; it's never passed as a keyword argument.] - -The tool can also be invoked as a decorator like this:: - - @cherrypy.expose - @cherrypy.tools.protect(users=['me', 'myself', 'I']) - def resource(self): - return "Hello, %s!" % cherrypy.request.login - -name ----- - -This argument is optional as long as you set the Tool onto a Toolbox. That is:: - - - def foo(): - cherrypy.request.foo = True - cherrypy.tools.TOOLNAME = cherrypy.Tool('on_start_resource', foo) - -The above will set the 'name' arg for you (to 'TOOLNAME'). The only time you -would need to provide this argument is if you're bypassing the toolbox in some way. - -priority --------- - -This specifies a priority order (from 0 - 100) that determines the order in -which callbacks in the same hook point are called. The lower the priority -number, the sooner it will run (that is, we call .sort(priority) on the list). -The default priority for a tool is set to 50 and most built-in tools use that -default value. - -Custom Toolboxes -================ - -All of the builtin CherryPy tools are collected into a Toolbox called -:attr:`cherrypy.tools`. It responds to config entries in the "tools" -:ref:`namespace<namespaces>`. You can add your own Tools to this Toolbox -as described above. - -You can also make your own Toolboxes if you need more modularity. For example, -you might create multiple Tools for working with JSON, or you might publish -a set of Tools covering authentication and authorization from which everyone -could benefit (hint, hint). Creating a new Toolbox is as simple as:: - - # cpstuff/newauth.py - import cherrypy - - # Create a new Toolbox. - newauthtools = cherrypy._cptools.Toolbox("newauth") - - # Add a Tool to our new Toolbox. - def check_access(default=False): - if not getattr(cherrypy.request, "userid", default): - raise cherrypy.HTTPError(401) - newauthtools.check_access = cherrypy.Tool('before_request_body', check_access) - -Then, in your application, use it just like you would use ``cherrypy.tools``, -with the additional step of registering your toolbox with your app. -Note that doing so automatically registers the "newauth" config namespace; -you can see the config entries in action below:: - - import cherrypy - from cpstuff import newauth - - - class Root(object): - def default(self): - return "Hello" - default.exposed = True - - conf = {'/demo': { - 'newauth.check_access.on': True, - 'newauth.check_access.default': True, - }} - - app = cherrypy.tree.mount(Root(), config=conf) - if hasattr(app, 'toolboxes'): - # CherryPy 3.1+ - app.toolboxes['newauth'] = newauth.newauthtools - -Just the Beginning -================== - -Hopefully that information is enough to get you up and running and create some -simple but useful CherryPy tools. Much more than what you have seen in this -tutorial is possible. Also, remember to take advantage of the fact that CherryPy -is open source! Check out :doc:`/progguide/builtintools` and the -:doc:`libraries</refman/lib/index>` that they are built upon. - -In closing, here is a slightly more complicated tool that acts as a -"traffic meter" and triggers a callback if a certain traffic threshold is -exceeded within a certain time frame. It should probably launch its own -watchdog thread that actually checks the log and triggers the alerts rather -than waiting on a request to do so, but I wanted to -keep it simple for the purpose of example:: - - # traffictool.py - import time - - import cherrypy - - - class TrafficAlert(cherrypy.Tool): - - def __init__(self, listclass=list): - """Initialize the TrafficAlert Tool with the given listclass.""" - - # A ring buffer subclass of list would probably be a more robust - # choice than a standard Python list. - - self._point = "on_start_resource" - self._name = None - self._priority = 50 - # set the args of self.callable as attributes on self - self._setargs() - # a log for storing our per-path traffic data - self._log = {} - # a history of the last alert for a given path - self._history = {} - self.__doc__ = self.callable.__doc__ - self._struct = listclass - - def log_hit(self, path): - """Log the time of a hit to a unique sublog for the path.""" - log = self._log.setdefault(path, self._struct()) - log.append(time.time()) - - def last_alert(self, path): - """Returns the time of the last alert for path.""" - return self._history.get(path, 0) - - def check_alert(self, path, window, threshhold, delay, callback=None): - # set the bar - now = time.time() - bar = now - window - hits = [t for t in self._log[path] if t > bar] - num_hits = len(hits) - if num_hits > threshhold: - if self.last_alert(path) + delay < now: - self._history[path] = now - if callback: - callback(path, window, threshhold, num_hits) - else: - msg = '%s - %s hits within the last %s seconds.' - msg = msg % (path, num_hits, window) - cherrypy.log.error(msg, 'TRAFFIC') - - def callable(self, window=60, threshhold=100, delay=30, callback=None): - """Alert when traffic thresholds are exceeded. - - window: the time frame within which the threshhold applies - threshhold: the number of hits within the window that will trigger - an alert - delay: the delay between alerts - callback: a callback that accepts(path, window, threshhold, num_hits) - """ - - path = cherrypy.request.path_info - self.log_hit(path) - self.check_alert(path, window, threshhold, delay, callback) - - - cherrypy.tools.traffic_alert = TrafficAlert() - - if __name__ == '__main__': - class Root(object): - @cherrypy.expose - def index(self): - return "Hi!!" - - @cherrypy.expose - @cherrypy.tools.traffic_alert(threshhold=5) - def popular(self): - return "A popular page." - - cherrypy.quickstart(Root()) - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/index.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/index.rst deleted file mode 100644 index dd5fac5..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/extending/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -****************** -Extending CherryPy -****************** - -If you need to perform some work that doesn't fit in a page handler, there are -two ways to do it depending on the scope of the task. If your code needs to run -on each request, or for only some URL's in your application, use a Tool. If your -code needs to run elsewhere, such as process start/stop/restart/exit, or thread -start/stop, use an Engine Plugin. - -.. toctree:: - - customtools - customplugins - 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) - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/index.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/index.rst deleted file mode 100644 index 0049441..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/index.rst +++ /dev/null @@ -1,35 +0,0 @@ -****************** -Programmer's Guide -****************** - -When you build a web application, you need more than just headers and bodies. -Here are a number of discussions on how to add higher-level features to your -CherryPy application, and how to leverage some of the power of HTTP. - -Features -======== - -.. toctree:: - :maxdepth: 2 - - choosingtemplate - Exceptions </refman/_cperror> - files/index - Logging </refman/_cplogging> - responsetimeouts - Sessions </refman/lib/sessions> - extending/index - - -HTTP details -============ - -.. toctree:: - :maxdepth: 2 - - cookies - customheaders - Request Bodies </refman/_cpreqbody> - REST - streaming - diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/responsetimeouts.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/responsetimeouts.rst deleted file mode 100644 index a024eb1..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/responsetimeouts.rst +++ /dev/null @@ -1,41 +0,0 @@ -***************** -Response Timeouts -***************** - -CherryPy responses include 3 attributes related to time: - - * ``response.time``: the :func:`time.time` at which the response began - * ``response.timeout``: the number of seconds to allow responses to run - * ``response.timed_out``: a boolean indicating whether the response has - timed out (default False). - -The request processing logic inspects the value of ``response.timed_out`` at -various stages; if it is ever True, then :class:`TimeoutError` is raised. -You are free to do the same within your own code. - -Rather than calculate the difference by hand, you can call -``response.check_timeout`` to set ``timed_out`` for you. - - -.. _timeoutmonitor: - -Timeout Monitor -=============== - -In addition, CherryPy includes a ``cherrypy.engine.timeout_monitor`` which -monitors all active requests in a separate thread; periodically, it calls -``check_timeout`` on them all. It is subscribed by default. To turn it off:: - - [global] - engine.timeout_monitor.on: False - -or:: - - cherrypy.engine.timeout_monitor.unsubscribe() - -You can also change the interval (in seconds) at which the timeout monitor runs:: - - [global] - engine.timeout_monitor.frequency: 60 * 60 - -The default is once per minute. The above example changes that to once per hour. diff --git a/vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst b/vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst deleted file mode 100644 index 0811bb0..0000000 --- a/vendor/CherryPy-3.2.0/sphinx/source/progguide/streaming.rst +++ /dev/null @@ -1,81 +0,0 @@ -*************************** -Streaming the response body -*************************** - -CherryPy handles HTTP requests, packing and unpacking the low-level details, -then passing control to your application's :ref:`pagehandlers`, which produce -the body of the response. CherryPy allows you to return body content in a -variety of types: a string, a list of strings, a file. CherryPy also allows you -to *yield* content, rather than *return* content. When you use "yield", you also -have the option of streaming the output. - -**In general, it is safer and easier to not stream output.** Therefore, -streaming output is off by default. - -The "normal" CherryPy response process -====================================== - -When you provide content from your page handler, CherryPy manages the -conversation between the HTTP server and your code like this: - -.. image:: cpreturn.gif - -Notice that the HTTP server gathers all output first and then writes everything -to the client at once: status, headers, and body. This works well for static or -simple pages, since the entire response can be changed at any time, either in -your application code, or by the CherryPy framework. - -How "streaming output" works with CherryPy -========================================== - -When you set the config entry "response.stream" to True (and use "yield"), -CherryPy manages the conversation between the HTTP server and your code like this: - -.. image:: cpyield.gif - -When you stream, your application doesn't immediately pass raw body content -back to CherryPy or to the HTTP server. Instead, it passes back a generator. -At that point, CherryPy finalizes the status and headers, **before** the -generator has been consumed, or has produced any output. This is necessary to -allow the HTTP server to send the headers and pieces of the body as they become -available. - -Once CherryPy has set the status and headers, it sends them to the HTTP server, -which then writes them out to the client. From that point on, the CherryPy -ramework mostly steps out of the way, and the HTTP server essentially requests -content directly from your application code (your page handler method). - -Therefore, when streaming, if an error occurs within your page handler, -CherryPy will not catch it--the HTTP server will catch it. Because the headers -(and potentially some of the body) have already been written to the client, -the server *cannot* know a safe means of handling the error, and will therefore -simply close the connection (the current, builtin servers actually write out a -short error message in the body, but this may be changed, and is not guaranteed -behavior for all HTTP servers you might use with CherryPy). - -In addition, you cannot manually modify the status or headers within your page -handler if that handler method is a streaming generator, because the method will -not be iterated over until after the headers have been written to the client. -**This includes raising exceptions like HTTPError, NotFound, InternalRedirect -and HTTPRedirect.** To use a streaming generator while modifying headers, you -would have to return a generator that is separate from (or embedded in) your -page handler. For example:: - - class Root: - def thing(self): - cherrypy.response.headers['Content-Type'] = 'text/plain' - if not authorized(): - raise cherrypy.NotFound() - def content(): - yield "Hello, " - yield "world" - return content() - thing._cp_config = {'response.stream': True} - -Streaming generators are sexy, but they play havoc with HTTP. CherryPy allows -you to stream output for specific situations: pages which take many minutes to -produce, or pages which need a portion of their content immediately output to -the client. Because of the issues outlined above, **it is usually better to -flatten (buffer) content rather than stream content**. Do otherwise only when -the benefits of streaming outweigh the risks. - |
