The Pyramid Web Application Development Framework

Pyramid is a small, fast, down-to-earth Python web application development framework. It is developed as part of the Pylons Project. It is licensed under a BSD-like license.

Front Matter

• Copyright, Trademarks, and Attributions
• Typographical Conventions

“What’s New” Documents

• What’s New In Pyramid 1.0
  • Major Feature Additions
  • Minor Feature Additions
  • Backwards Incompatibilities
  • Deprecations and Behavior Differences
  • Dependency Changes
  • Documentation Enhancements

Narrative documentation

Narrative documentation in chapter form explaining how to use Pyramid.

• Pyramid Introduction
  • What Is The Pylons Project?
  • Pyramid and Other Web Frameworks
• Installing Pyramid
  • Before You Install
  • Installing Pyramid on a UNIX System
  • Installing Pyramid on a Windows System
  • Installing Pyramid on Google App Engine
  • Installing Pyramid on Jython
  • What Gets Installed
• Application Configuration
  • Imperative Configuration
  • Configuration Decorations and Code Scanning
  • Declarative Configuration
• Creating Your First Pyramid Application
  • Hello World, Goodbye World
  • References
• Creating a Pyramid Project
  • Paster Templates Included with Pyramid
  • Creating the Project
  • Installing your Newly Created Project for Development
  • Running The Tests For Your Application
  • The Interactive Shell
  • Running The Project Application
  • Viewing the Application
  • The Project Structure
  • The MyProject Project
  • The myproject Package
  • Modifying Package Structure
• Startup
  • The Startup Process
  • Deployment Settings
• URL Dispatch
  • High-Level Operational Overview
  • Route Configuration
  • Route Matching
  • Routing Examples
  • Matching the Root URL
  • Generating Route URLs
  • Redirecting to Slash-Appended Routes
  • Cleaning Up After a Request
  • Using Pyramid Security With URL Dispatch
  • Debugging Route Matching
  • Displaying All Application Routes
  • Route View Callable Registration and Lookup Details
  • References
• Much Ado About Traversal
  • URL Dispatch
  • Historical Refresher
  • Traversal (aka Resource Location)
  • What Is a “Resource”?
  • View Lookup
  • Use Cases
• Traversal
  • Traversal Details
  • The Resource Tree
  • The Traversal Algorithm
  • References
• Views
  • View Callables
  • Defining a View Callable as a Function
  • Defining a View Callable as a Class
  • Alternate View Callable Argument/Calling Conventions
  • View Callable Responses
  • Using a View Callable to Do an HTTP Redirect
  • Using Special Exceptions In View Callables
  • Exception Views
  • Handling Form Submissions in View Callables (Unicode and Character Set Issues)
• Renderers
  • Writing View Callables Which Use a Renderer
  • Built-In Renderers
  • Varying Attributes of Rendered Responses
  • Adding and Changing Renderers
  • Overriding A Renderer At Runtime
• Templates
  • Using Templates Directly
  • System Values Used During Rendering
  • Templates Used as Renderers via Configuration
  • Chameleon ZPT Templates
  • Templating with Chameleon Text Templates
  • Side Effects of Rendering a Chameleon Template
  • Nicer Exceptions in Chameleon Templates
  • Chameleon Template Internationalization
  • Templating With Mako Templates
  • Automatically Reloading Templates
  • Available Add-On Template System Bindings
• View Configuration
  • View Lookup and Invocation
  • Mapping a Resource or URL Pattern to a View Callable
• Resources
  • Defining a Resource Tree
  • Location-Aware Resources
  • Generating The URL Of A Resource
  • Generating the Path To a Resource
  • Finding a Resource by Path
  • Obtaining the Lineage of a Resource
  • Determining if a Resource is In The Lineage of Another Resource
  • Finding the Root Resource
  • Resources Which Implement Interfaces
  • Finding a Resource With a Class or Interface in Lineage
  • Pyramid API Functions That Act Against Resources
• Static Assets
  • Understanding Asset Specifications
  • Serving Static Assets
  • Advanced: Serving Static Assets Using a View Callable
  • Overriding Assets
• Request and Response Objects
  • Request
  • Response
  • Multidict
• Sessions
  • Using The Default Session Factory
  • Using a Session Object
  • Using Alternate Session Factories
  • Creating Your Own Session Factory
  • Flash Messages
  • Preventing Cross-Site Request Forgery Attacks
• Security
  • Enabling an Authorization Policy
  • Protecting Views with Permissions
  • Assigning ACLs to your Resource Objects
  • Elements of an ACL
  • Special Principal Names
  • Special Permissions
  • Special ACEs
  • ACL Inheritance and Location-Awareness
  • Changing the Forbidden View
  • Debugging View Authorization Failures
  • Debugging Imperative Authorization Failures
  • Creating Your Own Authentication Policy
  • Creating Your Own Authorization Policy
• Combining Traversal and URL Dispatch
  • A Review of Non-Hybrid Applications
  • Hybrid Applications
  • Corner Cases
• Internationalization and Localization
  • Creating a Translation String
  • Working With gettext Translation Files
  • Using a Localizer
  • Obtaining the Locale Name for a Request
  • Performing Date Formatting and Currency Formatting
  • Chameleon Template Support for Translation Strings
  • Mako Pyramid I18N Support
  • Localization-Related Deployment Settings
  • “Detecting” Available Languages
  • Activating Translation
  • Locale Negotiators
• Virtual Hosting
  • Hosting an Application Under a URL Prefix
  • Virtual Root Support
  • Further Documentation and Examples
