diff options
author | Ryan Petrello <lists@ryanpetrello.com> | 2012-12-05 13:09:40 -0800 |
---|---|---|
committer | Ryan Petrello <lists@ryanpetrello.com> | 2012-12-05 13:09:40 -0800 |
commit | bcb7faca3a4c3811e9a8460869d207b5e204fbcb (patch) | |
tree | 878e2d2b9cc12d0a2ffead58d7f4dbfd8d4edbf5 | |
parent | 5728102b47fa992b02e46c0b94b37d99bdf32eac (diff) | |
parent | f16f82c866b688e49c5de8ca0ef6e827fa9b9fc9 (diff) | |
download | pecan-bcb7faca3a4c3811e9a8460869d207b5e204fbcb.tar.gz |
Merge pull request #148 from berler/next
Improved Documentation
-rw-r--r-- | docs/source/configuration.rst | 9 | ||||
-rw-r--r-- | docs/source/quick_start.rst | 9 | ||||
-rw-r--r-- | pecan/__init__.py | 26 |
3 files changed, 44 insertions, 0 deletions
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index befefcc..84549a7 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -49,6 +49,15 @@ Let's look at each value and what it means: **app** is a reserved variable name for the configuration, so make sure you don't override it. +**modules** is a list of modules where pecan will search for applications. +Generally this should contain a single item, the name of your project's +python package. +At least one of the listed modules must contain an ``app.setup_app`` function +which is called to create the WSGI app. In other words, this package should +be where your ``app.py`` file is located, and this file should contain a +``setup_app`` function. +See :ref:`app_template` for more about the ``app.py`` file. + **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"``). diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst index 941c076..c35ce84 100644 --- a/docs/source/quick_start.rst +++ b/docs/source/quick_start.rst @@ -9,6 +9,7 @@ Let's create a small sample project with Pecan. This guide does not cover the installation of Pecan. If you need instructions for installing Pecan, go to :ref:`installation`. +.. _app_template: Base Application Template ------------------------- @@ -76,6 +77,13 @@ remaining directories encompass your models, controllers and templates... * **test_project/tests**: All of the tests for your application. +The **test_project/app.py** file controls how the Pecan application will be +created. This file must contain a ``setup_app`` function which returns the +WSGI application object. Generally you will not need to modify the ``app.py`` +file provided by the base application template unless you need to customize +your app in a way that cannot be accomplished using config. See +:ref:`python_based_config` below. + To avoid unneeded dependencies and to remain as flexible as possible, Pecan doesn't impose any database or ORM (`Object Relational Mapper @@ -111,6 +119,7 @@ configuration, it will bring up the development server and serve the app:: The location for the configuration file and the argument itself are very flexible - you can pass an absolute or relative path to the file. +.. _python_based_config: Python-Based Configuration -------------------------- diff --git a/pecan/__init__.py b/pecan/__init__.py index 5263cb0..705b1f2 100644 --- a/pecan/__init__.py +++ b/pecan/__init__.py @@ -27,7 +27,33 @@ __all__ = [ def make_app(root, static_root=None, logging={}, debug=False, wrap_app=None, **kw): + ''' + Utility for creating the Pecan application object. This function should + generally be called from the ``setup_app`` function in your project's + ``app.py`` file. + :param root: A string representing a root controller object (e.g., + "myapp.controller.root.RootController") + :param static_root: The relative path to a directory containing static + files. Serving static files is only enabled when + debug mode is set. + :param logging: A dictionary used to configure logging. This uses + ``logging.config.dictConfig``. + :param debug: A flag to enable debug mode. This enables the debug + middleware and serving static files. + :param wrap_app: A function or middleware class to wrap the Pecan app. + This must either be a wsgi middleware class or a + function that returns a wsgi application. This wrapper + is applied first before wrapping the application in + other middlewares such as Pecan's debug middleware. + This should be used if you want to use middleware to + perform authentication or intercept all requests before + they are routed to the root controller. + + All other keyword arguments are passed in to the Pecan app constructor. + + :returns: a ``Pecan`` object. + ''' # A shortcut for the RequestViewerHook middleware. if hasattr(conf, 'requestviewer'): existing_hooks = kw.get('hooks', []) |