diff --git a/docs/source/hooks.rst b/docs/source/hooks.rst index 02b2bdd..8179d9c 100644 --- a/docs/source/hooks.rst +++ b/docs/source/hooks.rst @@ -2,32 +2,29 @@ Hooks ===== -Pecan Hooks are a nice way to interact with the framework itself rather than -writing middleware. +Pecan Hooks are a nice way to interact with the framework itself without having to +write WSGI middleware. There is nothing wrong with WSGI Middleware, and actually, it is really easy to -use middleware with Pecan, but it is rather hard (sometimes impossible) to have -access to Pecan's internals. +use middleware with Pecan, but it can be hard (sometimes impossible) to have +access to Pecan's internals from within middleware. Hooks make this easier. Hooks offer four ways of dealing with a request: -* ``on_route``: called before Pecan attempts to route a request +* ``on_route``: called before Pecan attempts to route a request to a controller -* ``before``: called after routing but before processing the request +* ``before``: called after routing, but before controller code is run -* ``after``: called after a request has been processed +* ``after``: called after controller code has been run -* ``on_error``: called when a request generates an error +* ``on_error``: called when a request generates an exception Implementation -------------- -They are very easy to plug into Pecan. In the below example we will go through -a simple hook that will gather some information about the request and then it -will print it out to ``stdout``. +In the below example, we will write a simple hook that will gather +some information about the request and print it out to ``stdout``. -Your hook needs to import ``PecanHook`` which will be used to inherit from. - -This is how your hook file should look like:: +Your hook implementation needs to import ``PecanHook`` so it can be used as a base class:: from pecan.hooks import PecanHook @@ -35,41 +32,48 @@ This is how your hook file should look like:: def after(self, state): print "\nmethod: \t %s" % state.request.method - print "response: \t %s" % state.response.status - -The ``after`` method will be called after the request has been dealt with. - -If you save your file as ``my_hook.py`` you should be able to add it to your -application like this:: + print "\nresponse: \t %s" % state.response.status + +``on_route``, ``before``, and ``after`` are passed a shared state object which includes useful +information about the request, such as the request and response object, and which controller +was chosen by Pecan's routing. + +Attaching Hooks +-------------- +Hooks can be attached in a project-wide manner by specifying a list of hooks +in your project's ``app.py`` file:: from application.root import RootController - from my_hook import SimpleHook - + from my_hooks import SimpleHook + app = make_app( RootController(), - hooks = [SimpleHook()] - ) + hooks = [SimpleHook()] + ) -We are passing the ``RootController`` of our application (make sure to replace -the bogus values with your own) and our ``SimpleHook`` goes into a list for the -``hooks`` parameter. +Hooks can also be applied selectively to controllers and their sub-controllers +using the ``__hooks__`` attribute on one or more controllers:: -We are not displaying how the entire file should look like but showing what is -of interest to get a hook into Pecan. + from pecan import expose + from my_hooks import SimpleHook + + class SimpleController(object): + + __hooks__ = [SimpleHook()] + + @expose('json') + def index(self): + return dict() Running it ---------- -Now that our ``SimpleHook`` is passed on, let's see what happens when we run +Now that our ``SimpleHook`` is included, let's see what happens when we run the app and browse the application:: - python start.py config - Serving on http://0.0.0.0:8080 + pecan serve config.py serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 method: GET response: 200 OK -``config`` is our configuration file that we pass on to ``start.py`` and as -soon as a request is served we see the information from our ``after`` method. - diff --git a/docs/source/index.rst b/docs/source/index.rst index b8d4eef..c20fc7b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,13 +1,8 @@ -.. Pecan documentation master file, created by - sphinx-quickstart on Sat Oct 9 14:41:27 2010. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +Pecan Documentation +=================== -Pecan's documentation -========================= - -A WSGI object-dispatching web framework, in the spirit of TurboGears, only -much much smaller, with many fewer dependencies. +A WSGI object-dispatching web framework, designed to be lean and fast, +with few dependancies. Contents: @@ -28,39 +23,33 @@ Contents: testing.rst -Introduction -============ -Pecan packs a few good features but it is also extremely lean, it requires just -a few dependencies but for the most part it feels like a full fledged web -framework! +Introduction and History +======================== +Welcome to Pecan, a lean Python web framework inspired by CherryPy, +TurboGears, and Pylons. Pecan was originally created by the developers +of `ShootQ `_ while working at `Pictage +`_. - * Object-Dispatch for easy routing - * Pre and Post Hooks - * REST controllers - * Validation and Error handling - * Secure controllers - * Template language support - * AppEngine out of the box (no patching!) +Pecan was created to fill a void in the Python web-framework world – a +very lightweight framework that provides object-dispatch style routing. +Pecan does not aim to be a "full stack" framework, and therefore +includes no out of the box support for things like sessions or +databases. Pecan instead focuses on HTTP itself. +Although it is lightweight, Pecan does offer an extensive feature set +for building HTTP-based applications, including: + * Object-dispatch for easy routing + * Full support for REST-style controllers + * Validation and error handling + * Extensible security framework + * Extensible template language support + * Extensible JSON support + * Easy Python-based configuration -Pecan Hello World ------------------- -In this example we use ``httpserver`` from ``paste`` but you can use any -WSGI server you want:: - - from paste import httpserver - from pecan import make_app, expose - - - class RootController(object): - - @expose() - def index(self): - return 'Hello, World!' - - app = make_app(RootController(), debug=True) - httpserver.serve(app, host='0.0.0.0', port=8080) +While Pecan doesn't provide support for sessions or databases out of the +box, tutorials are included for integrating these yourself in just a few +lines of code. Cookbook