• Using Events
  • Configuring an Event Listener Imperatively
  • Configuring an Event Listener Using a Decorator
  • An Example
• Environment Variables and .ini File Settings
  • Reloading Templates
  • Reloading Assets
  • Debugging Authorization
  • Debugging Not Found Errors
  • Debugging Route Matching
  • Debugging All
  • Reloading All
  • Default Locale Name
  • Mako Template Render Settings
  • Examples
  • Understanding the Distinction Between reload_templates and reload_assets
• Unit, Integration, and Functional Testing
  • Test Set Up and Tear Down
  • Using the Configurator and pyramid.testing APIs in Unit Tests
  • Creating Integration Tests
  • Creating Functional Tests
• Using Hooks
  • Changing the Not Found View
  • Changing the Forbidden View
  • Changing the Request Factory
  • Adding Renderer Globals
  • Using The Before Render Event
  • Using Response Callbacks
  • Using Finished Callbacks
  • Changing the Traverser
  • Changing How pyramid.url.resource_url Generates a URL
  • Using a View Mapper
  • Registering Configuration Decorators
• Advanced Configuration
  • Conflict Detection
  • Including Configuration from External Sources
  • Two-Phase Configuration
  • Adding Methods to the Configurator via add_directive
• Extending An Existing Pyramid Application
  • The Difference Between “Extensible” and “Pluggable” Applications
  • Rules for Building An Extensible Application
  • Extending an Existing Application
• Request Processing
• Thread Locals
  • Why and How Pyramid Uses Thread Local Variables
  • Why You Shouldn’t Abuse Thread Locals
• Using the Zope Component Architecture in Pyramid
  • Using the ZCA Global API in a Pyramid Application

Tutorials

Detailed tutorials explaining how to use Pyramid to build various types of applications and how to deploy Pyramid applications to various platforms.

• ZODB + Traversal Wiki Tutorial
  • Background
  • Installation
  • Basic Layout
  • Defining the Domain Model
  • Defining Views
  • Adding Authorization
  • Distributing Your Application
• SQLAlchemy + URL Dispatch Wiki Tutorial
  • Background
  • Installation
  • Basic Layout
  • Defining the Domain Model
  • Defining Views
  • Adding Authorization
  • Distributing Your Application
• Converting a repoze.bfg Application to Pyramid
• Running Pyramid on Google’s App Engine
  • Zipping Files Via Pip
• Running a Pyramid Application under mod_wsgi

Reference Material

Reference material includes documentation for every Pyramid API.

• API Documentation
  • pyramid.authorization
  • pyramid.authentication
  • pyramid.chameleon_text
  • pyramid.chameleon_zpt
  • pyramid.config
  • pyramid.events
  • pyramid.exceptions
  • pyramid.httpexceptions
  • pyramid.i18n
  • pyramid.interfaces
  • pyramid.location
  • pyramid.paster
  • pyramid.registry
  • pyramid.renderers
  • pyramid.request
  • pyramid.response
  • pyramid.scripting
  • pyramid.security
  • pyramid.session
  • pyramid.settings
  • pyramid.testing
  • pyramid.threadlocal
  • pyramid.traversal
  • pyramid.url
  • pyramid.view
  • pyramid.wsgi

Detailed Change History

• Pyramid Change History
• repoze.bfg Change History (previous name for Pyramid)

Design Documentation

• Defending Pyramid’s Design

Sample Applications

cluegun is a simple pastebin application based on Rocky Burt’s ClueBin. It demonstrates form processing, security, and the use of ZODB within a Pyramid application. Check this application out via:

git clone git://github.com/Pylons/cluegun.git

virginia is a very simple dynamic file rendering application. It is willing to render structured text documents, HTML documents, and images from a filesystem directory. An earlier version of this application runs the repoze.org website. Check this application out via:

git clone git://github.com/Pylons/virginia.git

shootout is an example “idea competition” application by Carlos de la Guardia. It demonstrates a hybrid of URL dispatch and traversal and integration with SQLAlchemy, repoze.who, and Deliverance. Check this application out of version control via:

git clone git://github.com/Pylons/shootout.git

Older Sample Applications (repoze.bfg)

Note

These applications are for an older version of Pyramid, which was named repoze.bfg. They won’t work unmodified under Pyramid, but might provide useful clues.

bfgsite is the software which runs the bfg.repoze.org website. It demonstrates integration with Trac, and includes several mini-applications such as a pastebin and tutorial engine. Check a buildout for this application out of Subversion via:

svn co http://svn.repoze.org/buildouts/bfgsite/ bfgsite_buildout

KARL is a moderately-sized application (roughly 70K lines of Python code) built on top of repoze.bfg and other Repoze software. It is an open source web system for collaboration, organizational intranets, and knowledge management, It provides facilities for wikis, calendars, manuals, searching, tagging, commenting, and file uploads. See the KARL site for download and installation details.

Support and Development

The Pylons Project web site is the main online source of Pyramid support and development information.

To report bugs, use the issue tracker.

If you’ve got questions that aren’t answered by this documentation, contact the Pylons-devel maillist or join the #pylons IRC channel.

Browse and check out tagged and trunk versions of Pyramid via the Pyramid GitHub repository. To check out the trunk via git, use this command:

git clone git@github.com:Pylons/pyramid.git

To find out how to become a contributor to Pyramid, please see the contributor’s section of the documentation.

Index and Glossary

• Glossary
• Index
• Search Page