openstack/deb-python-pecan
Code Issues Proposed changes

Merge pull request #18 from ryanpetrello/master

Browse Source 
More documentation proofreading and fixes.
This commit is contained in:
Ryan Petrello
2011-09-02 14:27:54 -07:00
parent 92818783f1 7eb1a7d7f0
commit 5d182911b4
5 changed files with 51 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/source/configuration.rst
View File

@@ -62,91 +62,59 @@ Let's look at each value and what it means:
**app** is a reserved variable name for the configuration, so make sure you are
not overriding, otherwise you will get default values.
**root** Needs the Root Controller of your application, this where your main
class that points to all the spots in your application should be. Rememeber
that you are passing the actual object so you would need to import it at the
top of the file. In the example configuration, this would be something like::
**root** Needs the Root Controller of your application. Remember that you are
passing an object instance, so you'll need to import it at the top of the file.
In the example configuration, this would look something like::
from myproject.controllers.root import RootController
**static_root** Points to the directory where your static files live in.
**static_root** Points to the directory where your static files live.
**template_path** The path where your templates are.
**template_path** Points to the directory where your template files live.
**debug** Enables ``WebError`` to have full tracebacks in the browser (this is
OFF by default).
Any application specifics should go in here in the case that your environment
required it.
.. _server_configuration:
Server Configuration
--------------------
Depending on the WSGI server you choose, you will need some values. As shown
before, Pecan has already some defaults and they would look like this::
Pecan provides some defaults. Change these to alter the host and port your
WSGI app is served on.::
server = {
'port' : '8080',
'host' : '0.0.0.0'
}
There is not too much going on there, it is just specifying the port and the
host it should use to serve the application. Any other values that you might
need can get added as key/values to that same dictionary so the server of your
choosing can use them.
.. _accessibility:
Accessibility
--------------
You can access any configuration values at runtime importing ``conf`` from
``pecan``. This includes custom, application and server specific values.
Below is an example on how to access those values for an application::
>>> from pecan import conf
>>> conf.app.root
<test_project.controllers.root.RootController object at 0x10292b0d0>
>>> conf.app.static_root
'public'
>>> conf.app.template_path
'test_project/templates'
>>> conf.app.debug
True
Accessing Configuration at Runtime
----------------------------------
You can access any configuration values at runtime via ``pecan.conf``.
This includes custom, application and server-specific values.
Below is an example on how to access those values from your application::
Custom and Single Values
------------------------
There might be times when you do not need to have a dictionary to specify some
values because all you need is a simple key that holds a value. For example, if
you needed to specify a global administrator, you could do so like this within
the configuration file::
There might be times when you do not need a dictionary, but instead a simple
value. For example, if you needed to specify a global administrator, you could
do so like this within the configuration file::
administrator = 'foo_bar_user'
And it would be accessible like this::
And it would be accessible in `pecan.conf` like::
>>>> from pecan import conf
>>>> conf.administrator
'foo_bar_user'
Similarly, if I had a custom ``foo`` entry on my configuration file once the
app is running I can access ``foo`` values like::
>>> from pecan import conf
>>> conf.foo.bar
True
>>> conf.foo.baz
False
>>> conf.foo
Config({'bar': True, 'baz': False})
Fully Valid Dictionaries
------------------------
In certain situations you might want to deal with keys and values but in strict
In certain situations you might want to deal with keys and values, but in strict
dictionary form. The ``Config`` object has a helper method for this purpose
that will return a dictionary representation of itself including nested values.
@@ -164,7 +132,7 @@ should return as a result (shortened for brevity):
Prefixing Values
----------------
The ``as_dict`` method allows you to pass an optional argument if you need to
``Config.as_dict`` allows you to pass an optional argument if you need to
prefix the keys in the returned dictionary. This is a single argument in string
form and it works like this (shortened for brevity):

6
docs/source/hooks.rst
View File

@@ -85,7 +85,7 @@ the app and browse the application from our web browser::
Included Pecan Hooks
====================
--------------------
Pecan includes some hooks in its core and are very simple to start using them
away. This section will describe their different uses, how to configure them
and examples of common scenarios.
@@ -93,7 +93,7 @@ and examples of common scenarios.
.. _requestviewerhook:
RequestViewerHook
=================
-----------------
This hooks is very useful for debugging purposes. It has access to every
attribute the ``response`` object has plus a few others that are specific to
the framework.
@@ -250,7 +250,7 @@ And these are the specific ones from Pecan and the hook:
Blacklisting
------------
Sometimes is annoying to get information about *every* single request. For this
Sometimes it's annoying to get information about *every* single request. For this
purpose, there is a matching list of url paths that you can pass into the hook
so that paths that do not match are returned.

5
docs/source/index.rst
View File

@@ -55,16 +55,13 @@ lines of code.
Cookbook
========
We provide a couple of easy ways to get started including a short
tutorial on App Engine.
.. toctree::
:maxdepth: 2
app_engine.rst
sessions.rst
databases.rst
deployment.rst
app_engine.rst
API Documentation

6
docs/source/jsonify.rst
View File

@@ -5,14 +5,14 @@ JSON Support
============
Pecan includes a simple, easy-to-use system for generating and serving
``JSON``. To get started, create a file in your project called
``json.py`` which should be imported in your ``app.py``.
``json.py`` and import it in your project's ``app.py``.
Your ``json`` module will contain a series of rules for generating
``JSON`` from objects you return in your controller, utilizing
"generic" function support from the
`simplegeneric <http://pypi.python.org/pypi/simplegeneric>`_ library.
Let us imagine that we have a controller in our Pecan application which
Let's say that we have a controller in our Pecan application which
we want to use to return ``JSON`` output for a ``User`` object::
from myproject.lib import get_current_user
@@ -68,4 +68,4 @@ specifying a ``__json__`` method on the object::
The benefit of using a ``json.py`` module is having all of your ``JSON``
rules defined in a central location, but some projects prefer the
simplicity of keeping the ``JSON`` rules attached directly to their
model objects.
model objects.

