diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/changes.rst | 5 | ||||
-rw-r--r-- | docs/source/conf.py | 7 | ||||
-rw-r--r-- | docs/source/deployment.rst | 80 | ||||
-rw-r--r-- | docs/source/hooks.rst | 6 |
4 files changed, 91 insertions, 7 deletions
diff --git a/docs/source/changes.rst b/docs/source/changes.rst index 8ca46aa..c0a21ba 100644 --- a/docs/source/changes.rst +++ b/docs/source/changes.rst @@ -1,3 +1,8 @@ +0.3.1 +===== +* ``on_error`` hooks can now return a Pecan Response objects. +* Minor documentation and release tooling updates. + 0.3.0 ===== * Pecan now supports Python 2.6, 2.7, 3.2, and 3.3. diff --git a/docs/source/conf.py b/docs/source/conf.py index e2bdefb..4b89f31 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,6 +11,8 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import pkg_resources + import sys import os @@ -49,9 +51,10 @@ copyright = u'2010, Jonathan LaCour' # built documents. # # The short X.Y version. -version = '0.3.0' +dist = pkg_resources.get_distribution('pecan') +version = release = dist.version # The full version, including alpha/beta/rc tags. -release = '0.3.0' +#release = '0.3.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/deployment.rst b/docs/source/deployment.rst index b95ab39..9cc1fec 100644 --- a/docs/source/deployment.rst +++ b/docs/source/deployment.rst @@ -11,7 +11,7 @@ probably vary. .. :: - While Pecan comes packaged with a simple server *for development use* + While Pecan comes packaged with a simple server *for development use* (``pecan serve``), using a *production-ready* server similar to the ones described in this document is **very highly encouraged**. @@ -82,7 +82,7 @@ Considerations for Static Files ------------------------------- Pecan comes with static file serving (e.g., CSS, Javascript, images) -middleware which is **not** recommended for use in production. +middleware which is **not** recommended for use in production. In production, Pecan doesn't serve media files itself; it leaves that job to whichever web server you choose. @@ -93,7 +93,7 @@ performance reasons). There are several popular ways to accomplish this. Here are two: 1. Set up a proxy server (such as `nginx <http://nginx.org/en>`__, `cherokee - <http://www.cherokee-project.com>`__, or `lighttpd + <http://www.cherokee-project.com>`__, :ref:`cherrypy`, or `lighttpd <http://www.lighttpd.net/>`__) to serve static files and proxy application requests through to your WSGI application: @@ -204,3 +204,77 @@ Pecan's default project:: $ pecan create simpleapp && cd simpleapp $ python setup.py develop $ gunicorn_pecan config.py + + +.. _cherrypy: + +CherryPy +++++++++ + +`CherryPy <http://cherrypy.org/>`__ offers a pure Python HTTP/1.1-compliant WSGI +thread-pooled web server. It can support Pecan applications easily and even +serve static files like a production server would do. + +The examples that follow are geared towards using CherryPy as the server in +charge of handling a Pecan app along with serving static files. + +:: + + $ pip install cherrypy + $ pecan create simpleapp && cd simpleapp + $ python setup.py develop + +To run with CherryPy, the easiest approach is to create a script in the root of +the project (alongside ``setup.py``), so that we can describe how our example +application should be served. This is how the script (named ``run.py``) looks:: + + import os + import cherrypy + from cherrypy import wsgiserver + + from pecan import deploy + + simpleapp_wsgi_app = deploy('/path/to/production_config.py') + + public_path = os.path.abspath(os.path.join(os.path.dirname(__file__), 'public')) + + # A dummy class for our Root object + # necessary for some CherryPy machinery + class Root(object): + pass + + def make_static_config(static_dir_name): + """ + All custom static configurations are set here, since most are common, it + makes sense to generate them just once. + """ + static_path = os.path.join('/', static_dir_name) + path = os.path.join(public_path, static_dir_name) + configuration = { + static_path: { + 'tools.staticdir.on': True, + 'tools.staticdir.dir': path + } + } + return cherrypy.tree.mount(Root(), '/', config=configuration) + + # Assuming your app has media on diferent paths, like 'css', and 'images' + application = wsgiserver.WSGIPathInfoDispatcher({ + '/': simpleapp_wsgi_app, + '/css': make_static_config('css'), + '/images': make_static_config('images') + } + ) + + server = wsgiserver.CherryPyWSGIServer(('0.0.0.0', 8080), application, + server_name='simpleapp') + + try: + server.start() + except KeyboardInterrupt: + print "Terminating server..." + server.stop() + +To start the server, simply call it with the Python executable:: + + $ python run.py diff --git a/docs/source/hooks.rst b/docs/source/hooks.rst index 9a9d099..e1c54c4 100644 --- a/docs/source/hooks.rst +++ b/docs/source/hooks.rst @@ -46,8 +46,10 @@ object which includes useful information, such as the request and response objects, and which controller was selected by Pecan's routing. -:func:`on_error` is passed a shared state object **and** the original exception. - +:func:`on_error` is passed a shared state object **and** the original exception. If +an :func:`on_error` handler returns a Response object, this response will be returned +to the end user and no furthur :func:`on_error` hooks will be executed. + Attaching Hooks --------------- |