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.

Here is one of the simplest Pyramid applications you can make:

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response


def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)

if __name__ == '__main__':
    config = Configurator()
    config.add_route('hello', '/hello/{name}')
    config.add_view(hello_world, route_name='hello')
    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

After you install Pyramid and run this application, when you visit localhost:8080/hello/world in a browser, you will see the text Hello, world!

See Creating Your First Pyramid Application for a full explanation of how this application works. Read the Narrative documentation to understand how Pyramid is designed to scale from simple applications like this to very large web applications.

Front Matter¶

Copyright, Trademarks, and Attributions
Typographical Conventions

What’s New¶

What’s New In Pyramid 1.4
What’s New In Pyramid 1.3
What’s New In Pyramid 1.2
What’s New In Pyramid 1.1
What’s New In Pyramid 1.0

Narrative documentation¶

Narrative documentation in chapter form explaining how to use Pyramid.

Pyramid Introduction
- What Makes Pyramid Unique
- 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
- What Gets Installed
Creating Your First Pyramid Application
- Hello World
- References
Application Configuration
- Imperative Configuration
- Declarative Configuration
- Summary
Creating a Pyramid Project
- Scaffolds Included with Pyramid
- Creating the Project
- Installing your Newly Created Project for Development
- Running The Tests For Your Application
- Running The Project Application
- Viewing the Application
- The Project Structure
- The MyProject Project
- The myproject Package
- Modifying Package Structure
- Using the Interactive Shell
- What Is This pserve Thing
- Using an Alternate WSGI Server
Startup
- The Startup Process
- Deployment Settings
Request Processing
URL Dispatch
- High-Level Operational Overview
- Route Configuration
- Route Matching
- Routing Examples
- Matching the Root URL
- Generating Route URLs
- Static Routes
- Redirecting to Slash-Appended Routes
- Debugging Route Matching
- Using a Route Prefix to Compose Applications
- Custom Route Predicates
- Route Factories
- Using Pyramid Security With URL Dispatch
- Route View Callable Registration and Lookup Details
- References
Views
- View Callables
- Defining a View Callable as a Function
- Defining a View Callable as a Class
- View Callable Responses
- Using Special Exceptions In View Callables
- Custom Exception Views
- Using a View Callable to Do an HTTP Redirect
- Handling Form Submissions in View Callables (Unicode and Character Set Issues)
- Alternate View Callable Argument/Calling Conventions
- Passing Configuration Variables to a View
- Pylons-1.0-Style “Controller” Dispatch
Renderers
- Writing View Callables Which Use a Renderer
- Built-In Renderers
- Varying Attributes of Rendered Responses
- Deprecated Mechanism to Vary 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
- Debugging Templates
- Chameleon Template Internationalization
- Templating With Mako Templates
- Automatically Reloading Templates
- Available Add-On Template System Bindings
View Configuration
- Mapping a Resource or URL Pattern to a View Callable
- @view_defaults Class Decorator
- Influencing HTTP Caching
- Debugging View Configuration
Static Assets
- Understanding Asset Specifications
- Serving Static Assets
- Advanced: Serving Static Assets Using a View Callable
- Overriding Assets
Request and Response Objects
- Request
- Response
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
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
- Preventing HTTP Caching
- Debugging All
- Reloading All
- Default Locale Name
- Including Packages
- Explicit Tween Configuration
- Mako Template Render Settings
- Examples
- Understanding the Distinction Between reload_templates and reload_assets
- Adding A Custom Setting
Logging
- Logging Configuration
- Sending Logging Messages
- Filtering log messages
- Advanced Configuration
- Logging Exceptions
- Request Logging with Paste’s TransLogger
PasteDeploy Configuration Files
- PasteDeploy
Command-Line Pyramid
- Displaying Matching Views for a Given URL
- The Interactive Shell
- Displaying All Application Routes
- Displaying “Tweens”
- Invoking a Request
- Writing a Script
- Making Your Script into a Console Script
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
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
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
Hello Traversal World
- Example requests
- See Also
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
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
Invoking a Subrequest
Using Hooks
- Changing the Not Found View
- Changing the Forbidden View
- Changing the Request Factory
- Using The Before Render Event
- Adding Renderer Globals (Deprecated)
- Using Response Callbacks
- Using Finished Callbacks
- Changing the Traverser
- Changing How pyramid.request.Request.resource_url() Generates a URL
- Changing How Pyramid Treats View Responses
- Using a View Mapper
- Registering Configuration Decorators
- Registering “Tweens”
- Adding A Third Party View, Route, or Subscriber Predicate
Pyramid Configuration Introspection
- Using the Introspector
- Introspectable Objects
- Pyramid Introspection Categories
- Introspection in the Toolbar
- Disabling Introspection
Extending An Existing Pyramid Application
- The Difference Between “Extensible” and “Pluggable” Applications
- Rules for Building An Extensible Application
- Extending an Existing Application
Advanced Configuration
- Conflict Detection
- Including Configuration from External Sources
- Two-Phase Configuration
- More Information
Extending Pyramid Configuration
- Adding Methods to the Configurator via add_directive
- Using config.action in a Directive
- Adding Configuration Introspection
Creating Pyramid Scaffolds
- Basics
- Supporting Older Pyramid Versions
- Examples
Upgrading Pyramid
- Deprecation and Removal Policy
- Consulting the Change History
- Testing Your Application Under a New Pyramid Release
- My Application Doesn’t Have Any Tests or Has Few Tests
- Upgrading to the Very Latest Pyramid Release
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¶

Tutorials explaining how to use Pyramid to build various types of applications, and how to deploy Pyramid applications to various platforms.

SQLAlchemy + URL Dispatch Wiki Tutorial
- Background
- Design
- Installation
- Basic Layout
- Defining the Domain Model
- Defining Views
- Adding Authorization
- Adding Tests
- Distributing Your Application
ZODB + Traversal Wiki Tutorial
- Background
- Design
- Installation
- Basic Layout
- Defining the Domain Model
- Defining Views
- Adding Authorization
- Adding Tests
- Distributing Your Application
Converting a repoze.bfg Application

Navigation

The Pyramid Web Application Development Framework¶

Front Matter¶

What’s New¶

Narrative documentation¶

Tutorials¶