Merge branch 'master' of github.com:cleverdevil/pecan
This commit is contained in:
Mark McClain
@@ -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.
|
||||
|
||||
|
||||
|
||||
@@ -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 <http://shootq.com>`_ while working at `Pictage
|
||||
<http://pictage.com>`_.
|
||||
|
||||
* 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
|
||||
|
||||
Reference in New Issue
Block a user