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.

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 (although tutorials are included for integrating these yourself in just a few lines of code). 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

• Extensible security framework

• Extensible template language support

• Extensible JSON support

• Easy Python-based configuration

Narrative Documentation

• Installation
  • Stable Version
  • Development (Unstable) Version
• Creating Your First Pecan Application
  • Base Application Template
  • Running the Application
  • Python-Based Configuration
  • The Application Root
  • Running the Tests For Your Application
  • Deploying to a Web Server
• Controllers and Routing
  • Exposing Controllers
  • Specifying Explicit Path Segments
  • Routing Based on Request Method
  • Pecan’s Routing Algorithm
  • Routing to Subcontrollers with _lookup
  • Falling Back with _default
  • Defining Customized Routing with _route
• Interacting with the Request and Response Object
  • Specifying a Custom Response
  • Extending Pecan’s Request and Response Object
  • Mapping Controller Arguments
  • Static File Serving
  • Handling File Uploads
  • Thread-Safe Per-Request Storage
  • Helper Functions
  • Determining the URL for a Controller
• Templating in Pecan
  • Using Template Renderers
  • Overriding Templates
  • Manual Rendering
  • The JSON Renderer
  • Defining Custom Renderers
• Writing RESTful Web Services with Generic Controllers
• Writing RESTful Web Services with RestController
  • URL Mapping
  • Nesting RestController
  • Defining Custom Actions
• Configuring Pecan Applications
  • Default Values
  • Application Configuration
  • Server Configuration
  • Additional Configuration
  • Accessing Configuration at Runtime
  • Dictionary Conversion
  • Prefixing Dictionary Keys
  • Dotted Keys, Non-Python Idenfitiers, and Native Dictionaries
• Security and Authentication
  • secure Decorator Basics
  • SecureController
  • Writing Authentication/Authorization Methods
  • More on secure
  • Multiple Secure Controllers
• Pecan Hooks
  • Implementating a Pecan Hook
  • Attaching Hooks
  • Hooks That Come with Pecan
• JSON Serialization
• Context/Thread-Locals vs. Explicit Argument Passing
  • Disabling Thread-Local Proxies
• Command Line Pecan
  • Serving a Pecan App For Development
  • Reloading Automatically as Files Change
  • The Interactive Shell
  • Configuration from an environment variable
  • Extending pecan with Custom Commands
• Developing Pecan Applications Locally
  • Reloading Automatically as Files Change
  • Debugging Pecan Applications
  • Serving Static Files
• Deploying Pecan in Production
  • Installing Pecan
  • Disabling Debug Mode
  • Pecan and WSGI
  • Considerations for Static Files
  • Common Recipes
• Logging
  • Configuring Logging
  • Writing Log Messages in Your Application
  • Logging to Files and Other Locations
  • Logging Requests with Paste Translogger
• Testing Pecan Applications
  • Test Discovery and Other Tools
  • Writing Functional Tests with WebTest
  • Special Testing Variables

Cookbook and Common Patterns

• Generating and Validating Forms
  • Defining a Form Definition
  • Rendering a Form in a Template
  • Validating POST Values
• Working with Sessions and User Authentication
  • Setting up Session Management
• Working with Databases, Transactions, and ORM’s
  • init_model and Preparing Your Model
  • Binding Within the Application
  • Splitting Reads and Writes
• Custom Error Documents
  • Overview
  • Configure Routing
  • Write Custom Controllers
• Example Application: Simple Forms Processing
  • Project Setup
  • Adding Validation
• Example Application: Simple AJAX
  • Project Setup
  • Adding JavaScript AJAX Support
  • Adding Additional HTML
  • Building the Model with JSON Support
  • Working with the Controllers

API Documentation

Pecan’s source code is well documented using Python docstrings and comments. In addition, we have generated API documentation from the docstrings here:

• pecan.core – Pecan Core
• pecan.commands – Pecan Commands
  • pecan.commands.server – Pecan Development Server
  • pecan.commands.shell – Pecan Interactive Shell
• pecan.configuration – Pecan Configuration Engine
• pecan.decorators – Pecan Decorators
• pecan.deploy – Pecan Deploy
• pecan.hooks – Pecan Hooks
• pecan.middleware.debug – Pecan Debugging Middleware
• pecan.jsonify – Pecan JSON Support
• pecan.rest – Pecan REST Controller
• pecan.routing – Pecan Routing
• pecan.secure – Pecan Secure Controllers
• pecan.templating – Pecan Templating
• pecan.testing – Pecan Testing
• pecan.util – Pecan Utils

Change History

• 1.4.1
• 1.4.0
• 1.3.3
• 1.3.2
• 1.3.1
• 1.3.0
• 1.2.1
• 1.2
• 1.1.2
• 1.1.1
• 1.1.0
• 1.0.5
• 1.0.4
• 1.0.3
• 1.0.2
• 1.0.1
• 1.0.0
• 0.9.0
• 0.8.3
• 0.8.2
• 0.8.1
• 0.8.0
• 0.7.0
• 0.6.1
• 0.6.0
• 0.5.0
• 0.4.5
• 0.4.4
• 0.4.3
• 0.4.2
• 0.4.1
• 0.3.2
• 0.3.1
• 0.3.0
• 0.2.4
• 0.2.3
• 0.2.2
• 0.2.1
• 0.2.0
• 0.2.0b

License

The Pecan framework and the documentation is BSD Licensed:

Copyright (c) <2010>, Pecan Framework
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the <organization> nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.