openstack/deb-python-pecan
Code Issues Proposed changes

Bringing docs up to date.

Browse Source
This commit is contained in:
Ryan Petrello
2012-03-05 18:01:37 -05:00
parent 7ba057b4d2
commit 3facdd545f
4 changed files with 71 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/source/configuration.rst
View File

@@ -2,11 +2,10 @@
Configuration
=============
Pecan is very easy to configure. As long as you follow certain conventions;
Pecan is very easy to configure. As long as you follow certain conventions,
using, setting and dealing with configuration should be very intuitive.
Python files is what the framework uses to get the values from configuration
files. These files need to specify the values in a key/value way (Python
Pecan configuration files are pure Python. These files need to specify the values in a key/value way (Python
dictionaries) or if you need simple one-way values you can also specify them as
direct variables (more on that below).
@@ -48,12 +47,14 @@ Things like debug mode, Root Controller and possible Hooks, should be specified
here. This is what is used when the framework is wrapping your application into
a valid WSGI app.
A typical application configuration would look like this::
A typical application configuration might look like this::
app = {
'root' : RootController(),
'static_root' : 'public',
'template_path' : 'project/templates',
'root' : 'project.controllers.root.RootController',
'modules' : ['project'],
'static_root' : '%(confdir)s/public',
'template_path' : '%(confdir)s/project/templates',
'reload' : True,
'debug' : True
}
@@ -62,18 +63,22 @@ 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. 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::
**root** The root controller of your application. Remember to provide
a string representing a Python path to some callable (e.g.,
`yourapp.controllers.root.RootController`).
from myproject.controllers.root import RootController
**static_root** Points to the directory where your static files live (relative
to the project root).
**static_root** Points to the directory where your static files live.
**template_path** Points to the directory where your template files live
(relative to the project root).
**template_path** Points to the directory where your template files live.
**reload** - When ``True``, ``pecan serve`` will listen for file changes and
restare your app (especially useful for development).
**debug** Enables ``WebError`` to have full tracebacks in the browser (this is
OFF by default).
**debug** Enables ``WebError`` to have display tracebacks in the browser
(**IMPORTANT**: Make sure this is *always* set to ``False`` in production
environments).
.. _server_configuration:
@@ -81,7 +86,7 @@ OFF by default).
Server Configuration
--------------------
Pecan provides some defaults. Change these to alter the host and port your
WSGI app is served on.::
WSGI app is served on::
server = {
'port' : '8080',
@@ -92,23 +97,18 @@ WSGI app is served on.::
Accessing Configuration at Runtime
----------------------------------
You can access any configuration values at runtime via ``pecan.conf``.
You can access any configuration value 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 a dictionary, but instead a simple
value. For example, if you needed to specify a global administrator, you could
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 in `pecan.conf` like::
And it would be accessible in `pecan.conf` as::
>>>> from pecan import conf
>>>> conf.administrator
>>> from pecan import conf
>>> conf.administrator
'foo_bar_user'

10
docs/source/installation.rst
View File

@@ -13,7 +13,7 @@ Pecan can be isolated from other packages is best practice.
To get started with an environment for Pecan, create a new
`virtual environment <http://www.virtualenv.org>`_::
virtualenv --no-site-packages pecan-env
virtualenv pecan-env
cd pecan-env
source bin/activate
@@ -31,12 +31,16 @@ After a lot of output, you should have Pecan successfully installed.
Development (Unstable) Version
------------------------------
If you want to run the development version of Pecan you will
need to install git and clone the repo from github::
need to install git and clone the repo from GitHub::
git clone https://github.com/pecan/pecan.git
git clone https://github.com/dreamhost/pecan.git
If your virtual environment is still activated, call ``setup.py`` to install
the development version::
cd pecan
python setup.py develop
...alternatively, you can also install from GitHub directly with ``pip``::
pip install -e git://github.com/dreamhost/pecan.git#egg=pecan

61
docs/source/quick_start.rst
View File

@@ -114,11 +114,7 @@ Simple Configuration
--------------------
For ease of use, Pecan configuration files are pure Python.
This is how your default configuration file should look::
from test_project.controllers.root import RootController
import test_project
This is how your default (generated) configuration file should look::
# Server Specific Configurations
server = {
@@ -128,8 +124,8 @@ This is how your default configuration file should look::
# Pecan Application Configurations
app = {
'root' : RootController(),
'modules' : [test_project],
'root' : 'test_project.controllers.root.RootController',
'modules' : ['test_project'],
'static_root' : '%(confdir)s/public',
'template_path' : '%(confdir)s/test_project/templates',
'reload': True,
@@ -162,9 +158,10 @@ Root Controller
---------------
The Root Controller is the root of your application.
This is how it looks in the project template::
This is how it looks in the project template
(``test_project.controllers.root.RootController``)::
from pecan import expose, request
from pecan import expose
from formencode import Schema, validators as v
from webob.exc import status_map
@@ -175,13 +172,23 @@ This is how it looks in the project template::
class RootController(object):
@expose('index.html')
def index(self, name='', age=''):
return dict(errors=request.validation_errors, name=name, age=age)
@expose(
generic = True,
template = 'index.html'
)
def index(self):
return dict()
@expose('success.html', schema=SampleForm(), error_handler='index')
def handle_form(self, name, age):
return dict(name=name, age=age)
@index.when(
method = 'POST',
template = 'success.html',
schema = SampleForm(),
error_handler = '/index',
htmlfill = dict(auto_insert_errors = True, prefix_error = False)
)
def index_post(self, name, age):
return dict(name=name)
@expose('error.html')
def error(self, status):
@@ -193,34 +200,32 @@ This is how it looks in the project template::
return dict(status=status, message=message)
You can specify additional classes and methods if you need to do so, but for
now we have an *index* and *index_post* method.
You can specify additional classes if you need to do so, but for now we have an
*index* and *handle_form* method.
**index**: is *exposed* via the decorator ``@expose`` (which in turn uses the
**def index**: is *exposed* via the decorator ``@expose`` (which in turn uses the
``index.html`` template) at the root of the application (http://127.0.0.1:8080/),
so anything that hits the root of your application will touch this method.
so any HTTP GET that hits the root of your application (/) will be routed to
this method.
Notice that the index method returns a dictionary - this dictionary is used as
a namespace to render the specified template (``index.html``) into HTML.
Since we are performing form validation and want to pass any errors we might
get to the template, we set ``errors`` to receive form validation errors that
may exist in ``request.validation_errors``.
**handle_form**: receives 2 arguments (*name* and *age*) that are validated
**def index_post**: receives 2 arguments (*name* and *age*) that are validated
through the *SampleForm* schema.
``method`` has been set to 'POST', so HTTP POSTs to the application root (in
our example, form submissions) will be routed to this method.
The ``error_handler`` has been set to index. This means that when errors are
raised, they will be sent to the index controller and rendered through its
template.
**error**: Finally, we have the error controller that allows your application to
**def error**: Finally, we have the error controller that allows your application to
display custom pages for certain HTTP errors (404, etc...).
Application Interaction
-----------------------
If you still have your application running and you visit it in your browser,
you should see a page with some information about Pecan and a form so you can
you should see a page with some information about Pecan and the form so you can
play a bit.

8
docs/source/routing.rst
View File

@@ -3,11 +3,13 @@
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 an
When a user requests a certain URL in your app, how does Pecan know which
controller to route to? 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 bookstore application:
the root controller. You can imagine your application's controllers as a tree
of objects (branches of the object tree map directly to URL paths). Let's look
at a simple bookstore application:
::