106
docs/source/routing.rst
View File

@@ -4,10 +4,10 @@ Routing
=======
When a user requests a Pecan-powered page how does Pecan know which
controller to use? Pecan uses a method known as Object-dispatch to map a
controller to use? Pecan uses a method known as object-dispatch to map an
HTTP request to a controller. Object-dispatch begins by splitting the
path into a list of components and then walking an object path starting at
the root controller. Let's look at a simple store application:
path into a list of components and then walking an object path, starting at
the root controller. Let's look at a simple bookstore application:
::
@@ -41,12 +41,11 @@ the root controller. Let's look at a simple store application:
catalog = CatalogController()
A request for ``/catalog/books/bestsellers`` from the online store would
begin by Pecan breaking the request up into ``catalog``, ``books``, and
``bestsellers``. Next, Pecan would then lookup ``catalog`` on the root
begin with Pecan breaking the request up into ``catalog``, ``books``, and
``bestsellers``. Next, Pecan would lookup ``catalog`` on the root
controller. Using the ``catalog`` object, Pecan would then lookup
``books`` followed by ``bestsellers``. What if the URL ends in a slash?
Pecan will check for an ``index`` method on the current object. In the
example above, you may have noticed the ``expose`` decorator.
``books``, followed by ``bestsellers``. What if the URL ends in a slash?
Pecan will check for an ``index`` method on the current object.
Routing Algorithm
-----------------
@@ -54,29 +53,23 @@ Routing Algorithm
Sometimes, the standard object-dispatch routing isn't adequate to properly
route a URL to a controller. Pecan provides several ways to short-circuit
the object-dispatch system to process URLs with more control, including the
``_lookup``, ``_default``, and ``_route`` special methods. Defining these
methods on your controller objects provide several additional ways to
process all or part of a URL.
special ``_lookup``, ``_default``, and ``_route`` methods. Defining these
methods on your controller objects provides additional flexibility for
processing all or part of a URL.
``_lookup``
-----------
The ``_lookup`` special method provides a way to process part of a URL,
and then return a new controller object to route on for the remainder.
The ``_lookup`` special method provides a way to process a portion of a URL,
and then return a new controller object to route to for the remainder.
A ``_lookup`` method will accept one or more arguments representing chunks
of the URL to be processed, split on `/`, and then a `*remainder` list which
will be processed by the returned controller via object-dispatch.
A ``_lookup`` method will accept one or more arguments, representing chunks
of the URL to be processed, split on `/`, and then provide a `*remainder` list
which will be processed by the returned controller via object-dispatch.
The ``_lookup`` method must return a two-tuple including the controller to
process the remainder of the URL, and the remainder of the URL itself.
The ``_lookup`` method on a controller is called when no other controller
matches the URL via standard object-dispatch.
Example
Additionally, the ``_lookup`` method on a controller is called as a last
resort, when no other controller matches the URL via standard object-dispatch.
::
@@ -91,23 +84,23 @@ Example
def name(self):
return self.student.name
class ClassController(object):
class RootController(object):
@expose()
def _lookup(self, name, *remainder):
student = get_student_by_name(name)
def _lookup(self, primary_key, *remainder):
student = get_student_by_primary_key(primary_key)
if student:
return StudentController(student), remainder
else:
abort(404)
An HTTP GET request to `/8/name` would return the name of the student
where `primary_key == 8`.
``_default``
------------
The ``_default`` controller is called when no other controller methods
match the URL vis standard object-dispatch.
Example
match the URL via standard object-dispatch.
::
@@ -145,53 +138,6 @@ A controller can receive arguments in a variety of ways, including ``GET`` and
arguments simply map to arguments on the controller method, while unprocessed
chunks of the URL can be passed as positional arguments to the controller method.
Example
::
from pecan import expose
class RootController(object):
@expose()
def say(self, msg):
return msg
In this example, if a ``GET`` request is sent to ``/say/hello``, the controller
returns "hello". On the other hand, if a ``GET`` request is sent to
``/say?msg=World``, then the controller returns "World".
Keyword arguments are also supported for defaults.
kwargs
::
from pecan import expose
class RootController(object):
@expose()
def say(self, msg="No message"):
return msg
In this example, if the client requests ``/say?msg=hello`` the controller returns
"hello". However, if the client requests ``/say`` without any arguments, the
controller returns "No message".
Generic Functions
-----------------
Pecan also provides a unique and useful way to dispatch from a controller to other
methods based upon the ``HTTP`` method (``GET``, ``POST``, ``PUT``, etc.) using
a system called "generic functions." A controller can be flagged as generic via a
keyword argument on the ``@expose`` decorator. This makes it possible to utilize
the ``@when`` decorator on the controller itself to define controllers to be called
instead when certain ``HTTP`` methods are sent.
Example
::
from pecan import expose
@@ -223,8 +169,8 @@ are documented in :ref:`pecan_core`.
-----------
At its core, ``@expose`` is how you tell Pecan which methods in a class
are controllers. ``@expose`` accepts eight optional parameters some of
which can impact routing.
are publically-visible controllers. ``@expose`` accepts eight optional
parameters, some of which can impact routing.
::