Navigation

index

modules |

next |

The Pyramid Web Application Development Framework v1.0 »

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 [http://docs.pylonsproject.org/]. It is licensed under a BSD-like license [http://repoze.org/license.html].

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 [https://github.com/Pylons/cluegun] is a simple pastebin application based on Rocky Burt’s ClueBin [http://pypi.python.org/pypi/ClueBin/0.2.3]. 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 [https://github.com/Pylons/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 [http://repoze.org] website. Check this application out via:

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

shootout [https://github.com/Pylons/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 [http://www.sqlalchemy.org/], repoze.who, and Deliverance [http://www.deliveranceproject.org/]. 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 [http://svn.repoze.org/bfgsite/trunk] is the software which runs the bfg.repoze.org [http://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 [http://karlproject.org] 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 [http://karlproject.org] for download and installation details.

Support and Development

The Pylons Project web site [http://pylonsproject.org/] is the main online source of Pyramid support and development information.

To report bugs, use the issue tracker [http://github.com/Pylons/pyramid/issues].

If you’ve got questions that aren’t answered by this documentation, contact the Pylons-devel maillist [http://groups.google.com/group/pylons-devel] or join the #pylons IRC channel.

Browse and check out tagged and trunk versions of Pyramid via the Pyramid GitHub repository [http://github.com/Pylons/pyramid/]. 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 [http://docs.pylonsproject.org/index.html#contributing].

Index and Glossary

Glossary

Index

Search Page

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Copyright, Trademarks, and Attributions

The Pyramid Web Application Development Framework, Version 1.0

by Chris McDonough

Copyright © 2008-2011, Agendaless Consulting.

ISBN-10: 0615445675

ISBN-13: 978-0615445670

First print publishing: February, 2011

All rights reserved. This material may be copied or distributed only subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License [http://creativecommons.org/licenses/by-nc-sa/3.0/us/]. You must give the original author credit. You may not use this work for commercial purposes. If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.

Note

While the Pyramid documentation is offered under the Creative Commons Attribution-Nonconmmercial-Share Alike 3.0 United States License, the Pyramid software is offered under a less restrictive (BSD-like) license [http://repoze.org/license.html] .

All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. However, use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.

Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness is implied. The information provided is on as “as-is” basis. The author and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book. No patent liability is assumed with respect to the use of the information contained herein.

Attributions

Editor:

Casey Duncan

Contributors:

Ben Bangert, Blaise Laflamme, Rob Miller, Mike Orr, Carlos de la Guardia, Paul Everitt, Tres Seaver, John Shipman, Marius Gedminas, Chris Rossi, Joachim Krebs, Xavier Spriet, Reed O’Brien, William Chambers, Charlie Choiniere, Jamaludin Ahmad, Graham Higgins.

Used with permission:

The Request and Response Objects chapter is adapted, with permission, from documentation originally written by Ian Bicking.

The Much Ado About Traversal chapter is adapted, with permission, from an article written by Rob Miller.

Print Production

The print version of this book was produced using the Sphinx [http://sphinx.pocoo.org/] documentation generation system and the LaTeX [http://www.latex-project.org/] typesetting system.

Contacting The Publisher

Please send documentation licensing inquiries, translation inquiries, and other business communications to Agendaless Consulting. Please send software and other technical queries to the Pylons-devel maillist [http://groups.google.com/group/pylons-devel].

HTML Version and Source Code

An HTML version of this book is freely available via http://docs.pylonsproject.org

The source code for the examples used in this book are available within the Pyramid software distribution, always available via https://github.com/Pylons/pyramid

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Typographical Conventions

Literals, filenames and function arguments are presented using the following style:

argument1

Warnings, which represent limitations and need-to-know information related to a topic or concept are presented in the following style:

Warning

This is a warning.

Notes, which represent additional information related to a topic or concept are presented in the following style:

Note

This is a note.

We present Python method names using the following style:

pyramid.config.Configurator.add_view()

We present Python class names, module names, attributes and global variables using the following style:

pyramid.config.Configurator.registry

References to glossary terms are presented using the following style:

Pylons

URLs are presented using the following style:

Pylons [http://pylonsproject.org]

References to sections and chapters are presented using the following style:

Traversal

Code and configuration file blocks are presented in the following style:

1
2

def foo(abc):
    pass

When a command that should be typed on one line is too long to fit on a page, the backslash \ is used to indicate that the following printed line should actually be part of the command:

c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
      --cover-erase --with-coverage

A sidebar, which presents a concept tangentially related to content discussed on a page, is rendered like so:

This is a sidebar

Sidebar information.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

What’s New In Pyramid 1.0

This article explains the new features in Pyramid version 1.0 as compared to its predecessor, repoze.bfg 1.3. It also documents backwards incompatibilities between the two versions and deprecations added to Pyramid 1.0, as well as software dependency changes and notable documentation additions.

Major Feature Additions

The major feature additions in Pyramid 1.0 are:

New name and branding association with the Pylons Project.

BFG conversion script

Paster template improvements

Terminology changes

Better platform compatibility and support

Direct built-in support for the Mako templating language.

Built-in support for sessions.

Updated URL dispatch features

Better imperative extensibility

ZCML externalized

Better support for global template variables during rendering

View mappers

Testing system improvements

Authentication support improvements

Documentation improvements

New Name and Branding

The name of repoze.bfg has been changed to Pyramid. The project is also now a subproject of a new entity, “The Pylons Project”. The Pylons Project is the project name for a collection of web-framework-related technologies. Pyramid was the first package in the Pylons Project. Other packages to the collection have been added over time, such as support packages useful for Pylons 1 users as well as ex-Zope users. Pyramid is the successor to both repoze.bfg and Pylons version 1.

The Pyramid codebase is derived almost entirely from repoze.bfg with some changes made for the sake of Pylons 1 compatibility.

Pyramid is technically backwards incompatible with repoze.bfg, as it has a new package name, so older imports from the repoze.bfg module will fail if you do nothing to your existing repoze.bfg application. However, you won’t have to do much to use your existing BFG applications on Pyramid. There’s automation which will change most of your import statements and ZCML declarations. See http://docs.pylonshq.com/pyramid/dev/tutorials/bfg/index.html for upgrade instructions.

Pylons 1 users will need to do more work to use Pyramid, as Pyramid shares no “DNA” with Pylons. It is hoped that over time documentation and upgrade code will be developed to help Pylons 1 users transition to Pyramid more easily.

repoze.bfg version 1.3 will be its last major release. Minor updates will be made for critical bug fixes. Pylons version 1 will continue to see maintenance releases, as well.

The Repoze project will continue to exist. Repoze will be able to regain its original focus: bringing Zope technologies to WSGI. The popularity of repoze.bfg as its own web framework hindered this goal.

We hope that people are attracted at first by the spirit of cooperation demonstrated by the Pylons Project and the merging of development communities. It takes humility to sacrifice a little sovereignty and work together. The opposite, forking or splintering of projects, is much more common in the open source world. We feel there is a limited amount of oxygen in the space of “top-tier” Python web frameworks and we don’t do the Python community a service by over-crowding. By merging the repoze.bfg and the philosophically-similar Pylons communities, both gain an expanded audience and a stronger chance of future success.

BFG Conversion Script

The bfg2pyramid conversion script performs a mostly automated conversion of an existing repoze.bfg application to Pyramid. The process is described in Converting a repoze.bfg Application to Pyramid.

Paster Template Improvements

The paster templates now have much nicer CSS and graphics.

The development.ini generated by all paster templates is now configured to use the WebError interactive exception debugger by default.

All paster templates have been normalized: each now uses the name main to represent the function that returns a WSGI application, and each now has roughly the same shape of development.ini style.

All preexisting paster templates now use “imperative” configuration (starter, routesalchemy, alchemy, zodb) instead of ZCML configuration.

The pyramid_zodb, pyramid_routesalchemy and pyramid_alchemy paster templates now use a default “commit veto” hook when configuring the repoze.tm2 transaction manager in development.ini. This prevents a transaction from being committed when the response status code is within the 400 or 500 ranges. See also http://docs.repoze.org/tm2/#using-a-commit-veto.

Terminology Changes

The Pyramid concept previously known as “model” is now known as “resource”. As a result, the following API renames have been made. Backwards compatibility shims for the old names have been left in place in all cases:

pyramid.url.model_url ->
                  pyramid.url.resource_url

pyramid.traversal.find_model ->
                  pyramid.url.find_resource

pyramid.traversal.model_path ->
                  pyramid.traversal.resource_path

pyramid.traversal.model_path_tuple ->
                  pyramid.traversal.resource_path_tuple

pyramid.traversal.ModelGraphTraverser ->
                  pyramid.traversal.ResourceTreeTraverser

pyramid.config.Configurator.testing_models ->
                  pyramid.config.Configurator.testing_resources

pyramid.testing.registerModels ->
                  pyramid.testing.registerResources

pyramid.testing.DummyModel ->
                  pyramid.testing.DummyResource

All documentation which previously referred to “model” now refers to “resource”.

The starter paster template now has a resources.py`` module instead of a models.py module.

Positional argument names of various APIs have been changed from model to resource.

The Pyramid concept previously known as “resource” is now known as “asset”. As a result, the following API changes were made. Backwards compatibility shims have been left in place as necessary:

pyramid.config.Configurator.absolute_resource_spec ->
                  pyramid.config.Configurator.absolute_asset_spec

pyramid.config.Configurator.override_resource ->
                  pyramid.config.Configurator.override_asset

The (non-API) module previously known as pyramid.resource is now known as pyramid.asset.

All docs that previously referred to “resource specification” now refer to “asset specification”.

The setting previously known as BFG_RELOAD_RESOURCES (envvar) or reload_resources (config file) is now known, respectively, as PYRAMID_RELOAD_ASSETS and reload_assets.

Better Platform Compatibility and Support

We’ve made Pyramid’s test suite pass on both Jython and PyPy. However, Chameleon doesn’t work on either, so you’ll need to use Mako or Jinja2 templates on these platforms.

Sessions

Pyramid now has built-in sessioning support, documented in Sessions. The sessioning implementation is pluggable. It also provides flash messaging and cross-site-scripting prevention features.

Using request.session now returns a (dictionary-like) session object if a session factory has been configured.

A new argument to the Configurator constructor exists: session_factory and a new method on the configurator exists: pyramid.config.Configurator.set_session_factory().

Mako

In addition to Chameleon templating, Pyramid now also provides built-in support for Mako templating. See Templating With Mako Templates for more information.

URL Dispatch

URL Dispatch now allows for replacement markers to be located anywhere in the pattern, instead of immediately following a /.

URL Dispatch now uses the form {marker} to denote a replace marker in the route pattern instead of :marker. The old colon-style marker syntax is still accepted for backwards compatibility. The new format allows a regular expression for that marker location to be used instead of the default [^/]+, for example {marker:\d+} is now valid to require the marker to be digits.

Addded a new API pyramid.url.current_route_url(), which computes a URL based on the “current” route (if any) and its matchdict values.

Added a paster proute command which displays a summary of the routing table. See the narrative documentation section entitled Displaying All Application Routes.

Added debug_routematch configuration setting (settable in your .ini file) that logs matched routes including the matchdict and predicates.

Add a pyramid.url.route_path() API, allowing folks to generate relative URLs. Calling route_path is the same as calling pyramid.url.route_url() with the argument _app_url equal to the empty string.

Add a pyramid.request.Request.route_path() API. This is a convenience method of the request which calls pyramid.url.route_url().

Added class vars matchdict and matched_route to pyramid.request.Request. Each is set to None when a route isn’t matched during a request.

ZCML Externalized

The load_zcml method of a Configurator has been removed from the Pyramid core. Loading ZCML is now a feature of the pyramid_zcml package, which can be downloaded from PyPI. Documentation for the package should be available via http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how to add a configuration statement to your main block to reobtain this method. You will also need to add an install_requires dependency upon the pyramid_zcml distribution to your setup.py file.

The “Declarative Configuration” narrative chapter has been removed (it was moved to the pyramid_zcml package).

Most references to ZCML in narrative chapters have been removed or redirected to pyramid_zcml locations.

The starter_zcml paster template has been moved to the pyramid_zcml package.

Imperative Two-Phase Configuration

To support application extensibility, the Pyramid Configurator, by default, now detects configuration conflicts and allows you to include configuration imperatively from other packages or modules. It also, by default, performs configuration in two separate phases. This allows you to ignore relative configuration statement ordering in some circumstances. See Advanced Configuration for more information.

The pyramid.config.Configurator.add_directive() allows framework extenders to add methods to the configurator, which allows extenders to avoid subclassing a Configurator just to add methods. See Adding Methods to the Configurator via add_directive for more info.

Surrounding application configuration with config.begin() and config.end() is no longer necessary. All paster templates have been changed to no longer call these functions.

Better Support for Global Template Variables During Rendering

A new event type named pyramid.interfaces.IBeforeRender is now sent as an event before a renderer is invoked. Applications may now subscribe to the IBeforeRender event type in order to introspect the and modify the set of renderer globals before they are passed to a renderer. The event object iself has a dictionary-like interface that can be used for this purpose. For example:

from repoze.events import subscriber
from pyramid.interfaces import IRendererGlobalsEvent

@subscriber(IRendererGlobalsEvent)
def add_global(event):
    event['mykey'] = 'foo'

View Mappers

A “view mapper” subsystem has been extracted, which allows framework extenders to control how view callables are constructed and called. This feature is not useful for “civilians”, only for extension writers. See Using a View Mapper for more information.

Testing Support Improvements

The pyramid.testing.setUp() and pyramid.testing.tearDown() APIs have been undeprecated. They are now the canonical setup and teardown APIs for test configuration, replacing “direct” creation of a Configurator. This is a change designed to provide a facade that will protect against any future Configurator deprecations.

Authentication Support Improvements

The pyramid.interfaces.IAuthenticationPolicy interface now specifies an unauthenticated_userid method. This method supports an important optimization required by people who are using persistent storages which do not support object caching and whom want to create a “user object” as a request attribute.

A new API has been added to the pyramid.security module named unauthenticated_userid. This API function calls the unauthenticated_userid method of the effective security policy.

The class pyramid.authentication.AuthTktCookieHelper is now an API. This class can be used by third-party authentication policy developers to help in the mechanics of authentication cookie-setting.

The pyramid.authentication.AuthTktAuthenticationPolicy now accepts a tokens parameter via pyramid.security.remember(). The value must be a sequence of strings. Tokens are placed into the auth_tkt “tokens” field and returned in the auth_tkt cookie.

Added a wild_domain argument to pyramid.authentication.AuthTktAuthenticationPolicy, which defaults to True. If it is set to False, the feature of the policy which sets a cookie with a wilcard domain will be turned off.

Documentation Improvements

Casey Duncan, a good friend, and an excellent technical writer has given us the gift of professionally editing the entire Pyramid documentation set. Any faults in the documentation are the development team’s, and all improvements are his.

The “Resource Location and View Lookup” chapter has been replaced with a variant of Rob Miller’s “Much Ado About Traversal” (originally published at http://blog.nonsequitarian.org/2010/much-ado-about-traversal/).

Many users have contributed documentation fixes and improvements including Ben Bangert, Blaise Laflamme, Rob Miller, Mike Orr, Carlos de la Guardia, Paul Everitt, Tres Seaver, John Shipman, Marius Gedminas, Chris Rossi, Joachim Krebs, Xavier Spriet, Reed O’Brien, William Chambers, Charlie Choiniere, and Jamaludin Ahmad.

Minor Feature Additions

The settings dictionary passed to the Configurator is now available as config.registry.settings in configuration code and request.registry.settings in view code).

pyramid.config.Configurator.add_view() now accepts a decorator keyword argument, a callable which will decorate the view callable before it is added to the registry.

Allow static renderer provided during view registration to be overridden at request time via a request attribute named override_renderer, which should be the name of a previously registered renderer. Useful to provide “omnipresent” RPC using existing rendered views.

If a resource implements a __resource_url__ method, it will be called as the result of invoking the pyramid.url.resource_url() function to generate a URL, overriding the default logic. See Generating The URL Of A Resource for more information.

The name registry is now available in a pshell environment by default. It is the application registry object.

Added support for json on Google App Engine by catching NotImplementedError and importing simplejson from django.utils.

Added the pyramid.httpexceptions module, which is a facade for the webob.exc module.

New class: pyramid.response.Response. This is a pure facade for webob.Response (old code need not change to use this facade, it’s existence is mostly for vanity and documentation-generation purposes).

The request now has a new attribute: tmpl_context for benefit of Pylons users.

New API methods for pyramid.request.Request: model_url, route_url, and static_url. These are simple passthroughs for their respective functions in pyramid.url.

Backwards Incompatibilities

When a pyramid.exceptions.Forbidden error is raised, its status code now 403 Forbidden. It was previously 401 Unauthorized, for backwards compatibility purposes with repoze.bfg. This change will cause problems for users of Pyramid with repoze.who, which intercepts 401 Unauthorized by default, but allows 403 Forbidden to pass through. Those deployments will need to configure repoze.who to also react to 403 Forbidden. To do so, use a repoze.who challenge_decider that looks like this:

import zope.interface
from repoze.who.interfaces import IChallengeDecider

def challenge_decider(environ, status, headers):
    return status.startswith('403') or status.startswith('401')
zope.interface.directlyProvides(challenge_decider, IChallengeDecider)

The paster bfgshell command is now known as paster pshell.

There is no longer an IDebugLogger object registered as a named utility with the name repoze.bfg.debug.

These deprecated APIs have been removed: pyramid.testing.registerViewPermission, pyramid.testing.registerRoutesMapper, pyramid.request.get_request, pyramid.security.Unauthorized, pyramid.view.view_execution_permitted, pyramid.view.NotFound

The Venusian “category” for all built-in Venusian decorators (e.g. subscriber and view_config/bfg_view) is now pyramid instead of bfg.

The pyramid.renderers.rendered_response function removed; use pyramid.renderers.render_to_response() instead.

Renderer factories now accept a renderer info object rather than an absolute resource specification or an absolute path. The object has the following attributes: name (the renderer= value), package (the ‘current package’ when the renderer configuration statement was found), type: the renderer type, registry: the current registry, and settings: the deployment settings dictionary. Third-party repoze.bfg renderer implementations that must be ported to Pyramid will need to account for this. This change was made primarily to support more flexible Mako template rendering.

The presence of the key repoze.bfg.message in the WSGI environment when an exception occurs is now deprecated. Instead, code which relies on this environ value should use the exception attribute of the request (e.g. request.exception[0]) to retrieve the message.

The values bfg_localizer and bfg_locale_name kept on the request during internationalization for caching purposes were never APIs. These however have changed to localizer and locale_name, respectively.

The default cookie_name value of the pyramid.authentication.AuthTktAuthenticationPolicy now defaults to auth_tkt (it used to default to repoze.bfg.auth_tkt).

The pyramid.testing.zcml_configure() API has been removed. It had been advertised as removed since repoze.bfg 1.2a1, but hadn’t actually been.

All environment variables which used to be prefixed with BFG_ are now prefixed with PYRAMID_ (e.g. BFG_DEBUG_NOTFOUND is now PYRAMID_DEBUG_NOTFOUND)

Since the pyramid.interfaces.IAuthenticationPolicy interface now specifies that a policy implementation must implement an unauthenticated_userid method, all third-party custom authentication policies now must implement this method. It, however, will only be called when the global function named pyramid.security.unauthenticated_userid() is invoked, so if you’re not invoking that, you will not notice any issues.

The configure_zcml setting within the deployment settings (within **settings passed to a Pyramid main function) has ceased to have any meaning.

The make_app function has been removed from the pyramid.router module. It continues life within the pyramid_zcml package. This leaves the pyramid.router module without any API functions.

Deprecations and Behavior Differences

pyramid.configuration.Configurator is now deprecated. Use pyramid.config.Configurator, passing its constructor autocommit=True instead. The pyramid.configuration.Configurator alias will live for a long time, as every application uses it, but its import now issues a deprecation warning. The pyramid.config.Configurator class has the same API as the pyramid.configuration.Configurator class, which it means to replace, except by default it is a non-autocommitting configurator. The now-deprecated pyramid.configuration.Configurator will autocommit every time a configuration method is called. The pyramid.configuration module remains, but it is deprecated. Use pyramid.config instead.

The pyramid.settings.get_settings() API is now deprecated. Use pyramid.threadlocals.get_current_registry().settings instead or use the settings attribute of the registry available from the request (request.registry.settings).

The decorator previously known as pyramid.view.bfg_view is now known most formally as pyramid.view.view_config in docs and paster templates.

Obtaining the settings object via registry.{get|query}Utility(ISettings) is now deprecated. Instead, obtain the settings object via the registry.settings attribute. A backwards compatibility shim was added to the registry object to register the settings object as an ISettings utility when setattr(registry, 'settings', foo) is called, but it will be removed in a later release.

Obtaining the settings object via pyramid.settings.get_settings() is now deprecated. Obtain it instead as the settings attribute of the registry now (obtain the registry via pyramid.threadlocal.get_registry() or as request.registry).

Dependency Changes

Depend on Venusian >= 0.5 (for scanning conflict exception decoration).

Documentation Enhancements

Added a pyramid.httpexceptions API documentation chapter.

Added a pyramid.session API documentation chapter.

Added an API chapter for the pyramid.response module.

Added a Sessions narrative documentation chapter.

All documentation which previously referred to webob.Response now uses pyramid.response.Response instead.

The documentation has been overhauled to use imperative configuration, moving declarative configuration (ZCML) explanations to an external package, pyramid_zcml.

Removed zodbsessions tutorial chapter. It’s still useful, but we now have a SessionFactory abstraction which competes with it, and maintaining documentation on both ways to do it is a distraction.

Added an example of WebTest functional testing to the testing narrative chapter at Creating Functional Tests.

Extended the Resources chapter with examples of calls to resource-related APIs.

Add “Pyramid Provides More Than One Way to Do It” to Design Defense documentation.

The (weak) “Converting a CMF Application to Pyramid” tutorial has been removed from the tutorials section. It was moved to the pyramid_tutorials Github repository at http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/.

Moved “Using ZODB With ZEO” and “Using repoze.catalog Within Pyramid” tutorials out of core documentation and into the Pyramid Tutorials site (http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/).

Removed API documentation for deprecated pyramid.testing APIs named registerDummySecurityPolicy, registerResources, registerModels, registerEventListener, registerTemplateRenderer, registerDummyRenderer, registerView, registerUtility, registerAdapter, registerSubscriber, registerRoute, and registerSettings.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Pyramid Introduction

Pyramid is a general, open source, Python web application development framework. Its primary goal is to make it easier for a developer to create web applications. The type of application being created could be a spreadsheet, a corporate intranet, or a social networking platform; Pyramid’s generality enables it to be used to build an unconstrained variety of web applications.

Frameworks vs. Libraries

A framework differs from a library in one very important way: library code is always called by code that you write, while a framework always calls code that you write. Using a set of libraries to create an application is usually easier than using a framework initially, because you can choose to cede control to library code you have not authored very selectively. But when you use a framework, you are required to cede a greater portion of control to code you have not authored: code that resides in the framework itself. You needn’t use a framework at all to create a web application using Python. A rich set of libraries already exists for the platform. In practice, however, using a framework to create an application is often more practical than rolling your own via a set of libraries if the framework provides a set of facilities that fits your application requirements.

The first release of Pyramid’s predecessor (named repoze.bfg) was made in July of 2008. We have worked hard to ensure that Pyramid continues to follow the design and engineering principles that we consider to be the core characteristics of a successful framework:

Simplicity

Pyramid takes a “pay only for what you eat” approach. This means that you can get results even if you have only a partial understanding of Pyramid. It doesn’t force you to use any particular technology to produce an application, and we try to keep the core set of concepts that you need to understand to a minimum.

Minimalism

Pyramid concentrates on providing fast, high-quality solutions to the fundamental problems of creating a web application: the mapping of URLs to code, templating, security and serving static assets. We consider these to be the core activities that are common to nearly all web applications.

Documentation

Pyramid’s minimalism means that it is relatively easy for us to maintain extensive and up-to-date documentation. It is our goal that no aspect of Pyramid remains undocumented.

Speed

Pyramid is designed to provide noticeably fast execution for common tasks such as templating and simple response generation. Although the “hardware is cheap” mantra may appear to offer a ready solution to speed problems, the limits of this approach become painfully evident when one finds him or herself responsible for managing a great many machines.

Reliability

Pyramid is developed conservatively and tested exhaustively. Where Pyramid source code is concerned, our motto is: “If it ain’t tested, it’s broke”. Every release of Pyramid has 100% statement coverage via unit tests.

Openness

As with Python, the Pyramid software is distributed under a permissive open source license [http://repoze.org/license.html].

What Is The Pylons Project?

Pyramid is a member of the collection of software published under the Pylons Project. Pylons software is written by a loose-knit community of contributors. The Pylons Project website [http://docs.pylonsproject.org] includes details about how Pyramid relates to the Pylons Project.

Pyramid and Other Web Frameworks

Until the end of 2010, Pyramid was known as repoze.bfg; it was merged into the Pylons project as Pyramid in November of that year.

Pyramid was inspired by Zope, Pylons (version 1.0) and Django. As a result, Pyramid borrows several concepts and features from each, combining them into a unique web framework.

Many features of Pyramid trace their origins back to Zope. Like Zope applications, Pyramid applications can be configured via a set of declarative configuration files. Like Zope applications, Pyramid applications can be easily extended: if you obey certain constraints, the application you produce can be reused, modified, re-integrated, or extended by third-party developers without forking the original application. The concepts of traversal and declarative security in Pyramid were pioneered first in Zope.

The Pyramid concept of URL dispatch is inspired by the Routes system used by Pylons version 1.0. Like Pylons version 1.0, Pyramid is mostly policy-free. It makes no assertions about which database you should use, and its built-in templating facilities are included only for convenience. In essence, it only supplies a mechanism to map URLs to view code, along with a set of conventions for calling those views. You are free to use third-party components that fit your needs in your applications.

The concept of view is used by Pyramid mostly as it would be by Django. Pyramid has a documentation culture more like Django’s than like Zope’s.

Like Pylons version 1.0, but unlike Zope, a Pyramid application developer may use completely imperative code to perform common framework configuration tasks such as adding a view or a route. In Zope, ZCML is typically required for similar purposes. In Grok, a Zope-based web framework, decorator objects and class-level declarations are used for this purpose. Pyramid supports ZCML and decorator-based configuration, but does not require either. See Application Configuration for more information.

Also unlike Zope and unlike other “full-stack” frameworks such as Django, Pyramid makes no assumptions about which persistence mechanisms you should use to build an application. Zope applications are typically reliant on ZODB; Pyramid allows you to build ZODB applications, but it has no reliance on the ZODB software. Likewise, Django tends to assume that you want to store your application’s data in a relational database. Pyramid makes no such assumption; it allows you to use a relational database but doesn’t encourage or discourage the decision.

Other Python web frameworks advertise themselves as members of a class of web frameworks named model-view-controller [http://en.wikipedia.org/wiki/Model–view–controller] frameworks. Insofar as this term has been claimed to represent a class of web frameworks, Pyramid also generally fits into this class.

You Say Pyramid is MVC, But Where’s The Controller?

The Pyramid authors believe that the MVC pattern just doesn’t really fit the web very well. In a Pyramid application, there is a resource tree, which represents the site structure, and views, which tend to present the data stored in the resource tree and a user-defined “domain model”. However, no facility provided by the framework actually necessarily maps to the concept of a “controller” or “model”. So if you had to give it some acronym, I guess you’d say Pyramid is actually an “RV” framework rather than an “MVC” framework. “MVC”, however, is close enough as a general classification moniker for purposes of comparison with other web frameworks.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Installing Pyramid

Before You Install

You will need Python [http://python.org] version 2.4 or better to run Pyramid.

Python Versions

As of this writing, Pyramid has been tested under Python 2.4.6, Python 2.5.4 and Python 2.6.2, and Python 2.7. To ensure backwards compatibility, development of Pyramid is currently done primarily under Python 2.4 and Python 2.5. Pyramid does not run under any version of Python before 2.4, and does not yet run under Python 3.X.

Pyramid is known to run on all popular Unix-like systems such as Linux, MacOS X, and FreeBSD as well as on Windows platforms. It is also known to run on Google’s App Engine and Jython.

Pyramid installation does not require the compilation of any C code, so you need only a Python interpreter that meets the requirements mentioned.

If You Don’t Yet Have A Python Interpreter (UNIX)

If your system doesn’t have a Python interpreter, and you’re on UNIX, you can either install Python using your operating system’s package manager or you can install Python from source fairly easily on any UNIX system that has development tools.

Package Manager Method

You can use your system’s “package manager” to install Python. Every system’s package manager is slightly different, but the “flavor” of them is usually the same.

For example, on an Ubuntu Linux system, to use the system package manager to install a Python 2.6 interpreter, use the following command:

$ sudo apt-get install python2.6-dev

Once these steps are performed, the Python interpreter will usually be invokable via python2.6 from a shell prompt.

Source Compile Method

It’s useful to use a Python interpreter that isn’t the “system” Python interpreter to develop your software. The authors of Pyramid tend not to use the system Python for development purposes; always a self-compiled one. Compiling Python is usually easy, and often the “system” Python is compiled with options that aren’t optimal for web development.

To compile software on your UNIX system, typically you need development tools. Often these can be installed via the package manager. For example, this works to do so on an Ubuntu Linux system:

$ sudo apt-get install build-essential

On Mac OS X, installing XCode [http://developer.apple.com/tools/xcode/] has much the same effect.

Once you’ve got development tools installed on your system, On the same system, to install a Python 2.6 interpreter from source, use the following commands:

[chrism@vitaminf ~]$ cd ~
[chrism@vitaminf ~]$ mkdir tmp
[chrism@vitaminf ~]$ mkdir opt
[chrism@vitaminf ~]$ cd tmp
[chrism@vitaminf tmp]$ wget \
       http://www.python.org/ftp/python/2.6.4/Python-2.6.4.tgz
[chrism@vitaminf tmp]$ tar xvzf Python-2.6.4.tgz
[chrism@vitaminf tmp]$ cd Python-2.6.4
[chrism@vitaminf Python-2.6.4]$ ./configure \
        --prefix=$HOME/opt/Python-2.6.4
[chrism@vitaminf Python-2.6.4]$ make; make install

Once these steps are performed, the Python interpreter will be invokable via $HOME/opt/Python-2.6.4/bin/python from a shell prompt.

If You Don’t Yet Have A Python Interpreter (Windows)

If your Windows system doesn’t have a Python interpreter, you’ll need to install it by downloading a Python 2.6-series interpreter executable from python.org’s download section [http://python.org/download/] (the files labeled “Windows Installer”). Once you’ve downloaded it, double click on the executable and accept the defaults during the installation process. You may also need to download and install the Python for Windows extensions [http://sourceforge.net/projects/pywin32/files/].

Warning

After you install Python on Windows, you may need to add the C:\Python26 directory to your environment’s Path in order to make it possible to invoke Python from a command prompt by typing python. To do so, right click My Computer, select Properties –> Advanced Tab –> Environment Variables and add that directory to the end of the Path environment variable.

Installing Pyramid on a UNIX System

It is best practice to install Pyramid into a “virtual” Python environment in order to obtain isolation from any “system” packages you’ve got installed in your Python version. This can be done by using the virtualenv package. Using a virtualenv will also prevent Pyramid from globally installing versions of packages that are not compatible with your system Python.

To set up a virtualenv in which to install Pyramid, first ensure that setuptools is installed. Invoke import setuptools within the Python interpreter you’d like to run Pyramid under:

[chrism@vitaminf pyramid]$ python
Python 2.4.5 (#1, Aug 29 2008, 12:27:37)
[GCC 4.0.1 (Apple Inc. build 5465)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import setuptools

If running import setuptools does not raise an ImportError, it means that setuptools is already installed into your Python interpreter. If import setuptools fails, you will need to install setuptools manually. Note that above we’re using a Python 2.4-series interpreter on Mac OS X; your output may differ if you’re using a later Python version or a different platform.

If you are using a “system” Python (one installed by your OS distributor or a 3rd-party packager such as Fink or MacPorts), you can usually install the setuptools package by using your system’s package manager. If you cannot do this, or if you’re using a self-installed version of Python, you will need to install setuptools “by hand”. Installing setuptools “by hand” is always a reasonable thing to do, even if your package manager already has a pre-chewed version of setuptools for installation.

To install setuptools by hand, first download ez_setup.py [http://peak.telecommunity.com/dist/ez_setup.py] then invoke it using the Python interpreter into which you want to install setuptools.

$ python ez_setup.py

Once this command is invoked, setuptools should be installed on your system. If the command fails due to permission errors, you may need to be the administrative user on your system to successfully invoke the script. To remediate this, you may need to do:

$ sudo python ez_setup.py

Installing the virtualenv Package

Once you’ve got setuptools installed, you should install the virtualenv package. To install the virtualenv package into your setuptools-enabled Python interpreter, use the easy_install command.

$ easy_install virtualenv

This command should succeed, and tell you that the virtualenv package is now installed. If it fails due to permission errors, you may need to install it as your system’s administrative user. For example:

$ sudo easy_install virtualenv

Creating the Virtual Python Environment

Once the virtualenv package is installed in your Python, you can then create a virtual environment. To do so, invoke the following:

$ virtualenv --no-site-packages env
New python executable in env/bin/python
Installing setuptools.............done.

Warning

Using --no-site-packages when generating your virtualenv is very important. This flag provides the necessary isolation for running the set of packages required by Pyramid. If you do not specify --no-site-packages, it’s possible that Pyramid will not install properly into the virtualenv, or, even if it does, may not run properly, depending on the packages you’ve already got installed into your Python’s “main” site-packages dir.

Warning

If you’re on UNIX, do not use sudo to run the virtualenv script. It’s perfectly acceptable (and desirable) to create a virtualenv as a normal user.

You should perform any following commands that mention a “bin” directory from within the env virtualenv dir.

Installing Pyramid Into the Virtual Python Environment

After you’ve got your env virtualenv installed, you may install Pyramid itself using the following commands from within the virtualenv (env) directory:

$ bin/easy_install pyramid

This command will take longer than the previous ones to complete, as it downloads and installs a number of dependencies.

Installing Pyramid on a Windows System

Install, or find Python 2.6 [http://python.org/download/releases/2.6.4/] for your system.

Install the Python for Windows extensions [http://sourceforge.net/projects/pywin32/files/]. Make sure to pick the right download for Python 2.6 and install it using the same Python installation from the previous step.

Install latest setuptools distribution into the Python you obtained/installed/found in the step above: download ez_setup.py [http://peak.telecommunity.com/dist/ez_setup.py] and run it using the python interpreter of your Python 2.6 installation using a command prompt:

c:\> c:\Python26\python ez_setup.py

Use that Python’s bin/easy_install to install virtualenv:

c:\> c:\Python26\Scripts\easy_install virtualenv

Use that Python’s virtualenv to make a workspace:

c:\> c:\Python26\Scripts\virtualenv --no-site-packages env

Switch to the env directory:

c:\> cd env

(Optional) Consider using Scripts\activate.bat to make your shell environment wired to use the virtualenv.

Use easy_install pointed at the “current” index to get Pyramid and its direct dependencies installed:

c:\env> Scripts\easy_install pyramid

Installing Pyramid on Google App Engine

Running Pyramid on Google’s App Engine documents the steps required to install a Pyramid application on Google App Engine.

Installing Pyramid on Jython

Pyramid is known to work under Jython version 2.5.1. Install Jython, and then follow the installation steps for Pyramid on your platform described in one of the sections entitled Installing Pyramid on a UNIX System or Installing Pyramid on a Windows System above, replacing the python command with jython as necessary. The steps are exactly the same except you should use the jython command name instead of the python command name.

One caveat exists to using Pyramid under Jython: the Chameleon templating engine does not work on Jython. However, the Mako templating system, which is also included with Pyramid, does work under Jython; use it instead.

What Gets Installed

When you easy_install Pyramid, various Zope libraries, various Chameleon libraries, WebOb, Paste, PasteScript, and PasteDeploy libraries are installed.

Additionally, as chronicled in Creating a Pyramid Project, PasteScript (aka paster) templates will be registered that make it easy to start a new Pyramid project.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Application Configuration

Each deployment of an application written using Pyramid implies a specific configuration of the framework itself. For example, an application which serves up MP3 files for your listening enjoyment might plug code into the framework that manages song files, while an application that manages corporate data might plug in code that manages accounting information. The way in which code is plugged in to Pyramid for a specific application is referred to as “configuration”.

Most people understand “configuration” as coarse settings that inform the high-level operation of a specific application deployment. For instance, it’s easy to think of the values implied by a .ini file parsed at application startup time as “configuration”. Pyramid extends this pattern to application development, using the term “configuration” to express standardized ways that code gets plugged into a deployment of the framework itself. When you plug code into the Pyramid framework, you are “configuring” Pyramid to create a particular application.

Imperative Configuration

Here’s one of the simplest Pyramid applications, configured imperatively:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from paste.httpserver import serve
from pyramid.config import Configurator
from pyramid.response import Response

def hello_world(request):
    return Response('Hello world!')

if __name__ == '__main__':
    config = Configurator()
    config.add_view(hello_world)
    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

We won’t talk much about what this application does yet. Just note that the “configuration’ statements take place underneath the if __name__ == '__main__': stanza in the form of method calls on a Configurator object (e.g. config.add_view(...)). These statements take place one after the other, and are executed in order, so the full power of Python, including conditionals, can be employed in this mode of configuration.

Configuration Decorations and Code Scanning

A different mode of configuration gives more locality of reference to a configuration declaration. It’s sometimes painful to have all configuration done in imperative code, because often the code for a single application may live in many files. If the configuration is centralized in one place, you’ll need to have at least two files open at once to see the “big picture”: the file that represents the configuration, and the file that contains the implementation objects referenced by the configuration. To avoid this, Pyramid allows you to insert configuration decoration statements very close to code that is referred to by the declaration itself. For example:

1
2
3
4
5
6

from pyramid.response import Response
from pyramid.view import view_config

@view_config(name='hello', request_method='GET')
def hello(request):
    return Response('Hello')

The mere existence of configuration decoration doesn’t cause any configuration registration to be performed. Before it has any effect on the configuration of a Pyramid application, a configuration decoration within application code must be found through a process known as a scan.

For example, the pyramid.view.view_config decorator in the code example above adds an attribute to the hello function, making it available for a scan to find it later.

A scan of a module or a package and its subpackages for decorations happens when the pyramid.config.Configurator.scan() method is invoked: scanning implies searching for configuration declarations in a package and its subpackages. For example:

Starting A Scan

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from paste.httpserver import serve
from pyramid.response import Response
from pyramid.view import view_config

@view_config()
def hello(request):
    return Response('Hello')

if __name__ == '__main__':
    from pyramid.config import Configurator
    config = Configurator()
    config.scan()
    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

The scanning machinery imports each module and subpackage in a package or module recursively, looking for special attributes attached to objects defined within a module. These special attributes are typically attached to code via the use of a decorator. For example, the view_config decorator can be attached to a function or instance method.

Once scanning is invoked, and configuration decoration is found by the scanner, a set of calls are made to a Configurator on your behalf: these calls replace the need to add imperative configuration statements that don’t live near the code being configured.

In the example above, the scanner translates the arguments to view_config into a call to the pyramid.config.Configurator.add_view() method, effectively:

1

config.add_view(hello)

Declarative Configuration

A third mode of configuration can be employed when you create a Pyramid application named declarative configuration. This mode uses an XML language known as ZCML to represent configuration statements rather than Python. ZCML is not built-in to Pyramid, but almost everything that can be configured imperatively can also be configured via ZCML if you install the pyramid_zcml package.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Creating Your First Pyramid Application

In this chapter, we will walk through the creation of a tiny Pyramid application. After we’re finished creating the application, we’ll explain in more detail how it works.

Hello World, Goodbye World

Here’s one of the very simplest Pyramid applications, configured imperatively:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from pyramid.config import Configurator
from pyramid.response import Response
from paste.httpserver import serve

def hello_world(request):
    return Response('Hello world!')

def goodbye_world(request):
    return Response('Goodbye world!')

if __name__ == '__main__':
    config = Configurator()
    config.add_view(hello_world)
    config.add_view(goodbye_world, name='goodbye')
    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

When this code is inserted into a Python script named helloworld.py and executed by a Python interpreter which has the Pyramid software installed, an HTTP server is started on TCP port 8080:

$ python helloworld.py
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080

When port 8080 is visited by a browser on the root URL (/), the server will simply serve up the text “Hello world!” When visited by a browser on the URL /goodbye, the server will serve up the text “Goodbye world!”

Press Ctrl-C to stop the application.

Now that we have a rudimentary understanding of what the application does, let’s examine it piece-by-piece.

Imports

The above helloworld.py script uses the following set of import statements:

1
2
3

from pyramid.config import Configurator
from pyramid.response import Response
from paste.httpserver import serve

The script imports the Configurator class from the pyramid.config module. An instance of the Configurator class is later used to configure your Pyramid application.

The script uses the pyramid.response.Response class later in the script to create a response object.

Like many other Python web frameworks, Pyramid uses the WSGI protocol to connect an application and a web server together. The paste.httpserver server is used in this example as a WSGI server for convenience, as the paste package is a dependency of Pyramid itself.

View Callable Declarations

The above script, beneath its set of imports, defines two functions: one named hello_world and one named goodbye_world.

1
2
3
4
5

def hello_world(request):
    return Response('Hello world!')

def goodbye_world(request):
    return Response('Goodbye world!')

These functions don’t do anything very difficult. Both functions accept a single argument (request). The hello_world function does nothing but return a response instance with the body Hello world!. The goodbye_world function returns a response instance with the body Goodbye world!.

Each of these functions is known as a view callable. A view callable accepts a single argument, request. It is expected to return a response object. A view callable doesn’t need to be a function; it can be represented via another type of object, like a class or an instance, but for our purposes here, a function serves us well.

A view callable is always called with a request object. A request object is a representation of an HTTP request sent to Pyramid via the active WSGI server.

A view callable is required to return a response object because a response object has all the information necessary to formulate an actual HTTP response; this object is then converted to text by the upstream WSGI server and sent back to the requesting browser. To return a response, each view callable creates an instance of the Response class. In the hello_world function, the string 'Hello world!' is passed to the Response constructor as the body of the response. In the goodbye_world function, the string 'Goodbye world!' is passed.

Note

As we’ll see in later chapters, returning a literal response object from a view callable is not always required; we can instead use a renderer in our view configurations. If we use a renderer, our view callable is allowed to return a value that the renderer understands, and the renderer generates a response on our behalf.

Application Configuration

In the above script, the following code represents the configuration of this simple application. The application is configured using the previously defined imports and function definitions, placed within the confines of an if statement:

1
2
3
4
5
6

if __name__ == '__main__':
    config = Configurator()
    config.add_view(hello_world)
    config.add_view(goodbye_world, name='goodbye')
    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

Let’s break this down this piece-by-piece.

Configurator Construction

1
2

if __name__ == '__main__':
    config = Configurator()

The if __name__ == '__main__': line in the code sample above represents a Python idiom: the code inside this if clause is not invoked unless the script containing this code is run directly from the command line. For example, if the file named helloworld.py contains the entire script body, the code within the if statement will only be invoked when python helloworld.py is executed from the operating system command line.

helloworld.py in this case is a Python module. Using the if clause is necessary – or at least best practice – because code in any Python module may be imported by another Python module. By using this idiom, the script is indicating that it does not want the code within the if statement to execute if this module is imported; the code within the if block should only be run during a direct script execution.

The config = Configurator() line above creates an instance of the Configurator class. The resulting config object represents an API which the script uses to configure this particular Pyramid application. Methods called on the Configurator will cause registrations to be made in a application registry associated with the application.

Adding Configuration

1
2

config.add_view(hello_world)
config.add_view(goodbye_world, name='goodbye')

Each of these lines calls the pyramid.config.Configurator.add_view() method. The add_view method of a configurator registers a view configuration within the application registry. A view configuration represents a set of circumstances related to the request that will cause a specific view callable to be invoked. This “set of circumstances” is provided as one or more keyword arguments to the add_view method. Each of these keyword arguments is known as a view configuration predicate.

The line config.add_view(hello_world) registers the hello_world function as a view callable. The add_view method of a Configurator must be called with a view callable object or a dotted Python name as its first argument, so the first argument passed is the hello_world function. This line calls add_view with a default value for the predicate argument, named name. The name predicate defaults to a value equalling the empty string (''). This means that we’re instructing Pyramid to invoke the hello_world view callable when the view name is the empty string. We’ll learn in later chapters what a view name is, and under which circumstances a request will have a view name that is the empty string; in this particular application, it means that the hello_world view callable will be invoked when the root URL / is visited by a browser.

The line config.add_view(goodbye_world, name='goodbye') registers the goodbye_world function as a view callable. The line calls add_view with the view callable as the first required positional argument, and a predicate keyword argument name with the value 'goodbye'. The name argument supplied in this view configuration implies that only a request that has a view name of goodbye should cause the goodbye_world view callable to be invoked. In this particular application, this means that the goodbye_world view callable will be invoked when the URL /goodbye is visited by a browser.

Each invocation of the add_view method registers a view configuration. Each predicate provided as a keyword argument to the add_view method narrows the set of circumstances which would cause the view configuration’s callable to be invoked. In general, a greater number of predicates supplied along with a view configuration will more strictly limit the applicability of its associated view callable. When Pyramid processes a request, the view callable with the most specific view configuration (the view configuration that matches the most specific set of predicates) is always invoked.

In this application, Pyramid chooses the most specific view callable based only on view predicate applicability. The ordering of calls to add_view() is never very important. We can register goodbye_world first and hello_world second; Pyramid will still give us the most specific callable when a request is dispatched to it.

WSGI Application Creation

1

app = config.make_wsgi_app()

After configuring views and ending configuration, the script creates a WSGI application via the pyramid.config.Configurator.make_wsgi_app() method. A call to make_wsgi_app implies that all configuration is finished (meaning all method calls to the configurator which set up views, and various other configuration settings have been performed). The make_wsgi_app method returns a WSGI application object that can be used by any WSGI server to present an application to a requestor. WSGI is a protocol that allows servers to talk to Python applications. We don’t discuss WSGI in any depth within this book, however, you can learn more about it by visiting wsgi.org [http://wsgi.org].

The Pyramid application object, in particular, is an instance of a class representing a Pyramid router. It has a reference to the application registry which resulted from method calls to the configurator used to configure it. The router consults the registry to obey the policy choices made by a single application. These policy choices were informed by method calls to the Configurator made earlier; in our case, the only policy choices made were implied by two calls to its add_view method.

WSGI Application Serving

1

serve(app, host='0.0.0.0')

Finally, we actually serve the application to requestors by starting up a WSGI server. We happen to use the paste.httpserver.serve() WSGI server runner, passing it the app object (a router) as the application we wish to serve. We also pass in an argument host=='0.0.0.0', meaning “listen on all TCP interfaces.” By default, the Paste HTTP server listens only on the 127.0.0.1 interface, which is problematic if you’re running the server on a remote system and you wish to access it with a web browser from a local system. We don’t specify a TCP port number to listen on; this means we want to use the default TCP port, which is 8080.

When this line is invoked, it causes the server to start listening on TCP port 8080. It will serve requests forever, or at least until we stop it by killing the process which runs it (usually by pressing Ctrl-C in the terminal we used to start it).

Conclusion

Our hello world application is one of the simplest possible Pyramid applications, configured “imperatively”. We can see that it’s configured imperatively because the full power of Python is available to us as we perform configuration tasks.

References

For more information about the API of a Configurator object, see Configurator .

For more information about view configuration, see View Configuration.

An example of using declarative configuration (ZCML) instead of imperative configuration to create a similar “hello world” is available within the documentation for pyramid_zcml.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Creating a Pyramid Project

As we saw in Creating Your First Pyramid Application, it’s possible to create a Pyramid application completely manually. However, it’s usually more convenient to use a template to generate a basic Pyramid project.

A project is a directory that contains at least one Python package. You’ll use a template to create a project, and you’ll create your application logic within a package that lives inside the project. Even if your application is extremely simple, it is useful to place code that drives the application within a package, because a package is more easily extended with new code. An application that lives inside a package can also be distributed more easily than one which does not live within a package.

Pyramid comes with a variety of templates that you can use to generate a project. Each template makes different configuration assumptions about what type of application you’re trying to construct.

These templates are rendered using the PasteDeploy paster script, and so therefore they are often referred to as “paster templates”.

Paster Templates Included with Pyramid

The convenience paster templates included with Pyramid differ from each other on a number of axes:

the persistence mechanism they offer (no persistence mechanism, ZODB, or SQLAlchemy).

the mechanism they use to map URLs to code (traversal or URL dispatch).

whether or not the pyramid_beaker library is relied upon as the sessioning implementation (as opposed to no sessioning or default sessioning).

The included templates are these:

pyramid_starter

URL mapping via traversal and no persistence mechanism.

pyramid_zodb

URL mapping via traversal and persistence via ZODB.

pyramid_routesalchemy

URL mapping via URL dispatch and persistence via SQLAlchemy

pyramid_alchemy

URL mapping via traversal and persistence via SQLAlchemy

Note

At this time, each of these templates uses the Chameleon templating system, which is incompatible with both Jython and PyPy. To use paster templates to build applications which will run on Jython and PyPy, you can try the pyramid_jinja2_starter template which ships as part of the pyramid_jinja2 package or the pyramid_sqla paster template which ships with the pyramid_sqla package (it uses Mako), both available from PyPI. You can also just use the above paster templates to build a skeleton and replace the Chameleon template it includes with a Mako analogue.

Rather than use any of the above templates, Pylons 1 users may feel more comfortable installing the pyramid_sqla add-on package, which provides a paster template named pyramid_sqla. This paster template configures a Pyramid application in a “Pylons-esque” way, including the use of a view handler to map URLs to code (it’s much like a Pylons “controller”).

Creating the Project

In Installing Pyramid, you created a virtual Python environment via the virtualenv command. To start a Pyramid project, use the paster facility installed within the virtualenv. In Installing Pyramid we called the virtualenv directory env; the following command assumes that our current working directory is that directory.

We’ll choose the pyramid_starter template for this purpose.

$ bin/paster create -t pyramid_starter

The above command uses the paster command to create a project using the pyramid_starter template. The paster create command creates project from a template. To use a different template, such as pyramid_routesalchemy, you’d just change the last argument. For example:

$ bin/paster create -t pyramid_routesalchemy

paster create will ask you a single question: the name of the project. You should use a string without spaces and with only letters in it. Here’s sample output from a run of paster create for a project we name MyProject:

$ bin/paster create -t pyramid_starter
Selected and implied templates:
  pyramid#pyramid_starter  pyramid starter project

Enter project name: MyProject
Variables:
  egg:      MyProject
  package:  myproject
  project:  MyProject
Creating template pyramid
Creating directory ./MyProject
# ... more output ...
Running /Users/chrism/projects/pyramid/bin/python setup.py egg_info

Note

You can skip the interrogative question about a project name during paster create by adding the project name to the command line, e.g. paster create -t pyramid_starter MyProject.

Note

You may encounter an error when using paster create if a dependent Python package is not installed. This will result in a traceback ending in pkg_resources.DistributionNotFound: <package name>. Simply run bin/easy_install, with the missing package name from the error message to work around this issue.

As a result of invoking the paster create command, a project is created in a directory named MyProject. That directory is a project directory. The setup.py file in that directory can be used to distribute your application, or install your application for deployment or development.

A PasteDeploy .ini file named development.ini will be created in the project directory. You will use this .ini file to configure a server, to run your application, and to and debug your application. It sports configuration that enables an interactive debugger and settings optimized for development.

Another PasteDeploy .ini file named production.ini will also be created in the project directory. It sports configuration that disables any interactive debugger (to prevent inappropriate access and disclosure), and turns off a number of debugging settings. You can use this file to put your application into production, and you can modify it to do things like send email when an exception occurs.

The MyProject project directory contains an additional subdirectory named myproject (note the case difference) representing a Python package which holds very simple Pyramid sample code. This is where you’ll edit your application’s Python code and templates.

Installing your Newly Created Project for Development

To install a newly created project for development, you should cd to the newly created project directory and use the Python interpreter from the virtualenv you created during Installing Pyramid to invoke the command python setup.py develop

The file named setup.py will be in the root of the paster-generated project directory. The python you’re invoking should be the one that lives in the bin directory of your virtual Python environment. Your terminal’s current working directory must the the newly created project directory. For example:

$ ../bin/python setup.py develop

Elided output from a run of this command is shown below:

$ ../bin/python setup.py develop
...
Finished processing dependencies for MyProject==0.0

This will install a distribution representing your project into the interpreter’s library set so it can be found by import statements and by PasteDeploy commands such as paster serve and paster pshell.

Running The Tests For Your Application

To run unit tests for your application, you should invoke them using the Python interpreter from the virtualenv you created during Installing Pyramid (the python command that lives in the bin directory of your virtualenv):

$ ../bin/python setup.py test -q

Here’s sample output from a test run:

$ python setup.py test -q
running test
running egg_info
writing requirements to MyProject.egg-info/requires.txt
writing MyProject.egg-info/PKG-INFO
writing top-level names to MyProject.egg-info/top_level.txt
writing dependency_links to MyProject.egg-info/dependency_links.txt
writing entry points to MyProject.egg-info/entry_points.txt
reading manifest file 'MyProject.egg-info/SOURCES.txt'
writing manifest file 'MyProject.egg-info/SOURCES.txt'
running build_ext
..
----------------------------------------------------------------------
Ran 1 test in 0.108s

OK

Note

The -q option is passed to the setup.py test command to limit the output to a stream of dots. If you don’t pass -q, you’ll see more verbose test result output (which normally isn’t very useful).

The tests themselves are found in the tests.py module in your paster create -generated project. Within a project generated by the pyramid_starter template, a single sample test exists.

The Interactive Shell

Once you’ve installed your program for development using setup.py develop, you can use an interactive Python shell to examine your Pyramid project’s resource and view objects from a Python prompt. To do so, use your virtualenv’s paster pshell command.

The first argument to pshell is the path to your application’s .ini file. The second is the app section name inside the .ini file which points to your application as opposed to any other section within the .ini file. For example, if your application .ini file might have a [app:MyProject] section that looks like so:

1
2
3
4
5
6
7

[app:MyProject]
use = egg:MyProject
reload_templates = true
debug_authorization = false
debug_notfound = false
debug_templates = true
default_locale_name = en

If so, you can use the following command to invoke a debug shell using the name MyProject as a section name:

[chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject
Python 2.4.5 (#1, Aug 29 2008, 12:27:37)
[GCC 4.0.1 (Apple Inc. build 5465)] on darwin
Type "help" for more information. "root" is the Pyramid app root object,
"registry" is the Pyramid registry object.
>>> root
<myproject.resources.MyResource object at 0x445270>
>>> registry
<Registry myproject>
>>> registry.settings['debug_notfound']
False
>>> from myproject.views import my_view
>>> from pyramid.request import Request
>>> r = Request.blank('/')
>>> my_view(r)
{'project': 'myproject'}

Two names are made available to the pshell user as globals: root and registry. root is the the object returned by the default root factory in your application. registry is the application registry object associated with your project’s application (often accessed within view code as request.registry).

If you have IPython [http://en.wikipedia.org/wiki/IPython] installed in the interpreter you use to invoke the paster command, the pshell command will use an IPython interactive shell instead of a standard Python interpreter shell. If you don’t want this to happen, even if you have IPython installed, you can pass the --disable-ipython flag to the pshell command to use a standard Python interpreter shell unconditionally.

[chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \
                             development.ini MyProject

You should always use a section name argument that refers to the actual app section within the Paste configuration file that points at your Pyramid application without any middleware wrapping. In particular, a section name is inappropriate as the second argument to pshell if the configuration section it names is a pipeline rather than an app. For example, if you have the following .ini file content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[app:MyProject]
use = egg:MyProject
reload_templates = true
debug_authorization = false
debug_notfound = false
debug_templates = true
default_locale_name = en

[pipeline:main]
pipeline =
    egg:WebError#evalerror
    MyProject

Use MyProject instead of main as the section name argument to pshell against the above .ini file (e.g. paster pshell development.ini MyProject). If you use main instead, an error will occur. Use the most specific reference to your application within the .ini file possible as the section name argument.

Press Ctrl-D to exit the interactive shell (or Ctrl-Z on Windows).

Running The Project Application

Once a project is installed for development, you can run the application it represents using the paster serve command against the generated configuration file. In our case, this file is named development.ini:

$ ../bin/paster serve development.ini

Here’s sample output from a run of paster serve:

$ ../bin/paster serve development.ini
Starting server in PID 16601.
serving on 0.0.0.0:6543 view at http://127.0.0.1:6543

By default, Pyramid applications generated from a paster template will listen on TCP port 6543. You can shut down a server started this way by pressing Ctrl-C.

During development, it’s often useful to run paster serve using its --reload option. When --reload is passed to paster serve, changes to any Python module your project uses will cause the server to restart. This typically makes development easier, as changes to Python code made within a Pyramid application is not put into effect until the server restarts.

For example:

$ ../bin/paster serve development.ini --reload
Starting subprocess with file monitor
Starting server in PID 16601.
serving on 0.0.0.0:6543 view at http://127.0.0.1:6543

For more detailed information about the startup process, see Startup. For more information about environment variables and configuration file settings that influence startup and runtime behavior, see Environment Variables and .ini File Settings.

Viewing the Application

Once your application is running via paster serve, you may visit http://localhost:6543/ in your browser. You will see something in your browser like what is displayed in the following image:

This is the page shown by default when you visit an unmodified paster create -generated pyramid_starter application in a browser.

Using an Alternate WSGI Server

The code generated by Pyramid paster templates assumes that you will be using the paster serve command to start your application while you do development. However, paster serve is by no means the only way to start up and serve a Pyramid application. As we saw in Creating Your First Pyramid Application, paster serve needn’t be invoked at all to run a Pyramid application. The use of paster serve to run a Pyramid application is purely conventional based on the output of its paster templates.

Any WSGI server is capable of running a Pyramid application. Some WSGI servers don’t require the PasteDeploy framework’s paster serve command to do server process management at all. Each WSGI server has its own documentation about how it creates a process to run an application, and there are many of them, so we cannot provide the details for each here. But the concepts are largely the same, whatever server you happen to use.

One popular production alternative to a paster-invoked server is mod_wsgi. You can also use mod_wsgi to serve your Pyramid application using the Apache web server rather than any “pure-Python” server that is started as a result of paster serve. See Running a Pyramid Application under mod_wsgi for details. However, it is usually easier to develop an application using a paster serve -invoked webserver, as exception and debugging output will be sent to the console.

The Project Structure

The pyramid_starter template generated a project (named MyProject), which contains a Python package. The package is also named myproject, but it’s lowercased; the paster template generates a project which contains a package that shares its name except for case.

All Pyramid paster -generated projects share a similar structure. The MyProject project we’ve generated has the following directory structure:

MyProject/
|-- CHANGES.txt
|-- development.ini
|-- MANIFEST.in
|-- myproject
|   |-- __init__.py
|   |-- resources.py
|   |-- static
|   |   |-- favicon.ico
|   |   |-- logo.png
|   |   `-- pylons.css
|   |-- templates
|   |   `-- mytemplate.pt
|   |-- tests.py
|   `-- views.py
|-- production.ini
|-- README.txt
|-- setup.cfg
`-- setup.py

The MyProject Project

The MyProject project directory is the distribution and deployment wrapper for your application. It contains both the myproject package representing your application as well as files used to describe, run, and test your application.

CHANGES.txt describes the changes you’ve made to the application. It is conventionally written in ReStructuredText format.

README.txt describes the application in general. It is conventionally written in ReStructuredText format.

development.ini is a PasteDeploy configuration file that can be used to execute your application during development.

production.ini is a PasteDeploy configuration file that can be used to execute your application in a production configuration.

setup.cfg is a setuptools configuration file used by setup.py.

MANIFEST.in is a distutils “manifest” file, naming which files should be included in a source distribution of the package when python setup.py sdist is run.

setup.py is the file you’ll use to test and distribute your application. It is a standard setuptools setup.py file.

development.ini

The development.ini file is a PasteDeploy configuration file. Its purpose is to specify an application to run when you invoke paster serve, as well as the deployment settings provided to that application.

The generated development.ini file looks like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

[app:MyProject]
use = egg:MyProject
reload_templates = true
debug_authorization = false
debug_notfound = false
debug_routematch = false
debug_templates = true
default_locale_name = en

[pipeline:main]
pipeline =
    egg:WebError#evalerror
    MyProject

[server:main]
use = egg:Paste#http
host = 0.0.0.0
port = 6543

# Begin logging configuration

[loggers]
keys = root, myproject

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[logger_myproject]
level = DEBUG
handlers =
qualname = myproject

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s

# End logging configuration

This file contains several “sections” including [app:MyProject], [pipeline:main], and [server:main].

The [app:MyProject] section represents configuration for your application. This section name represents the MyProject application (and it’s an app -lication, thus app:MyProject)

The use setting is required in the [app:MyProject] section. The use setting points at a setuptools entry point named MyProject (the egg: prefix in egg:MyProject indicates that this is an entry point URI specifier, where the “scheme” is “egg”). egg:MyProject is actually shorthand for a longer spelling: egg:MyProject#main. The #main part is omitted for brevity, as it is the default.

setuptools Entry Points and PasteDeploy .ini Files

This part of configuration can be confusing so let’s try to clear things up a bit. Take a look at the generated setup.py file for this project. Note that the entry_point line in setup.py points at a string which looks a lot like an .ini file. This string representation of an .ini file has a section named [paste.app_factory]. Within this section, there is a key named main (the entry point name) which has a value myproject:main. The key main is what our egg:MyProject#main value of the use section in our config file is pointing at (although it is actually shortened to egg:MyProject there). The value represents a dotted Python name path, which refers to a callable in our myproject package’s __init__.py module. In English, this entry point can thus be referred to as a “Paste application factory in the MyProject project which has the entry point named main where the entry point refers to a main function in the mypackage module”. If indeed if you open up the __init__.py module generated within the myproject package, you’ll see a main function. This is the function called by PasteDeploy when the paster serve command is invoked against our application. It accepts a global configuration object and returns an instance of our application.

The use setting is the only setting required in the [app:MyProject] section unless you’ve changed the callable referred to by the egg:MyProject entry point to accept more arguments: other settings you add to this section are passed as keywords arguments to the callable represented by this entry point (main in our __init__.py module). You can provide startup-time configuration parameters to your application by adding more settings to this section.

The reload_templates setting in the [app:MyProject] section is a Pyramid -specific setting which is passed into the framework. If it exists, and its value is true, Chameleon and Mako template changes will not require an application restart to be detected. See Automatically Reloading Templates for more information.

Warning

The reload_templates option should be turned off for production applications, as template rendering is slowed when it is turned on.

The debug_templates setting in the [app:MyProject] section is a Pyramid -specific setting which is passed into the framework. If it exists, and its value is true, Chameleon template exceptions will contained more detailed and helpful information about the error than when this value is false. See Nicer Exceptions in Chameleon Templates for more information.

Warning

The debug_templates option should be turned off for production applications, as template rendering is slowed when it is turned on.

Various other settings may exist in this section having to do with debugging or influencing runtime behavior of a Pyramid application. See Environment Variables and .ini File Settings for more information about these settings.

[pipeline:main], has the name main signifying that this is the default ‘application’ (although it’s actually a pipeline of middleware and an application) run by paster serve when it is invoked against this configuration file. The name main is a convention used by PasteDeploy signifying that it is the default application.

The [server:main] section of the configuration file configures a WSGI server which listens on TCP port 6543. It is configured to listen on all interfaces (0.0.0.0). The Paste#http server will create a new thread for each request.

Note

In general, Pyramid applications generated from paster templates should be threading-aware. It is not required that a Pyramid application be nonblocking as all application code will run in its own thread, provided by the server you’re using.

See the PasteDeploy documentation for more information about other types of things you can put into this .ini file, such as other applications, middleware and alternate WSGI server implementations.

Note

You can add a [DEFAULT] section to your development.ini file. Such a section should consists of global parameters that are shared by all the applications, servers and middleware defined within the configuration file. The values in a [DEFAULT] section will be passed to your application’s main function as global_values.

production.ini

The development.ini file is a PasteDeploy configuration file with a purpose much like that of development.ini. However, it disables the WebError interactive debugger, replacing it with a logger which outputs exception messages to stderr by default. It also turns off template development options such that templates are not automatically reloaded when changed, and turns off all debugging options. You can use this file instead of development.ini when you put your application into production.

setup.py

The setup.py file is a setuptools setup file. It is meant to be run directly from the command line to perform a variety of functions, such as testing your application, packaging, and distributing your application.

Note

setup.py is the defacto standard which Python developers use to distribute their reusable code. You can read more about setup.py files and their usage in the Setuptools documentation [http://peak.telecommunity.com/DevCenter/setuptools].

Our generated setup.py looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import os

from setuptools import setup, find_packages

here = os.path.abspath(os.path.dirname(__file__))
README = open(os.path.join(here, 'README.txt')).read()
CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()

requires = ['pyramid', 'WebError']

setup(name='MyProject',
      version='0.0',
      description='MyProject',
      long_description=README + '\n\n' +  CHANGES,
      classifiers=[
        "Programming Language :: Python",
        "Framework :: Pylons",
        "Topic :: Internet :: WWW/HTTP",
        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
        ],
      author='',
      author_email='',
      url='',
      keywords='web pyramid pylons',
      packages=find_packages(),
      include_package_data=True,
      zip_safe=False,
      install_requires=requires,
      tests_require=requires,
      test_suite="myproject",
      entry_points = """\
      [paste.app_factory]
      main = myproject:main
      """,
      paster_plugins=['pyramid'],
      )

The setup.py file calls the setuptools setup function, which does various things depending on the arguments passed to setup.py on the command line.

Within the arguments to this function call, information about your application is kept. While it’s beyond the scope of this documentation to explain everything about setuptools setup files, we’ll provide a whirlwind tour of what exists in this file in this section.

Your application’s name can be any string; it is specified in the name field. The version number is specified in the version value. A short description is provided in the description field. The long_description is conventionally the content of the README and CHANGES file appended together. The classifiers field is a list of Trove [http://pypi.python.org/pypi?%3Aaction=list_classifiers] classifiers describing your application. author and author_email are text fields which probably don’t need any description. url is a field that should point at your application project’s URL (if any). packages=find_packages() causes all packages within the project to be found when packaging the application. include_package_data will include non-Python files when the application is packaged if those files are checked into version control. zip_safe indicates that this package is not safe to use as a zipped egg; instead it will always unpack as a directory, which is more convenient. install_requires and tests_require indicate that this package depends on the pyramid package. test_suite points at the package for our application, which means all tests found in the package will be run when setup.py test is invoked. We examined entry_points in our discussion of the development.ini file; this file defines the main entry point that represents our project’s application.

Usually you only need to think about the contents of the setup.py file when distributing your application to other people, or when versioning your application for your own use. For fun, you can try this command now:

$ python setup.py sdist

This will create a tarball of your application in a dist subdirectory named MyProject-0.1.tar.gz. You can send this tarball to other people who want to use your application.

Warning

Without the presence of a MANIFEST.in file or without checking your source code into a version control repository, setup.py sdist places only Python source files (files ending with a .py extension) into tarballs generated by python setup.py sdist. This means, for example, if your project was not checked into a setuptools-compatible source control system, and your project directory didn’t contain a MANIFEST.in file that told the sdist machinery to include *.pt files, the myproject/templates/mytemplate.pt file would not be included in the generated tarball.

Projects generated by Pyramid paster templates include a default MANIFEST.in file. The MANIFEST.in file contains declarations which tell it to include files like *.pt, *.css and *.js in the generated tarball. If you include files with extensions other than the files named in the project’s MANIFEST.in and you don’t make use of a setuptools-compatible version control system, you’ll need to edit the MANIFEST.in file and include the statements necessary to include your new files. See http://docs.python.org/distutils/sourcedist.html#principle for more information about how to do this.

You can also delete MANIFEST.in from your project and rely on a setuptools feature which simply causes all files checked into a version control system to be put into the generated tarball. To allow this to happen, check all the files that you’d like to be distributed along with your application’s Python files into Subversion. After you do this, when you rerun setup.py sdist, all files checked into the version control system will be included in the tarball. If you don’t use Subversion, and instead use a different version control system, you may need to install a setuptools add-on such as setuptools-git or setuptools-hg for this behavior to work properly.

setup.cfg

The setup.cfg file is a setuptools configuration file. It contains various settings related to testing and internationalization:

Our generated setup.cfg looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

[nosetests]
match = ^test
nocapture = 1
cover-package = myproject
with-coverage = 1
cover-erase = 1

[compile_catalog]
directory = myproject/locale
domain = MyProject
statistics = true

[extract_messages]
add_comments = TRANSLATORS:
output_file = myproject/locale/MyProject.pot
width = 80

[init_catalog]
domain = MyProject
input_file = myproject/locale/MyProject.pot
output_dir = myproject/locale

[update_catalog]
domain = MyProject
input_file = myproject/locale/MyProject.pot
output_dir = myproject/locale
previous = true

The values in the default setup file allow various commonly-used internationalization commands and testing commands to work more smoothly.

The myproject Package

The myproject package lives inside the MyProject project. It contains:

An __init__.py file signifies that this is a Python package. It also contains code that helps users run the application, including a main function which is used as a Paste entry point.

A resources.py module, which contains resource code.

A templates directory, which contains Chameleon (or other types of) templates.

A tests.py module, which contains unit test code for the application.

A views.py module, which contains view code for the application.

These are purely conventions established by the paster template: Pyramid doesn’t insist that you name things in any particular way. However, it’s generally a good idea to follow Pyramid standards for naming, so that other Pyramid developers can get up to speed quickly on your code when you need help.

__init__.py

We need a small Python module that configures our application and which advertises an entry point for use by our PasteDeploy .ini file. This is the file named __init__.py. The presence of an __init__.py also informs Python that the directory which contains it is a package.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from pyramid.config import Configurator
from myproject.resources import Root

def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    config = Configurator(root_factory=Root, settings=settings)
    config.add_view('myproject.views.my_view',
                    context='myproject.resources.Root',
                    renderer='myproject:templates/mytemplate.pt')
    config.add_static_view('static', 'myproject:static')
    return config.make_wsgi_app()

Line 1 imports the Configurator class from pyramid.config that we use later.

Line 2 imports the Root class from myproject.resources that we use later.

Lines 4-12 define a function that returns a Pyramid WSGI application. This function is meant to be called by the PasteDeploy framework as a result of running paster serve.

Within this function, application configuration is performed.

Lines 8-10 register a “default view” (a view that has no name attribute). It is registered so that it will be found when the context of the request is an instance of the myproject.resources.Root class. The first argument to add_view points at a Python function that does all the work for this view, also known as a view callable, via a dotted Python name. The view declaration also names a renderer, which in this case is a template that will be used to render the result of the view callable. This particular view declaration points at myproject:templates/mytemplate.pt, which is a asset specification that specifies the mytemplate.pt file within the templates directory of the myproject package. The template file it actually points to is a Chameleon ZPT template file.

Line 11 registers a static view, which will serve up the files from the mypackage:static asset specification (the static directory of the mypackage package).

Line 12 returns a WSGI application to the caller of the function (Paste).

views.py

Much of the heavy lifting in a Pyramid application is done by view callables. A view callable is the main tool of a Pyramid web application developer; it is a bit of code which accepts a request and which returns a response.

1
2

def my_view(request):
    return {'project':'MyProject'}

This bit of code was registered as the view callable within __init__.py (via add_view). add_view said that the default URL for instances that are of the class myproject.resources.Root should run this myproject.views.my_view() function.

This view callable function is handed a single piece of information: the request. The request is an instance of the WebOb Request class representing the browser’s request to our server.

This view returns a dictionary. When this view is invoked, a renderer converts the dictionary returned by the view into HTML, and returns the result as the response. This view is configured to invoke a renderer which uses a Chameleon ZPT template (mypackage:templates/my_template.pt, as specified in the __init__.py file call to add_view).

See Writing View Callables Which Use a Renderer for more information about how views, renderers, and templates relate and cooperate.

Note

Because our development.ini has a reload_templates = true directive indicating that templates should be reloaded when they change, you won’t need to restart the application server to see changes you make to templates. During development, this is handy. If this directive had been false (or if the directive did not exist), you would need to restart the application server for each template change. For production applications, you should set your project’s reload_templates to false to increase the speed at which templates may be rendered.

resources.py

The resources.py module provides the resource data and behavior for our application. Resources are objects which exist to provide site structure in applications which use traversal to map URLs to code. We write a class named Root that provides the behavior for the root resource.

1
2
3

class Root(object):
    def __init__(self, request):
        self.request = request

Lines 1-3 define the Root class. The Root class is a “root resource factory” function that will be called by the Pyramid Router for each request when it wants to find the root of the resource tree.

In a “real” application, the Root object would likely not be such a simple object. Instead, it might be an object that could access some persistent data store, such as a database. Pyramid doesn’t make any assumption about which sort of data storage you’ll want to use, so the sample application uses an instance of myproject.resources.Root to represent the root.

static

This directory contains static assets which support the mytemplate.pt template. It includes CSS and images.

templates/mytemplate.pt

The single Chameleon template exists in the project. Its contents are too long to show here, but it displays a default page when rendered. It is referenced by the call to add_view as the renderer attribute in the __init__ file. See Writing View Callables Which Use a Renderer for more information about renderers.

Templates are accessed and used by view configurations and sometimes by view functions themselves. See Using Templates Directly and Templates Used as Renderers via Configuration.

tests.py

The tests.py module includes unit tests for your application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

import unittest

from pyramid import testing

class ViewTests(unittest.TestCase):
    def setUp(self):
        self.config = testing.setUp()

    def tearDown(self):
        testing.tearDown()

    def test_my_view(self):
        from myproject.views import my_view
        request = testing.DummyRequest()
        info = my_view(request)
        self.assertEqual(info['project'], 'MyProject')

This sample tests.py file has a single unit test defined within it. This test is executed when you run python setup.py test. You may add more tests here as you build your application. You are not required to write tests to use Pyramid, this file is simply provided as convenience and example.

See Unit, Integration, and Functional Testing for more information about writing Pyramid unit tests.

Modifying Package Structure

It is best practice for your application’s code layout to not stray too much from accepted Pyramid paster template defaults. If you refrain from changing things very much, other Pyramid coders will be able to more quickly understand your application. However, the code layout choices made for you by a paster template are in no way magical or required. Despite the choices made for you by any paster template, you can decide to lay your code out any way you see fit.

For example, the configuration method named add_view() requires you to pass a dotted Python name or a direct object reference as the class or function to be used as a view. By default, the pyramid_starter paster template would have you add view functions to the views.py module in your package. However, you might be more comfortable creating a views directory, and adding a single file for each view.

If your project package name was myproject and you wanted to arrange all your views in a Python subpackage within the myproject package named views instead of within a single views.py file, you might:

Create a views directory inside your mypackage package directory (the same directory which holds views.py).

Move the existing views.py file to a file inside the new views directory named, say, blog.py.

Create a file within the new views directory named __init__.py (it can be empty, this just tells Python that the views directory is a package.

Then change the __init__.py of your myproject project (not the __init__.py you just created in the views directory, the one in its parent directory). For example, from something like:

1
2

config.add_view('myproject.views.my_view',
                renderer='myproject:templates/mytemplate.pt')

To this:

1
2

config.add_view('myproject.views.blog.my_view',
                renderer='myproject:templates/mytemplate.pt')

You can then continue to add files to the views directory, and refer to view classes or functions within those files via the dotted name passed as the first argument to add_view. For example, if you added a file named anothermodule.py to the views subdirectory, and added a view callable named my_view to it:

1
2

config.add_view('myproject.views.anothermodule.my_view',
                renderer='myproject:templates/anothertemplate.pt')

This pattern can be used to rearrage code referred to by any Pyramid API argument which accepts a dotted Python name or direct object reference.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Startup

When you cause a Pyramid application to start up in a console window, you’ll see something much like this show up on the console:

$ paster serve myproject/MyProject.ini
Starting server in PID 16601.
serving on 0.0.0.0:6543 view at http://127.0.0.1:6543

This chapter explains what happens between the time you press the “Return” key on your keyboard after typing paster serve myproject/MyProject.ini and the time the line serving on 0.0.0.0:6543 ... is output to your console.

The Startup Process

The easiest and best-documented way to start and serve a Pyramid application is to use the paster serve command against a PasteDeploy .ini file. This uses the .ini file to infer settings and starts a server listening on a port. For the purposes of this discussion, we’ll assume that you are using this command to run your Pyramid application.

Here’s a high-level time-ordered overview of what happens when you press return after running paster serve development.ini.

The PasteDeploy paster command is invoked under your shell with the arguments serve and development.ini. As a result, the PasteDeploy framework recognizes that it is meant to begin to run and serve an application using the information contained within the development.ini file.

The PasteDeploy framework finds a section named either [app:main], [pipeline:main], or [composite:main] in the .ini file. This section represents the configuration of a WSGI application that will be served. If you’re using a simple application (e.g. [app:main]), the application entry point or dotted Python name will be named on the use= line within the section’s configuration. If, instead of a simple application, you’re using a WSGI pipeline (e.g. a [pipeline:main] section), the application named on the “last” element will refer to your Pyramid application. If instead of a simple application or a pipeline, you’re using a Paste “composite” (e.g. [composite:main]), refer to the documentation for that particular composite to understand how to make it refer to your Pyramid application.

The application’s constructor (named by the entry point reference or dotted Python name on the use= line of the section representing your Pyramid application) is passed the key/value parameters mentioned within the section in which it’s defined. The constructor is meant to return a router instance, which is a WSGI application.

For Pyramid applications, the constructor will be a function named main in the __init__.py file within the package in which your application lives. If this function succeeds, it will return a Pyramid router instance. Here’s the contents of an example __init__.py module:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from pyramid.config import Configurator
from myproject.resources import Root

def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    config = Configurator(root_factory=Root, settings=settings)
    config.add_view('myproject.views.my_view',
                    context='myproject.resources.Root',
                    renderer='myproject:templates/mytemplate.pt')
    config.add_static_view('static', 'myproject:static')
    return config.make_wsgi_app()

Note that the constructor function accepts a global_config argument, which is a dictionary of key/value pairs mentioned in the [DEFAULT] section of an .ini file. It also accepts a **settings argument, which collects another set of arbitrary key/value pairs. The arbitrary key/value pairs received by this function in **settings will be composed of all the key/value pairs that are present in the [app:MyProject] section (except for the use= setting) when this function is called by the PasteDeploy framework when you run paster serve.

Our generated development.ini file looks like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

[app:MyProject]
use = egg:MyProject
reload_templates = true
debug_authorization = false
debug_notfound = false
debug_routematch = false
debug_templates = true
default_locale_name = en

[pipeline:main]
pipeline =
    egg:WebError#evalerror
    MyProject

[server:main]
use = egg:Paste#http
host = 0.0.0.0
port = 6543

# Begin logging configuration

[loggers]
keys = root, myproject

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[logger_myproject]
level = DEBUG
handlers =
qualname = myproject

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s

# End logging configuration

In this case, the myproject.__init__:main function referred to by the entry point URI egg:MyProject (see development.ini for more information about entry point URIs, and how they relate to callables), will receive the key/value pairs {'reload_templates':'true', 'debug_authorization':'false', 'debug_notfound':'false', 'debug_routematch':'false', 'debug_templates':'true', 'default_locale_name':'en'}.

The main function first constructs a Configurator instance, passing a root resource factory (constructor) to it as its root_factory argument, and settings dictionary captured via the **settings kwarg as its settings argument.

The root resource factory is invoked on every request to retrieve the application’s root resource. It is not called during startup, only when a request is handled.

The settings dictionary contains all the options in the [app:MyProject] section of our .ini file except the use option (which is internal to Paste) such as reload_templates, debug_authorization, etc.

The main function then calls various methods on the an instance of the class Configurator method. The intent of calling these methods is to populate an application registry, which represents the Pyramid configuration related to the application.

The make_wsgi_app() method is called. The result is a router instance. The router is associated with the application registry implied by the configurator previously populated by other methods run against the Configurator. The router is a WSGI application.

A ApplicationCreated event is emitted (see Using Events for more information about events).

Assuming there were no errors, the main function in myproject returns the router instance created by make_wsgi_app back to PasteDeploy. As far as PasteDeploy is concerned, it is “just another WSGI application”.

PasteDeploy starts the WSGI server defined within the [server:main] section. In our case, this is the Paste#http server (use = egg:Paste#http), and it will listen on all interfaces (host = 0.0.0.0), on port number 6543 (port = 6543). The server code itself is what prints serving on 0.0.0.0:6543 view at http://127.0.0.1:6543. The server serves the application, and the application is running, waiting to receive requests.

Deployment Settings

Note that an augmented version of the values passed as **settings to the Configurator constructor will be available in Pyramid view callable code as request.registry.settings. You can create objects you wish to access later from view code, and put them into the dictionary you pass to the configurator as settings. They will then be present in the request.registry.settings dictionary at application runtime.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

URL Dispatch

URL dispatch provides a simple way to map URLs to view code using a simple pattern matching language. An ordered set of patterns is checked one-by-one. If one of the patterns matches the path information associated with a request, a particular view callable is invoked.

URL dispatch is one of two ways to perform resource location in Pyramid; the other way is using traversal. If no route is matched using URL dispatch, Pyramid falls back to traversal to handle the request.

It is the responsibility of the resource location subsystem (i.e., URL dispatch or traversal) to find the resource object that is the context of the request. Once the context is determined, view lookup is then responsible for finding and invoking a view callable. A view callable is a specific bit of code, defined in your application, that receives the request and returns a response object.

Where appropriate, we will describe how view lookup interacts with resource location. The View Configuration chapter describes the details of view lookup.

High-Level Operational Overview

If route configuration is present in an application, the Pyramid Router checks every incoming request against an ordered set of URL matching patterns present in a route map.

If any route pattern matches the information in the request, Pyramid will invoke view lookup using a context resource generated by the route match.

However, if no route pattern matches the information in the request provided to Pyramid, it will fail over to using traversal to perform resource location and view lookup.

Technically, URL dispatch is a resource location mechanism (it finds a context object). But ironically, using URL dispatch (instead of traversal) allows you to avoid thinking about your application in terms of “resources” entirely, because it allows you to directly map a view callable to a route.

Route Configuration

Route configuration is the act of adding a new route to an application. A route has a pattern, representing a pattern meant to match against the PATH_INFO portion of a URL (the portion following the scheme and port, e.g. /foo/bar in the URL http://localhost:8080/foo/bar), and a route name, which is used by developers within a Pyramid application to uniquely identify a particular route when generating a URL. It also optionally has a factory, a set of route predicate parameters, and a set of view parameters.

Configuring a Route via The add_route Configurator Method

The pyramid.config.Configurator.add_route() method adds a single route configuration to the application registry. Here’s an example:

# "config" below is presumed to be an instance of the
# pyramid.config.Configurator class; "myview" is assumed
# to be a "view callable" function
from views import myview
config.add_route('myroute', '/prefix/{one}/{two}', view=myview)

Changed in version 1.0a4: Prior to 1.0a4, routes allow for a marker starting with a :, for example /prefix/:one/:two. This style is now deprecated in favor of {} usage which allows for additional functionality.

Route Configuration That Names a View Callable

When a route configuration declaration names a view attribute, the value of the attribute will reference a view callable. This view callable will be invoked when the route matches. A view callable, as described in Views, is developer-supplied code that “does stuff” as the result of a request.

Here’s an example route configuration that references a view callable:

1
2
3
4
5

# "config" below is presumed to be an instance of the
# pyramid.config.Configurator class; "myview" is assumed
# to be a "view callable" function
from myproject.views import myview
config.add_route('myroute', '/prefix/{one}/{two}', view=myview)

You can also pass a dotted Python name as the view argument rather than an actual callable:

1
2
3
4
5

# "config" below is presumed to be an instance of the
# pyramid.config.Configurator class; "myview" is assumed
# to be a "view callable" function
config.add_route('myroute', '/prefix/{one}/{two}',
                 view='myproject.views.myview')

When a route configuration names a view attribute, the view callable named as that view attribute will always be found and invoked when the associated route pattern matches during a request.

Route Pattern Syntax

The syntax of the pattern matching language used by Pyramid URL dispatch in the pattern argument is straightforward; it is close to that of the Routes system used by Pylons.

The pattern used in route configuration may start with a slash character. If the pattern does not start with a slash character, an implicit slash will be prepended to it at matching time. For example, the following patterns are equivalent:

{foo}/bar/baz

and:

/{foo}/bar/baz

A pattern segment (an individual item between / characters in the pattern) may either be a literal string (e.g. foo) or it may be a replacement marker (e.g. {foo}) or a certain combination of both. A replacement marker does not need to be preceded by a / character.

A replacement marker is in the format {name}, where this means “accept any characters up to the next slash character and use this as the name matchdict value.” A matchdict is the dictionary representing the dynamic parts extracted from a URL based on the routing pattern. It is available as request.matchdict. For example, the following pattern defines one literal segment (foo) and two replacement markers (baz, and bar):

foo/{baz}/{bar}

The above pattern will match these URLs, generating the following matchdicts:

foo/1/2        -> {'baz':u'1', 'bar':u'2'}
foo/abc/def    -> {'baz':u'abc', 'bar':u'def'}

It will not match the following patterns however:

foo/1/2/        -> No match (trailing slash)
bar/abc/def     -> First segment literal mismatch

The match for a segment replacement marker in a segment will be done only up to the first non-alphanumeric character in the segment in the pattern. So, for instance, if this route pattern was used:

foo/{name}.html

The literal path /foo/biz.html will match the above route pattern, and the match result will be {'name':u'biz'}. However, the literal path /foo/biz will not match, because it does not contain a literal .html at the end of the segment represented by {name}.html (it only contains biz, not biz.html).

To capture both segments, two replacement markers can be used:

foo/{name}.{ext}

The literal path /foo/biz.html will match the above route pattern, and the match result will be {'name': 'biz', 'ext': 'html'}. This occurs because there is a literal part of . (period) between the two replacement markers {name} and {ext}.

Replacement markers can optionally specify a regular expression which will be used to decide whether a path segment should match the marker. To specify that a replacement marker should match only a specific set of characters as defined by a regular expression, you must use a slightly extended form of replacement marker syntax. Within braces, the replacement marker name must be followed by a colon, then directly thereafter, the regular expression. The default regular expression associated with a replacement marker [^/]+ matches one or more characters which are not a slash. For example, under the hood, the replacement marker {foo} can more verbosely be spelled as {foo:[^/]+}. You can change this to be an arbitrary regular expression to match an arbitrary sequence of characters, such as {foo:\d+} to match only digits.

It is possible to use two replacement markers without any literal characters between them, for instance /{foo}{bar}. However, this would be a nonsensical pattern without specifying a custom regular expression to restrict what each marker captures.

Segments must contain at least one character in order to match a segment replacement marker. For example, for the URL /abc/:

/abc/{foo} will not match.

/{foo}/ will match.

Note that values representing matched path segments will be url-unquoted and decoded from UTF-8 into Unicode within the matchdict. So for instance, the following pattern:

foo/{bar}

When matching the following URL:

foo/La%20Pe%C3%B1a

The matchdict will look like so (the value is URL-decoded / UTF-8 decoded):

{'bar':u'La Pe\xf1a'}

If the pattern has a * in it, the name which follows it is considered a “remainder match”. A remainder match must come at the end of the pattern. Unlike segment replacement markers, it does not need to be preceded by a slash. For example:

foo/{baz}/{bar}*fizzle

The above pattern will match these URLs, generating the following matchdicts:

foo/1/2/           ->
         {'baz':u'1', 'bar':u'2', 'fizzle':()}

foo/abc/def/a/b/c  ->
         {'baz':u'abc', 'bar':u'def', 'fizzle':(u'a', u'b', u'c')}

Note that when a *stararg remainder match is matched, the value put into the matchdict is turned into a tuple of path segments representing the remainder of the path. These path segments are url-unquoted and decoded from UTF-8 into Unicode. For example, for the following pattern:

foo/*fizzle

When matching the following path:

/foo/La%20Pe%C3%B1a/a/b/c

Will generate the following matchdict:

{'fizzle':(u'La Pe\xf1a', u'a', u'b', u'c')}

By default, the *stararg will parse the remainder sections into a tuple split by segment. Changing the regular expression used to match a marker can also capture the remainder of the URL, for example:

foo/{baz}/{bar}{fizzle:.*}

The above pattern will match these URLs, generating the following matchdicts:

foo/1/2/           -> {'baz':u'1', 'bar':u'2', 'fizzle':()}
foo/abc/def/a/b/c  -> {'baz':u'abc', 'bar':u'def', 'fizzle': u'a/b/c')}

This occurs because the default regular expression for a marker is [^/]+ which will match everything up to the first /, while {fizzle:.*} will result in a regular expression match of .* capturing the remainder into a single value.

Route Declaration Ordering

Route configuration declarations are evaluated in a specific order when a request enters the system. As a result, the order of route configuration declarations is very important.

The order that routes declarations are evaluated is the order in which they are added to the application at startup time. This is unlike traversal, which depends on emergent behavior which happens as a result of traversing a resource tree.

For routes added via the add_route method, the order that routes are evaluated is the order in which they are added to the configuration imperatively.

For example, route configuration statements with the following patterns might be added in the following order:

members/{def}
members/abc

In such a configuration, the members/abc pattern would never be matched. This is because the match ordering will always match members/{def} first; the route configuration with members/abc will never be evaluated.

Route Factories

A “route” configuration declaration can mention a “factory”. When that route matches a request, and a factory is attached to a route, the root factory passed at startup time to the Configurator is ignored; instead the factory associated with the route is used to generate a root object. This object will usually be used as the context resource of the view callable ultimately found via view lookup.

1
2

config.add_route('abc', '/abc', view='myproject.views.theview',
                 factory='myproject.resources.root_factory')

The factory can either be a Python object or a dotted Python name (a string) which points to such a Python object, as it is above.

In this way, each route can use a different factory, making it possible to supply a different context resource object to the view related to each particular route.

Supplying a different resource factory each route is useful when you’re trying to use a Pyramid authorization policy to provide declarative, “context sensitive” security checks; each resource can maintain a separate ACL, as documented in Using Pyramid Security With URL Dispatch. It is also useful when you wish to combine URL dispatch with traversal as documented within Combining Traversal and URL Dispatch.

Route Configuration Arguments

Route configuration add_route statements may specify a large number of arguments. They are documented as part of the API documentation at pyramid.config.Configurator.add_route().

Many of these arguments are route predicate arguments. A route predicate argument specifies that some aspect of the request must be true for the associated route to be considered a match during the route matching process. Examples of route predicate arguments are pattern, xhr, and request_method.

Other arguments are view configuration related arguments. These only have an effect when the route configuration names a view.

Other arguments are name and factory. These arguments represent neither predicates nor view configuration information.

Custom Route Predicates

Each of the predicate callables fed to the custom_predicates argument of add_route() must be a callable accepting two arguments. The first argument passed to a custom predicate is a dictionary conventionally named info. The second argument is the current request object.

The info dictionary has a number of contained values: match is a dictionary: it represents the arguments matched in the URL by the route. route is an object representing the route which was matched (see pyramid.interfaces.IRoute for the API of such a route object).

info['match'] is useful when predicates need access to the route match. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

def any_of(segment_name, *allowed):
    def predicate(info, request):
        if info['match'][segment_name] in allowed:
            return True
    return predicate

num_one_two_or_three = any_of('num', 'one', 'two', 'three')

config.add_route('num', '/{num}',
                 custom_predicates=(num_one_two_or_three,))

The above any_of function generates a predicate which ensures that the match value named segment_name is in the set of allowable values represented by allowed. We use this any_of function to generate a predicate function named num_one_two_or_three, which ensures that the num segment is one of the values one, two, or three , and use the result as a custom predicate by feeding it inside a tuple to the custom_predicates argument to add_route().

A custom route predicate may also modify the match dictionary. For instance, a predicate might do some type conversion of values:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

 def integers(*segment_names):
     def predicate(info, request):
         match = info['match']
         for segment_name in segment_names:
             try:
                 match[segment_name] = int(match[segment_name])
             except (TypeError, ValueError):
                 pass
         return True
     return predicate

 ymd_to_int = integers('year', 'month', 'day')

 config.add_route('num', '/{year}/{month}/{day}',
                  custom_predicates=(ymd_to_int,))

Note that a conversion predicate is still a predicate so it must return True or False; a predicate that does only conversion, such as the one we demonstrate above should unconditionally return True.

To avoid the try/except uncertainty, the route pattern can contain regular expressions specifying requirements for that marker. For instance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

 def integers(*segment_names):
     def predicate(info, request):
         match = info['match']
         for segment_name in segment_names:
             match[segment_name] = int(match[segment_name])
         return True
     return predicate

 ymd_to_int = integers('year', 'month', 'day')

 config.add_route('num', '/{year:\d+}/{month:\d+}/{day:\d+}',
                  custom_predicates=(ymd_to_int,))

Now the try/except is no longer needed because the route will not match at all unless these markers match \d+ which requires them to be valid digits for an int type conversion.

The match dictionary passed within info to each predicate attached to a route will be the same dictionary. Therefore, when registering a custom predicate which modifies the match dict, the code registering the predicate should usually arrange for the predicate to be the last custom predicate in the custom predicate list. Otherwise, custom predicates which fire subsequent to the predicate which performs the match modification will receive the modified match dictionary.

Warning

It is a poor idea to rely on ordering of custom predicates to build a conversion pipeline, where one predicate depends on the side effect of another. For instance, it’s a poor idea to register two custom predicates, one which handles conversion of a value to an int, the next which handles conversion of that integer to some custom object. Just do all that in a single custom predicate.

The route object in the info dict is an object that has two useful attributes: name and pattern. The name attribute is the route name. The pattern attribute is the route pattern. An example of using the route in a set of route predicates:

1
2
3
4
5
6
7
8

 def twenty_ten(info, request):
     if info['route'].name in ('ymd', 'ym', 'y'):
         return info['match']['year'] == '2010'

 config.add_route('y', '/{year}', custom_predicates=(twenty_ten,))
 config.add_route('ym', '/{year}/{month}', custom_predicates=(twenty_ten,))
 config.add_route('ymd', '/{year}/{month}/{day}',
                  custom_predicates=(twenty_ten,))

The above predicate, when added to a number of route configurations ensures that the year match argument is ‘2010’ if and only if the route name is ‘ymd’, ‘ym’, or ‘y’.

See also pyramid.interfaces.IRoute for more API documentation about route objects.

Route Matching

The main purpose of route configuration is to match (or not match) the PATH_INFO present in the WSGI environment provided during a request against a URL path pattern.

The way that Pyramid does this is very simple. When a request enters the system, for each route configuration declaration present in the system, Pyramid checks the PATH_INFO against the pattern declared.

If any route matches, the route matching process stops. The request is decorated with a special interface which describes it as a “route request”, the context resource is generated, and the context and the resulting request are handed off to view lookup. During view lookup, if any view argument was provided within the matched route configuration, the view callable it points to is called.

When a route configuration is declared, it may contain route predicate arguments. All route predicates associated with a route declaration must be True for the route configuration to be used for a given request.

If any predicate in the set of route predicate arguments provided to a route configuration returns False, that route is skipped and route matching continues through the ordered set of routes.

If no route matches after all route patterns are exhausted, Pyramid falls back to traversal to do resource location and view lookup.

The Matchdict

When the URL pattern associated with a particular route configuration is matched by a request, a dictionary named matchdict is added as an attribute of the request object. Thus, request.matchdict will contain the values that match replacement patterns in the pattern element. The keys in a matchdict will be strings. The values will be Unicode objects.

Note

If no route URL pattern matches, the matchdict object attached to the request will be None.

The Matched Route

When the URL pattern associated with a particular route configuration is matched by a request, an object named matched_route is added as an attribute of the request object. Thus, request.matched_route will be an object implementing the IRoute interface which matched the request. The most useful attribute of the route object is name, which is the name of the route that matched.

Note

If no route URL pattern matches, the matched_route object attached to the request will be None.

Routing Examples

Let’s check out some examples of how route configuration statements might be commonly declared, and what will happen if they are matched by the information present in a request.

Example 1

The simplest route declaration which configures a route match to directly result in a particular view callable being invoked:

1

 config.add_route('idea', 'site/{id}', view='mypackage.views.site_view')

When a route configuration with a view attribute is added to the system, and an incoming request matches the pattern of the route configuration, the view callable named as the view attribute of the route configuration will be invoked.

In the case of the above example, when the URL of a request matches /site/{id}, the view callable at the Python dotted path name mypackage.views.site_view will be called with the request. In other words, we’ve associated a view callable directly with a route pattern.

When the /site/{id} route pattern matches during a request, the site_view view callable is invoked with that request as its sole argument. When this route matches, a matchdict will be generated and attached to the request as request.matchdict. If the specific URL matched is /site/1, the matchdict will be a dictionary with a single key, id; the value will be the string '1', ex.: {'id':'1'}.

The mypackage.views module referred to above might look like so:

1
2
3
4

from pyramid.response import Response

def site_view(request):
    return Response(request.matchdict['id'])

The view has access to the matchdict directly via the request, and can access variables within it that match keys present as a result of the route pattern.

See Views, and View Configuration for more information about views.

Example 2

Below is an example of a more complicated set of route statements you might add to your application:

1
2
3

config.add_route('idea', 'ideas/{idea}', view='mypackage.views.idea_view')
config.add_route('user', 'users/{user}', view='mypackage.views.user_view')
config.add_route('tag', 'tags/{tags}', view='mypackage.views.tag_view')

The above configuration will allow Pyramid to service URLs in these forms:

/ideas/{idea}
/users/{user}
/tags/{tag}

When a URL matches the pattern /ideas/{idea}, the view callable available at the dotted Python pathname mypackage.views.idea_view will be called. For the specific URL /ideas/1, the matchdict generated and attached to the request will consist of {'idea':'1'}.

When a URL matches the pattern /users/{user}, the view callable available at the dotted Python pathname mypackage.views.user_view will be called. For the specific URL /users/1, the matchdict generated and attached to the request will consist of {'user':'1'}.

When a URL matches the pattern /tags/{tag}, the view callable available at the dotted Python pathname mypackage.views.tag_view will be called. For the specific URL /tags/1, the matchdict generated and attached to the request will consist of {'tag':'1'}.

In this example we’ve again associated each of our routes with a view callable directly. In all cases, the request, which will have a matchdict attribute detailing the information found in the URL by the process will be passed to the view callable.

Example 3

The context resource object passed in to a view found as the result of URL dispatch will, by default, be an instance of the object returned by the root factory configured at startup time (the root_factory argument to the Configurator used to configure the application).

You can override this behavior by passing in a factory argument to the add_route() method for a particular route. The factory should be a callable that accepts a request and returns an instance of a class that will be the context resource used by the view.

An example of using a route with a factory:

1
2
3

config.add_route('idea', 'ideas/{idea}',
                 view='myproject.views.idea_view',
                 factory='myproject.resources.Idea')

The above route will manufacture an Idea resource as a context, assuming that mypackage.resources.Idea resolves to a class that accepts a request in its __init__. For example:

1
2
3

class Idea(object):
    def __init__(self, request):
        pass

In a more complicated application, this root factory might be a class representing a SQLAlchemy model.

Example 4

It is possible to create a route declaration without a view attribute, but associate the route with a view callable using a view declaration.

1
2

config.add_route('idea', 'site/{id}')
config.add_view(route_name='idea', view='mypackage.views.site_view')

This set of configuration parameters creates a configuration completely equivalent to this example provided in Example 1:

1

config.add_route('idea', 'site/{id}', view='mypackage.views.site_view')

In fact, the spelling which names a view attribute is just syntactic sugar for the more verbose spelling which contains separate view and route registrations.

More uses for this style of associating views with routes are explored in Combining Traversal and URL Dispatch.

Matching the Root URL

It’s not entirely obvious how to use a route pattern to match the root URL (“/”). To do so, give the empty string as a pattern in a call to add_route():

1

config.add_route('root', '', view='mypackage.views.root_view')

Or provide the literal string / as the pattern:

1

config.add_route('root', '/', view='mypackage.views.root_view')

Generating Route URLs

Use the pyramid.url.route_url() function to generate URLs based on route patterns. For example, if you’ve configured a route with the name “foo” and the pattern “{a}/{b}/{c}”, you might do this.

1
2

from pyramid.url import route_url
url = route_url('foo', request, a='1', b='2', c='3')

This would return something like the string http://example.com/1/2/3 (at least if the current protocol and hostname implied http:/example.com). See the route_url() API documentation for more information.

Redirecting to Slash-Appended Routes

For behavior like Django’s APPEND_SLASH=True, use the append_slash_notfound_view() view as the Not Found view in your application. Defining this view as the Not Found view is a way to automatically redirect requests where the URL lacks a trailing slash, but requires one to match the proper route. When configured, along with at least one other route in your application, this view will be invoked if the value of PATH_INFO does not already end in a slash, and if the value of PATH_INFO plus a slash matches any route’s pattern. In this case it does an HTTP redirect to the slash-appended PATH_INFO.

Let’s use an example, because this behavior is a bit magical. If the append_slash_notfound_view is configured in your application and your route configuration looks like so:

1
2
3
4

config.add_route('noslash', 'no_slash',
                 view='myproject.views.no_slash')
config.add_route('hasslash', 'has_slash/',
                 view='myproject.views.has_slash')

If a request enters the application with the PATH_INFO value of /has_slash/, the second route will match. If a request enters the application with the PATH_INFO value of /has_slash, a route will be found by the slash-appending not found view. An HTTP redirect to /has_slash/ will be returned to the user’s browser.

If a request enters the application with the PATH_INFO value of /no_slash, the first route will match. However, if a request enters the application with the PATH_INFO value of /no_slash/, no route will match, and the slash-appending not found view will not find a matching route with an appended slash.

Warning

You should not rely on this mechanism to redirect POST requests. The redirect of the slash-appending not found view will turn a POST request into a GET, losing any POST data in the original request.

To configure the slash-appending not found view in your application, change the application’s startup configuration, adding the following stanza:

1
2

config.add_view(context='pyramid.exceptions.NotFound',
                view='pyramid.view.append_slash_notfound_view')

See pyramid.view and Changing the Not Found View for more information about the slash-appending not found view and for a more general description of how to configure a not found view.

Custom Not Found View With Slash Appended Routes

There can only be one Not Found view in any Pyramid application. Even if you use append_slash_notfound_view() as the Not Found view, Pyramid still must generate a 404 Not Found response when it cannot redirect to a slash-appended URL; this not found response will be visible to site users.

If you don’t care what this 404 response looks like, and only you need redirections to slash-appended route URLs, you may use the append_slash_notfound_view() object as the Not Found view as described above. However, if you wish to use a custom notfound view callable when a URL cannot be redirected to a slash-appended URL, you may wish to use an instance of the AppendSlashNotFoundViewFactory class as the Not Found view, supplying a view callable to be used as the custom notfound view as the first argument to its constructor. For instance:

1
2
3
4
5
6
7
8

from pyramid.exceptions import NotFound
from pyramid.view import AppendSlashNotFoundViewFactory

def notfound_view(context, request):
    return HTTPNotFound('It aint there, stop trying!')

custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
config.add_view(custom_append_slash, context=NotFound)

The notfound_view supplied must adhere to the two-argument view callable calling convention of (context, request) (context will be the exception object).

Cleaning Up After a Request

Sometimes it’s required that some cleanup be performed at the end of a request when a database connection is involved.

For example, let’s say you have a mypackage Pyramid application package that uses SQLAlchemy, and you’d like the current SQLAlchemy database session to be removed after each request. Put the following in the mypackage.__init__ module:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from mypackage.models import DBSession

from pyramid.events import subscriber
from pyramid.events import NewRequest

def cleanup_callback(request):
    DBSession.remove()

@subscriber(NewRequest)
def add_cleanup_callback(event):
    event.request.add_finished_callback(cleanup_callback)

Registering the cleanup_callback finished callback at the start of a request (by causing the add_cleanup_callback to receive a pyramid.events.NewRequest event at the start of each request) will cause the DBSession to be removed whenever request processing has ended. Note that in the example above, for the pyramid.events.subscriber decorator to “work”, the pyramid.config.Configurator.scan() method must be called against your mypackage package during application initialization.

Note

This is only an example. In particular, it is not necessary to cause DBSession.remove to be called in an application generated from any Pyramid paster template, because these all use the repoze.tm2 middleware. The cleanup done by DBSession.remove is unnecessary when repoze.tm2 middleware is in the WSGI pipeline.

Using Pyramid Security With URL Dispatch

Pyramid provides its own security framework which consults an authorization policy before allowing any application code to be called. This framework operates in terms of an access control list, which is stored as an __acl__ attribute of a resource object. A common thing to want to do is to attach an __acl__ to the resource object dynamically for declarative security purposes. You can use the factory argument that points at a factory which attaches a custom __acl__ to an object at its creation time.

Such a factory might look like so:

1
2
3
4
5
6

class Article(object):
    def __init__(self, request):
       matchdict = request.matchdict
       article = matchdict.get('article', None)
       if article == '1':
           self.__acl__ = [ (Allow, 'editor', 'view') ]

If the route archives/{article} is matched, and the article number is 1, Pyramid will generate an Article context resource with an ACL on it that allows the editor principal the view permission. Obviously you can do more generic things than inspect the routes match dict to see if the article argument matches a particular string; our sample Article factory class is not very ambitious.

Note

See Security for more information about Pyramid security and ACLs.

Debugging Route Matching

It’s useful to be able to take a peek under the hood when requests that enter your application arent matching your routes as you expect them to. To debug route matching, use the PYRAMID_DEBUG_ROUTEMATCH environment variable or the debug_routematch configuration file setting (set either to true). Details of the route matching decision for a particular request to the Pyramid application will be printed to the stderr of the console which you started the application from. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

 [chrism@thinko pylonsbasic]$ PYRAMID_DEBUG_ROUTEMATCH=true \
                              bin/paster serve development.ini
 Starting server in PID 13586.
 serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
 2010-12-16 14:45:19,956 no route matched for url \
                                     http://localhost:6543/wontmatch
 2010-12-16 14:45:20,010 no route matched for url \
                             http://localhost:6543/favicon.ico
 2010-12-16 14:41:52,084 route matched for url \
                             http://localhost:6543/static/logo.png; \
                             route_name: 'static/', ....

See Environment Variables and .ini File Settings for more information about how, and where to set these values.

Displaying All Application Routes

You can use the paster proutes command in a terminal window to print a summary of routes related to your application. Much like the paster pshell command (see The Interactive Shell), the paster proutes command accepts two arguments. The first argument to proutes is the path to your application’s .ini file. The second is the app section name inside the .ini file which points to your application.

For example:

1
2
3
4
5
6
7
8

[chrism@thinko MyProject]$ ../bin/paster proutes development.ini MyProject
Name            Pattern                        View
----            -------                        ----
home            /                              <function my_view>
home2           /                              <function my_view>
another         /another                       None
static/         static/*subpath                <static_view object>
catchall        /*subpath                      <function static_view>

paster proutes generates a table. The table has three columns: a Name name column, a Pattern column, and a View column. The items listed in the Name column are route names, the items listen in the Pattern column are route patterns, and the items listed in the View column are representations of the view callable that will be invoked when a request matches the associated route pattern. The view column may show None if no associated view callable could be found. If no routes are configured within your application, nothing will be printed to the console when paster proutes is executed.

Route View Callable Registration and Lookup Details

The purpose of making it possible to specify a view callable within a route configuration is to prevent developers from needing to deeply understand the details of resource location and view lookup. When a route names a view callable as a view argument, and a request enters the system which matches the pattern of the route, the result is simple: the view callable associated with the route is invoked with the request that caused the invocation.

For most usage, you needn’t understand more than this; how it works is an implementation detail. In the interest of completeness, however, we’ll explain how it does work in the this section. You can skip it if you’re uninterested.

When a view attribute is attached to a route configuration, Pyramid ensures that a view configuration is registered that will always be found when the route pattern is matched during a request. To do so:

A special route-specific interface is created at startup time for each route configuration declaration.

When a route configuration declaration mentions a view attribute, a view configuration is registered at startup time. This view configuration uses the route-specific interface as a request type.

At runtime, when a request causes any route to match, the request object is decorated with the route-specific interface.

The fact that the request is decorated with a route-specific interface causes the view lookup machinery to always use the view callable registered using that interface by the route configuration to service requests that match the route pattern.

In this way, we supply a shortcut to the developer. Under the hood, the resource location and view lookup subsystems provided by Pyramid are still being utilized, but in a way which does not require a developer to understand either of them in detail. It also means that we can allow a developer to combine URL dispatch and traversal in various exceptional cases as documented in Combining Traversal and URL Dispatch.

References

A tutorial showing how URL dispatch can be used to create a Pyramid application exists in SQLAlchemy + URL Dispatch Wiki Tutorial.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Much Ado About Traversal

Note

This chapter was adapted, with permission, from a blog post by Rob Miller [http://blog.nonsequitarian.org/], originally published at http://blog.nonsequitarian.org/2010/much-ado-about-traversal/ .

Traversal is an alternative to URL dispatch which allows Pyramid applications to map URLs to code.

Note

Ex-Zope users whom are already familiar with traversal and view lookup conceptually may want to skip directly to the Traversal chapter, which discusses technical details. This chapter is mostly aimed at people who have previous Pylons experience or experience in another framework which does not provide traversal, and need an introduction to the “why” of traversal.

Some folks who have been using Pylons and its Routes-based URL matching for a long time are being exposed for the first time, via Pyramid, to new ideas such as “traversal” and “view lookup” as a way to route incoming HTTP requests to callable code. Some of the same folks believe that traversal is hard to understand. Others question its usefulness; URL matching has worked for them so far, why should they even consider dealing with another approach, one which doesn’t fit their brain and which doesn’t provide any immediately obvious value?

You can be assured that if you don’t want to understand traversal, you don’t have to. You can happily build Pyramid applications with only URL dispatch. However, there are some straightforward, real-world use cases that are much more easily served by a traversal-based approach than by a pattern-matching mechanism. Even if you haven’t yet hit one of these use cases yourself, understanding these new ideas is worth the effort for any web developer so you know when you might want to use them. Traversal is actually a straightforward metaphor easily comprehended by anyone who’s ever used a run-of-the-mill file system with folders and files.

URL Dispatch

Let’s step back and consider the problem we’re trying to solve. An HTTP request for a particular path has been routed to our web application. The requested path will possibly invoke a specific view callable function defined somewhere in our app. We’re trying to determine which callable function, if any, should be invoked for a given requested URL.

Many systems, including Pyramid, offer a simple solution. They offer the concept of “URL matching”. URL matching approaches this problem by parsing the URL path and comparing the results to a set of registered “patterns”, defined by a set of regular expressions, or some other URL path templating syntax. Each pattern is mapped to a callable function somewhere; if the request path matches a specific pattern, the associated function is called. If the request path matches more than one pattern, some conflict resolution scheme is used, usually a simple order precedence so that the first match will take priority over any subsequent matches. If a request path doesn’t match any of the defined patterns, a “404 Not Found” response is returned.

In Pyramid, we offer an implementation of URL matching which we call URL dispatch. Using Pyramid syntax, we might have a match pattern such as /{userid}/photos/{photoid}, mapped to a photo_view() function defined somewhere in our code. Then a request for a path such as /joeschmoe/photos/photo1 would be a match, and the photo_view() function would be invoked to handle the request. Similarly, /{userid}/blog/{year}/{month}/{postid} might map to a blog_post_view() function, so /joeschmoe/blog/2010/12/urlmatching would trigger the function, which presumably would know how to find and render the urlmatching blog post.

Historical Refresher

Now that we’ve refreshed our understanding of URL dispatch, we’ll dig in to the idea of traversal. Before we do, though, let’s take a trip down memory lane. If you’ve been doing web work for a while, you may remember a time when we didn’t have fancy web frameworks like Pylons and Pyramid. Instead, we had general purpose HTTP servers that primarily served files off of a file system. The “root” of a given site mapped to a particular folder somewhere on the file system. Each segment of the request URL path represented a subdirectory. The final path segment would be either a directory or a file, and once the server found the right file it would package it up in an HTTP response and send it back to the client. So serving up a request for /joeschmoe/photos/photo1 literally meant that there was a joeschmoe folder somewhere, which contained a photos folder, which in turn contained a photo1 file. If at any point along the way we find that there is not a folder or file matching the requested path, we return a 404 response.

As the web grew more dynamic, however, a little bit of extra complexity was added. Technologies such as CGI and HTTP server modules were developed. Files were still looked up on the file system, but if the file ended with (for example) .cgi or .php, or if it lived in a special folder, instead of simply sending the file to the client the server would read the file, execute it using an interpreter of some sort, and then send the output from this process to the client as the final result. The server configuration specified which files would trigger some dynamic code, with the default case being to just serve the static file.

Traversal (aka Resource Location)

Believe it or not, if you understand how serving files from a file system works,you understand traversal. And if you understand that a server might do something different based on what type of file a given request specifies, then you understand view lookup.

The major difference between file system lookup and traversal is that a file system lookup steps through nested directories and files in a file system tree, while traversal steps through nested dictionary-type objects in a resource tree. Let’s take a detailed look at one of our example paths, so we can see what I mean:

The path /joeschmoe/photos/photo1, has four segments: /, joeschmoe, photos and photo1. With file system lookup we might have a root folder (/) containing a nested folder (joeschmoe), which contains another nested folder (photos), which finally contains a JPG file (photo1). With traversal, we instead have a dictionary-like root object. Asking for the joeschmoe key gives us another dictionary-like object. Asking this in turn for the photos key gives us yet another mapping object, which finally (hopefully) contains the resource that we’re looking for within its values, referenced by the photo1 key.

In pure Python terms, then, the traversal or “resource location” portion of satisfying the /joeschmoe/photos/photo1 request will look something like this pseudocode:

get_root()['joeschmoe']['photos']['photo1']

get_root() is some function that returns a root traversal resource. If all of the specified keys exist, then the returned object will be the resource that is being requested, analogous to the JPG file that was retrieved in the file system example. If a KeyError is generated anywhere along the way, Pyramid will return 404. (This isn’t precisely true, as you’ll see when we learn about view lookup below, but the basic idea holds.)

What Is a “Resource”?

“Files on a file system I understand”, you might say. “But what are these nested dictionary things? Where do these objects, these ‘resources’, live? What are they?”

Since Pyramid is not a highly opinionated framework, it makes no restriction on how a resource is implemented; a developer can implement them as he wishes. One common pattern used is to persist all of the resources, including the root, in a database as a graph. The root object is a dictionary-like object. Dictionary-like objects in Python supply a __getitem__ method which is called when key lookup is done. Under the hood, when adict is a dictionary-like object, Python translates adict['a'] to adict.__getitem__('a'). Try doing this in a Python interpreter prompt if you don’t believe us:

1
2
3
4
5
6
7
8
9

Python 2.4.6 (#2, Apr 29 2010, 00:31:48)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> adict = {}
>>> adict['a'] = 1
>>> adict['a']
1
>>> adict.__getitem__('a')
1

The dictionary-like root object stores the ids of all of its subresources as keys, and provides a __getitem__ implementation that fetches them. So get_root() fetches the unique root object, while get_root()['joeschmoe'] returns a different object, also stored in the database, which in turn has its own subresources and __getitem__ implementation, etc. These resources might be persisted in a relational database, one of the many “NoSQL” solutions that are becoming popular these days, or anywhere else, it doesn’t matter. As long as the returned objects provide the dictionary-like API (i.e. as long as they have an appropriately implemented __getitem__ method) then traversal will work.

In fact, you don’t need a “database” at all. You could use plain dictionaries, with your site’s URL structure hard-coded directly in the Python source. Or you could trivially implement a set of objects with __getitem__ methods that search for files in specific directories, and thus precisely recreate the traditional mechanism of having the URL path mapped directly to a folder structure on the file system. Traversal is in fact a superset of file system lookup.

Note

See the chapter entitled Resources for a more technical overview of resources.

View Lookup

At this point we’re nearly there. We’ve covered traversal, which is the process by which a specific resource is retrieved according to a specific URL path. But what is “view lookup”?

The need for view lookup is simple: there is more than one possible action that you might want to take after finding a resource. With our photo example, for instance, you might want to view the photo in a page, but you might also want to provide a way for the user to edit the photo and any associated metadata. We’ll call the former the view view, and the latter will be the edit view. (Original, I know.) Pyramid has a centralized view application registry where named views can be associated with specific resource types. So in our example, we’ll assume that we’ve registered view and edit views for photo objects, and that we’ve specified the view view as the default, so that /joeschmoe/photos/photo1/view and /joeschmoe/photos/photo1 are equivalent. The edit view would sensibly be provided by a request for /joeschmoe/photos/photo1/edit.

Hopefully it’s clear that the first portion of the edit view’s URL path is going to resolve to the same resource as the non-edit version, specifically the resource returned by get_root()['joeschmoe']['photos']['photo1']. But traveral ends there; the photo1 resource doesn’t have an edit key. In fact, it might not even be a dictionary-like object, in which case photo1['edit'] would be meaningless. When the Pyramid resource location has been resolved to a leaf resource, but the entire request path has not yet been expended, the very next path segment is treated as a view name. The registry is then checked to see if a view of the given name has been specified for a resource of the given type. If so, the view callable is invoked, with the resource passed in as the related context object (also available as request.context). If a view callable could not be found, Pyramid will return a “404 Not Found” response.

You might conceptualize a request for /joeschmoe/photos/photo1/edit as ultimately converted into the following piece of Pythonic pseudocode:

context = get_root()['joeschmoe']['photos']['photo1']
view_callable = get_view(context, 'edit')
request.context = context
view_callable(request)

The get_root and get_view functions don’t really exist. Internally, Pyramid does something more complicated. But the example above is a reasonable approximation of the view lookup algorithm in pseudocode.

Use Cases

Why should we care about traversal? URL matching is easier to explain, and it’s good enough, right?

In some cases, yes, but certainly not in all cases. So far we’ve had very structured URLs, where our paths have had a specific, small number of pieces, like this:

/{userid}/{typename}/{objectid}[/{view_name}]

In all of the examples thus far, we’ve hard coded the typename value, assuming that we’d know at development time what names were going to be used (“photos”, “blog”, etc.). But what if we don’t know what these names will be? Or, worse yet, what if we don’t know anything about the structure of the URLs inside a user’s folder? We could be writing a CMS where we want the end user to be able to arbitrarily add content and other folders inside his folder. He might decide to nest folders dozens of layers deep. How will you construct matching patterns that could account for every possible combination of paths that might develop?

It might be possible, but it certainly won’t be easy. The matching patterns are going to become complex quickly as you try to handle all of the edge cases.

With traversal, however, it’s straightforward. Twenty layers of nesting would be no problem. Pyramid will happily call __getitem__ as many times as it needs to, until it runs out of path segments or until a resource raises a KeyError. Each resource only needs to know how to fetch its immediate children, the traversal algorithm takes care of the rest. Also, since the structure of the resource tree can live in the database and not in the code, it’s simple to let users modify the tree at runtime to set up their own personalized “directory” structures.

Another use case in which traversal shines is when there is a need to support a context-dependent security policy. One example might be a document management infrastructure for a large corporation, where members of different departments have varying access levels to the various other departments’ files. Reasonably, even specific files might need to be made available to specific individuals. Traversal does well here if your resources actually represent the data objects related to your documents, because the idea of a resource authorization is baked right into the code resolution and calling process. Resource objects can store ACLs, which can be inherited and/or overridden by the subresources.

If each resource can thus generate a context-based ACL, then whenever view code is attempting to perform a sensitive action, it can check against that ACL to see whether the current user should be allowed to perform the action. In this way you achieve so called “instance based” or “row level” security which is considerably harder to model using a traditional tabular approach. Pyramid actively supports such a scheme, and in fact if you register your views with guard permissions and use an authorization policy, Pyramid can check against a resource’s ACL when deciding whether or not the view itself is available to the current user.

In summary, there are entire classes of problems that are more easily served by traversal and view lookup than by URL dispatch. If your problems don’t require it, great: stick with URL dispatch. But if you’re using Pyramid and you ever find that you do need to support one of these use cases, you’ll be glad you have traversal in your toolkit.

Note

It is even possible to mix and match traversal with URL dispatch in the same Pyramid application. See the Combining Traversal and URL Dispatch chapter for details.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Traversal

A traversal uses the URL (Universal Resource Locator) to find a resource located in a resource tree, which is a set of nested dictionary-like objects. Traversal is done by using each segment of the path portion of the URL to navigate through the resource tree. You might think of this as looking up files and directories in a file system. Traversal walks down the path until it finds a published resource, analogous to a file system “directory” or “file”. The resource found as the result of a traversal becomes the context of the request. Then, the view lookup subsystem is used to find some view code willing “publish” this resource by generating a response.

Using Traversal to map a URL to code is optional. It is often less easy to understand than URL dispatch, so if you’re a rank beginner, it probably makes sense to use URL dispatch to map URLs to code instead of traversal. In that case, you can skip this chapter.

Traversal Details

Traversal is dependent on information in a request object. Every request object contains URL path information in the PATH_INFO portion of the WSGI environment. The PATH_INFO string is the portion of a request’s URL following the hostname and port number, but before any query string elements or fragment element. For example the PATH_INFO portion of the URL http://example.com:8080/a/b/c?foo=1 is /a/b/c.

Traversal treats the PATH_INFO segment of a URL as a sequence of path segments. For example, the PATH_INFO string /a/b/c is converted to the sequence ['a', 'b', 'c'].

This path sequence is then used to descend through the resource tree, looking up a resource for each path segment. Each lookup uses the __getitem__ method of a resource in the tree.

For example, if the path info sequence is ['a', 'b', 'c']:

Traversal starts by acquiring the root resource of the application by calling the root factory. The root factory can be configured to return whatever object is appropriate as the traversal root of your application.

Next, the first element (a) is popped from the path segment sequence and is used as a key to lookup the corresponding resource in the root. This invokes the root resource’s __getitem__ method using that value (a) as an argument.

If the root resource “contains” a resource with key a, its __getitem__ method will return it. The context temporarily becomes the “A” resource.

The next segment (b) is popped from the path sequence, and the “A” resource’s __getitem__ is called with that value (b) as an argument; we’ll presume it succeeds.

The “A” resource’s __getitem__ returns another resource, which we’ll call “B”. The context temporarily becomes the “B” resource.

Traversal continues until the path segment sequence is exhausted or a path element cannot be resolved to a resource. In either case, the context resource is the last object that the traversal successfully resolved. If any resource found during traversal lacks a __getitem__ method, or if its __getitem__ method raises a KeyError, traversal ends immediately, and that resource becomes the context.

The results of a traversal also include a view name. If traversal ends before the path segment sequence is exhausted, the view name is the next remaining path segment element. If the traversal expends all of the path segments, then the view name is the empty string (‘’).

The combination of the context resource and the view name found via traversal is used later in the same request by the view lookup subsystem to find a view callable. How Pyramid performs view lookup is explained within the View Configuration chapter.

The Resource Tree

The resource tree is a set of nested dictionary-like resource objects that begins with a root resource. In order to use traversal to resolve URLs to code, your application must supply a resource tree to Pyramid.

In order to supply a root resource for an application the Pyramid Router is configured with a callback known as a root factory. The root factory is supplied by the application, at startup time, as the root_factory argument to the Configurator.

The root factory is a Python callable that accepts a request object, and returns the root object of the resource tree. A function, or class is typically used as an application’s root factory. Here’s an example of a simple root factory class:

1
2
3

class Root(dict):
    def __init__(self, request):
        pass

Here’s an example of using this root factory within startup configuration, by passing it to an instance of a Configurator named config:

1

config = Configurator(root_factory=Root)

The root_factory argument to the Configurator constructor registers this root factory to be called to generate a root resource whenever a request enters the application. The root factory registered this way is also known as the global root factory. A root factory can alternately be passed to the Configurator as a dotted Python name which can refer to a root factory defined in a different module.

If no root factory is passed to the Pyramid Configurator constructor, or if the root_factory value specified is None, a default root factory is used. The default root factory always returns a resource that has no child resources; it is effectively empty.

Usually a root factory for a traversal-based application will be more complicated than the above Root class; in particular it may be associated with a database connection or another persistence mechanism.

Emulating the Default Root Factory

For purposes of understanding the default root factory better, we’ll note that you can emulate the default root factory by using this code as an explicit root factory in your application setup:

1
2
3
4
5

class Root(object):
    def __init__(self, request):
        pass

config = Configurator(root_factory=Root)

The default root factory is just a really stupid object that has no behavior or state. Using traversal against an application that uses the resource tree supplied by the default root resource is not very interesting, because the default root resource has no children. Its availability is more useful when you’re developing an application using URL dispatch.

Note

If the items contained within the resource tree are “persistent” (they have state that lasts longer than the execution of a single process), they become analogous to the concept of domain model objects used by many other frameworks.

The resource tree consists of container resources and leaf resources. There is only one difference between a container resource and a leaf resource: container resources possess a __getitem__ method (making it “dictionary-like”) while leaf resources do not. The __getitem__ method was chosen as the signifying difference between the two types of resources because the presence of this method is how Python itself typically determines whether an object is “containerish” or not (dictionary objects are “containerish”).

Each container resource is presumed to be willing to return a child resource or raise a KeyError based on a name passed to its __getitem__.

Leaf-level instances must not have a __getitem__. If instances that you’d like to be leaves already happen to have a __getitem__ through some historical inequity, you should subclass these resource types and cause their __getitem__ methods to simply raise a KeyError. Or just disuse them and think up another strategy.

Usually, the traversal root is a container resource, and as such it contains other resources. However, it doesn’t need to be a container. Your resource tree can be as shallow or as deep as you require.

In general, the resource tree is traversed beginning at its root resource using a sequence of path elements described by the PATH_INFO of the current request; if there are path segments, the root resource’s __getitem__ is called with the next path segment, and it is expected to return another resource. The resulting resource’s __getitem__ is called with the very next path segment, and it is expected to return another resource. This happens ad infinitum until all path segments are exhausted.

The Traversal Algorithm

This section will attempt to explain the Pyramid traversal algorithm. We’ll provide a description of the algorithm, a diagram of how the algorithm works, and some example traversal scenarios that might help you understand how the algorithm operates against a specific resource tree.

We’ll also talk a bit about view lookup. The View Configuration chapter discusses view lookup in detail, and it is the canonical source for information about views. Technically, view lookup is a Pyramid subsystem that is separated from traversal entirely. However, we’ll describe the fundamental behavior of view lookup in the examples in the next few sections to give you an idea of how traversal and view lookup cooperate, because they are almost always used together.

A Description of The Traversal Algorithm

When a user requests a page from your traversal-powered application, the system uses this algorithm to find a context resource and a view name.

The request for the page is presented to the Pyramid router in terms of a standard WSGI request, which is represented by a WSGI environment and a WSGI start_response callable.

The router creates a request object based on the WSGI environment.

The root factory is called with the request. It returns a root resource.

The router uses the WSGI environment’s PATH_INFO information to determine the path segments to traverse. The leading slash is stripped off PATH_INFO, and the remaining path segments are split on the slash character to form a traversal sequence.

The traversal algorithm by default attempts to first URL-unquote and then Unicode-decode each path segment derived from PATH_INFO from its natural byte string (str type) representation. URL unquoting is performed using the Python standard library urllib.unquote function. Conversion from a URL-decoded string into Unicode is attempted using the UTF-8 encoding. If any URL-unquoted path segment in PATH_INFO is not decodeable using the UTF-8 decoding, a TypeError is raised. A segment will be fully URL-unquoted and UTF8-decoded before it is passed it to the __getitem__ of any resource during traversal.

Thus, a request with a PATH_INFO variable of /a/b/c maps to the traversal sequence [u'a', u'b', u'c'].

Traversal begins at the root resource returned by the root factory. For the traversal sequence [u'a', u'b', u'c'], the root resource’s __getitem__ is called with the name a. Traversal continues through the sequence. In our example, if the root resource’s __getitem__ called with the name a returns a resource (aka “resource a”), that resource’s __getitem__ is called with the name b. If resource A returns a resource when asked for b, “resource b“‘s __getitem__ is then asked for the name c, and may return “resource c”.

Traversal ends when a) the entire path is exhausted or b) when any resouce raises a KeyError from its __getitem__ or c) when any non-final path element traversal does not have a __getitem__ method (resulting in a NameError) or d) when any path element is prefixed with the set of characters @@ (indicating that the characters following the @@ token should be treated as a view name).

When traversal ends for any of the reasons in the previous step, the last resource found during traversal is deemed to be the context. If the path has been exhausted when traversal ends, the view name is deemed to be the empty string (''). However, if the path was not exhausted before traversal terminated, the first remaining path segment is treated as the view name.

Any subsequent path elements after the view name is found are deemed the subpath. The subpath is always a sequence of path segments that come from PATH_INFO that are “left over” after traversal has completed.

Once the context resource, the view name, and associated attributes such as the subpath are located, the job of traversal is finished. It passes back the information it obtained to its caller, the Pyramid Router, which subsequently invokes view lookup with the context and view name information.

The traversal algorithm exposes two special cases:

You will often end up with a view name that is the empty string as the result of a particular traversal. This indicates that the view lookup machinery should look up the default view. The default view is a view that is registered with no name or a view which is registered with a name that equals the empty string.

If any path segment element begins with the special characters @@ (think of them as goggles), the value of that segment minus the goggle characters is considered the view name immediately and traversal stops there. This allows you to address views that may have the same names as resource names in the tree unambiguously.

Finally, traversal is responsible for locating a virtual root. A virtual root is used during “virtual hosting”; see the Virtual Hosting chapter for information. We won’t speak more about it in this chapter.

Traversal Algorithm Examples

No one can be expected to understand the traversal algorithm by analogy and description alone, so let’s examine some traversal scenarios that use concrete URLs and resource tree compositions.

Let’s pretend the user asks for http://example.com/foo/bar/baz/biz/buz.txt. The request’s PATH_INFO in that case is /foo/bar/baz/biz/buz.txt. Let’s further pretend that when this request comes in that we’re traversing the following resource tree:

/--
   |
   |-- foo
        |
        ----bar

Here’s what happens:

traversal traverses the root, and attempts to find “foo”, which it finds.

traversal traverses “foo”, and attempts to find “bar”, which it finds.

traversal traverses bar, and attempts to find “baz”, which it does not find (the “bar” resource raises a KeyError when asked for “baz”).

The fact that it does not find “baz” at this point does not signify an error condition. It signifies that:

the context is the “bar” resource (the context is the last resource found during traversal).

the view name is baz

the subpath is ('biz', 'buz.txt')

At this point, traversal has ended, and view lookup begins.

Because it’s the “context” resource, the view lookup machinery examines “bar” to find out what “type” it is. Let’s say it finds that the context is a Bar type (because “bar” happens to be an instance of the class Bar). Using the view name (baz) and the type, view lookup asks the application registry this question:

Please find me a view callable registered using a view configuration with the name “baz” that can be used for the class Bar.

Let’s say that view lookup finds no matching view type. In this circumstance, the Pyramid router returns the result of the not found view and the request ends.

However, for this tree:

/--
   |
   |-- foo
        |
        ----bar
             |
             ----baz
                    |
                    biz

The user asks for http://example.com/foo/bar/baz/biz/buz.txt

traversal traverses “foo”, and attempts to find “bar”, which it finds.

traversal traverses “bar”, and attempts to find “baz”, which it finds.

traversal traverses “baz”, and attempts to find “biz”, which it finds.

traversal traverses “biz”, and attempts to find “buz.txt” which it does not find.

The fact that it does not find a resource related to “buz.txt” at this point does not signify an error condition. It signifies that:

the context is the “biz” resource (the context is the last resource found during traversal).

the view name is “buz.txt”

the subpath is an empty sequence ( () ).

At this point, traversal has ended, and view lookup begins.

Because it’s the “context” resource, the view lookup machinery examines the “biz” resource to find out what “type” it is. Let’s say it finds that the resource is a Biz type (because “biz” is an instance of the Python class Biz). Using the view name (buz.txt) and the type, view lookup asks the application registry this question:

Please find me a view callable registered with a view configuration with the name buz.txt that can be used for class Biz.

Let’s say that question is answered by the application registry; in such a situation, the application registry returns a view callable. The view callable is then called with the current WebOb request as the sole argument: request; it is expected to return a response.

The Example View Callables Accept Only a Request; How Do I Access the Context Resource?

Most of the examples in this book assume that a view callable is typically passed only a request object. Sometimes your view callables need access to the context resource, especially when you use traversal. You might use a supported alternate view callable argument list in your view callables such as the (context, request) calling convention described in Alternate View Callable Argument/Calling Conventions. But you don’t need to if you don’t want to. In view callables that accept only a request, the context resource found by traversal is available as the context attribute of the request object, e.g. request.context. The view name is available as the view_name attribute of the request object, e.g. request.view_name. Other Pyramid -specific request attributes are also available as described in Special Attributes Added to the Request by Pyramid.

References

A tutorial showing how traversal can be used within a Pyramid application exists in ZODB + Traversal Wiki Tutorial.

See the View Configuration chapter for detailed information about view lookup.

The pyramid.traversal module contains API functions that deal with traversal, such as traversal invocation from within application code.

The pyramid.url.resource_url() function generates a URL when given a resource retrieved from a resource tree.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Views

One of the primary jobs of Pyramid is to find and invoke a view callable when a request reaches your application. View callables are bits of code which do something interesting in response to a request made to your application.

Note

A Pyramid view callable is often referred to in conversational shorthand as a view. In this documentation, however, we need to use less ambiguous terminology because there are significant differences between view configuration, the code that implements a view callable, and the process of view lookup.

The URL Dispatch, and Traversal chapters describes how, using information from the request, a context resource is computed. But the context resource itself isn’t very useful without an associated view callable. A view callable returns a response to a user, often using the context resource to do so.

The job of actually locating and invoking the “best” view callable is the job of the view lookup subsystem. The view lookup subsystem compares the resource supplied by resource location and information in the request against view configuration statements made by the developer to choose the most appropriate view callable for a specific set of circumstances.

This chapter describes how view callables work. In the View Configuration chapter, there are details about performing view configuration, and a detailed explanation of view lookup.

View Callables

View callables are, at the risk of sounding obvious, callable Python objects. Specifically, view callables can be functions, classes, or instances that implement an __call__ method (making the instance callable).

View callables must, at a minimum, accept a single argument named request. This argument represents a Pyramid Request object. A request object encapsulates a WSGI environment provided to Pyramid by the upstream WSGI server. As you might expect, the request object contains everything your application needs to know about the specific HTTP request being made.

A view callable’s ultimate responsibility is to create a Pyramid Response object. This can be done by creating the response object in the view callable code and returning it directly, as we will be doing in this chapter. However, if a view callable does not return a response itself, it can be configured to use a renderer that converts its return value into a Response object. Using renderers is the common way that templates are used with view callables to generate markup. See the Renderers chapter for details.

Defining a View Callable as a Function

One of the easiest way to define a view callable is to create a function that accepts a single argument named request, and which returns a Response object. For example, this is a “hello world” view callable implemented as a function:

1
2
3
4

from pyramid.response import Response

def hello_world(request):
    return Response('Hello world!')

Defining a View Callable as a Class

A view callable may also be represented by a Python class instead of a function. When a view callable is a class, the calling semantics are slightly different than when it is a function or another non-class callable. When a view callable is a class, the class’ __init__ is called with a request parameter. As a result, an instance of the class is created. Subsequently, that instance’s __call__ method is invoked with no parameters. Views defined as classes must have the following traits:

an __init__ method that accepts a request argument.

a __call__ (or other) method that accepts no parameters and which returns a response.

For example:

1
2
3
4
5
6
7
8

from pyramid.response import Response

class MyView(object):
    def __init__(self, request):
        self.request = request

    def __call__(self):
        return Response('hello')

The request object passed to __init__ is the same type of request object described in Defining a View Callable as a Function.

If you’d like to use a different attribute than __call__ to represent the method expected to return a response, you can either:

use an attr value as part of the configuration for the view. See View Configuration Parameters. The same view callable class can be used in different view configuration statements with different attr values, each pointing at a different method of the class if you’d like the class to represent a collection of related view callables.

Note

A package named pyramid_handlers (available from PyPI) provides an analogue of Pylons -style “controllers”, which are a special kind of view class which provides more automation when your application uses URL dispatch solely.

Alternate View Callable Argument/Calling Conventions

Usually, view callables are defined to accept only a single argument: request. However, view callables may alternately be defined as classes, functions, or any callable that accept two positional arguments: a context resource as the first argument and a request as the second argument.

The context and request arguments passed to a view function defined in this style can be defined as follows:

context

The resource object found via tree traversal or URL dispatch.

request

A Pyramid Request object representing the current WSGI request.

The following types work as view callables in this style:

Functions that accept two arguments: context, and request, e.g.:

1
2
3
4

from pyramid.response import Response

def view(context, request):
        return Response('OK')

Classes that have an __init__ method that accepts context, request and a __call__ which accepts no arguments, e.g.:

1
2
3
4
5
6
7
8
9

from pyramid.response import Response

class view(object):
        def __init__(self, context, request):
                self.context = context
                self.request = request

        def __call__(self):
                return Response('OK')

Arbitrary callables that have a __call__ method that accepts context, request, e.g.:

1
2
3
4
5
6

from pyramid.response import Response

class View(object):
        def __call__(self, context, request):
                return Response('OK')
view = View() # this is the view callable

This style of calling convention is most useful for traversal based applications, where the context object is frequently used within the view callable code itself.

No matter which view calling convention is used, the view code always has access to the context via request.context.

View Callable Responses

A view callable may always return an object that implements the Pyramid Response interface. The easiest way to return something that implements the Response interface is to return a pyramid.response.Response object instance directly. For example:

1
2
3
4

from pyramid.response import Response

def view(request):
    return Response('OK')

You don’t need to always use Response to represent a response. Pyramid provides a range of different “exception” classes which can act as response objects too. For example, an instance of the class pyramid.httpexceptions.HTTPFound is also a valid response object (see Using a View Callable to Do an HTTP Redirect). A view can actually return any object that has the following attributes.

status

The HTTP status code (including the name) for the response as a string. E.g. 200 OK or 401 Unauthorized.

headerlist

A sequence of tuples representing the list of headers that should be set in the response. E.g. [('Content-Type', 'text/html'), ('Content-Length', '412')]

app_iter

An iterable representing the body of the response. This can be a list, e.g. ['<html><head></head><body>Hello world!</body></html>'] or it can be a file-like object, or any other sort of iterable.

These attributes form the notional “Pyramid Response interface”.

Using a View Callable to Do an HTTP Redirect

You can issue an HTTP redirect from within a view by returning a particular kind of response.

1
2
3
4

from pyramid.httpexceptions import HTTPFound

def myview(request):
    return HTTPFound(location='http://example.com')

All exception types from the pyramid.httpexceptions module implement the Response interface; any can be returned as the response from a view. See pyramid.httpexceptions for the documentation for the HTTPFound exception; it also includes other response types that imply other HTTP response codes, such as HTTPUnauthorized for 401 Unauthorized.

Note

Although exception types from the pyramid.httpexceptions module are in fact bona fide Python Exception types, the Pyramid view machinery expects them to be returned by a view callable rather than raised.

It is possible, however, in Python 2.5 and above, to configure an exception view to catch these exceptions, and return an appropriate Response. The simplest such view could just catch and return the original exception. See Exception Views for more details.

Using Special Exceptions In View Callables

Usually when a Python exception is raised within a view callable, Pyramid allows the exception to propagate all the way out to the WSGI server which invoked the application.

However, for convenience, two special exceptions exist which are always handled by Pyramid itself. These are pyramid.exceptions.NotFound and pyramid.exceptions.Forbidden. Both are exception classes which accept a single positional constructor argument: a message.

If NotFound is raised within view code, the result of the Not Found View will be returned to the user agent which performed the request.

If Forbidden is raised within view code, the result of the Forbidden View will be returned to the user agent which performed the request.

In all cases, the message provided to the exception constructor is made available to the view which Pyramid invokes as request.exception.args[0].

Exception Views

The machinery which allows the special NotFound and Forbidden exceptions to be caught by specialized views as described in Using Special Exceptions In View Callables can also be used by application developers to convert arbitrary exceptions to responses.

To register a view that should be called whenever a particular exception is raised from with Pyramid view code, use the exception class or one of its superclasses as the context of a view configuration which points at a view callable you’d like to generate a response.

For example, given the following exception class in a module named helloworld.exceptions:

1
2
3

class ValidationFailure(Exception):
    def __init__(self, msg):
        self.msg = msg

You can wire a view callable to be called whenever any of your other code raises a hellworld.exceptions.ValidationFailure exception:

1
2
3
4
5
6
7

from helloworld.exceptions import ValidationFailure

@view_config(context=ValidationFailure)
def failed_validation(exc, request):
    response =  Response('Failed validation: %s' % exc.msg)
    response.status_int = 500
    return response

Assuming that a scan was run to pick up this view registration, this view callable will be invoked whenever a helloworld.exceptions.ValidationError is raised by your application’s view code. The same exception raised by a custom root factory or a custom traverser is also caught and hooked.

Other normal view predicates can also be used in combination with an exception view registration:

1
2
3
4
5
6
7

from pyramid.view import view_config
from pyramid.exceptions import NotFound
from pyramid.httpexceptions import HTTPNotFound

@view_config(context=NotFound, route_name='home')
def notfound_view(request):
    return HTTPNotFound()

The above exception view names the route_name of home, meaning that it will only be called when the route matched has a name of home. You can therefore have more than one exception view for any given exception in the system: the “most specific” one will be called when the set of request circumstances match the view registration.

The only view predicate that cannot be used successfully when creating an exception view configuration is name. The name used to look up an exception view is always the empty string. Views registered as exception views which have a name will be ignored.

Note

Normal (i.e., non-exception) views registered against a context resource type which inherits from Exception will work normally. When an exception view configuration is processed, two views are registered. One as a “normal” view, the other as an “exception” view. This means that you can use an exception as context for a normal view.

Exception views can be configured with any view registration mechanism: @view_config decorator, ZCML, or imperative add_view styles.

Handling Form Submissions in View Callables (Unicode and Character Set Issues)

Most web applications need to accept form submissions from web browsers and various other clients. In Pyramid, form submission handling logic is always part of a view. For a general overview of how to handle form submission data using the WebOb API, see Request and Response Objects and “Query and POST variables” within the WebOb documentation [http://pythonpaste.org/webob/reference.html#query-post-variables]. Pyramid defers to WebOb for its request and response implementations, and handling form submission data is a property of the request implementation. Understanding WebOb’s request API is the key to understanding how to process form submission data.

There are some defaults that you need to be aware of when trying to handle form submission data in a Pyramid view. Having high-order (i.e., non-ASCII) characters in data contained within form submissions is exceedingly common, and the UTF-8 encoding is the most common encoding used on the web for character data. Since Unicode values are much saner than working with and storing bytestrings, Pyramid configures the WebOb request machinery to attempt to decode form submission values into Unicode from UTF-8 implicitly. This implicit decoding happens when view code obtains form field values via the request.params, request.GET, or request.POST APIs (see pyramid.request for details about these APIs).

Note

Many people find the difference between Unicode and UTF-8 confusing. Unicode is a standard for representing text that supports most of the world’s writing systems. However, there are many ways that Unicode data can be encoded into bytes for transit and storage. UTF-8 is a specific encoding for Unicode, that is backwards-compatible with ASCII. This makes UTF-8 very convenient for encoding data where a large subset of that data is ASCII characters, which is largely true on the web. UTF-8 is also the standard character encoding for URLs.

As an example, let’s assume that the following form page is served up to a browser client, and its action points at some Pyramid view code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  </head>
  <form method="POST" action="myview">
    <div>
      <input type="text" name="firstname"/>
    </div>
    <div>
      <input type="text" name="lastname"/>
    </div>
    <input type="submit" value="Submit"/>
  </form>
</html>

The myview view code in the Pyramid application must expect that the values returned by request.params will be of type unicode, as opposed to type str. The following will work to accept a form post from the above form:

1
2
3

def myview(request):
    firstname = request.params['firstname']
    lastname = request.params['lastname']

But the following myview view code may not work, as it tries to decode already-decoded (unicode) values obtained from request.params:

1
2
3
4
5

def myview(request):
    # the .decode('utf-8') will break below if there are any high-order
    # characters in the firstname or lastname
    firstname = request.params['firstname'].decode('utf-8')
    lastname = request.params['lastname'].decode('utf-8')

For implicit decoding to work reliably, you should ensure that every form you render that posts to a Pyramid view explicitly defines a charset encoding of UTF-8. This can be done via a response that has a ;charset=UTF-8 in its Content-Type header; or, as in the form above, with a meta http-equiv tag that implies that the charset is UTF-8 within the HTML head of the page containing the form. This must be done explicitly because all known browser clients assume that they should encode form data in the same character set implied by Content-Type value of the response containing the form when subsequently submitting that form. There is no other generally accepted way to tell browser clients which charset to use to encode form data. If you do not specify an encoding explicitly, the browser client will choose to encode form data in its default character set before submitting it, which may not be UTF-8 as the server expects. If a request containing form data encoded in a non-UTF8 charset is handled by your view code, eventually the request code accessed within your view will throw an error when it can’t decode some high-order character encoded in another character set within form data, e.g., when request.params['somename'] is accessed.

If you are using the Response class to generate a response, or if you use the render_template_* templating APIs, the UTF-8 charset is set automatically as the default via the Content-Type header. If you return a Content-Type header without an explicit charset, a request will add a ;charset=utf-8 trailer to the Content-Type header value for you, for response content types that are textual (e.g. text/html, application/xml, etc) as it is rendered. If you are using your own response object, you will need to ensure you do this yourself.

Note

Only the values of request params obtained via request.params, request.GET or request.POST are decoded to Unicode objects implicitly in the Pyramid default configuration. The keys are still (byte) strings.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Renderers

A view needn’t always return a Response object. If a view happens to return something which does not implement the Pyramid Response interface, Pyramid will attempt to use a renderer to construct a response. For example:

1
2
3
4
5
6

from pyramid.response import Response
from pyramid.view import view_config

@view_config(renderer='json')
def hello_world(request):
    return {'content':'Hello!'}

The above example returns a dictionary from the view callable. A dictionary does not implement the Pyramid response interface, so you might believe that this example would fail. However, since a renderer is associated with the view callable through its view configuration (in this case, using a renderer argument passed to view_config()), if the view does not return a Response object, the renderer will attempt to convert the result of the view to a response on the developer’s behalf.

Of course, if no renderer is associated with a view’s configuration, returning anything except an object which implements the Response interface will result in an error. And, if a renderer is used, whatever is returned by the view must be compatible with the particular kind of renderer used, or an error may occur during view invocation.

One exception exists: it is always OK to return a Response object, even when a renderer is configured. If a view callable returns a response object from a view that is configured with a renderer, the renderer is bypassed entirely.

Various types of renderers exist, including serialization renderers and renderers which use templating systems. See also Writing View Callables Which Use a Renderer.

Writing View Callables Which Use a Renderer

As we’ve seen, view callables needn’t always return a Response object. Instead, they may return an arbitrary Python object, with the expectation that a renderer will convert that object into a response instance on your behalf. Some renderers use a templating system; other renderers use object serialization techniques.

View configuration can vary the renderer associated with a view callable via the renderer attribute. For example, this call to add_view() associates the json renderer with a view callable:

1

config.add_view('myproject.views.my_view', renderer='json')

When this configuration is added to an application, the myproject.views.my_view view callable will now use a json renderer, which renders view return values to a JSON response serialization.

Other built-in renderers include renderers which use the Chameleon templating language to render a dictionary to a response.

If the view callable associated with a view configuration returns a Response object directly (an object with the attributes status, headerlist and app_iter), any renderer associated with the view configuration is ignored, and the response is passed back to Pyramid unmolested. For example, if your view callable returns an instance of the pyramid.httpexceptions.HTTPFound class as a response, no renderer will be employed.

1
2
3
4

from pyramid.httpexceptions import HTTPFound

def view(request):
    return HTTPFound(location='http://example.com') # any renderer avoided

Views which use a renderer can vary non-body response attributes (such as headers and the HTTP status code) by attaching properties to the request. See Varying Attributes of Rendered Responses.

Additional renderers can be added by developers to the system as necessary (see Adding and Changing Renderers).

Built-In Renderers

Several built-in renderers exist in Pyramid. These renderers can be used in the renderer attribute of view configurations.

string: String Renderer

The string renderer is a renderer which renders a view callable result to a string. If a view callable returns a non-Response object, and the string renderer is associated in that view’s configuration, the result will be to run the object through the Python str function to generate a string. Note that if a Unicode object is returned by the view callable, it is not str() -ified.

Here’s an example of a view that returns a dictionary. If the string renderer is specified in the configuration for this view, the view will render the returned dictionary to the str() representation of the dictionary:

1
2
3
4
5
6

from pyramid.response import Response
from pyramid.view import view_config

@view_config(renderer='string')
def hello_world(request):
    return {'content':'Hello!'}

The body of the response returned by such a view will be a string representing the str() serialization of the return value:

1

{'content': 'Hello!'}

Views which use the string renderer can vary non-body response attributes by attaching properties to the request. See Varying Attributes of Rendered Responses.

json: JSON Renderer

The json renderer renders view callable results to JSON. It passes the return value through the json.dumps standard library function, and wraps the result in a response object. It also sets the response content-type to application/json.

Here’s an example of a view that returns a dictionary. Since the json renderer is specified in the configuration for this view, the view will render the returned dictionary to a JSON serialization:

1
2
3
4
5
6

from pyramid.response import Response
from pyramid.view import view_config

@view_config(renderer='json')
def hello_world(request):
    return {'content':'Hello!'}

The body of the response returned by such a view will be a string representing the JSON serialization of the return value:

1

'{"content": "Hello!"}'

The return value needn’t be a dictionary, but the return value must contain values serializable by json.dumps().

You can configure a view to use the JSON renderer by naming json as the renderer argument of a view configuration, e.g. by using add_view():

1
2
3
4

config.add_view('myproject.views.hello_world',
                 name='hello',
                 context='myproject.resources.Hello',
                 renderer='json')

Views which use the JSON renderer can vary non-body response attributes by attaching properties to the request. See Varying Attributes of Rendered Responses.

*.pt or *.txt: Chameleon Template Renderers

Two built-in renderers exist for Chameleon templates.

If the renderer attribute of a view configuration is an absolute path, a relative path or asset specification which has a final path element with a filename extension of .pt, the Chameleon ZPT renderer is used. See Chameleon ZPT Templates for more information about ZPT templates.

If the renderer attribute of a view configuration is an absolute path or a asset specification which has a final path element with a filename extension of .txt, the Chameleon text renderer is used. See Chameleon ZPT Templates for more information about Chameleon text templates.

The behavior of these renderers is the same, except for the engine used to render the template.

When a renderer attribute that names a template path or asset specification (e.g. myproject:templates/foo.pt or myproject:templates/foo.txt) is used, the view must return a Response object or a Python dictionary. If the view callable with an associated template returns a Python dictionary, the named template will be passed the dictionary as its keyword arguments, and the template renderer implementation will return the resulting rendered template in a response to the user. If the view callable returns anything but a Response object or a dictionary, an error will be raised.

Before passing keywords to the template, the keyword arguments derived from the dictionary returned by the view are augmented. The callable object – whatever object was used to define the view – will be automatically inserted into the set of keyword arguments passed to the template as the view keyword. If the view callable was a class, the view keyword will be an instance of that class. Also inserted into the keywords passed to the template are renderer_name (the string used in the renderer attribute of the directive), renderer_info (an object containing renderer-related information), context (the context resource of the view used to render the template), and request (the request passed to the view used to render the template).

Here’s an example view configuration which uses a Chameleon ZPT renderer:

1
2
3
4
5
6

 # config is an instance of pyramid.config.Configurator

 config.add_view('myproject.views.hello_world',
                 name='hello',
                 context='myproject.resources.Hello',
                 renderer='myproject:templates/foo.pt')

Here’s an example view configuration which uses a Chameleon text renderer:

1
2
3
4

 config.add_view('myproject.views.hello_world',
                 name='hello',
                 context='myproject.resources.Hello',
                 renderer='myproject:templates/foo.txt')

Views which use a Chameleon renderer can vary response attributes by attaching properties to the request. See Varying Attributes of Rendered Responses.

*.mak or *.mako: Mako Template Renderer

The Mako template renderer renders views using a Mako template. When used, the view must return a Response object or a Python dictionary. The dictionary items will then be used in the global template space. If the view callable returns anything but a Response object, or a dictionary, an error will be raised.

When using a renderer argument to a view configuration to specify a Mako template, the value of the renderer may be a path relative to the mako.directories setting (e.g. some/template.mak) or, alternately, it may be a asset specification (e.g. apackage:templates/sometemplate.mak). Mako templates may internally inherit other Mako templates using a relative filename or a asset specification as desired.

Here’s an example view configuration which uses a relative path:

1
2
3
4
5
6

 # config is an instance of pyramid.config.Configurator

 config.add_view('myproject.views.hello_world',
                 name='hello',
                 context='myproject.resources.Hello',
                 renderer='foo.mak')

It’s important to note that in Mako’s case, the ‘relative’ path name foo.mak above is not relative to the package, but is relative to the directory (or directories) configured for Mako via the mako.directories configuration file setting.

The renderer can also be provided in asset specification format. Here’s an example view configuration which uses one:

1
2
3
4

 config.add_view('myproject.views.hello_world',
                 name='hello',
                 context='myproject.resources.Hello',
                 renderer='mypackage:templates/foo.mak')

The above configuration will use the file named foo.mak in the templates directory of the mypackage package.

The Mako template renderer can take additional arguments beyond the standard reload_templates setting, see the Environment Variables and .ini File Settings for additional Mako Template Render Settings.

Varying Attributes of Rendered Responses

Before a response constructed by a renderer is returned to Pyramid, several attributes of the request are examined which have the potential to influence response behavior.

View callables that don’t directly return a response should set these attributes on the request object via setattr during their execution, to influence associated response attributes.

response_content_type

Defines the content-type of the resulting response, e.g. text/xml.

response_headerlist

A sequence of tuples describing cookie values that should be set in the response, e.g. [('Set-Cookie', 'abc=123'), ('X-My-Header', 'foo')].

response_status

A WSGI-style status code (e.g. 200 OK) describing the status of the response.

response_charset

The character set (e.g. UTF-8) of the response.

response_cache_for

A value in seconds which will influence Cache-Control and Expires headers in the returned response. The same can also be achieved by returning various values in the response_headerlist, this is purely a convenience.

For example, if you need to change the response status from within a view callable that uses a renderer, assign the response_status attribute to the request before returning a result:

1
2
3
4
5
6

from pyramid.view import view_config

@view_config(name='gone', renderer='templates/gone.pt')
def myview(request):
    request.response_status = '404 Not Found'
    return {'URL':request.URL}

For more information on attributes of the request, see the API documentation in pyramid.request.

Adding and Changing Renderers

New templating systems and serializers can be associated with Pyramid renderer names. To this end, configuration declarations can be made which change an existing renderer factory, and which add a new renderer factory.

Renderers can be registered imperatively using the pyramid.config.Configurator.add_renderer() API.

For example, to add a renderer which renders views which have a renderer attribute that is a path that ends in .jinja2:

1

config.add_renderer('.jinja2', 'mypackage.MyJinja2Renderer')

The first argument is the renderer name. The second argument is a reference to an implementation of a renderer factory or a dotted Python name referring to such an object.

Adding a New Renderer

You may add a new renderer by creating and registering a renderer factory.

A renderer factory implementation is typically a class with the following interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

class RendererFactory:
    def __init__(self, info):
        """ Constructor: info will be an object having the the
        following attributes: name (the renderer name), package
        (the package that was 'current' at the time the
        renderer was registered), type (the renderer type
        name), registry (the current application registry) and
        settings (the deployment settings dictionary).  """

    def __call__(self, value, system):
        """ Call a the renderer implementation with the value
        and the system value passed in as arguments and return
        the result (a string or unicode object).  The value is
        the return value of a view.  The system value is a
        dictionary containing available system values
        (e.g. view, context, and request). """

The formal interface definition of the info object passed to a renderer factory constructor is available as pyramid.interfaces.IRendererInfo.

There are essentially two different kinds of renderer factories:

A renderer factory which expects to accept a asset specification, or an absolute path, as the name attribute of the info object fed to its constructor. These renderer factories are registered with a name value that begins with a dot (.). These types of renderer factories usually relate to a file on the filesystem, such as a template.

A renderer factory which expects to accept a token that does not represent a filesystem path or an asset specification in the name attribute of the info object fed to its constructor. These renderer factories are registered with a name value that does not begin with a dot. These renderer factories are typically object serializers.

Asset Specifications

An asset specification is a colon-delimited identifier for an asset. The colon separates a Python package name from a package subpath. For example, the asset specification my.package:static/baz.css identifies the file named baz.css in the static subdirectory of the my.package Python package.

Here’s an example of the registration of a simple renderer factory via add_renderer():

1
2
3

# config is an instance of pyramid.config.Configurator

config.add_renderer(name='amf', factory='my.package.MyAMFRenderer')

Adding the above code to your application startup configuration will allow you to use the my.package.MyAMFRenderer renderer factory implementation in view configurations. Your application can use this renderer by specifying amf in the renderer attribute of a view configuration:

1
2
3
4
5

from pyramid.view import view_config

@view_config(renderer='amf')
def myview(request):
    return {'Hello':'world'}

At startup time, when a view configuration is encountered, which has a name attribute that does not contain a dot, the full name value is used to construct a renderer from the associated renderer factory. In this case, the view configuration will create an instance of an AMFRenderer for each view configuration which includes amf as its renderer value. The name passed to the AMFRenderer constructor will always be amf.

Here’s an example of the registration of a more complicated renderer factory, which expects to be passed a filesystem path:

1
2

config.add_renderer(name='.jinja2',
                    factory='my.package.MyJinja2Renderer')

Adding the above code to your application startup will allow you to use the my.package.MyJinja2Renderer renderer factory implementation in view configurations by referring to any renderer which ends in .jinja in the renderer attribute of a view configuration:

1
2
3
4
5

from pyramid.view import view_config

@view_config(renderer='templates/mytemplate.jinja2')
def myview(request):
    return {'Hello':'world'}

When a view configuration is encountered at startup time, which has a name attribute that does contain a dot, the value of the name attribute is split on its final dot. The second element of the split is typically the filename extension. This extension is used to look up a renderer factory for the configured view. Then the value of renderer is passed to the factory to create a renderer for the view. In this case, the view configuration will create an instance of a Jinja2Renderer for each view configuration which includes anything ending with .jinja2 in its renderer value. The name passed to the Jinja2Renderer constructor will be the full value that was set as renderer= in the view configuration.

Changing an Existing Renderer

You can associate more than one filename extension with the same existing renderer implementation as necessary if you need to use a different file extension for the same kinds of templates. For example, to associate the .zpt extension with the Chameleon ZPT renderer factory, use the pyramid.config.Configurator.add_renderer() method:

1

config.add_renderer('.zpt', 'pyramid.chameleon_zpt.renderer_factory')

After you do this, Pyramid will treat templates ending in both the .pt and .zpt filename extensions as Chameleon ZPT templates.

To change the default mapping in which files with a .pt extension are rendered via a Chameleon ZPT page template renderer, use a variation on the following in your application’s startup code:

1

config.add_renderer('.pt', 'mypackage.pt_renderer')

After you do this, the renderer factory in mypackage.pt_renderer will be used to render templates which end in .pt, replacing the default Chameleon ZPT renderer.

To associate a default renderer with all view configurations (even ones which do not possess a renderer attribute), pass None as the name attribute to the renderer tag:

1

config.add_renderer(None, 'mypackage.json_renderer_factory')

Overriding A Renderer At Runtime

Warning

This is an advanced feature, not typically used by “civilians”.

In some circumstances, it is necessary to instruct the system to ignore the static renderer declaration provided by the developer in view configuration, replacing the renderer with another after a request starts. For example, an “omnipresent” XML-RPC implementation that detects that the request is from an XML-RPC client might override a view configuration statement made by the user instructing the view to use a template renderer with one that uses an XML-RPC renderer. This renderer would produce an XML-RPC representation of the data returned by an arbitrary view callable.

To use this feature, create a NewRequest subscriber which sniffs at the request data and which conditionally sets an override_renderer attribute on the request itself, which is the name of a registered renderer. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from pyramid.event import subscriber
from pyramid.event import NewRequest

@subscriber(NewRequest)
def set_xmlrpc_params(event):
    request = event.request
    if (request.content_type == 'text/xml'
        and request.method == 'POST'
        and not 'soapaction' in request.headers
        and not 'x-pyramid-avoid-xmlrpc' in request.headers):
        params, method = parse_xmlrpc_request(request)
        request.xmlrpc_params, request.xmlrpc_method = params, method
        request.is_xmlrpc = True
        request.override_renderer = 'xmlrpc'
        return True

The result of such a subscriber will be to replace any existing static renderer configured by the developer with a (notional, nonexistent) XML-RPC renderer if the request appears to come from an XML-RPC client.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Templates

A template is a file on disk which can be used to render dynamic data provided by a view. Pyramid offers a number of ways to perform templating tasks out of the box, and provides add-on templating support through a set of bindings packages.

Out of the box, Pyramid provides templating via the Chameleon and Mako templating libraries. Chameleon provides support for two different types of templates: ZPT templates, and text templates.

Before discussing how built-in templates are used in detail, we’ll discuss two ways to render templates within Pyramid in general: directly, and via renderer configuration.

Using Templates Directly

The most straightforward way to use a template within Pyramid is to cause it to be rendered directly within a view callable. You may use whatever API is supplied by a given templating engine to do so.

Pyramid provides various APIs that allow you to render templates directly from within a view callable. For example, if there is a Chameleon ZPT template named foo.pt in a directory named templates in your application, you can render the template from within the body of a view callable like so:

1
2
3
4
5
6

from pyramid.renderers import render_to_response

def sample_view(request):
    return render_to_response('templates/foo.pt',
                              {'foo':1, 'bar':2},
                              request=request)

Warning

Earlier iterations of this documentation (pre-version-1.3) encouraged the application developer to use ZPT-specific APIs such as pyramid.chameleon_zpt.render_template_to_response() and pyramid.chameleon_zpt.render_template() to render templates directly. This style of rendering still works, but at least for purposes of this documentation, those functions are deprecated. Application developers are encouraged instead to use the functions available in the pyramid.renderers module to perform rendering tasks. This set of functions works to render templates for all renderer extensions registered with Pyramid.

The sample_view view callable function above returns a response object which contains the body of the templates/foo.pt template. In this case, the templates directory should live in the same directory as the module containing the sample_view function. The template author will have the names foo and bar available as top-level names for replacement or comparison purposes.

In the example above, the path templates/foo.pt is relative to the directory containing the file which defines the view configuration. In this case, this is the directory containing the file that defines the sample_view function. Although a renderer path is usually just a simple relative pathname, a path named as a renderer can be absolute, starting with a slash on UNIX or a drive letter prefix on Windows.

Warning

Only Chameleon templates support defining a renderer for a template relative to the location of the module where the view callable is defined. Mako templates, and other templating system bindings work differently. In particular, Mako templates use a “lookup path” as defined by the mako.directories configuration file instead of treating relative paths as relative to the current view module. See Templating With Mako Templates.

The path can alternately be a asset specification in the form some.dotted.package_name:relative/path. This makes it possible to address template assets which live in another package. For example:

1
2
3
4
5
6

from pyramid.renderers import render_to_response

def sample_view(request):
    return render_to_response('mypackage:templates/foo.pt',
                              {'foo':1, 'bar':2},
                              request=request)

An asset specification points at a file within a Python package. In this case, it points at a file named foo.pt within the templates directory of the mypackage package. Using a asset specification instead of a relative template name is usually a good idea, because calls to render_to_response using asset specifications will continue to work properly if you move the code containing them around.

Note

Mako templating system bindings also respect absolute asset specifications as an argument to any of the render* commands. If a template name defines a : (colon) character and is not an absolute path, it is treated as an absolute asset specification.

In the examples above we pass in a keyword argument named request representing the current Pyramid request. Passing a request keyword argument will cause the render_to_response function to supply the renderer with more correct system values (see System Values Used During Rendering), because most of the information required to compose proper system values is present in the request. If your template relies on the name request or context, or if you’ve configured special renderer globals, make sure to pass request as a keyword argument in every call to to a pyramid.renderers.render_* function.

Every view must return a response object, except for views which use a renderer named via view configuration (which we’ll see shortly). The pyramid.renderers.render_to_response() function is a shortcut function that actually returns a response object. This allows the example view above to simply return the result of its call to render_to_response() directly.

Obviously not all APIs you might call to get response data will return a response object. For example, you might render one or more templates to a string that you want to use as response data. The pyramid.renderers.render() API renders a template to a string. We can manufacture a response object directly, and use that string as the body of the response:

1
2
3
4
5
6
7
8
9

from pyramid.renderers import render
from pyramid.response import Response

def sample_view(request):
    result = render('mypackage:templates/foo.pt',
                    {'foo':1, 'bar':2},
                    request=request)
    response = Response(result)
    return response

Because view callable functions are typically the only code in Pyramid that need to know anything about templates, and because view functions are very simple Python, you can use whatever templating system you’re most comfortable with within Pyramid. Install the templating system, import its API functions into your views module, use those APIs to generate a string, then return that string as the body of a Pyramid Response object.

For example, here’s an example of using “raw” Mako [http://www.makotemplates.org/] from within a Pyramid view:

1
2
3
4
5
6
7
8

from mako.template import Template
from pyramid.response import Response

def make_view(request):
    template = Template(filename='/templates/template.mak')
    result = template.render(name=request.params['name'])
    response = Response(result)
    return response

You probably wouldn’t use this particular snippet in a project, because it’s easier to use the Mako renderer bindings which already exist in Pyramid. But if your favorite templating system is not supported as a renderer extension for Pyramid, you can create your own simple combination as shown above.

Note

If you use third-party templating languages without cooperating Pyramid bindings directly within view callables, the auto-template-reload strategy explained in Automatically Reloading Templates will not be available, nor will the template asset overriding capability explained in Overriding Assets be available, nor will it be possible to use any template using that language as a renderer. However, it’s reasonably easy to write custom templating system binding packages for use under Pyramid so that templates written in the language can be used as renderers. See Adding and Changing Renderers for instructions on how to create your own template renderer and Available Add-On Template System Bindings for example packages.

If you need more control over the status code and content-type, or other response attributes from views that use direct templating, you may set attributes on the response that influence these values.

Here’s an example of changing the content-type and status of the response object returned by render_to_response():

1
2
3
4
5
6
7
8
9

from pyramid.renderers import render_to_response

def sample_view(request):
    response = render_to_response('templates/foo.pt',
                                  {'foo':1, 'bar':2},
                                  request=request)
    response.content_type = 'text/plain'
    response.status_int = 204
    return response

Here’s an example of manufacturing a response object using the result of render() (a string):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from pyramid.renderers import render
from pyramid.response import Response

def sample_view(request):
    result = render('mypackage:templates/foo.pt',
                    {'foo':1, 'bar':2},
                    request=request)
    response = Response(result)
    response.content_type = 'text/plain'
    return response

System Values Used During Rendering

When a template is rendered using render_to_response() or render(), the renderer representing the template will be provided with a number of system values. These values are provided in a dictionary to the renderer and include:

context

The current Pyramid context if request was provided as a keyword argument, or None.

request

The request provided as a keyword argument.

renderer_name

The renderer name used to perform the rendering, e.g. mypackage:templates/foo.pt.

renderer_info

An object implementing the pyramid.interfaces.IRendererInfo interface. Basically, an object with the following attributes: name, package and type.

You can define more values which will be passed to every template executed as a result of rendering by defining renderer globals.

What any particular renderer does with these system values is up to the renderer itself, but most template renderers, including Chameleon and Mako renderers, make these names available as top-level template variables.

Templates Used as Renderers via Configuration

An alternative to using render_to_response() to render templates manually in your view callable code, is to specify the template as a renderer in your view configuration. This can be done with any of the templating languages supported by Pyramid.

To use a renderer via view configuration, specify a template asset specification as the renderer argument, or attribute to the view configuration of a view callable. Then return a dictionary from that view callable. The dictionary items returned by the view callable will be made available to the renderer template as top-level names.

The association of a template as a renderer for a view configuration makes it possible to replace code within a view callable that handles the rendering of a template.

Here’s an example of using a view_config decorator to specify a view configuration that names a template renderer:

1
2
3
4
5

from pyramid.view import view_config

@view_config(renderer='templates/foo.pt')
def my_view(request):
    return {'foo':1, 'bar':2}

Note

You do not need to supply the request value as a key in the dictionary result returned from a renderer-configured view callable. Pyramid automatically supplies this value for you so that the “most correct” system values are provided to the renderer.

Warning

The renderer argument to the @view_config configuration decorator shown above is the template path. In the example above, the path templates/foo.pt is relative. Relative to what, you ask? Because we’re using a Chameleon renderer, it means “relative to the directory in which the file which defines the view configuration lives”. In this case, this is the directory containing the file that defines the my_view function. View-configuration-relative asset specifications work only in Chameleon, not in Mako templates.

Similar renderer configuration can be done imperatively and via ZCML. See Writing View Callables Which Use a Renderer. See also Built-In Renderers.

Although a renderer path is usually just a simple relative pathname, a path named as a renderer can be absolute, starting with a slash on UNIX or a drive letter prefix on Windows. The path can alternately be an asset specification in the form some.dotted.package_name:relative/path, making it possible to address template assets which live in another package.

Not just any template from any arbitrary templating system may be used as a renderer. Bindings must exist specifically for Pyramid to use a templating language template as a renderer. Currently, Pyramid has built-in support for two Chameleon templating languages: ZPT and text, and the Mako templating system. See Built-In Renderers for a discussion of their details. Pyramid also supports the use of Jinja2 templates as renderers. See Available Add-On Template System Bindings.

Why Use A Renderer via View Configuration

Using a renderer in view configuration is usually a better way to render templates than using any rendering API directly from within a view callable because it makes the view callable more unit-testable. Views which use templating or rendering APIs directly must return a Response object. Making testing assertions about response objects is typically an indirect process, because it means that your test code often needs to somehow parse information out of the response body (often HTML). View callables configured with renderers externally via view configuration typically return a dictionary, as above. Making assertions about results returned in a dictionary is almost always more direct and straightforward than needing to parse HTML. Specifying a renderer from within ZCML (as opposed to imperatively or via a view_config decorator, or using a template directly from within a view callable) also makes it possible for someone to modify the template used to render a view without needing to fork your code to do so. See Extending An Existing Pyramid Application for more information.

By default, views rendered via a template renderer return a Response object which has a status code of 200 OK, and a content-type of text/html. To vary attributes of the response of a view that uses a renderer, such as the content-type, headers, or status attributes, you must set attributes on the request object within the view before returning the dictionary. See Varying Attributes of Rendered Responses for more information.

The same set of system values are provided to templates rendered via a renderer view configuration as those provided to templates rendered imperatively. See System Values Used During Rendering.

Chameleon ZPT Templates

Like Zope, Pyramid uses ZPT (Zope Page Templates) as its default templating language. However, Pyramid uses a different implementation of the ZPT specification than Zope does: the Chameleon templating engine. The Chameleon engine complies largely with the Zope Page Template [http://wiki.zope.org/ZPT/FrontPage] template specification. However, it is significantly faster.

The language definition documentation for Chameleon ZPT-style templates is available from the Chameleon website [http://chameleon.repoze.org/].

Warning

Chameleon only works on CPython platforms and Google App Engine. On Jython and other non-CPython platforms, you should use Mako (see Templating With Mako Templates) or pyramid_jinja2 instead. See Available Add-On Template System Bindings.

Given a Chameleon ZPT template named foo.pt in a directory in your application named templates, you can render the template as a renderer like so:

1
2
3
4
5

from pyramid.view import view_config

@view_config(renderer='templates/foo.pt')
def my_view(request):
    return {'foo':1, 'bar':2}

See also Built-In Renderers for more general information about renderers, including Chameleon ZPT renderers.

A Sample ZPT Template

Here’s what a simple Chameleon ZPT template used under Pyramid might look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml"
       xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head>
     <meta http-equiv="content-type" content="text/html; charset=utf-8" />
     <title>${project} Application</title>
 </head>
   <body>
      <h1 class="title">Welcome to <code>${project}</code>, an
       application generated by the <a
       href="http://docs.pylonsproject.org/projects/pyramid/dev/"
      >pyramid</a> web
       application framework.</h1>
   </body>
 </html>

Note the use of Genshi -style ${replacements} above. This is one of the ways that Chameleon ZPT differs from standard ZPT. The above template expects to find a project key in the set of keywords passed in to it via render() or render_to_response(). Typical ZPT attribute-based syntax (e.g. tal:content and tal:replace) also works in these templates.

Using ZPT Macros in Pyramid

When a renderer is used to render a template, Pyramid makes at least two top-level names available to the template by default: context and request. One of the common needs in ZPT-based templates is to use one template’s “macros” from within a different template. In Zope, this is typically handled by retrieving the template from the context. But the context in Pyramid is a resource object, and templates cannot usually be retrieved from resources. To use macros in Pyramid, you need to make the macro template itself available to the rendered template by passing the macro template, or even the macro itself, into the rendered template. To do this you can use the pyramid.renderers.get_renderer() API to retrieve the macro template, and pass it into the template being rendered via the dictionary returned by the view. For example, using a view configuration via a view_config decorator that uses a renderer:

1
2
3
4
5
6
7

from pyramid.renderers import get_renderer
from pyramid.view import view_config

@view_config(renderer='templates/mytemplate.pt')
def my_view(request):
    main = get_renderer('templates/master.pt').implementation()
    return {'main':main}

Where templates/master.pt might look like so:

1
2
3
4
5
6
7
8
9

 <html xmlns="http://www.w3.org/1999/xhtml"
       xmlns:tal="http://xml.zope.org/namespaces/tal"
       xmlns:metal="http://xml.zope.org/namespaces/metal">
   <span metal:define-macro="hello">
     <h1>
       Hello <span metal:define-slot="name">Fred</span>!
     </h1>
   </span>
 </html>

And templates/mytemplate.pt might look like so:

1
2
3
4
5
6
7

 <html xmlns="http://www.w3.org/1999/xhtml"
       xmlns:tal="http://xml.zope.org/namespaces/tal"
       xmlns:metal="http://xml.zope.org/namespaces/metal">
   <span metal:use-macro="main.macros['hello']">
     <span metal:fill-slot="name">Chris</span>
   </span>
 </html>

Templating with Chameleon Text Templates

Pyramid also allows for the use of templates which are composed entirely of non-XML text via Chameleon. To do so, you can create templates that are entirely composed of text except for ${name} -style substitution points.

Here’s an example usage of a Chameleon text template. Create a file on disk named mytemplate.txt in your project’s templates directory with the following contents:

Hello, ${name}!

Then in your project’s views.py module, you can create a view which renders this template:

1
2
3
4
5

from pyramid.view import view_config

@view_config(renderer='templates/mytemplate.txt')
def my_view(request):
    return {'name':'world'}

When the template is rendered, it will show:

Hello, world!

If you’d rather use templates directly within a view callable (without the indirection of using a renderer), see pyramid.chameleon_text for the API description.

See also Built-In Renderers for more general information about renderers, including Chameleon text renderers.

Side Effects of Rendering a Chameleon Template

When a Chameleon template is rendered from a file, the templating engine writes a file in the same directory as the template file itself as a kind of cache, in order to do less work the next time the template needs to be read from disk. If you see “strange” .py files showing up in your templates directory (or otherwise directly “next” to your templates), it is due to this feature.

If you’re using a version control system such as Subversion, you should configure it to ignore these files. Here’s the contents of the author’s svn propedit svn:ignore . in each of my templates directories.

*.pt.py
*.txt.py

Note that I always name my Chameleon ZPT template files with a .pt extension and my Chameleon text template files with a .txt extension so that these svn:ignore patterns work.

Nicer Exceptions in Chameleon Templates

The exceptions raised by Chameleon templates when a rendering fails are sometimes less than helpful. Pyramid allows you to configure your application development environment so that exceptions generated by Chameleon during template compilation and execution will contain nicer debugging information.

Warning

Template-debugging behavior is not recommended for production sites as it slows renderings; it’s usually only desirable during development.

In order to turn on template exception debugging, you can use an environment variable setting or a configuration file setting.

To use an environment variable, start your application under a shell using the PYRAMID_DEBUG_TEMPLATES operating system environment variable set to 1, For example:

$ PYRAMID_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini

To use a setting in the application .ini file for the same purpose, set the debug_templates key to true within the application’s configuration section, e.g.:

1
2
3

[app:MyProject]
use = egg:MyProject#app
debug_templates = true

With template debugging off, a NameError exception resulting from rendering a template with an undefined variable (e.g. ${wrong}) might end like this:

File "...", in __getitem__
  raise NameError(key)
NameError: wrong

Note that the exception has no information about which template was being rendered when the error occured. But with template debugging on, an exception resulting from the same problem might end like so:

RuntimeError: Caught exception rendering template.
 - Expression: ``wrong``
 - Filename:   /home/fred/env/proj/proj/templates/mytemplate.pt
 - Arguments:  renderer_name: proj:templates/mytemplate.pt
               template: <PageTemplateFile - at 0x1d2ecf0>
               xincludes: <XIncludes - at 0x1d3a130>
               request: <Request - at 0x1d2ecd0>
               project: proj
               macros: <Macros - at 0x1d3aed0>
               context: <MyResource None at 0x1d39130>
               view: <function my_view at 0x1d23570>

NameError: wrong

The latter tells you which template the error occurred in, as well as displaying the arguments passed to the template itself.

Note

Turning on debug_templates has the same effect as using the Chameleon environment variable CHAMELEON_DEBUG. See Chameleon Environment Variables [http://chameleon.repoze.org/docs/latest/config.html#environment-variables] for more information.

Chameleon Template Internationalization

See Chameleon Template Support for Translation Strings for information about supporting internationalized units of text within Chameleon templates.

Templating With Mako Templates

Mako is a templating system written by Mike Bayer. Pyramid has built-in bindings for the Mako templating system. The language definition documentation for Mako templates is available from the Mako website [http://www.makotemplates.org/].

To use a Mako template, given a Mako ZPT template file named foo.mak in the templates subdirectory in your application package named mypackage, you can configure the template as a renderer like so:

1
2
3
4
5

from pyramid.view import view_config

@view_config(renderer='foo.mak')
def my_view(request):
    return {'project':'my project'}

For the above view callable to work, the following setting needs to be present in the application stanza of your configuration’s ini file:

mako.directories = mypackage:templates

This lets the Mako templating system know that it should look for templates in the templates subdirectory of the mypackage Python package. See Mako Template Render Settings for more information about the mako.directories setting and other Mako-related settings that can be placed into the application’s ini file.

A Sample Mako Template

Here’s what a simple Mako template used under Pyramid might look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml"
       xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head>
     <meta http-equiv="content-type" content="text/html; charset=utf-8" />
     <title>${project} Application</title>
 </head>
   <body>
      <h1 class="title">Welcome to <code>${project}</code>, an
       application generated by the <a
       href="http://docs.pylonsproject.org/projects/pyramid/dev/"
      >pyramid</a> web application framework.</h1>
   </body>
 </html>

This template doesn’t use any advanced features of Mako, only the ${squiggly} replacement syntax for names that are passed in as renderer globals. See the the Mako documentation [http://www.makotemplates.org/] to use more advanced features.

Automatically Reloading Templates

It’s often convenient to see changes you make to a template file appear immediately without needing to restart the application process. Pyramid allows you to configure your application development environment so that a change to a template will be automatically detected, and the template will be reloaded on the next rendering.

Warning

Auto-template-reload behavior is not recommended for production sites as it slows rendering slightly; it’s usually only desirable during development.

In order to turn on automatic reloading of templates, you can use an environment variable, or a configuration file setting.

To use an environment variable, start your application under a shell using the PYRAMID_RELOAD_TEMPLATES operating system environment variable set to 1, For example:

$ PYRAMID_RELOAD_TEMPLATES=1 bin/paster serve myproject.ini

To use a setting in the application .ini file for the same purpose, set the reload_templates key to true within the application’s configuration section, e.g.:

1
2
3

[app:main]
use = egg:MyProject#app
reload_templates = true

Available Add-On Template System Bindings

Jinja2 template bindings are available for Pyramid in the pyramid_jinja2 package. You can get the latest release of this package from the Python package index [http://pypi.python.org/pypi/pyramid_jinja2] (pypi).

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

View Configuration

View configuration controls how view lookup operates in your application. In earlier chapters, you have been exposed to a few simple view configuration declarations without much explanation. In this chapter we will explore the subject in detail.

View Lookup and Invocation

View lookup is the Pyramid subsystem responsible for finding an invoking a view callable. The view lookup subsystem is passed a context and a request object.

View configuration information stored within in the application registry is compared against the context and request by the view lookup subsystem in order to find the “best” view callable for the set of circumstances implied by the context and request.

View predicate attributes are an important part of view configuration that enables the View lookup subsystem to find and invoke the appropriate view. Predicate attributes can be thought of like “narrowers”. In general, the greater number of predicate attributes possessed by a view’s configuration, the more specific the circumstances need to be before the registered view callable will be invoked.

Mapping a Resource or URL Pattern to a View Callable

A developer makes a view callable available for use within a Pyramid application via view configuration. A view configuration associates a view callable with a set of statements that determine the set of circumstances which must be true for the view callable to be invoked.

A view configuration statement is made about information present in the context resource and the request.

View configuration is performed in one of these ways:

by running a scan against application source code which has a pyramid.view.view_config decorator attached to a Python object as per View Configuration Using the @view_config Decorator.

by using the pyramid.config.Configurator.add_view() method as per View Registration Using add_view().

By specifying a view within a route configuration. View configuration via a route configuration is performed by using the pyramid.config.Configurator.add_route() method, passing a view argument specifying a view callable.

Note

A package named pyramid_handlers (available from PyPI) provides an analogue of Pylons -style “controllers”, which are a special kind of view class which provides more automation when your application uses URL dispatch solely.

View Configuration Parameters

All forms of view configuration accept the same general types of arguments.

Many arguments supplied during view configuration are view predicate arguments. View predicate arguments used during view configuration are used to narrow the set of circumstances in which view lookup will find a particular view callable.

In general, the fewer number of predicates which are supplied to a particular view configuration, the more likely it is that the associated view callable will be invoked. The greater the number supplied, the less likely. A view with five predicates will always be found and evaluated before a view with two, for example. All predicates must match for the associated view to be called.

This does not mean however, that Pyramid “stops looking” when it finds a view registration with predicates that don’t match. If one set of view predicates does not match, the “next most specific” view (if any) is consulted for predicates, and so on, until a view is found, or no view can be matched up with the request. The first view with a set of predicates all of which match the request environment will be invoked.

If no view can be found with predicates which allow it to be matched up with the request, Pyramid will return an error to the user’s browser, representing a “not found” (404) page. See Changing the Not Found View for more information about changing the default notfound view.

Some view configuration arguments are non-predicate arguments. These tend to modify the response of the view callable or prevent the view callable from being invoked due to an authorization policy. The presence of non-predicate arguments in a view configuration does not narrow the circumstances in which the view callable will be invoked.

Non-Predicate Arguments

permission

The name of a permission that the user must possess in order to invoke the view callable. See Configuring View Security for more information about view security and permissions.

If permission is not supplied, no permission is registered for this view (it’s accessible by any caller).

attr

The view machinery defaults to using the __call__ method of the view callable (or the function itself, if the view callable is a function) to obtain a response. The attr value allows you to vary the method attribute used to obtain the response. For example, if your view was a class, and the class has a method named index and you wanted to use this method instead of the class’ __call__ method to return the response, you’d say attr="index" in the view configuration for the view. This is most useful when the view definition is a class.

If attr is not supplied, None is used (implying the function itself if the view is a function, or the __call__ callable attribute if the view is a class).

renderer

Denotes the renderer implementation which will be used to construct a response from the associated view callable’s return value. (see also Renderers).

This is either a single string term (e.g. json) or a string implying a path or asset specification (e.g. templates/views.pt) naming a renderer implementation. If the renderer value does not contain a dot (.), the specified string will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the view return value. If the renderer value contains a dot (.), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path.

When the renderer is a path, although a path is usually just a simple relative pathname (e.g. templates/foo.pt, implying that a template named “foo.pt” is in the “templates” directory relative to the directory of the current package), a path can be absolute, starting with a slash on UNIX or a drive letter prefix on Windows. The path can alternately be a asset specification in the form some.dotted.package_name:relative/path, making it possible to address template assets which live in a separate package.

The renderer attribute is optional. If it is not defined, the “null” renderer is assumed (no rendering is performed and the value is passed back to the upstream Pyramid machinery unmolested). Note that if the view callable itself returns a response (see View Callable Responses), the specified renderer implementation is never called.

wrapper

The view name of a different view configuration which will receive the response body of this view as the request.wrapped_body attribute of its own request, and the response returned by this view as the request.wrapped_response attribute of its own request. Using a wrapper makes it possible to “chain” views together to form a composite response. The response of the outermost wrapper view will be returned to the user. The wrapper view will be found as any view is found: see View Lookup and Invocation. The “best” wrapper view will be found based on the lookup ordering: “under the hood” this wrapper view is looked up via pyramid.view.render_view_to_response(context, request, 'wrapper_viewname'). The context and request of a wrapper view is the same context and request of the inner view.

If wrapper is not supplied, no wrapper view is used.

decorator

A dotted Python name to function (or the function itself) which will be used to decorate the registered view callable. The decorator function will be called with the view callable as a single argument. The view callable it is passed will accept (context, request). The decorator must return a replacement view callable which also accepts (context, request).

mapper

A Python object or dotted Python name which refers to a view mapper, or None. By default it is None, which indicates that the view should use the default view mapper. This plug-point is useful for Pyramid extension developers, but it’s not very useful for ‘civilians’ who are just developing stock Pyramid applications. Pay no attention to the man behind the curtain.

Predicate Arguments

These arguments modify view lookup behavior. In general, the more predicate arguments that are supplied, the more specific, and narrower the usage of the configured view.

name

The view name required to match this view callable. Read Traversal to understand the concept of a view name.

If name is not supplied, the empty string is used (implying the default view).

context

An object representing a Python class that the context resource must be an instance of or the interface that the context resource must provide in order for this view to be found and called. This predicate is true when the context resource is an instance of the represented class or if the context resource provides the represented interface; it is otherwise false.

If context is not supplied, the value None, which matches any resource, is used.

route_name

If route_name is supplied, the view callable will be invoked only when the named route has matched.

This value must match the name of a route configuration declaration (see URL Dispatch) that must match before this view will be called. Note that the route configuration referred to by route_name will usually have a *traverse token in the value of its pattern, representing a part of the path that will be used by traversal against the result of the route’s root factory.

If route_name is not supplied, the view callable will be have a chance of being invoked if no other route was matched. This is when the request/context pair found via resource location does not indicate it matched any configured route.

request_type

This value should be an interface that the request must provide in order for this view to be found and called.

If request_type is not supplied, the value None is used, implying any request type.

This is an advanced feature, not often used by “civilians”.

request_method

This value can either be one of the strings GET, POST, PUT, DELETE, or HEAD representing an HTTP REQUEST_METHOD. A view declaration with this argument ensures that the view will only be called when the request’s method attribute (aka the REQUEST_METHOD of the WSGI environment) string matches the supplied value.

If request_method is not supplied, the view will be invoked regardless of the REQUEST_METHOD of the WSGI environment.

request_param

This value can be any string. A view declaration with this argument ensures that the view will only be called when the request has a key in the request.params dictionary (an HTTP GET or POST variable) that has a name which matches the supplied value.

If the value supplied has a = sign in it, e.g. request_params="foo=123", then the key (foo) must both exist in the request.params dictionary, and the value must match the right hand side of the expression (123) for the view to “match” the current request.

If request_param is not supplied, the view will be invoked without consideration of keys and values in the request.params dictionary.

containment

This value should be a reference to a Python class or interface that a parent object in the context resource’s lineage must provide in order for this view to be found and called. The resources in your resource tree must be “location-aware” to use this feature.

If containment is not supplied, the interfaces and classes in the lineage are not considered when deciding whether or not to invoke the view callable.

See Location-Aware Resources for more information about location-awareness.

xhr

This value should be either True or False. If this value is specified and is True, the WSGI environment must possess an HTTP_X_REQUESTED_WITH (aka X-Requested-With) header that has the value XMLHttpRequest for the associated view callable to be found and called. This is useful for detecting AJAX requests issued from jQuery, Prototype and other Javascript libraries.

If xhr is not specified, the HTTP_X_REQUESTED_WITH HTTP header is not taken into consideration when deciding whether or not to invoke the associated view callable.

accept

The value of this argument represents a match query for one or more mimetypes in the Accept HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form text/plain, a wildcard mimetype match token in the form text/* or a match-all wildcard mimetype match token in the form */*. If any of the forms matches the Accept header of the request, this predicate will be true.

If accept is not specified, the HTTP_ACCEPT HTTP header is not taken into consideration when deciding whether or not to invoke the associated view callable.

header

This value represents an HTTP header name or a header name/value pair.

If header is specified, it must be a header name or a headername:headervalue pair.

If header is specified without a value (a bare header name only, e.g. If-Modified-Since), the view will only be invoked if the HTTP header exists with any value in the request.

If header is specified, and possesses a name/value pair (e.g. User-Agent:Mozilla/.*), the view will only be invoked if the HTTP header exists and the HTTP header matches the value requested. When the headervalue contains a : (colon), it will be considered a name/value pair (e.g. User-Agent:Mozilla/.* or Host:localhost). The value portion should be a regular expression.

Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant.

If header is not specified, the composition, presence or absence of HTTP headers is not taken into consideration when deciding whether or not to invoke the associated view callable.

path_info

This value represents a regular expression pattern that will be tested against the PATH_INFO WSGI environment variable to decide whether or not to call the associated view callable. If the regex matches, this predicate will be True.

If path_info is not specified, the WSGI PATH_INFO is not taken into consideration when deciding whether or not to invoke the associated view callable.

custom_predicates

If custom_predicates is specified, it must be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates do what you need. Custom predicates can be combined with predefined predicates as necessary. Each custom predicate callable should accept two arguments: context and request and should return either True or False after doing arbitrary evaluation of the context resource and/or the request. If all callables return True, the associated view callable will be considered viable for a given request.

If custom_predicates is not specified, no custom predicates are used.

View Configuration Using the @view_config Decorator

For better locality of reference, you may use the pyramid.view.view_config decorator to associate your view functions with URLs instead of using imperative configuration for the same purpose.

Warning

Using this feature tends to slows down application startup slightly, as more work is performed at application startup to scan for view declarations.

Usage of the view_config decorator is a form of declarative configuration in decorator form. view_config can be used to associate view configuration information – as done via the equivalent imperative code – with a function that acts as a Pyramid view callable. All arguments to the pyramid.config.Configurator.add_view() method (save for the view argument) are available in decorator form and mean precisely the same thing.

An example of the view_config decorator might reside in a Pyramid application module views.py:

1
2
3
4
5
6
7
8

from resources import MyResource
from pyramid.view import view_config
from pyramid.response import Response

@view_config(name='my_view', request_method='POST', context=MyResource,
             permission='read')
def my_view(request):
    return Response('OK')

Using this decorator as above replaces the need to add this imperative configuration stanza:

1
2

config.add_view('.views.my_view', name='my_view', request_method='POST',
                context=MyResource, permission='read')

All arguments to view_config may be omitted. For example:

1
2
3
4
5
6
7

from pyramid.response import Response
from pyramid.view import view_config

@view_config()
def my_view(request):
    """ My view """
    return Response()

Such a registration as the one directly above implies that the view name will be my_view, registered with a context argument that matches any resource type, using no permission, registered against requests with any request method, request type, request param, route name, or containment.

The mere existence of a @view_config decorator doesn’t suffice to perform view configuration. All that the decorator does is “annotate” the function with your configuration declarations, it doesn’t process them. To make Pyramid process your view_config declarations, you must do use the scan method of a Configurator:

1
2
3

# config is assumed to be an instance of the
# pyramid.config.Configurator class
config.scan()

Please see Configuration Decorations and Code Scanning for detailed information about what happens when code is scanned for configuration declarations resulting from use of decorators like view_config.

See pyramid.config for additional API arguments to the scan() method. For example, the method allows you to supply a package argument to better control exactly which code will be scanned.

@view_config Placement

A view_config decorator can be placed in various points in your application.

If your view callable is a function, it may be used as a function decorator:

1
2
3
4
5
6

from pyramid.view import view_config
from pyramid.response import Response

@view_config(name='edit')
def edit(request):
    return Response('edited!')

If your view callable is a class, the decorator can also be used as a class decorator in Python 2.6 and better (Python 2.5 and below do not support class decorators). All the arguments to the decorator are the same when applied against a class as when they are applied against a function. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from pyramid.response import Response
from pyramid.view import view_config

@view_config()
class MyView(object):
    def __init__(self, request):
        self.request = request

    def __call__(self):
        return Response('hello')

You can use the view_config decorator as a simple callable to manually decorate classes in Python 2.5 and below without the decorator syntactic sugar, if you wish:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from pyramid.response import Response
from pyramid.view import view_config

class MyView(object):
    def __init__(self, request):
        self.request = request

    def __call__(self):
        return Response('hello')

my_view = view_config()(MyView)

More than one view_config decorator can be stacked on top of any number of others. Each decorator creates a separate view registration. For example:

1
2
3
4
5
6
7

from pyramid.view import view_config
from pyramid.response import Response

@view_config(name='edit')
@view_config(name='change')
def edit(request):
    return Response('edited!')

This registers the same view under two different names.

The decorator can also be used against class methods:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from pyramid.response import Response
from pyramid.view import view_config

class MyView(object):
    def __init__(self, request):
        self.request = request

    @view_config(name='hello')
    def amethod(self):
        return Response('hello')

When the decorator is used against a class method, a view is registered for the class, so the class constructor must accept an argument list in one of two forms: either it must accept a single argument request or it must accept two arguments, context, request.

The method which is decorated must return a response.

Using the decorator against a particular method of a class is equivalent to using the attr parameter in a decorator attached to the class itself. For example, the above registration implied by the decorator being used against the amethod method could be spelled equivalently as the below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from pyramid.response import Response
from pyramid.view import view_config

@view_config(attr='amethod', name='hello')
class MyView(object):
    def __init__(self, request):
        self.request = request

    def amethod(self):
        return Response('hello')

View Registration Using add_view()

The pyramid.config.Configurator.add_view() method within pyramid.config is used to configure a view imperatively. The arguments to this method are very similar to the arguments that you provide to the @view_config decorator. For example:

1
2
3
4
5
6
7
8

from pyramid.response import Response

def hello_world(request):
    return Response('hello!')

# config is assumed to be an instance of the
# pyramid.config.Configurator class
config.add_view(hello_world, name='hello.html')

The first argument, view, is required. It must either be a Python object which is the view itself or a dotted Python name to such an object. All other arguments are optional. See pyramid.config.Configurator.add_view() for more information.

Using Resource Interfaces In View Configuration

Instead of registering your views with a context that names a Python resource class, you can optionally register a view callable with a context which is an interface. An interface can be attached arbitrarily to any resource object. View lookup treats context interfaces specially, and therefore the identity of a resource can be divorced from that of the class which implements it. As a result, associating a view with an interface can provide more flexibility for sharing a single view between two or more different implementations of a resource type. For example, if two resource objects of different Python class types share the same interface, you can use the same view configuration to specify both of them as a context.

In order to make use of interfaces in your application during view dispatch, you must create an interface and mark up your resource classes or instances with interface declarations that refer to this interface.

To attach an interface to a resource class, you define the interface and use the zope.interface.implements() function to associate the interface with the class.

1
2
3
4
5
6
7
8

from zope.interface import Interface
from zope.interface import implements

class IHello(Interface):
    """ A marker interface """

class Hello(object):
    implements(IHello)

To attach an interface to a resource instance, you define the interface and use the zope.interface.alsoProvides() function to associate the interface with the instance. This function mutates the instance in such a way that the interface is attached to it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from zope.interface import Interface
from zope.interface import alsoProvides

class IHello(Interface):
    """ A marker interface """

class Hello(object):
    pass

def make_hello():
    hello = Hello()
    alsoProvides(hello, IHello)
    return hello

Regardless of how you associate an interface, with a resource instance, or a resource class, the resulting code to associate that interface with a view callable is the same. Assuming the above code that defines an IHello interface lives in the root of your application, and its module is named “resources.py”, the interface declaration below will associate the mypackage.views.hello_world view with resources that implement, or provide, this interface.

1
2
3
4

# config is an instance of pyramid.config.Configurator

config.add_view('mypackage.views.hello_world', name='hello.html',
                context='mypackage.resources.IHello')

Any time a resource that is determined to be the context provides this interface, and a view named hello.html is looked up against it as per the URL, the mypackage.views.hello_world view callable will be invoked.

Note, in cases where a view is registered against a resource class, and a view is also registered against an interface that the resource class implements, an ambiguity arises. Views registered for the resource class take precedence over any views registered for any interface the resource class implements. Thus, if one view configuration names a context of both the class type of a resource, and another view configuration names a context of interface implemented by the resource’s class, and both view configurations are otherwise identical, the view registered for the context’s class will “win”.

For more information about defining resources with interfaces for use within view configuration, see Resources Which Implement Interfaces.

Configuring View Security

If an authorization policy is active, any permission attached to a view configuration found during view lookup will be verified. This will ensure that the currently authenticated user possesses that permission against the context resource before the view function is actually called. Here’s an example of specifying a permission in a view configuration using add_view():

1
2
3
4

# config is an instance of pyramid.config.Configurator

config.add_view('myproject.views.add_entry', name='add.html',
                context='myproject.resources.IBlog', permission='add')

When an authorization policy is enabled, this view will be protected with the add permission. The view will not be called if the user does not possess the add permission relative to the current context. Instead the forbidden view result will be returned to the client as per Protecting Views with Permissions.

NotFound Errors

It’s useful to be able to debug NotFound error responses when they occur unexpectedly due to an application registry misconfiguration. To debug these errors, use the PYRAMID_DEBUG_NOTFOUND environment variable or the debug_notfound configuration file setting. Details of why a view was not found will be printed to stderr, and the browser representation of the error will include the same information. See Environment Variables and .ini File Settings for more information about how, and where to set these values.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Resources

A resource is an object that represents a “place” in a tree related to your application. Every Pyramid application has at least one resource object: the root resource. Even if you don’t define a root resource manually, a default one is created for you. The root resource is the root of a resource tree. A resource tree is a set of nested dictionary-like objects which you can use to represent your website’s structure.

In an application which uses traversal to map URLs to code, the resource tree structure is used heavily to map each URL to a view callable. When traversal is used, Pyramid will walk through the resource tree by traversing through its nested dictionary structure in order to find a context resource. Once a context resource is found, the context resource and data in the request will be used to find a view callable.

In an application which uses URL dispatch, the resource tree is only used indirectly, and is often “invisible” to the developer. In URL dispatch applications, the resource “tree” is often composed of only the root resource by itself. This root resource sometimes has security declarations attached to it, but is not required to have any. In general, the resource tree is much less important in applications that use URL dispatch than applications that use traversal.

In “Zope-like” Pyramid applications, resource objects also often store data persistently, and offer methods related to mutating that persistent data. In these kinds of applications, resources not only represent the site structure of your website, but they become the domain model of the application.

Also:

The context and containment predicate arguments to add_view() (or a view_config() decorator) reference a resource class or resource interface.

A root factory returns a resource.

A resource is exposed to view code as the context of a view.

Various helpful Pyramid API methods expect a resource as an argument (e.g. resource_url() and others).

Defining a Resource Tree

When traversal is used (as opposed to a purely url dispatch based application), Pyramid expects to be able to traverse a tree composed of resources (the resource tree). Traversal begins at a root resource, and descends into the tree recursively, trying each resource’s __getitem__ method to resolve a path segment to another resource object. Pyramid imposes the following policy on resource instances in the tree:

A container resource (a resource which contains other resources) must supply a __getitem__ method which is willing to resolve a unicode name to a sub-resource. If a sub-resource by a particular name does not exist in a container resource, __getitem__ method of the container resource must raise a KeyError. If a sub-resource by that name does exist, the container’s __getitem__ should return the sub-resource.

Leaf resources, which do not contain other resources, must not implement a __getitem__, or if they do, their __getitem__ method must always raise a KeyError.

See Traversal for more information about how traversal works against resource instances.

Here’s a sample resource tree, represented by a variable named root:

1
2
3
4

 class Resource(dict):
     pass

 root = Resource({'a':Resource({'b':Resource({'c':Resource()})})})

The resource tree we’ve created above is represented by a dictionary-like root object which has a single child named a. a has a single child named b, and b has a single child named c, which has no children. It is therefore possible to access c like so:

1

root['a']['b']['c']

If you returned the above root object from a root factory, the path /a/b/c would find the c object in the resource tree as the result of traversal.

In this example, each of the resources in the tree is of the same class. This is not a requirement. Resource elements in the tree can be of any type. We used a single class to represent all resources in the tree for the sake of simplicity, but in a “real” app, the resources in the tree can be arbitrary.

Although the example tree above can service a traversal, the resource instances in the above example are not aware of location, so their utility in a “real” application is limited. To make best use of built-in Pyramid API facilities, your resources should be “location-aware”. The next section details how to make resources location-aware.

Location-Aware Resources

In order for certain Pyramid location, security, URL-generation, and traversal APIs to work properly against the resources in a resource tree, all resources in the tree must be location -aware. This means they must have two attributes: __parent__ and __name__.

The __parent__ attribute of a location-aware resource should be a reference to the resource’s parent resource instance in the tree. The __name__ attribute should be the name with which a resource’s parent refers to the resource via __getitem__.

The __parent__ of the root resource should be None and its __name__ should be the empty string. For instance:

1
2
3

class MyRootResource(object):
    __name__ = ''
    __parent__ = None

A resource returned from the root resource’s __getitem__ method should have a __parent__ attribute that is a reference to the root resource, and its __name__ attribute should match the name by which it is reachable via the root resource’s __getitem__. A container resource within the root resource should have a __getitem__ that returns resources with a __parent__ attribute that points at the container, and these subobjects should have a __name__ attribute that matches the name by which they are retrieved from the container via __getitem__. This pattern continues recursively “up” the tree from the root.

The __parent__ attributes of each resource form a linked list that points “downwards” toward the root. This is analogous to the .. entry in filesystem directories. If you follow the __parent__ values from any resource in the resource tree, you will eventually come to the root resource, just like if you keep executing the cd .. filesystem command, eventually you will reach the filesystem root directory.

Warning

If your root resource has a __name__ argument that is not None or the empty string, URLs returned by the resource_url() function and paths generated by the resource_path() and resource_path_tuple() APIs will be generated improperly. The value of __name__ will be prepended to every path and URL generated (as opposed to a single leading slash or empty tuple element).

Using pyramid_traversalwrapper

If you’d rather not manage the __name__ and __parent__ attributes of your resources “by hand”, an add-on package named pyramid_traversalwrapper can help.

In order to use this helper feature, you must first install the pyramid_traversalwrapper package (available via PyPI), then register its ModelGraphTraverser as the traversal policy, rather than the default Pyramid traverser. The package contains instructions for doing so.

Once Pyramid is configured with this feature, you will no longer need to manage the __parent__ and __name__ attributes on resource objects “by hand”. Instead, as necessary, during traversal Pyramid will wrap each resource (even the root resource) in a LocationProxy which will dynamically assign a __name__ and a __parent__ to the traversed resource (based on the last traversed resource and the name supplied to __getitem__). The root resource will have a __name__ attribute of None and a __parent__ attribute of None.

Applications which use tree-walking Pyramid APIs require location-aware resources. These APIs include (but are not limited to) resource_url(), find_resource(), find_root(), find_interface(), resource_path(), resource_path_tuple(), or traverse(), virtual_root(), and (usually) has_permission() and principals_allowed_by_permission().

In general, since so much Pyramid infrastructure depends on location-aware resources, it’s a good idea to make each resource in your tree location-aware.

Generating The URL Of A Resource

If your resources are location aware, you can use the pyramid.url.resource_url() API to generate a URL for the resource. This URL will use the resource’s position in the parent tree to create a resource path, and it will prefix the path with the current application URL to form a fully-qualified URL with the scheme, host, port, and path. You can also pass extra arguments to resource_url() to influence the generated URL.

The simplest call to resource_url() looks like this:

1
2

from pyramid.url import resource_url
url = resource_url(resource, request)

The request passed to resource_url in the above example is an instance of a Pyramid request object.

If the resource referred to as resource in the above example was the root resource, and the host that was used to contact the server was example.com, the URL generated would be http://example.com/. However, if the resource was a child of the root resource named a, the generated URL would be http://example.com/a/.

A slash is appended to all resource URLs when resource_url() is used to generate them in this simple manner, because resources are “places” in the hierarchy, and URLs are meant to be clicked on to be visited. Relative URLs that you include on HTML pages rendered as the result of the default view of a resource are more apt to be relative to these resources than relative to their parent.

You can also pass extra elements to resource_url():

1
2

from pyramid.url import resource_url
url = resource_url(resource, request, 'foo', 'bar')

If the resource referred to as resource in the above example was the root resource, and the host that was used to contact the server was example.com, the URL generated would be http://example.com/foo/bar. Any number of extra elements can be passed to resource_url() as extra positional arguments. When extra elements are passed, they are appended to the resource’s URL. A slash is not appended to the final segment when elements are passed.

You can also pass a query string:

1
2

from pyramid.url import resource_url
url = resource_url(resource, request, query={'a':'1'})

If the resource referred to as resource in the above example was the root resource, and the host that was used to contact the server was example.com, the URL generated would be http://example.com/?a=1.

When a virtual root is active, the URL generated by resource_url() for a resource may be “shorter” than its physical tree path. See Virtual Root Support for more information about virtually rooting a resource.

The shortcut method of the request named pyramid.request.Request.resource_url() can be used instead of resource_url() to generate a resource URL.

For more information about generating resource URLs, see the documentation for pyramid.url.resource_url().

Overriding Resource URL Generation

If a resource object implements a __resource_url__ method, this method will be called when resource_url() is called to generate a URL for the resource, overriding the default URL returned for the resource by resource_url().

The __resource_url__ hook is passed two arguments: request and info. request is the request object passed to resource_url(). info is a dictionary with two keys:

physical_path

The “physical path” computed for the resource, as defined by pyramid.traversal.resource_path(resource).

virtual_path

The “virtual path” computed for the resource, as defined by Virtual Root Support. This will be identical to the physical path if virtual rooting is not enabled.

The __resource_url__ method of a resource should return a string representing a URL. If it cannot override the default, it should return None. If it returns None, the default URL will be returned.

Here’s an example __resource_url__ method.

1
2
3

class Resource(object):
    def __resource_url__(self, request, info):
        return request.application_url + info['virtual_path']

The above example actually just generates and returns the default URL, which would have been what was returned anyway, but your code can perform arbitrary logic as necessary. For example, your code may wish to override the hostname or port number of the generated URL.

Note that the URL generated by __resource_url__ should be fully qualified, should end in a slash, and should not contain any query string or anchor elements (only path elements) to work best with resource_url().

Generating the Path To a Resource

pyramid.traversal.resource_path() returns a string object representing the absolute physical path of the resource object based on its position in the resource tree. Each segment of the path is separated with a slash character.

1
2

from pyramid.traversal import resource_path
url = resource_path(resource)

If resource in the example above was accessible in the tree as root['a']['b'], the above example would generate the string /a/b.

Any positional arguments passed in to resource_path() will be appended as path segments to the end of the resource path.

1
2

from pyramid.traversal import resource_path
url = resource_path(resource, 'foo', 'bar')

If resource in the example above was accessible in the tree as root['a']['b'], the above example would generate the string /a/b/foo/bar.

The resource passed in must be location-aware.

The presence or absence of a virtual root has no impact on the behavior of resource_path().

Finding a Resource by Path

If you have a string path to a resource, you can grab the resource from that place in the application’s resource tree using pyramid.traversal.find_resource().

You can resolve an absolute path by passing a string prefixed with a / as the path argument:

1
2

from pyramid.traversal import find_resource
url = find_resource(anyresource, '/path')

Or you can resolve a path relative to the resource you pass in by passing a string that isn’t prefixed by /:

1
2

from pyramid.traversal import find_resource
url = find_resource(anyresource, 'path')

Often the paths you pass to find_resource() are generated by the resource_path() API. These APIs are “mirrors” of each other.

If the path cannot be resolved when calling find_resource() (if the respective resource in the tree does not exist), a KeyError will be raised.

See the pyramid.traversal.find_resource() documentation for more information about resolving a path to a resource.

Obtaining the Lineage of a Resource

pyramid.location.lineage() returns a generator representing the lineage of the location aware resource object.

The lineage() function returns the resource it is passed, then each parent of the resource, in order. For example, if the resource tree is composed like so:

1
2
3
4
5

class Thing(object): pass

thing1 = Thing()
thing2 = Thing()
thing2.__parent__ = thing1

Calling lineage(thing2) will return a generator. When we turn it into a list, we will get:

list(lineage(thing2))
[ <Thing object at thing2>, <Thing object at thing1> ]

The generator returned by lineage() first returns the resource it was passed unconditionally. Then, if the resource supplied a __parent__ attribute, it returns the resource represented by resource.__parent__. If that resource has a __parent__ attribute, return that resource’s parent, and so on, until the resource being inspected either has no __parent__ attribute or which has a __parent__ attribute of None.

See the documentation for pyramid.location.lineage() for more information.

Determining if a Resource is In The Lineage of Another Resource

Use the pyramid.location.inside() function to determine if one resource is in the lineage of another resource.

For example, if the resource tree is:

1
2
3
4
5

class Thing(object): pass

a = Thing()
b = Thing()
b.__parent__ = a

Calling inside(b, a) will return True, because b has a lineage that includes a. However, calling inside(a, b) will return False because a does not have a lineage that includes b.

The argument list for inside() is (resource1, resource2). resource1 is ‘inside’ resource2 if resource2 is a lineage ancestor of resource1. It is a lineage ancestor if its parent (or one of its parent’s parents, etc.) is an ancestor.

See pyramid.location.inside() for more information.

Finding the Root Resource

Use the pyramid.traversal.find_root() API to find the root resource. The root resource is the root resource of the resource tree. The API accepts a single argument: resource. This is a resource that is location aware. It can be any resource in the tree for which you want to find the root.

For example, if the resource tree is:

1
2
3
4
5

class Thing(object): pass

a = Thing()
b = Thing()
b.__parent__ = a

Calling find_root(b) will return a.

The root resource is also available as request.root within view callable code.

The presence or absence of a virtual root has no impact on the behavior of find_root(). The root object returned is always the physical root object.

Resources Which Implement Interfaces

Resources can optionally be made to implement an interface. An interface is used to tag a resource object with a “type” that can later be referred to within view configuration and by pyramid.traversal.find_interface().

Specifying an interface instead of a class as the context or containment predicate arguments within view configuration statements makes it possible to use a single view callable for more than one class of resource object. If your application is simple enough that you see no reason to want to do this, you can skip reading this section of the chapter.

For example, here’s some code which describes a blog entry which also declares that the blog entry implements an interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import datetime
from zope.interface import implements
from zope.interface import Interface

class IBlogEntry(Interface):
    pass

class BlogEntry(object):
    implements(IBlogEntry)
    def __init__(self, title, body, author):
        self.title = title
        self.body = body
        self.author = author
        self.created = datetime.datetime.now()

This resource consists of two things: the class which defines the resource constructor as the class BlogEntry, and an interface attached to the class via an implements statement at class scope using the IBlogEntry interface as its sole argument.

The interface object used must be an instance of a class that inherits from zope.interface.Interface.

A resource class may implement zero or more interfaces. You specify that a resource implements an interface by using the zope.interface.implements() function at class scope. The above BlogEntry resource implements the IBlogEntry interface.

You can also specify that a particular resource instance provides an interface, as opposed to its class. When you declare that a class implements an interface, all instances of that class will also provide that interface. However, you can also just say that a single object provides the interface. To do so, use the zope.interface.directlyProvides() function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from zope.interface import directlyProvides
from zope.interface import Interface

class IBlogEntry(Interface):
    pass

class BlogEntry(object):
    def __init__(self, title, body, author):
        self.title = title
        self.body = body
        self.author = author
        self.created = datetime.datetime.now()

entry = BlogEntry('title', 'body', 'author')
directlyProvides(entry, IBlogEntry)

zope.interface.directlyProvides() will replace any existing interface that was previously provided by an instance. If a resource object already has instance-level interface declarations that you don’t want to replace, use the zope.interface.alsoProvides() function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from zope.interface import alsoProvides
from zope.interface import directlyProvides
from zope.interface import Interface

class IBlogEntry1(Interface):
    pass

class IBlogEntry2(Interface):
    pass

class BlogEntry(object):
    def __init__(self, title, body, author):
        self.title = title
        self.body = body
        self.author = author
        self.created = datetime.datetime.now()

entry = BlogEntry('title', 'body', 'author')
directlyProvides(entry, IBlogEntry1)
alsoProvides(entry, IBlogEntry2)

zope.interface.alsoProvides() will augment the set of interfaces directly provided by an instance instead of overwriting them like zope.interface.directlyProvides() does.

For more information about how resource interfaces can be used by view configuration, see Using Resource Interfaces In View Configuration.

Finding a Resource With a Class or Interface in Lineage

Use the find_interface() API to locate a parent that is of a particular Python class, or which implements some interface.

For example, if your resource tree is composed as follows:

1
2
3
4
5
6

class Thing1(object): pass
class Thing2(object): pass

a = Thing1()
b = Thing2()
b.__parent__ = a

Calling find_interface(a, Thing1) will return the a resource because a is of class Thing1 (the resource passed as the first argument is considered first, and is returned if the class or interface spec matches).

Calling find_interface(b, Thing1) will return the a resource because a is of class Thing1 and a is the first resource in b‘s lineage of this class.

Calling find_interface(b, Thing2) will return the b resource.

The second argument to find_interface may also be a interface instead of a class. If it is an interface, each resource in the lineage is checked to see if the resource implements the specificed interface (instead of seeing if the resource is of a class). See also Resources Which Implement Interfaces.

Pyramid API Functions That Act Against Resources

A resource object is used as the context provided to a view. See Traversal and URL Dispatch for more information about how a resource object becomes the context.

The APIs provided by pyramid.traversal are used against resource objects. These functions can be used to find the “path” of a resource, the root resource in a resource tree, or to generate a URL for a resource.

The APIs provided by pyramid.location are used against resources. These can be used to walk down a resource tree, or conveniently locate one resource “inside” another.

Some APIs in pyramid.security accept a resource object as a parameter. For example, the has_permission() API accepts a resource object as one of its arguments; the ACL is obtained from this resource or one of its ancestors. Other APIs in the pyramid.security module also accept context as an argument, and a context is always a resource.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Static Assets

An asset is any file contained within a Python package which is not a Python source code file. For example, each of the following is an asset:

a GIF image file contained within a Python package or contained within any subdirectory of a Python package.

a CSS file contained within a Python package or contained within any subdirectory of a Python package.

a JavaScript source file contained within a Python package or contained within any subdirectory of a Python package.

A directory within a package that does not have an __init__.py in it (if it possessed an __init__.py it would be a package).

a Chameleon or Mako template file contained within a Python package.

The use of assets is quite common in most web development projects. For example, when you create a Pyramid application using one of the available “paster” templates, as described in Creating the Project, the directory representing the application contains a Python package. Within that Python package, there are directories full of files which are static assets. For example, there’s a static directory which contains .css, .js, and .gif files. These asset files are delivered when a user visits an application URL.

Understanding Asset Specifications

Let’s imagine you’ve created a Pyramid application that uses a Chameleon ZPT template via the pyramid.renderers.render_to_response() API. For example, the application might address the asset using the asset specification myapp:templates/some_template.pt using that API within a views.py file inside a myapp package:

1
2

from pyramid.renderers import render_to_response
render_to_response('myapp:templates/some_template.pt', {}, request)

“Under the hood”, when this API is called, Pyramid attempts to make sense out of the string myapp:templates/some_template.pt provided by the developer. This string is an asset specification. It is composed of two parts:

The package name (myapp)

The asset name (templates/some_template.pt), relative to the package directory.

The two parts are separated by the colon character.

Pyramid uses the Python pkg_resources API to resolve the package name and asset name to an absolute (operating-system-specific) file name. It eventually passes this resolved absolute filesystem path to the Chameleon templating engine, which then uses it to load, parse, and execute the template file.

There is a second form of asset specification: a relative asset specification. Instead of using an “absolute” asset specification which includes the package name, in certain circumstances you can omit the package name from the specification. For example, you might be able to use templates/mytemplate.pt instead of myapp:templates/some_template.pt. Such asset specifications are usually relative to a “current package.” The “current package” is usually the package which contains the code that uses the asset specification. Pyramid APIs which accept relative asset specifications typically describe what the asset is relative to in their individual documentation.

Serving Static Assets

Pyramid makes it possible to serve up static asset files from a directory on a filesystem to an application user’s browser. Use the pyramid.config.Configurator.add_static_view() to instruct Pyramid to serve static assets such as JavaScript and CSS files. This mechanism makes a directory of static files available at a name relative to the application root URL, e.g. /static or as an external URL.

Note

add_static_view() cannot serve a single file, nor can it serve a directory of static files directly relative to the root URL of a Pyramid application. For these features, see Advanced: Serving Static Assets Using a View Callable.

Here’s an example of a use of add_static_view() that will serve files up from the /var/www/static directory of the computer which runs the Pyramid application as URLs beneath the /static URL prefix.

1
2

# config is an instance of pyramid.config.Configurator
config.add_static_view(name='static', path='/var/www/static')

The name prepresents a URL prefix. In order for files that live in the path directory to be served, a URL that requests one of them must begin with that prefix. In the example above, name is static, and path is /var/www/static. In English, this means that you wish to serve the files that live in /var/www/static as sub-URLs of the /static URL prefix. Therefore, the file /var/www/static/foo.css will be returned when the user visits your application’s URL /static/foo.css.

A static directory named at path may contain subdirectories recursively, and any subdirectories may hold files; these will be resolved by the static view as you would expect. The Content-Type header returned by the static view for each particular type of file is dependent upon its file extension.

By default, all files made available via add_static_view() are accessible by completely anonymous users. Simple authorization can be required, however. To protect a set of static files using a permission, in addition to passing the required name and path arguments, also pass the permission keyword argument to add_static_view(). The value of the permission argument represents the permission that the user must have relative to the current context when the static view is invoked. A user will be required to possess this permission to view any of the files represented by path of the static view. If your static assets must be protected by a more complex authorization scheme, see Advanced: Serving Static Assets Using a View Callable.

Here’s another example that uses an asset specification instead of an absolute path as the path argument. To convince add_static_view() to serve files up under the /static URL from the a/b/c/static directory of the Python package named some_package, we can use a fully qualified asset specification as the path:

1
2

# config is an instance of pyramid.config.Configurator
config.add_static_view(name='static', path='some_package:a/b/c/static')

The path provided to add_static_view() may be a fully qualified asset specification or an absolute path.

Instead of representing a URL prefix, the name argument of a call to add_static_view() can alternately be a URL. Each of examples we’ve seen so far have shown usage of the name argument as a URL prefix. However, when name is a URL, static assets can be served from an external webserver. In this mode, the name is used as the URL prefix when generating a URL using pyramid.url.static_url().

For example, add_static_view() may be fed a name argument which is http://example.com/images:

1
2
3

# config is an instance of pyramid.config.Configurator
config.add_static_view(name='http://example.com/images',
                       path='mypackage:images')

Because add_static_view() is provided with a name argument that is the URL http://example.com/images, subsequent calls to static_url() with paths that start with the path argument passed to add_static_view() will generate a URL something like http://example.com/images/logo.png. The external webserver listening on example.com must be itself configured to respond properly to such a request. The static_url() API is discussed in more detail later in this chapter.

Generating Static Asset URLs

When a add_static_view() method is used to register a static asset directory, a special helper API named pyramid.url.static_url() can be used to generate the appropriate URL for an asset that lives in one of the directories named by the static registration path attribute.

For example, let’s assume you create a set of static declarations like so:

1
2

config.add_static_view(name='static1', path='mypackage:assets/1')
config.add_static_view(name='static2', path='mypackage:assets/2')

These declarations create URL-accessible directories which have URLs that begin with /static1 and /static2, respectively. The assets in the assets/1 directory of the mypackage package are consulted when a user visits a URL which begins with /static1, and the assets in the assets/2 directory of the mypackage package are consulted when a user visits a URL which begins with /static2.

You needn’t generate the URLs to static assets “by hand” in such a configuration. Instead, use the static_url() API to generate them for you. For example:

1
2
3
4
5
6
7
8
9

from pyramid.url import static_url
from pyramid.chameleon_zpt import render_template_to_response

def my_view(request):
    css_url = static_url('mypackage:assets/1/foo.css', request)
    js_url = static_url('mypackage:assets/2/foo.js', request)
    return render_template_to_response('templates/my_template.pt',
                                       css_url = css_url,
                                       js_url = js_url)

If the request “application URL” of the running system is http://example.com, the css_url generated above would be: http://example.com/static1/foo.css. The js_url generated above would be http://example.com/static2/foo.js.

One benefit of using the static_url() function rather than constructing static URLs “by hand” is that if you need to change the name of a static URL declaration, the generated URLs will continue to resolve properly after the rename.

URLs may also be generated by static_url() to static assets that live outside the Pyramid application. This will happen when the add_static_view() API associated with the path fed to static_url() is a URL instead of a view name. For example, the name argument may be http://example.com while the the path given may be mypackage:images:

1
2

config.add_static_view(name='http://example.com/images',
                       path='mypackage:images')

Under such a configuration, the URL generated by static_url for assets which begin with mypackage:images will be prefixed with http://example.com/images:

1
2

static_url('mypackage:images/logo.png', request)
# -> http://example.com/images/logo.png

Using static_url() in conjunction with a add_static_view() makes it possible to put static media on a separate webserver during production (if the name argument to add_static_view() is a URL), while keeping static media package-internal and served by the development webserver during development (if the name argument to add_static_view() is a URL prefix). To create such a circumstance, we suggest using the pyramid.registry.Registry.settings API in conjunction with a setting in the application .ini file named media_location. Then set the value of media_location to either a prefix or a URL depending on whether the application is being run in development or in production (use a different .ini file for production than you do for development). This is just a suggestion for a pattern; any setting name other than media_location could be used.

Advanced: Serving Static Assets Using a View Callable

For more flexibility, static assets can be served by a view callable which you register manually. For example, if you’re using URL dispatch, you may want static assets to only be available as a fallback if no previous route matches. Alternately, you might like to serve a particular static asset manually, because its download requires authentication.

Note that you cannot use the static_url() API to generate URLs against assets made accessible by registering a custom static view.

Root-Relative Custom Static View (URL Dispatch Only)

The pyramid.view.static helper class generates a Pyramid view callable. This view callable can serve static assets from a directory. An instance of this class is actually used by the add_static_view() configuration method, so its behavior is almost exactly the same once it’s configured.

Warning

The following example will not work for applications that use traversal, it will only work if you use URL dispatch exclusively. The root-relative route we’ll be registering will always be matched before traversal takes place, subverting any views registered via add_view (at least those without a route_name). A static static view cannot be made root-relative when you use traversal.

To serve files within a directory located on your filesystem at /path/to/static/dir as the result of a “catchall” route hanging from the root that exists at the end of your routing table, create an instance of the static class inside a static.py file in your application root as below.

1
2

from pyramid.view import static
static_view = static('/path/to/static/dir')

Note

For better cross-system flexibility, use an asset specification as the argument to static instead of a physical absolute filesystem path, e.g. mypackage:static instead of /path/to/mypackage/static.

Subsequently, you may wire the files that are served by this view up to be accessible as /<filename> using a configuration method in your application’s startup code.

1
2
3
4

# .. every other add_route declaration should come
# before this one, as it will, by default, catch all requests

config.add_route('catchall_static', '/*subpath', 'myapp.static.static_view')

The special name *subpath above is used by the static view callable to signify the path of the file relative to the directory you’re serving.

Registering A View Callable to Serve a “Static” Asset

You can register a simple view callable to serve a single static asset. To do so, do things “by hand”. First define the view callable.

1
2
3
4
5
6
7

import os
from webob import Response

def favicon_view(request):
    here = os.path.dirname(__file__)
    icon = open(os.path.join(here, 'static', 'favicon.ico'))
    return Response(content_type='image/x-icon', app_iter=icon)

The above bit of code within favicon_view computes “here”, which is a path relative to the Python file in which the function is defined. It then uses the Python open function to obtain a file handle to a file within “here” named static, and returns a response using the open the file handle as the response’s app_iter. It makes sure to set the right content_type too.

You might register such a view via configuration as a view callable that should be called as the result of a traversal:

1

config.add_view('myapp.views.favicon_view', name='favicon.ico')

Or you might register it to be the view callable for a particular route:

1
2

config.add_route('favicon', '/favicon.ico',
                 view='myapp.views.favicon_view')

Because this is a simple view callable, it can be protected with a permission or can be configured to respond under different circumstances using view predicate arguments.

Overriding Assets

It can often be useful to override specific assets from “outside” a given Pyramid application. For example, you may wish to reuse an existing Pyramid application more or less unchanged. However, some specific template file owned by the application might have inappropriate HTML, or some static asset (such as a logo file or some CSS file) might not be appropriate. You could just fork the application entirely, but it’s often more convenient to just override the assets that are inappropriate and reuse the application “as is”. This is particularly true when you reuse some “core” application over and over again for some set of customers (such as a CMS application, or some bug tracking application), and you want to make arbitrary visual modifications to a particular application deployment without forking the underlying code.

To this end, Pyramid contains a feature that makes it possible to “override” one asset with one or more other assets. In support of this feature, a Configurator API exists named pyramid.config.Configurator.override_asset(). This API allows you to override the following kinds of assets defined in any Python package:

Individual Chameleon templates.

A directory containing multiple Chameleon templates.

Individual static files served up by an instance of the pyramid.view.static helper class.

A directory of static files served up by an instance of the pyramid.view.static helper class.

Any other asset (or set of assets) addressed by code that uses the setuptools pkg_resources API.

Note

The ZCML directive named asset serves the same purpose as the override_asset() method.

The override_asset API

An individual call to override_asset() can override a single asset. For example:

1
2
3

config.override_asset(
         to_override='some.package:templates/mytemplate.pt',
         override_with='another.package:othertemplates/anothertemplate.pt')

The string value passed to both to_override and override_with sent to the override_asset API is called an asset specification. The colon separator in a specification separates the package name from the asset name. The colon and the following asset name are optional. If they are not specified, the override attempts to resolve every lookup into a package from the directory of another package. For example:

1
2

config.override_asset(to_override='some.package',
                      override_with='another.package')

Individual subdirectories within a package can also be overridden:

1
2

config.override_asset(to_override='some.package:templates/',
                      override_with='another.package:othertemplates/')

If you wish to override a directory with another directory, you must make sure to attach the slash to the end of both the to_override specification and the override_with specification. If you fail to attach a slash to the end of a specification that points to a directory, you will get unexpected results.

You cannot override a directory specification with a file specification, and vice versa: a startup error will occur if you try. You cannot override an asset with itself: a startup error will occur if you try.

Only individual package assets may be overridden. Overrides will not traverse through subpackages within an overridden package. This means that if you want to override assets for both some.package:templates, and some.package.views:templates, you will need to register two overrides.

The package name in a specification may start with a dot, meaning that the package is relative to the package in which the configuration construction file resides (or the package argument to the Configurator class construction). For example:

1
2

config.override_asset(to_override='.subpackage:templates/',
                      override_with='another.package:templates/')

Multiple calls to override_asset which name a shared to_override but a different override_with specification can be “stacked” to form a search path. The first asset that exists in the search path will be used; if no asset exists in the override path, the original asset is used.

Asset overrides can actually override assets other than templates and static files. Any software which uses the pkg_resources.get_resource_filename(), pkg_resources.get_resource_stream() or pkg_resources.get_resource_string() APIs will obtain an overridden file when an override is used.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Request and Response Objects

Note

This chapter is adapted from a portion of the WebOb documentation, originally written by Ian Bicking.

Pyramid uses the WebOb package to supply request and response object implementations. The request object that is passed to a Pyramid view is an instance of the pyramid.request.Request class, which is a subclass of webob.Request. The response returned from a Pyramid view renderer is an instance of the webob.Response class. Users can also return an instance of webob.Response directly from a view as necessary.

WebOb is a project separate from Pyramid with a separate set of authors and a fully separate set of documentation [http://pythonpaste.org/webob/]. Pyramid adds some functionality to the standard WebOb request, which is documented in the pyramid.request API documentation.

WebOb provides objects for HTTP requests and responses. Specifically it does this by wrapping the WSGI [http://wsgi.org] request environment and response status/headers/app_iter (body).

WebOb request and response objects provide many conveniences for parsing WSGI requests and forming WSGI responses. WebOb is a nice way to represent “raw” WSGI requests and responses; however, we won’t cover that use case in this document, as users of Pyramid don’t typically need to use the WSGI-related features of WebOb directly. The reference documentation [http://pythonpaste.org/webob/reference.html] shows many examples of creating requests and using response objects in this manner, however.

Request

The request object is a wrapper around the WSGI environ dictionary [http://www.python.org/dev/peps/pep-0333/#environ-variables]. This dictionary contains keys for each header, keys that describe the request (including the path and query string), a file-like object for the request body, and a variety of custom keys. You can always access the environ with req.environ.

Some of the most important/interesting attributes of a request object:

req.method:

The request method, e.g., 'GET', 'POST'

req.GET:

A multidict with all the variables in the query string.

req.POST:

A multidict with all the variables in the request body. This only has variables if the request was a POST and it is a form submission.

req.params:

A multidict with a combination of everything in req.GET and req.POST.

req.body:

The contents of the body of the request. This contains the entire request body as a string. This is useful when the request is a POST that is not a form submission, or a request like a PUT. You can also get req.body_file for a file-like object.

req.cookies:

A simple dictionary of all the cookies.

req.headers:

A dictionary of all the headers. This dictionary is case-insensitive.

req.urlvars and req.urlargs:

req.urlvars are the keyword parameters associated with the request URL. req.urlargs are the positional parameters. These are set by products like Routes [http://routes.groovie.org/] and Selector [http://lukearno.com/projects/selector/].

Also, for standard HTTP request headers there are usually attributes, for instance: req.accept_language, req.content_length, req.user_agent, as an example. These properties expose the parsed form of each header, for whatever parsing makes sense. For instance, req.if_modified_since returns a datetime [http://python.org/doc/current/lib/datetime-datetime.html] object (or None if the header is was not provided).

Note

Full API documentation for the Pyramid request object is available in pyramid.request.

Special Attributes Added to the Request by Pyramid

In addition to the standard WebOb attributes, Pyramid adds special attributes to every request: context, registry, root, subpath, traversed, view_name, virtual_root, virtual_root_path, session, and tmpl_context, matchdict, and matched_route. These attributes are documented further within the pyramid.request.Request API documentation.

URLs

In addition to these attributes, there are several ways to get the URL of the request. I’ll show various values for an example URL http://localhost/app/blog?id=10, where the application is mounted at http://localhost/app.

req.url:

The full request URL, with query string, e.g., http://localhost/app/blog?id=10

req.host:

The host information in the URL, e.g., localhost

req.host_url:

The URL with the host, e.g., http://localhost

req.application_url:

The URL of the application (just the SCRIPT_NAME portion of the path, not PATH_INFO). E.g., http://localhost/app

req.path_url:

The URL of the application including the PATH_INFO. e.g., http://localhost/app/blog

req.path:

The URL including PATH_INFO without the host or scheme. e.g., /app/blog

req.path_qs:

The URL including PATH_INFO and the query string. e.g, /app/blog?id=10

req.query_string:

The query string in the URL, e.g., id=10

req.relative_url(url, to_application=False):

Gives a URL, relative to the current URL. If to_application is True, then resolves it relative to req.application_url.

Methods

There are several methods [http://pythonpaste.org/webob/class-webob.Request.html#__init__] but only a few you’ll use often:

Request.blank(base_url):

Creates a new request with blank information, based at the given URL. This can be useful for subrequests and artificial requests. You can also use req.copy() to copy an existing request, or for subrequests req.copy_get() which copies the request but always turns it into a GET (which is safer to share for subrequests).

req.get_response(wsgi_application):

This method calls the given WSGI application with this request, and returns a Response object. You can also use this for subrequests, or testing.

Unicode

Many of the properties in the request object will return unicode values if the request encoding/charset is provided. The client can indicate the charset with something like Content-Type: application/x-www-form-urlencoded; charset=utf8, but browsers seldom set this. You can set the charset with req.charset = 'utf8', or during instantiation with Request(environ, charset='utf8'). If you subclass Request you can also set charset as a class-level attribute.

If it is set, then req.POST, req.GET, req.params, and req.cookies will contain unicode strings. Each has a corresponding req.str_* (e.g., req.str_POST) that is always a str, and never unicode.

More Details

More detail about the request object API is available in:

The pyramid.request.Request API documentation.

The WebOb documentation [http://pythonpaste.org/webob]. All methods and attributes of a webob.Request documented within the WebOb documentation will work with request objects created by Pyramid.

Response

The Pyramid response object can be imported as pyramid.response.Response. This import location is merely a facade for its original location: webob.Response.

A response object has three fundamental parts:

response.status:

The response code plus reason message, like '200 OK'. To set the code without a message, use status_int, i.e.: response.status_int = 200.

response.headerlist:

A list of all the headers, like [('Content-Type', 'text/html')]. There’s a case-insensitive multidict in response.headers that also allows you to access these same headers.

response.app_iter:

An iterable (such as a list or generator) that will produce the content of the response. This is also accessible as response.body (a string), response.unicode_body (a unicode object, informed by response.charset), and response.body_file (a file-like object; writing to it appends to app_iter).

Everything else in the object derives from this underlying state. Here’s the highlights:

response.content_type

The content type not including the charset parameter. Typical use: response.content_type = 'text/html'.

response.charset:

The charset parameter of the content-type, it also informs encoding in response.unicode_body. response.content_type_params is a dictionary of all the parameters.

response.set_cookie(key, value, max_age=None, path='/', ...):

Set a cookie. The keyword arguments control the various cookie parameters. The max_age argument is the length for the cookie to live in seconds (you may also use a timedelta object). The Expires key will also be set based on the value of max_age.

response.delete_cookie(key, path='/', domain=None):

Delete a cookie from the client. This sets max_age to 0 and the cookie value to ''.

response.cache_expires(seconds=0):

This makes this response cacheable for the given number of seconds, or if seconds is 0 then the response is uncacheable (this also sets the Expires header).

response(environ, start_response):

The response object is a WSGI application. As an application, it acts according to how you create it. It can do conditional responses if you pass conditional_response=True when instantiating (or set that attribute later). It can also do HEAD and Range requests.

Headers

Like the request, most HTTP response headers are available as properties. These are parsed, so you can do things like response.last_modified = os.path.getmtime(filename).

The details are available in the extracted Response documentation [http://pythonpaste.org/webob/class-webob.Response.html].

Instantiating the Response

Of course most of the time you just want to make a response. Generally any attribute of the response can be passed in as a keyword argument to the class; e.g.:

1
2

from pyramid.response import Response
response = Response(body='hello world!', content_type='text/plain')

The status defaults to '200 OK'. The content_type does not default to anything, though if you subclass pyramid.response.Response and set default_content_type you can override this behavior.

Exception Responses

To facilitate error responses like 404 Not Found, the module webob.exc contains classes for each kind of error response. These include boring, but appropriate error bodies. The exceptions exposed by this module, when used under Pyramid, should be imported from the pyramid.httpexceptions “facade” module. This import location is merely a facade for the original location of these exceptions: webob.exc.

Each class is named pyramid.httpexceptions.HTTP*, where * is the reason for the error. For instance, pyramid.httpexceptions.HTTPNotFound. It subclasses pyramid.Response, so you can manipulate the instances in the same way. A typical example is:

1
2
3
4
5
6

from pyramid.httpexceptions import HTTPNotFound
from pyramid.httpexceptions import HTTPMovedPermanently

response = HTTPNotFound('There is no such resource')
# or:
response = HTTPMovedPermanently(location=new_url)

These are not exceptions unless you are using Python 2.5+, because they are new-style classes which are not allowed as exceptions until Python 2.5. To get an exception object use response.exception. You can use this like:

1
2
3
4
5
6
7
8
9

from pyramid.httpexceptions import HTTPException
from pyramid.httpexceptions import HTTPNotFound

def aview(request):
    try:
        # ... stuff ...
        raise HTTPNotFound('No such resource').exception
    except HTTPException, e:
        return request.get_response(e)

The exceptions are still WSGI applications, but you cannot set attributes like content_type, charset, etc. on these exception objects.

More Details

More details about the response object API are available in the pyramid.response documentation. More details about exception responses are in the pyramid.httpexceptions API documentation. The WebOb documentation [http://pythonpaste.org/webob] is also useful.

Multidict

Several parts of WebOb use a “multidict”; this is a dictionary where a key can have multiple values. The quintessential example is a query string like ?pref=red&pref=blue; the pref variable has two values: red and blue.

In a multidict, when you do request.GET['pref'] you’ll get back only 'blue' (the last value of pref). Sometimes returning a string, and sometimes returning a list, is the cause of frequent exceptions. If you want all the values back, use request.GET.getall('pref'). If you want to be sure there is one and only one value, use request.GET.getone('pref'), which will raise an exception if there is zero or more than one value for pref.

When you use operations like request.GET.items() you’ll get back something like [('pref', 'red'), ('pref', 'blue')]. All the key/value pairs will show up. Similarly request.GET.keys() returns ['pref', 'pref']. Multidict is a view on a list of tuples; all the keys are ordered, and all the values are ordered.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Sessions

A session is a namespace which is valid for some period of continual activity that can be used to represent a user’s interaction with a web application.

This chapter describes how to configure sessions, what session implementations Pyramid provides out of the box, how to store and retrieve data from sessions, and two session-specific features: flash messages, and cross-site request forgery attack prevention.

Using The Default Session Factory

In order to use sessions, you must set up a session factory during your Pyramid configuration.

A very basic, insecure sample session factory implementation is provided in the Pyramid core. It uses a cookie to store session information. This implementation has the following limitation:

The session information in the cookies used by this implementation is not encrypted, so it can be viewed by anyone with access to the cookie storage of the user’s browser or anyone with access to the network along which the cookie travels.

The maximum number of bytes that are storable in a serialized representation of the session is fewer than 4000. This is suitable only for very small data sets.

It is digitally signed, however, and thus its data cannot easily be tampered with.

You can configure this session factory in your Pyramid application by using the session_factory argument to the Configurator class:

1
2
3
4
5

from pyramid.session import UnencryptedCookieSessionFactoryConfig
my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')

from pyramid.config import Configurator
config = Configurator(session_factory = my_session_factory)

Warning

Note the very long, very explicit name for UnencryptedCookieSessionFactoryConfig. It’s trying to tell you that this implementation is, by default, unencrypted. You should not use it when you keep sensitive information in the session object, as the information can be easily read by both users of your application and third parties who have access to your users’ network traffic. Use a different session factory implementation (preferably one which keeps session data on the server) for anything but the most basic of applications where “session security doesn’t matter”.

Using a Session Object

Once a session factory has been configured for your application, you can access session objects provided by the session factory via the session attribute of any request object. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from pyramid.response import Response

def myview(request):
    session = request.session
    if 'abc' in session:
        session['fred'] = 'yes'
    session['abc'] = '123'
    if 'fred' in session:
        return Response('Fred was in the session')
    else:
        return Response('Fred was not in the session')

You can use a session much like a Python dictionary. It supports all dictionary methods, along with some extra attributes, and methods.

Extra attributes:

created

An integer timestamp indicating the time that this session was created.

new

A boolean. If new is True, this session is new. Otherwise, it has been constituted from data that was already serialized.

Extra methods:

changed()

Call this when you mutate a mutable value in the session namespace. See the gotchas below for details on when, and why you should call this.

invalidate()

Call this when you want to invalidate the session (dump all data, and – perhaps – set a clearing cookie).

The formal definition of the methods and attributes supported by the session object are in the pyramid.interfaces.ISession documentation.

Some gotchas:

Keys and values of session data must be pickleable. This means, typically, that they are instances of basic types of objects, such as strings, lists, dictionaries, tuples, integers, etc. If you place an object in a session data key or value that is not pickleable, an error will be raised when the session is serialized.

If you place a mutable value (for example, a list or a dictionary) in a session object, and you subsequently mutate that value, you must call the changed() method of the session object. In this case, the session has no way to know that is was modified. However, when you modify a session object directly, such as setting a value (i.e., __setitem__), or removing a key (e.g., del or pop), the session will automatically know that it needs to re-serialize its data, thus calling changed() is unnecessary. There is no harm in calling changed() in either case, so when in doubt, call it after you’ve changed sessioning data.

Using Alternate Session Factories

At the time of this writing, exactly one alternate session factory implementation exists, named pyramid_beaker. This is a session factory that uses the Beaker [http://beaker.groovie.org/] library as a backend. Beaker has support for file-based sessions, database based sessions, and encrypted cookie-based sessions. See http://github.com/Pylons/pyramid_beaker for more information about pyramid_beaker.

Creating Your Own Session Factory

If none of the default or otherwise available sessioning implementations for Pyramid suit you, you may create your own session object by implementing a session factory. Your session factory should return a session. The interfaces for both types are available in pyramid.interfaces.ISessionFactory and pyramid.interfaces.ISession. You might use the cookie implementation in the pyramid.session module as inspiration.

Flash Messages

“Flash messages” are simply a queue of message strings stored in the session. To use flash messaging, you must enable a session factory as described in Using The Default Session Factory or Using Alternate Session Factories.

Flash messaging has two main uses: to display a status message only once to the user after performing an internal redirect, and to allow generic code to log messages for single-time display without having direct access to an HTML template. The user interface consists of a number of methods of the session object.

Using the session.flash Method

To add a message to a flash message queue, use a session object’s flash() method:

request.session.flash('mymessage')

The flash() method appends a message to a flash queue, creating the queue if necessary.

flash() accepts three arguments:

flash(message, queue='', allow_duplicate=True)

The message argument is required. It represents a message you wish to later display to a user. It is usually a string but the message you provide is not modified in any way.

The queue argument allows you to choose a queue to which to append the message you provide. This can be used to push different kinds of messages into flash storage for later display in different places on a page. You can pass any name for your queue, but it must be a string. Each queue is independent, and can be popped by pop_flash() or examined via peek_flash() separately. queue defaults to the empty string. The empty string represents the default flash message queue.

request.session.flash(msg, 'myappsqueue')

The allow_duplicate argument defaults to True. If this is False, and you attempt to add a message value which is already present in the queue, it will not be added.

Using the session.pop_flash Method

Once one or more messages have been added to a flash queue by the session.flash() API, the session.pop_flash() API can be used to pop an entire queue and return it for use.

To pop a particular queue of messages from the flash object, use the session object’s pop_flash() method. This returns a list of the messages that were added to the flash queue, and empties the queue.

pop_flash(queue='')

1
2
3

>>> request.session.flash('info message')
>>> request.session.pop_flash()
['info message']

Calling session.pop_flash() again like above without a corresponding call to session.flash() will return an empty list, because the queue has already been popped.

1
2
3
4
5

>>> request.session.flash('info message')
>>> request.session.pop_flash()
['info message']
>>> request.session.pop_flash()
[]

Using the session.peek_flash Method

Once one or more messages has been added to a flash queue by the session.flash() API, the session.peek_flash() API can be used to “peek” at that queue. Unlike session.pop_flash(), the queue is not popped from flash storage.

peek_flash(queue='')

1
2
3
4
5
6
7
8
9

>>> request.session.flash('info message')
>>> request.session.peek_flash()
['info message']
>>> request.session.peek_flash()
['info message']
>>> request.session.pop_flash()
['info message']
>>> request.session.peek_flash()
[]

Preventing Cross-Site Request Forgery Attacks

Cross-site request forgery [http://en.wikipedia.org/wiki/Cross-site_request_forgery] attacks are a phenomenon whereby a user with an identity on your website might click on a URL or button on another website which unwittingly redirects the user to your application to perform some command that requires elevated privileges.

You can avoid most of these attacks by making sure that the correct CSRF token has been set in an Pyramid session object before performing any actions in code which requires elevated privileges that is invoked via a form post. To use CSRF token support, you must enable a session factory as described in Using The Default Session Factory or Using Alternate Session Factories.

Using the session.get_csrf_token Method

To get the current CSRF token from the session, use the session.get_csrf_token() method.

token = request.session.get_csrf_token()

The session.get_csrf_token() method accepts no arguments. It returns a CSRF token string. If session.get_csrf_token() or session.new_csrf_token() was invoked previously for this session, the existing token will be returned. If no CSRF token previously existed for this session, a new token will be will be set into the session and returned. The newly created token will be opaque and randomized.

You can use the returned token as the value of a hidden field in a form that posts to a method that requires elevated privileges. The handler for the form post should use session.get_csrf_token() again to obtain the current CSRF token related to the user from the session, and compare it to the value of the hidden form field. For example, if your form rendering included the CSRF token obtained via session.get_csrf_token() as a hidden input field named csrf_token:

1
2
3

token = request.session.get_csrf_token()
if token != request.POST['csrf_token']:
    raise ValueError('CSRF token did not match')

Using the session.new_csrf_token Method

To explicitly add a new CSRF token to the session, use the session.new_csrf_token() method. This differs only from session.get_csrf_token() inasmuch as it clears any existing CSRF token, creates a new CSRF token, sets the token into the session, and returns the token.

token = request.session.new_csrf_token()

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Security

Pyramid provides an optional declarative authorization system that can prevent a view from being invoked based on an authorization policy. Before a view is invoked, the authorization system can use the credentials in the request along with the context resource to determine if access will be allowed. Here’s how it works at a high level:

A request is generated when a user visits the application.

Based on the request, a context resource is located through resource location. A context is located differently depending on whether the application uses traversal or URL dispatch, but a context is ultimately found in either case. See the URL Dispatch chapter for more information.

A view callable is located by view lookup using the context as well as other attributes of the request.

If an authentication policy is in effect, it is passed the request; it returns some number of principal identifiers.

If an authorization policy is in effect and the view configuration associated with the view callable that was found has a permission associated with it, the authorization policy is passed the context, some number of principal identifiers returned by the authentication policy, and the permission associated with the view; it will allow or deny access.

If the authorization policy allows access, the view callable is invoked.

If the authorization policy denies access, the view callable is not invoked; instead the forbidden view is invoked.

Security in Pyramid, unlike many systems, cleanly and explicitly separates authentication and authorization. Authentication is merely the mechanism by which credentials provided in the request are resolved to one or more principal identifiers. These identifiers represent the users and groups in effect during the request. Authorization then determines access based on the principal identifiers, the view callable being invoked, and the context resource.

Authorization is enabled by modifying your application to include an authentication policy and authorization policy. Pyramid comes with a variety of implementations of these policies. To provide maximal flexibility, Pyramid also allows you to create custom authentication policies and authorization policies.

Enabling an Authorization Policy

By default, Pyramid enables no authorization policy. All views are accessible by completely anonymous users. In order to begin protecting views from execution based on security settings, you need to enable an authorization policy.

Enabling an Authorization Policy Imperatively

Passing an authorization_policy argument to the constructor of the Configurator class enables an authorization policy.

You must also enable an authentication policy in order to enable the authorization policy. This is because authorization, in general, depends upon authentication. Use the authentication_policy argument to the Configurator class during application setup to specify an authentication policy.

For example:

1
2
3
4
5
6
7

from pyramid.config import Configurator
from pyramid.authentication import AuthTktAuthenticationPolicy
from pyramid.authorization import ACLAuthorizationPolicy
authentication_policy = AuthTktAuthenticationPolicy('seekrit')
authorization_policy = ACLAuthorizationPolicy()
config = Configurator(authentication_policy=authentication_policy,
                      authorization_policy=authorization_policy)

Note

the authentication_policy and authorization_policy arguments may also be passed to the Configurator as dotted Python name values, each representing the dotted name path to a suitable implementation global defined at Python module scope.

The above configuration enables a policy which compares the value of an “auth ticket” cookie passed in the request’s environment which contains a reference to a single principal against the principals present in any ACL found in the resource tree when attempting to call some view.

While it is possible to mix and match different authentication and authorization policies, it is an error to pass an authentication policy without the authorization policy or vice versa to a Configurator constructor.

See also the pyramid.authorization and pyramid.authentication modules for alternate implementations of authorization and authentication policies.

Protecting Views with Permissions

To protect a view callable from invocation based on a user’s security settings when a particular type of resource becomes the context, you must pass a permission to view configuration. Permissions are usually just strings, and they have no required composition: you can name permissions whatever you like.

For example, the following view declaration protects the view named add_entry.html when the context resource is of type Blog with the add permission using the pyramid.config.Configurator.add_view() API:

1
2
3
4
5
6

# config is an instance of pyramid.config.Configurator

config.add_view('mypackage.views.blog_entry_add_view',
                name='add_entry.html',
                context='mypackage.resources.Blog',
                permission='add')

The equivalent view registration including the add permission name may be performed via the @view_config decorator:

1
2
3
4
5
6
7

from pyramid.view import view_config
from resources import Blog

@view_config(context=Blog, name='add_entry.html', permission='add')
def blog_entry_add_view(request):
    """ Add blog entry code goes here """
    pass

As a result of any of these various view configuration statements, if an authorization policy is in place when the view callable is found during normal application operations, the requesting user will need to possess the add permission against the context resource in order to be able to invoke the blog_entry_add_view view. If he does not, the Forbidden view will be invoked.

Setting a Default Permission

If a permission is not supplied to a view configuration, the registered view will always be executable by entirely anonymous users: any authorization policy in effect is ignored.

In support of making it easier to configure applications which are “secure by default”, Pyramid allows you to configure a default permission. If supplied, the default permission is used as the permission string to all view registrations which don’t otherwise name a permission argument.

These APIs are in support of configuring a default permission for an application:

The default_permission constructor argument to the Configurator constructor.

The pyramid.config.Configurator.set_default_permission() method.

When a default permission is registered:

if a view configuration names an explicit permission, the default permission is ignored for that view registration, and the view-configuration-named permission is used.

if a view configuration names an explicit permission as the string __no_permission_required__, the default permission is ignored, and the view is registered without a permission (making it available to all callers regardless of their credentials).

Warning

When you register a default permission, all views (even exception view views) are protected by a permission. For all views which are truly meant to be anonymously accessible, you will need to associate the view’s configuration with the __no_permission_required__ permission.

Assigning ACLs to your Resource Objects

When the default Pyramid authorization policy determines whether a user possesses a particular permission with respect to a resource, it examines the ACL associated with the resource. An ACL is associated with a resource by adding an __acl__ attribute to the resource object. This attribute can be defined on the resource instance if you need instance-level security, or it can be defined on the resource class if you just need type-level security.

For example, an ACL might be attached to the resource for a blog via its class:

1
2
3
4
5
6
7
8
9

from pyramid.security import Everyone
from pyramid.security import Allow

class Blog(object):
    __acl__ = [
        (Allow, Everyone, 'view'),
        (Allow, 'group:editors', 'add'),
        (Allow, 'group:editors', 'edit'),
        ]

Or, if your resources are persistent, an ACL might be specified via the __acl__ attribute of an instance of a resource:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from pyramid.security import Everyone
from pyramid.security import Allow

class Blog(object):
    pass

blog = Blog()

blog.__acl__ = [
        (Allow, Everyone, 'view'),
        (Allow, 'group:editors', 'add'),
        (Allow, 'group:editors', 'edit'),
        ]

Whether an ACL is attached to a resource’s class or an instance of the resource itself, the effect is the same. It is useful to decorate individual resource instances with an ACL (as opposed to just decorating their class) in applications such as “CMS” systems where fine-grained access is required on an object-by-object basis.

Elements of an ACL

Here’s an example ACL:

1
2
3
4
5
6
7
8

from pyramid.security import Everyone
from pyramid.security import Allow

__acl__ = [
        (Allow, Everyone, 'view'),
        (Allow, 'group:editors', 'add'),
        (Allow, 'group:editors', 'edit'),
        ]

The example ACL indicates that the pyramid.security.Everyone principal – a special system-defined principal indicating, literally, everyone – is allowed to view the blog, the group:editors principal is allowed to add to and edit the blog.

Each element of an ACL is an ACE or access control entry. For example, in the above code block, there are three ACEs: (Allow, Everyone, 'view'), (Allow, 'group:editors', 'add'), and (Allow, 'group:editors', 'edit').

The first element of any ACE is either pyramid.security.Allow, or pyramid.security.Deny, representing the action to take when the ACE matches. The second element is a principal. The third argument is a permission or sequence of permission names.

A principal is usually a user id, however it also may be a group id if your authentication system provides group information and the effective authentication policy policy is written to respect group information. For example, the pyramid.authentication.RepozeWho1AuthenicationPolicy respects group information if you configure it with a callback.

Each ACE in an ACL is processed by an authorization policy in the order dictated by the ACL. So if you have an ACL like this:

1
2
3
4
5
6
7
8

from pyramid.security import Everyone
from pyramid.security import Allow
from pyramid.security import Deny

__acl__ = [
    (Allow, Everyone, 'view'),
    (Deny, Everyone, 'view'),
    ]

The default authorization policy will allow everyone the view permission, even though later in the ACL you have an ACE that denies everyone the view permission. On the other hand, if you have an ACL like this:

1
2
3
4
5
6
7
8

from pyramid.security import Everyone
from pyramid.security import Allow
from pyramid.security import Deny

__acl__ = [
    (Deny, Everyone, 'view'),
    (Allow, Everyone, 'view'),
    ]

The authorization policy will deny everyone the view permission, even though later in the ACL is an ACE that allows everyone.

The third argument in an ACE can also be a sequence of permission names instead of a single permission name. So instead of creating multiple ACEs representing a number of different permission grants to a single group:editors group, we can collapse this into a single ACE, as below.

1
2
3
4
5
6
7

from pyramid.security import Everyone
from pyramid.security import Allow

__acl__ = [
    (Allow, Everyone, 'view'),
    (Allow, 'group:editors', ('add', 'edit')),
    ]

Special Principal Names

Special principal names exist in the pyramid.security module. They can be imported for use in your own code to populate ACLs, e.g. pyramid.security.Everyone.

pyramid.security.Everyone

Literally, everyone, no matter what. This object is actually a string “under the hood” (system.Everyone). Every user “is” the principal named Everyone during every request, even if a security policy is not in use.

pyramid.security.Authenticated

Any user with credentials as determined by the current security policy. You might think of it as any user that is “logged in”. This object is actually a string “under the hood” (system.Authenticated).

Special Permissions

Special permission names exist in the pyramid.security module. These can be imported for use in ACLs.

pyramid.security.ALL_PERMISSIONS

An object representing, literally, all permissions. Useful in an ACL like so: (Allow, 'fred', ALL_PERMISSIONS). The ALL_PERMISSIONS object is actually a stand-in object that has a __contains__ method that always returns True, which, for all known authorization policies, has the effect of indicating that a given principal “has” any permission asked for by the system.

Special ACEs

A convenience ACE is defined representing a deny to everyone of all permissions in pyramid.security.DENY_ALL. This ACE is often used as the last ACE of an ACL to explicitly cause inheriting authorization policies to “stop looking up the traversal tree” (effectively breaking any inheritance). For example, an ACL which allows only fred the view permission for a particular resource despite what inherited ACLs may say when the default authorization policy is in effect might look like so:

1
2
3
4

from pyramid.security import Allow
from pyramid.security import DENY_ALL

__acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ]

“Under the hood”, the pyramid.security.DENY_ALL ACE equals the following:

1
2

from pyramid.security import ALL_PERMISSIONS
__acl__ = [ (Deny, Everyone, ALL_PERMISSIONS) ]

ACL Inheritance and Location-Awareness

While the default authorization policy is in place, if a resource object does not have an ACL when it is the context, its parent is consulted for an ACL. If that object does not have an ACL, its parent is consulted for an ACL, ad infinitum, until we’ve reached the root and there are no more parents left.

In order to allow the security machinery to perform ACL inheritance, resource objects must provide location-awareness. Providing location-awareness means two things: the root object in the resource tree must have a _name__ attribute and a __parent__ attribute.

1
2
3

class Blog(object):
    __name__ = ''
    __parent__ = None

An object with a __parent__ attribute and a __name__ attribute is said to be location-aware. Location-aware objects define an __parent__ attribute which points at their parent object. The root object’s __parent__ is None.

See pyramid.location for documentations of functions which use location-awareness. See also Location-Aware Resources.

Changing the Forbidden View

When Pyramid denies a view invocation due to an authorization denial, the special forbidden view is invoked. “Out of the box”, this forbidden view is very plain. See Changing the Forbidden View within Using Hooks for instructions on how to create a custom forbidden view and arrange for it to be called when view authorization is denied.

Debugging View Authorization Failures

If your application in your judgment is allowing or denying view access inappropriately, start your application under a shell using the PYRAMID_DEBUG_AUTHORIZATION environment variable set to 1. For example:

$ PYRAMID_DEBUG_AUTHORIZATION=1 bin/paster serve myproject.ini

When any authorization takes place during a top-level view rendering, a message will be logged to the console (to stderr) about what ACE in which ACL permitted or denied the authorization based on authentication information.

This behavior can also be turned on in the application .ini file by setting the debug_authorization key to true within the application’s configuration section, e.g.:

1
2
3

[app:main]
use = egg:MyProject#app
debug_authorization = true

With this debug flag turned on, the response sent to the browser will also contain security debugging information in its body.

Debugging Imperative Authorization Failures

The pyramid.security.has_permission() API is used to check security within view functions imperatively. It returns instances of objects that are effectively booleans. But these objects are not raw True or False objects, and have information attached to them about why the permission was allowed or denied. The object will be one of pyramid.security.ACLAllowed, pyramid.security.ACLDenied, pyramid.security.Allowed, or pyramid.security.Denied, as documented in pyramid.security. At the very minimum these objects will have a msg attribute, which is a string indicating why the permission was denied or allowed. Introspecting this information in the debugger or via print statements when a call to has_permission() fails is often useful.

Creating Your Own Authentication Policy

Pyramid ships with a number of useful out-of-the-box security policies (see pyramid.authentication). However, creating your own authentication policy is often necessary when you want to control the “horizontal and vertical” of how your users authenticate. Doing so is a matter of creating an instance of something that implements the following interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

class AuthenticationPolicy(object):
    """ An object representing a Pyramid authentication policy. """
    def authenticated_userid(self, request):
        """ Return the authenticated userid or ``None`` if no
        authenticated userid can be found. """

    def effective_principals(self, request):

        """ Return a sequence representing the effective principals
        including the userid and any groups belonged to by the current
        user, including 'system' groups such as
        ``pyramid.security.Everyone`` and
        ``pyramid.security.Authenticated``. """

    def remember(self, request, principal, **kw):
        """ Return a set of headers suitable for 'remembering' the
        principal named ``principal`` when set in a response.  An
        individual authentication policy and its consumers can decide
        on the composition and meaning of **kw. """

    def forget(self, request):
        """ Return a set of headers suitable for 'forgetting' the
        current user on subsequent requests. """

After you do so, you can pass an instance of such a class into the Configurator class at configuration time as authentication_policy to use it.

Creating Your Own Authorization Policy

An authorization policy is a policy that allows or denies access after a user has been authenticated. By default, Pyramid will use the pyramid.authorization.ACLAuthorizationPolicy if an authentication policy is activated and an authorization policy isn’t otherwise specified.

In some cases, it’s useful to be able to use a different authorization policy than the default ACLAuthorizationPolicy. For example, it might be desirable to construct an alternate authorization policy which allows the application to use an authorization mechanism that does not involve ACL objects.

Pyramid ships with only a single default authorization policy, so you’ll need to create your own if you’d like to use a different one. Creating and using your own authorization policy is a matter of creating an instance of an object that implements the following interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

class IAuthorizationPolicy(object):
    """ An object representing a Pyramid authorization policy. """
    def permits(self, context, principals, permission):
        """ Return ``True`` if any of the ``principals`` is allowed the
        ``permission`` in the current ``context``, else return ``False``
        """

    def principals_allowed_by_permission(self, context, permission):
        """ Return a set of principal identifiers allowed by the
        ``permission`` in ``context``.  This behavior is optional; if you
        choose to not implement it you should define this method as
        something which raises a ``NotImplementedError``.  This method
        will only be called when the
        ``pyramid.security.principals_allowed_by_permission`` API is
        used."""

After you do so, you can pass an instance of such a class into the Configurator class at configuration time as authorization_policy to use it.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Combining Traversal and URL Dispatch

When you write most Pyramid applications, you’ll be using one or the other of two available resource location subsystems: traversal or URL dispatch. However, to solve a limited set of problems, it’s useful to use both traversal and URL dispatch together within the same application. Pyramid makes this possible via hybrid applications.

Warning

Reasoning about the behavior of a “hybrid” URL dispatch + traversal application can be challenging. To successfully reason about using URL dispatch and traversal together, you need to understand URL pattern matching, root factories, and the traversal algorithm, and the potential interactions between them. Therefore, we don’t recommend creating an application that relies on hybrid behavior unless you must.

A Review of Non-Hybrid Applications

When used according to the tutorials in its documentation Pyramid is a “dual-mode” framework: the tutorials explain how to create an application in terms of using either url dispatch or traversal. This chapter details how you might combine these two dispatch mechanisms, but we’ll review how they work in isolation before trying to combine them.

URL Dispatch Only

An application that uses url dispatch exclusively to map URLs to code will often have statements like this within your application startup configuration:

1
2
3
4

# config is an instance of pyramid.config.Configurator

config.add_route('foobar', '{foo}/{bar}', view='myproject.views.foobar')
config.add_route('bazbuz', '{baz}/{buz}', view='myproject.views.bazbuz')

Each route typically corresponds to a single view callable, and when that route is matched during a request, the view callable named by the view attribute is invoked.

Typically, an application that uses only URL dispatch won’t perform any calls to pyramid.config.Configurator.add_view() in its startup code.

Traversal Only

An application that uses only traversal will have view configuration declarations that look like this:

1
2
3
4

 # config is an instance of pyramid.config.Configurator

 config.add_view('mypackage.views.foobar', name='foobar')
 config.add_view('mypackage.views.bazbuz', name='bazbuz')

When the above configuration is applied to an application, the mypackage.views.foobar view callable above will be called when the URL /foobar is visited. Likewise, the view mypackage.views.bazbuz will be called when the URL /bazbuz is visited.

Typically, an application that uses traversal exclusively won’t perform any calls to pyramid.config.Configurator.add_route() in its startup code.

Hybrid Applications

Either traversal or url dispatch alone can be used to create a Pyramid application. However, it is also possible to combine the concepts of traversal and url dispatch when building an application: the result is a hybrid application. In a hybrid application, traversal is performed after a particular route has matched.

A hybrid application is a lot more like a “pure” traversal-based application than it is like a “pure” URL-dispatch based application. But unlike in a “pure” traversal-based application, in a hybrid application, traversal is performed during a request after a route has already matched. This means that the URL pattern that represents the pattern argument of a route must match the PATH_INFO of a request, and after the route pattern has matched, most of the “normal” rules of traversal with respect to resource location and view lookup apply.

There are only four real differences between a purely traversal-based application and a hybrid application:

In a purely traversal based application, no routes are defined; in a hybrid application, at least one route will be defined.

In a purely traversal based application, the root object used is global, implied by the root factory provided at startup time; in a hybrid application, the root object at which traversal begins may be varied on a per-route basis.

In a purely traversal-based application, the PATH_INFO of the underlying WSGI environment is used wholesale as a traversal path; in a hybrid application, the traversal path is not the entire PATH_INFO string, but a portion of the URL determined by a matching pattern in the matched route configuration’s pattern.

In a purely traversal based application, view configurations which do not mention a route_name argument are considered during view lookup; in a hybrid application, when a route is matched, only view configurations which mention that route’s name as a route_name are considered during view lookup.

More generally, a hybrid application is a traversal-based application except:

the traversal root is chosen based on the route configuration of the route that matched instead of from the root_factory supplied during application startup configuration.

the traversal path is chosen based on the route configuration of the route that matched rather than from the PATH_INFO of a request.

the set of views that may be chosen during view lookup when a route matches are limited to those which specifically name a route_name in their configuration that is the same as the matched route’s name.

To create a hybrid mode application, use a route configuration that implies a particular root factory and which also includes a pattern argument that contains a special dynamic part: either *traverse or *subpath.

The Root Object for a Route Match

A hybrid application implies that traversal is performed during a request after a route has matched. Traversal, by definition, must always begin at a root object. Therefore it’s important to know which root object will be traversed after a route has matched.

Figuring out which root object results from a particular route match is straightforward. When a route is matched:

If the route’s configuration has a factory argument which points to a root factory callable, that callable will be called to generate a root object.

If the route’s configuration does not have a factory argument, the global root factory will be called to generate a root object. The global root factory is the callable implied by the root_factory argument passed to the Configurator at application startup time.

If a root_factory argument is not provided to the Configurator at startup time, a default root factory is used. The default root factory is used to generate a root object.

Note

Root factories related to a route were explained previously within Route Factories. Both the global root factory and default root factory were explained previously within The Resource Tree.

Using *traverse In a Route Pattern

A hybrid application most often implies the inclusion of a route configuration that contains the special token *traverse at the end of a route’s pattern:

1

config.add_route('home', '{foo}/{bar}/*traverse')

A *traverse token at the end of the pattern in a route’s configuration implies a “remainder” capture value. When it is used, it will match the remainder of the path segments of the URL. This remainder becomes the path used to perform traversal.

Note

The *remainder route pattern syntax is explained in more detail within Route Pattern Syntax.

Note that unlike the examples provided within URL Dispatch, the add_route configuration statement named previously does not pass a view argument. This is because a hybrid mode application relies on traversal to do resource location and view lookup instead of invariably invoking a specific view callable named directly within the matched route’s configuration.

Because the pattern of the above route ends with *traverse, when this route configuration is matched during a request, Pyramid will attempt to use traversal against the root object implied by the root factory that is implied by the route’s configuration. Since no root_factory argument is explicitly specified for this route, this will either be the global root factory for the application, or the default root factory. Once traversal has found a context resource, view lookup will be invoked in almost exactly the same way it would have been invoked in a “pure” traversal-based application.

Let’s assume there is no global root factory configured in this application. The default root factory cannot be traversed: it has no useful __getitem__ method. So we’ll need to associate this route configuration with a custom root factory in order to create a useful hybrid application. To that end, let’s imagine that we’ve created a root factory that looks like so in a module named routes.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

class Resource(object):
    def __init__(self, subobjects):
       self.subobjects = subobjects

    def __getitem__(self, name):
       return self.subobjects[name]

root = Traversable(
        {'a':Resource({'b':Resource({'c':Resource({})})})}
       )

def root_factory(request):
    return root

Above, we’ve defined a (bogus) resource tree that can be traversed, and a root_factory function that can be used as part of a particular route configuration statement:

1
2

config.add_route('home', '{foo}/{bar}/*traverse',
                 factory='mypackage.routes.root_factory')

The factory above points at the function we’ve defined. It will return an instance of the Traversable class as a root object whenever this route is matched. Instances of the``Resource`` class can be used for tree traversal because they have a __getitem__ method that does something nominally useful. Since traversal uses __getitem__ to walk the resources of a resource tree, using traversal against the root resource implied by our route statement is a reasonable thing to do.

Note

We could have also used our root_factory callable as the root_factory argument of the Configurator constructor, instead of associating it with a particular route inside the route’s configuration. Every hybrid route configuration that is matched but which does not name a factory attribute will use the use global root_factory function to generate a root object.

When the route configuration named home above is matched during a request, the matchdict generated will be based on its pattern: {foo}/{bar}/*traverse. The “capture value” implied by the *traverse element in the pattern will be used to traverse the resource tree in order to find a context resource, starting from the root object returned from the root factory. In the above example, the root object found will be the instance named root in routes.py.

If the URL that matched a route with the pattern {foo}/{bar}/*traverse, is http://example.com/one/two/a/b/c, the traversal path used against the root object will be a/b/c. As a result, Pyramid will attempt to traverse through the edges a, b, and c, beginning at the root object.

In our above example, this particular set of traversal steps will mean that the context resource of the view would be the Traversable object we’ve named c in our bogus resource tree and the view name resulting from traversal will be the empty string; if you need a refresher about why this outcome is presumed, see The Traversal Algorithm.

At this point, a suitable view callable will be found and invoked using view lookup as described in View Configuration, but with a caveat: in order for view lookup to work, we need to define a view configuration that will match when view lookup is invoked after a route matches:

1
2
3

config.add_route('home', '{foo}/{bar}/*traverse',
                 factory='mypackage.routes.root_factory')
config.add_view('mypackage.views.myview', route_name='home')

Note that the above call to add_view() includes a route_name argument. View configurations that include a route_name argument are meant to associate a particular view declaration with a route, using the route’s name, in order to indicate that the view should only be invoked when the route matches.

Calls to add_view() may pass a route_name attribute, which refers to the value of an existing route’s name argument. In the above example, the route name is home, referring to the name of the route defined above it.

The above mypackage.views.myview view callable will be invoked when:

the route named “home” is matched

the view name resulting from traversal is the empty string.

the context resource is any object.

It is also possible to declare alternate views that may be invoked when a hybrid route is matched:

1
2
3
4
5

config.add_route('home', '{foo}/{bar}/*traverse',
                 factory='mypackage.routes.root_factory')
config.add_view('mypackage.views.myview', name='home')
config.add_view('mypackage.views.another_view', name='another',
                route_name='home')

The add_view call for mypackage.views.another_view above names a different view and, more importantly, a different view name. The above mypackage.views.another_view view will be invoked when:

the route named “home” is matched

the view name resulting from traversal is another.

the context resource is any object.

For instance, if the URL http://example.com/one/two/a/another is provided to an application that uses the previously mentioned resource tree, the mypackage.views.another view callable will be called instead of the mypackage.views.myview view callable because the view name will be another instead of the empty string.

More complicated matching can be composed. All arguments to route configuration statements and view configuration statements are supported in hybrid applications (such as predicate arguments).

Using the traverse Argument In a Route Definition

Rather than using the *traverse remainder marker in a pattern, you can use the traverse argument to the add_route() method.

When you use the *traverse remainder marker, the traversal path is limited to being the remainder segments of a request URL when a route matches. However, when you use the traverse argument or attribute, you have more control over how to compose a traversal path.

Here’s a use of the traverse pattern in a call to add_route():

1
2

config.add_route('abc', '/articles/{article}/edit',
                 traverse='/articles/{article}')

The syntax of the traverse argument is the same as it is for pattern.

If, as above, the pattern provided is articles/{article}/edit, and the traverse argument provided is /{article}, when a request comes in that causes the route to match in such a way that the article match value is 1 (when the request URI is /articles/1/edit), the traversal path will be generated as /1. This means that the root object’s __getitem__ will be called with the name 1 during the traversal phase. If the 1 object exists, it will become the context of the request. The Traversal chapter has more information about traversal.

If the traversal path contains segment marker names which are not present in the pattern argument, a runtime error will occur. The traverse pattern should not contain segment markers that do not exist in the path.

Note that the traverse argument is ignored when attached to a route that has a *traverse remainder marker in its pattern.

Traversal will begin at the root object implied by this route (either the global root, or the object returned by the factory associated with this route).

Making Global Views Match

By default, only view configurations that mention a route_name will be found during view lookup when a route that has a *traverse in its pattern matches. You can allow views without a route_name attribute to match a route by adding the use_global_views flag to the route definition. For example, the myproject.views.bazbuz view below will be found if the route named abc below is matched and the PATH_INFO is /abc/bazbuz, even though the view configuration statement does not have the route_name="abc" attribute.

1
2

config.add_route('abc', '/abc/*traverse', use_global_views=True)
config.add_view('myproject.views.bazbuz', name='bazbuz')

Using *subpath in a Route Pattern

There are certain extremely rare cases when you’d like to influence the traversal subpath when a route matches without actually performing traversal. For instance, the pyramid.wsgi.wsgiapp2() decorator and the pyramid.view.static helper attempt to compute PATH_INFO from the request’s subpath, so it’s useful to be able to influence this value.

When *subpath exists in a pattern, no path is actually traversed, but the traversal algorithm will return a subpath list implied by the capture value of *subpath. You’ll see this pattern most commonly in route declarations that look like this:

1
2

config.add_route('static', '/static/*subpath',
                 view='mypackage.views.static_view')

Where mypackage.views.static_view is an instance of pyramid.view.static. This effectively tells the static helper to traverse everything in the subpath as a filename.

Corner Cases

A number of corner case “gotchas” exist when using a hybrid application. We’ll detail them here.

Registering a Default View for a Route That Has a view Attribute

It is an error to provide both a view argument to a route configuration and a view configuration which names a route_name that has no name value or the empty name value. For example, this pair of declarations will generate a “conflict” error at startup time.

1
2
3

config.add_route('home', '{foo}/{bar}/*traverse',
                 view='myproject.views.home')
config.add_view('myproject.views.another', route_name='home')

This is because the view argument to the add_route() above is an implicit default view when that route matches. add_route calls don’t need to supply a view attribute. For example, this add_route call:

1
2

config.add_route('home', '{foo}/{bar}/*traverse',
                 view='myproject.views.home')

Can also be spelled like so:

1
2

config.add_route('home', '{foo}/{bar}/*traverse')
config.add_view('myproject.views.home', route_name='home')

The two spellings are logically equivalent. In fact, the former is just a syntactical shortcut for the latter.

Binding Extra Views Against a Route Configuration that Doesn’t Have a *traverse Element In Its Pattern

Here’s another corner case that just makes no sense:

1
2
3

config.add_route('abc', '/abc', view='myproject.views.abc')
config.add_view('myproject.views.bazbuz', name='bazbuz',
                route_name='abc')

The above view declaration is useless, because it will never be matched when the route it references has matched. Only the view associated with the route itself (myproject.views.abc) will ever be invoked when the route matches, because the default view is always invoked when a route matches and when no post-match traversal is performed.

To make the above view declaration useful, the special *traverse token must end the route’s pattern. For example:

1
2
3

config.add_route('abc', '/abc/*traverse', view='myproject.views.abc')
config.add_view('myproject.views.bazbuz', name='bazbuz',
                route_name='abc')

With the above configuration, the myproject.views.bazbuz view will be invoked when the request URI is /abc/bazbuz, assuming there is no object contained by the root object with the key bazbuz. A different request URI, such as /abc/foo/bar, would invoke the default myproject.views.abc view.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Internationalization and Localization

Internationalization (i18n) is the act of creating software with a user interface that can potentially be displayed in more than one language or cultural context. Localization (l10n) is the process of displaying the user interface of an internationalized application in a particular language or cultural context.

Pyramid offers internationalization and localization subsystems that can be used to translate the text of buttons, error messages and other software- and template-defined values into the native language of a user of your application.

Creating a Translation String

While you write your software, you can insert specialized markup into your Python code that makes it possible for the system to translate text values into the languages used by your application’s users. This markup creates a translation string. A translation string is an object that behaves mostly like a normal Unicode object, except that it also carries around extra information related to its job as part of the Pyramid translation machinery.

Using The TranslationString Class

The most primitive way to create a translation string is to use the pyramid.i18n.TranslationString callable:

1
2

from pyramid.i18n import TranslationString
ts = TranslationString('Add')

This creates a Unicode-like object that is a TranslationString.

Note

For people more familiar with Zope i18n, a TranslationString is a lot like a zope.i18nmessageid.Message object. It is not a subclass, however. For people more familiar with Pylons or Django i18n, using a TranslationString is a lot like using “lazy” versions of related gettext APIs.

The first argument to TranslationString is the msgid; it is required. It represents the key into the translation mappings provided by a particular localization. The msgid argument must be a Unicode object or an ASCII string. The msgid may optionally contain replacement markers. For instance:

1
2

from pyramid.i18n import TranslationString
ts = TranslationString('Add ${number}')

Within the string above, ${number} is a replacement marker. It will be replaced by whatever is in the mapping for a translation string. The mapping may be supplied at the same time as the replacement marker itself:

1
2

from pyramid.i18n import TranslationString
ts = TranslationString('Add ${number}', mapping={'number':1})

Any number of replacement markers can be present in the msgid value, any number of times. Only markers which can be replaced by the values in the mapping will be replaced at translation time. The others will not be interpolated and will be output literally.

A translation string should also usually carry a domain. The domain represents a translation category to disambiguate it from other translations of the same msgid, in case they conflict.

1
2
3

from pyramid.i18n import TranslationString
ts = TranslationString('Add ${number}', mapping={'number':1},
                       domain='form')

The above translation string named a domain of form. A translator function will often use the domain to locate the right translator file on the filesystem which contains translations for a given domain. In this case, if it were trying to translate our msgid to German, it might try to find a translation from a gettext file within a translation directory like this one:

locale/de/LC_MESSAGES/form.mo

In other words, it would want to take translations from the form.mo translation file in the German language.

Finally, the TranslationString constructor accepts a default argument. If a default argument is supplied, it replaces usages of the msgid as the default value for the translation string. When default is None, the msgid value passed to a TranslationString is used as an implicit message identifier. Message identifiers are matched with translations in translation files, so it is often useful to create translation strings with “opaque” message identifiers unrelated to their default text:

1
2
3

from pyramid.i18n import TranslationString
ts = TranslationString('add-number', default='Add ${number}',
                        domain='form', mapping={'number':1})

When default text is used, Default text objects may contain replacement values.

Using the TranslationStringFactory Class

Another way to generate a translation string is to use the TranslationStringFactory object. This object is a translation string factory. Basically a translation string factory presets the domain value of any translation string generated by using it. For example:

1
2
3

from pyramid.i18n import TranslationStringFactory
_ = TranslationStringFactory('pyramid')
ts = _('Add ${number}', msgid='add-number', mapping={'number':1})

Note

We assigned the translation string factory to the name _. This is a convention which will be supported by translation file generation tools.

After assigning _ to the result of a TranslationStringFactory(), the subsequent result of calling _ will be a TranslationString instance. Even though a domain value was not passed to _ (as would have been necessary if the TranslationString constructor were used instead of a translation string factory), the domain attribute of the resulting translation string will be pyramid. As a result, the previous code example is completely equivalent (except for spelling) to:

1
2
3

from pyramid.i18n import TranslationString as _
ts = _('Add ${number}', msgid='add-number', mapping={'number':1},
       domain='pyramid')

You can set up your own translation string factory much like the one provided above by using the TranslationStringFactory class. For example, if you’d like to create a translation string factory which presets the domain value of generated translation strings to form, you’d do something like this:

1
2
3

from pyramid.i18n import TranslationStringFactory
_ = TranslationStringFactory('form')
ts = _('Add ${number}', msgid='add-number', mapping={'number':1})

Creating a unique domain for your application via a translation string factory is best practice. Using your own unique translation domain allows another person to reuse your application without needing to merge your translation files with his own. Instead, he can just include your package’s translation directory via the pyramid.config.Configurator.add_translation_dirs() method.

Note

For people familiar with Zope internationalization, a TranslationStringFactory is a lot like a zope.i18nmessageid.MessageFactory object. It is not a subclass, however.

Working With gettext Translation Files

The basis of Pyramid translation services is GNU gettext. Once your application source code files and templates are marked up with translation markers, you can work on translations by creating various kinds of gettext files.

Note

The steps a developer must take to work with gettext message catalog files within a Pyramid application are very similar to the steps a Pylons developer must take to do the same. See the Pylons internationalization documentation [http://wiki.pylonshq.com/display/pylonsdocs/Internationalization+and+Localization] for more information.

GNU gettext uses three types of files in the translation framework, .pot files, .po files and .mo files.

.pot (Portable Object Template) files

A .pot file is created by a program which searches through your project’s source code and which picks out every message identifier passed to one of the ‘_() functions (eg. translation string constructions). The list of all message identifiers is placed into a .pot file, which serves as a template for creating .po files.

.po (Portable Object) files

The list of messages in a .pot file are translated by a human to a particular language; the result is saved as a .po file.

.mo (Machine Object) files

A .po file is turned into a machine-readable binary file, which is the .mo file. Compiling the translations to machine code makes the localized program run faster.

The tool for working with gettext translation files related to a Pyramid application is Babel.

Installing Babel

In order for the commands related to working with gettext translation files to work properly, you will need to have Babel installed into the same environment in which Pyramid is installed.

Installation on UNIX

If the virtualenv into which you’ve installed your Pyramid application lives in /my/virtualenv, you can install Babel like so:

$ cd /my/virtualenv
$ bin/easy_install Babel

Installation on Windows

If the virtualenv into which you’ve installed your Pyramid application lives in C:\my\virtualenv, you can install Babel like so:

C> cd \my\virtualenv
C> bin\easy_install Babel

Changing the setup.py

You need to add a few boilerplate lines to your application’s setup.py file in order to properly generate gettext files from your application.

Note

See Creating a Pyramid Project to learn about about the composition of an application’s setup.py file.

In particular, add the Babel distribution to the install_requires list and insert a set of references to Babel message extractors within the call to setuptools.setup() inside your application’s setup.py file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

 setup(name="mypackage",
       # ...
       install_requires = [
             # ...
             'Babel',
             ],
       message_extractors = { '.': [
             ('**.py',   'chameleon_python', None ),
             ('**.pt',   'chameleon_xml', None ),
             ]},
       )

The message_extractors stanza placed into the setup.py file causes the Babel message catalog extraction machinery to also consider **.pt files when doing message id extraction.

Extracting Messages from Code and Templates

Once Babel is installed and your application’s setup.py file has the correct message extractor references, you may extract a message catalog template from the code and Chameleon templates which reside in your Pyramid application. You run a setup.py command to extract the messages:

$ cd /place/where/myapplication/setup.py/lives
$ mkdir -p myapplication/locale
$ python setup.py extract_messages

The message catalog .pot template will end up in:

myapplication/locale/myapplication.pot.

Translation Domains

The name myapplication above in the filename myapplication.pot denotes the translation domain of the translations that must be performed to localize your application. By default, the translation domain is the project name of your Pyramid application.

To change the translation domain of the extracted messages in your project, edit the setup.cfg file of your application, The default setup.cfg file of a Paster-generated Pyramid application has stanzas in it that look something like the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

 [compile_catalog]
 directory = myproject/locale
 domain = MyProject
 statistics = true

 [extract_messages]
 add_comments = TRANSLATORS:
 output_file = myproject/locale/MyProject.pot
 width = 80

 [init_catalog]
 domain = MyProject
 input_file = myproject/locale/MyProject.pot
 output_dir = myproject/locale

 [update_catalog]
 domain = MyProject
 input_file = myproject/locale/MyProject.pot
 output_dir = myproject/locale
 previous = true

In the above example, the project name is MyProject. To indicate that you’d like the domain of your translations to be mydomain instead, change the setup.cfg file stanzas to look like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

 [compile_catalog]
 directory = myproject/locale
 domain = mydomain
 statistics = true

 [extract_messages]
 add_comments = TRANSLATORS:
 output_file = myproject/locale/mydomain.pot
 width = 80

 [init_catalog]
 domain = mydomain
 input_file = myproject/locale/mydomain.pot
 output_dir = myproject/locale

 [update_catalog]
 domain = mydomain
 input_file = myproject/locale/mydomain.pot
 output_dir = myproject/locale
 previous = true

Initializing a Message Catalog File

Once you’ve extracted messages into a .pot file (see Extracting Messages from Code and Templates), to begin localizing the messages present in the .pot file, you need to generate at least one .po file. A .po file represents translations of a particular set of messages to a particular locale. Initialize a .po file for a specific locale from a pre-generated .pot template by using the setup.py init_catalog command:

$ cd /place/where/myapplication/setup.py/lives
$ python setup.py init_catalog -l es

By default, the message catalog .po file will end up in:

myapplication/locale/es/LC_MESSAGES/myapplication.po.

Once the file is there, it can be worked on by a human translator. One tool which may help with this is Poedit [http://www.poedit.net/].

Note that Pyramid itself ignores the existence of all .po files. For a running application to have translations available, a .mo file must exist. See Compiling a Message Catalog File.

Updating a Catalog File

If more translation strings are added to your application, or translation strings change, you will need to update existing .po files based on changes to the .pot file, so that the new and changed messages can also be translated or re-translated.

First, regenerate the .pot file as per Extracting Messages from Code and Templates. Then use the setup.py update_catalog command.

$ cd /place/where/myapplication/setup.py/lives
$ python setup.py update_catalog

Compiling a Message Catalog File

Finally, to prepare an application for performing actual runtime translations, compile .po files to .mo files:

$ cd /place/where/myapplication/setup.py/lives
$ python setup.py compile_catalog

This will create a .mo file for each .po file in your application. As long as the translation directory in which the .mo file ends up in is configured into your application, these translations will be available to Pyramid.

Using a Localizer

A localizer is an object that allows you to perform translation or pluralization “by hand” in an application. You may use the pyramid.i18n.get_localizer() function to obtain a localizer. This function will return either the localizer object implied by the active locale negotiator or a default localizer object if no explicit locale negotiator is registered.

1
2
3
4

from pyramid.i18n import get_localizer

def aview(request):
    locale = get_localizer(request)

Performing a Translation

A localizer has a translate method which accepts either a translation string or a Unicode string and which returns a Unicode object representing the translation. So, generating a translation in a view component of an application might look like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from pyramid.i18n import get_localizer
from pyramid.i18n import TranslationString

ts = TranslationString('Add ${number}', mapping={'number':1},
                       domain='pyramid')

def aview(request):
    localizer = get_localizer(request)
    translated = localizer.translate(ts) # translation string
    # ... use translated ...

The get_localizer() function will return a pyramid.i18n.Localizer object bound to the locale name represented by the request. The translation returned from its pyramid.i18n.Localizer.translate() method will depend on the domain attribute of the provided translation string as well as the locale of the localizer.

Note

If you’re using Chameleon templates, you don’t need to pre-translate translation strings this way. See Chameleon Template Support for Translation Strings.

Performing a Pluralization

A localizer has a pluralize method with the following signature:

1
2

def pluralize(singular, plural, n, domain=None, mapping=None):
    ...

The singular and plural arguments should each be a Unicode value representing a message identifier. n should be an integer. domain should be a translation domain, and mapping should be a dictionary that is used for replacement value interpolation of the translated string. If n is plural for the current locale, pluralize will return a Unicode translation for the message id plural, otherwise it will return a Unicode translation for the message id singular.

The arguments provided as singular and/or plural may also be translation string objects, but the domain and mapping information attached to those objects is ignored.

1
2
3
4
5
6

from pyramid.i18n import get_localizer

def aview(request):
    localizer = get_localizer(request)
    translated = localizer.pluralize('Item', 'Items', 1, 'mydomain')
    # ... use translated ...

Obtaining the Locale Name for a Request

You can obtain the locale name related to a request by using the pyramid.i18n.get_locale_name() function.

1
2
3
4

from pyramid.i18n import get_locale_name

def aview(request):
    locale_name = get_locale_name(request)

This returns the locale name negotiated by the currently active locale negotiator or the default locale name if the locale negotiator returns None. You can change the default locale name by changing the default_locale_name setting; see Default Locale Name.

Once get_locale_name() is first run, the locale name is stored on the request object. Subsequent calls to get_locale_name() will return the stored locale name without invoking the locale negotiator. To avoid this caching, you can use the pyramid.i18n.negotiate_locale_name() function:

1
2
3
4

from pyramid.i18n import negotiate_locale_name

def aview(request):
    locale_name = negotiate_locale_name(request)

You can also obtain the locale name related to a request using the locale_name attribute of a localizer.

1
2
3
4
5

from pyramid.i18n import get_localizer

def aview(request):
    localizer = get_localizer(request)
    locale_name = localizer.locale_name

Obtaining the locale name as an attribute of a localizer is equivalent to obtaining a locale name by calling the get_locale_name() function.

Performing Date Formatting and Currency Formatting

Pyramid does not itself perform date and currency formatting for different locales. However, Babel can help you do this via the babel.core.Locale class. The Babel documentation for this class [http://babel.edgewall.org/wiki/ApiDocs/babel.core#babel.core:Locale] provides minimal information about how to perform date and currency related locale operations. See Installing Babel for information about how to install Babel.

The babel.core.Locale class requires a locale name as an argument to its constructor. You can use Pyramid APIs to obtain the locale name for a request to pass to the babel.core.Locale constructor; see Obtaining the Locale Name for a Request. For example:

1
2
3
4
5
6

from babel.core import Locale
from pyramid.i18n import get_locale_name

def aview(request):
    locale_name = get_locale_name(request)
    locale = Locale(locale_name)

Chameleon Template Support for Translation Strings

When a translation string is used as the subject of textual rendering by a Chameleon template renderer, it will automatically be translated to the requesting user’s language if a suitable translation exists. This is true of both the ZPT and text variants of the Chameleon template renderers.

For example, in a Chameleon ZPT template, the translation string represented by “some_translation_string” in each example below will go through translation before being rendered:

1

<span tal:content="some_translation_string"/>

1

<span tal:replace="some_translation_string"/>

1

<span>${some_translation_string}</span>

1

<a tal:attributes="href some_translation_string">Click here</a>

The features represented by attributes of the i18n namespace of Chameleon will also consult the Pyramid translations. See http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace.

Note

Unlike when Chameleon is used outside of Pyramid, when it is used within Pyramid, it does not support use of the zope.i18n translation framework. Applications which use Pyramid should use the features documented in this chapter rather than zope.i18n.

Third party Pyramid template renderers might not provide this support out of the box and may need special code to do an equivalent. For those, you can always use the more manual translation facility described in Performing a Translation.

Mako Pyramid I18N Support

There exists a recipe within the Pyramid Cookbook named “Mako Internationalization” which explains how to add idiomatic I18N support to Mako templates.

Localization-Related Deployment Settings

A Pyramid application will have a default_locale_name setting. This value represents the default locale name used when the locale negotiator returns None. Pass it to the Configurator constructor at startup time:

1
2

from pyramid.config import Configurator
config = Configurator(settings={'default_locale_name':'de'})

You may alternately supply a default_locale_name via an application’s Paster .ini file:

1
2
3
4
5
6

[app:main]
use = egg:MyProject#app
reload_templates = true
debug_authorization = false
debug_notfound = false
default_locale_name = de

If this value is not supplied via the Configurator constructor or via a Paste config file, it will default to en.

If this setting is supplied within the Pyramid application .ini file, it will be available as a settings key:

1
2
3

from pyramid.threadlocal import get_current_registry
settings = get_current_registry().settings
default_locale_name = settings['default_locale_name']

“Detecting” Available Languages

Other systems provide an API that returns the set of “available languages” as indicated by the union of all languages in all translation directories on disk at the time of the call to the API.

It is by design that Pyramid doesn’t supply such an API. Instead, the application itself is responsible for knowing the “available languages”. The rationale is this: any particular application deployment must always know which languages it should be translatable to anyway, regardless of which translation files are on disk.

Here’s why: it’s not a given that because translations exist in a particular language within the registered set of translation directories that this particular deployment wants to allow translation to that language. For example, some translations may exist but they may be incomplete or incorrect. Or there may be translations to a language but not for all translation domains.

Any nontrivial application deployment will always need to be able to selectively choose to allow only some languages even if that set of languages is smaller than all those detected within registered translation directories. The easiest way to allow for this is to make the application entirely responsible for knowing which languages are allowed to be translated to instead of relying on the framework to divine this information from translation directory file info.

You can set up a system to allow a deployer to select available languages based on convention by using the pyramid.settings mechanism:

Allow a deployer to modify your application’s PasteDeploy .ini file:

1
2
3
4

[app:main]
use = egg:MyProject#app
# ...
available_languages = fr de en ru

Then as a part of the code of a custom locale negotiator:

1
2
3

from pyramid.threadlocal import get_current_registry
settings = get_current_registry().settings
languages = settings['available_languages'].split()

This is only a suggestion. You can create your own “available languages” configuration scheme as necessary.

Activating Translation

By default, a Pyramid application performs no translation. To turn translation on, you must:

add at least one translation directory to your application.

ensure that your application sets the locale name correctly.

Adding a Translation Directory

gettext is the underlying machinery behind the Pyramid translation machinery. A translation directory is a directory organized to be useful to gettext. A translation directory usually includes a listing of language directories, each of which itself includes an LC_MESSAGES directory. Each LC_MESSAGES directory should contain one or more .mo files. Each .mo file represents a message catalog, which is used to provide translations to your application.

Adding a translation directory registers all of its constituent message catalog files within your Pyramid application to be available to use for translation services. This includes all of the .mo files found within all LC_MESSAGES directories within each locale directory in the translation directory.

You can add a translation directory imperatively by using the pyramid.config.Configurator.add_translation_dirs() during application startup. For example:

1
2
3

from pyramid.config import Configurator
config.add_translation_dirs('my.application:locale/',
                            'another.application:locale/')

A message catalog in a translation directory added via add_translation_dirs() will be merged into translations from a message catalog added earlier if both translation directories contain translations for the same locale and translation domain.

Setting the Locale

When the default locale negotiator (see The Default Locale Negotiator) is in use, you can inform Pyramid of the current locale name by doing any of these things before any translations need to be performed:

Set the _LOCALE_ attribute of the request to a valid locale name (usually directly within view code). E.g. request._LOCALE_ = 'de'.

Ensure that a valid locale name value is in the request.params dictionary under the key named _LOCALE_. This is usually the result of passing a _LOCALE_ value in the query string or in the body of a form post associated with a request. For example, visiting http://my.application?_LOCALE_=de.

Ensure that a valid locale name value is in the request.cookies dictionary under the key named _LOCALE_. This is usually the result of setting a _LOCALE_ cookie in a prior response, e.g. response.set_cookie('_LOCALE_', 'de').

Note

If this locale negotiation scheme is inappropriate for a particular application, you can configure a custom locale negotiator function into that application as required. See Using a Custom Locale Negotiator.

Locale Negotiators

A locale negotiator informs the operation of a localizer by telling it what locale name is related to a particular request. A locale negotiator is a bit of code which accepts a request and which returns a locale name. It is consulted when pyramid.i18n.Localizer.translate() or pyramid.i18n.Localizer.pluralize() is invoked. It is also consulted when get_locale_name() or negotiate_locale_name() is invoked.

The Default Locale Negotiator

Most applications can make use of the default locale negotiator, which requires no additional coding or configuration.

The default locale negotiator implementation named default_locale_negotiator uses the following set of steps to dermine the locale name.

First, the negotiator looks for the _LOCALE_ attribute of the request object (possibly set directly by view code or by a listener for an event).

Then it looks for the request.params['_LOCALE_'] value.

Then it looks for the request.cookies['_LOCALE_'] value.

If no locale can be found via the request, it falls back to using the default locale name (see Localization-Related Deployment Settings).

Finally, if the default locale name is not explicitly set, it uses the locale name en.

Using a Custom Locale Negotiator

Locale negotiation is sometimes policy-laden and complex. If the (simple) default locale negotiation scheme described in Activating Translation is inappropriate for your application, you may create and a special locale negotiator. Subsequently you may override the default locale negotiator by adding your newly created locale negotiator to your application’s configuration.

A locale negotiator is simply a callable which accepts a request and returns a single locale name or None if no locale can be determined.

Here’s an implementation of a simple locale negotiator:

1
2
3

 def my_locale_negotiator(request):
     locale_name = request.params.get('my_locale')
     return locale_name

If a locale negotiator returns None, it signifies to Pyramid that the default application locale name should be used.

You may add your newly created locale negotiator to your application’s configuration by passing an object which can act as the negotiator (or a dotted Python name referring to the object) as the locale_negotiator argument of the Configurator instance during application startup. For example:

1
2

from pyramid.config import Configurator
config = Configurator(locale_negotiator=my_locale_negotiator)

Alternately, use the pyramid.config.Configurator.set_locale_negotiator() method.

For example:

1
2
3

from pyramid.config import Configurator
config = Configurator()
config.set_locale_negotiator(my_locale_negotiator)

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Virtual Hosting

“Virtual hosting” is, loosely, the act of serving a Pyramid application or a portion of a Pyramid application under a URL space that it does not “naturally” inhabit.

Pyramid provides facilities for serving an application under a URL “prefix”, as well as serving a portion of a traversal based application under a root URL.

Hosting an Application Under a URL Prefix

Pyramid supports a common form of virtual hosting whereby you can host a Pyramid application as a “subset” of some other site (e.g. under http://example.com/mypyramidapplication/ as opposed to under http://example.com/).

If you use a “pure Python” environment, this functionality is provided by Paste’s urlmap [http://pythonpaste.org/modules/urlmap.html] “composite” WSGI application. Alternately, you can use mod_wsgi to serve your application, which handles this virtual hosting translation for you “under the hood”.

If you use the urlmap composite application “in front” of a Pyramid application or if you use mod_wsgi to serve up a Pyramid application, nothing special needs to be done within the application for URLs to be generated that contain a prefix. paste.urlmap and mod_wsgi manipulate the WSGI environment in such a way that the PATH_INFO and SCRIPT_NAME variables are correct for some given prefix.

Here’s an example of a PasteDeploy configuration snippet that includes a urlmap composite.

1
2
3
4
5
6

[app:mypyramidapp]
use = egg:mypyramidapp#app

[composite:main]
use = egg:Paste#urlmap
/pyramidapp = mypyramidapp

This “roots” the Pyramid application at the prefix /pyramidapp and serves up the composite as the “main” application in the file.

Note

If you’re using an Apache server to proxy to a Paste urlmap composite, you may have to use the ProxyPreserveHost [http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypreservehost] directive to pass the original HTTP_HOST header along to the application, so URLs get generated properly. As of this writing the urlmap composite does not seem to respect the HTTP_X_FORWARDED_HOST parameter, which will contain the original host header even if HTTP_HOST is incorrect.

If you use mod_wsgi, you do not need to use a composite application in your .ini file. The WSGIScriptAlias configuration setting in a mod_wsgi configuration does the work for you:

1

WSGIScriptAlias /pyramidapp /Users/chrism/projects/modwsgi/env/pyramid.wsgi

In the above configuration, we root a Pyramid application at /pyramidapp within the Apache configuration.

Virtual Root Support

Pyramid also supports “virtual roots”, which can be used in traversal -based (but not URL dispatch -based) applications.

Virtual root support is useful when you’d like to host some resource in a Pyramid resource tree as an application under a URL pathname that does not include the resource path itself. For example, you might want to serve the object at the traversal path /cms as an application reachable via http://example.com/ (as opposed to http://example.com/cms).

To specify a virtual root, cause an environment variable to be inserted into the WSGI environ named HTTP_X_VHM_ROOT with a value that is the absolute pathname to the resource object in the resource tree that should behave as the “root” resource. As a result, the traversal machinery will respect this value during traversal (prepending it to the PATH_INFO before traversal starts), and the pyramid.url.resource_url() API will generate the “correct” virtually-rooted URLs.

An example of an Apache mod_proxy configuration that will host the /cms subobject as http://www.example.com/ using this facility is below:

1
2
3
4
5
6
7
8
9

 NameVirtualHost *:80

 <VirtualHost *:80>
   ServerName www.example.com
   RewriteEngine On
   RewriteRule ^/(.*) http://127.0.0.1:6543/$1 [L,P]
   ProxyPreserveHost on
   RequestHeader add X-Vhm-Root /cms
 </VirtualHost>

Note

Use of the RequestHeader directive requires that the Apache mod_headers [http://httpd.apache.org/docs/2.2/mod/mod_headers.html] module be available in the Apache environment you’re using.

For a Pyramid application running under mod_wsgi, the same can be achieved using SetEnv:

1
2
3

 <Location />
   SetEnv HTTP_X_VHM_ROOT /cms
 </Location>

Setting a virtual root has no effect when using an application based on URL dispatch.

Further Documentation and Examples

The API documentation in pyramid.traversal documents a pyramid.traversal.virtual_root() API. When called, it returns the virtual root object (or the physical root object if no virtual root has been specified).

Running a Pyramid Application under mod_wsgi has detailed information about using mod_wsgi to serve Pyramid applications.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Using Events

An event is an object broadcast by the Pyramid framework at interesting points during the lifetime of an application. You don’t need to use events in order to create most Pyramid applications, but they can be useful when you want to perform slightly advanced operations. For example, subscribing to an event can allow you to run some code as the result of every new request.

Events in Pyramid are always broadcast by the framework. However, they only become useful when you register a subscriber. A subscriber is a function that accepts a single argument named event:

1
2

def mysubscriber(event):
    print event

The above is a subscriber that simply prints the event to the console when it’s called.

The mere existence of a subscriber function, however, is not sufficient to arrange for it to be called. To arrange for the subscriber to be called, you’ll need to use the pyramid.config.Configurator.add_subscriber() method or you’ll need to use the pyramid.events.subscriber() decorator to decorate a function found via a scan.

Configuring an Event Listener Imperatively

You can imperatively configure a subscriber function to be called for some event type via the add_subscriber() method (see also Configurator):

1
2
3
4
5
6
7
8

from pyramid.events import NewRequest

from subscribers import mysubscriber

# "config" below is assumed to be an instance of a
# pyramid.config.Configurator object

config.add_subscriber(mysubscriber, NewRequest)

The first argument to add_subscriber() is the subscriber function (or a dotted Python name which refers to a subscriber callable); the second argument is the event type.

Configuring an Event Listener Using a Decorator

You can configure a subscriber function to be called for some event type via the pyramid.events.subscriber() function.

1
2
3
4
5
6

from pyramid.events import NewRequest
from pyramid.events import subscriber

@subscriber(NewRequest)
def mysubscriber(event):
        event.request.foo = 1

When the subscriber() decorator is used a scan must be performed against the package containing the decorated function for the decorator to have any effect.

Either of the above registration examples implies that every time the Pyramid framework emits an event object that supplies an pyramid.events.NewRequest interface, the mysubscriber function will be called with an event object.

As you can see, a subscription is made in terms of a class (such as pyramid.events.NewResponse). The event object sent to a subscriber will always be an object that possesses an interface. For pyramid.events.NewResponse, that interface is pyramid.interfaces.INewResponse. The interface documentation provides information about available attributes and methods of the event objects.

The return value of a subscriber function is ignored. Subscribers to the same event type are not guaranteed to be called in any particular order relative to each other.

All the concrete Pyramid event types are documented in the pyramid.events API documentation.

An Example

If you create event listener functions in a subscribers.py file in your application like so:

1
2
3
4
5

def handle_new_request(event):
    print 'request', event.request

def handle_new_response(event):
    print 'response', event.response

You may configure these functions to be called at the appropriate times by adding the following code to your application’s configuration startup:

1
2
3
4
5
6

# config is an instance of pyramid.config.Configurator

config.add_subscriber('myproject.subscribers.handle_new_request',
                      'pyramid.events.NewRequest')
config.add_subscriber('myproject.subscribers.handle_new_response',
                      'pyramid.events.NewResponse')

Either mechanism causes the functions in subscribers.py to be registered as event subscribers. Under this configuration, when the application is run, each time a new request or response is detected, a message will be printed to the console.

Each of our subscriber functions accepts an event object and prints an attribute of the event object. This begs the question: how can we know which attributes a particular event has?

We know that pyramid.events.NewRequest event objects have a request attribute, which is a request object, because the interface defined at pyramid.interfaces.INewRequest says it must. Likewise, we know that pyramid.interfaces.NewResponse events have a response attribute, which is a response object constructed by your application, because the interface defined at pyramid.interfaces.INewResponse says it must (pyramid.events.NewResponse objects also have a request).

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Environment Variables and .ini File Settings

Pyramid behavior can be configured through a combination of operating system environment variables and .ini configuration file application section settings. The meaning of the environment variables and the configuration file settings overlap.

Note

Where a configuration file setting exists with the same meaning as an environment variable, and both are present at application startup time, the environment variable setting takes precedence.

The term “configuration file setting name” refers to a key in the .ini configuration for your application. The configuration file setting names documented in this chapter are reserved for Pyramid use. You should not use them to indicate application-specific configuration settings.

Reloading Templates

When this value is true, templates are automatically reloaded whenever they are modified without restarting the application, so you can see changes to templates take effect immediately during development. This flag is meaningful to Chameleon and Mako templates, as well as most third-party template rendering extensions.

Environment Variable Name | Config File Setting Name
PYRAMID_RELOAD_TEMPLATES | reload_templates

Reloading Assets

Don’t cache any asset file data when this value is true. See also Overriding Assets.

Environment Variable Name | Config File Setting Name
PYRAMID_RELOAD_ASSETS | reload_assets

Note

For backwards compatibility purposes, aliases can be used for configurating asset reloading: PYRAMID_RELOAD_RESOURCES (envvar) and reload_resources (config file).

Debugging Authorization

Print view authorization failure and success information to stderr when this value is true. See also Debugging View Authorization Failures.

Environment Variable Name | Config File Setting Name
PYRAMID_DEBUG_AUTHORIZATION | debug_authorization

Debugging Not Found Errors

Print view-related NotFound debug messages to stderr when this value is true. See also NotFound Errors.

Environment Variable Name | Config File Setting Name
PYRAMID_DEBUG_NOTFOUND | debug_notfound

Debugging Route Matching

Print debugging messages related to url dispatch route matching when this value is true. See also Debugging Route Matching.

Environment Variable Name | Config File Setting Name
PYRAMID_DEBUG_ROUTEMATCH | debug_routematch

Debugging All

Turns on all debug* settings.

Environment Variable Name | Config File Setting Name
PYRAMID_DEBUG_ALL | debug_all

Reloading All

Turns on all reload* settings.

Environment Variable Name | Config File Setting Name
PYRAMID_RELOAD_ALL | reload_all

Default Locale Name

The value supplied here is used as the default locale name when a locale negotiator is not registered. See also Localization-Related Deployment Settings.

Environment Variable Name | Config File Setting Name
PYRAMID_DEFAULT_LOCALE_NAME | default_locale_name

Mako Template Render Settings

Mako derives additional settings to configure its template renderer that should be set when using it. Many of these settings are optional and only need to be set if they should be different from the default. The Mako Template Renderer uses a subclass of Mako’s template lookup [http://www.makotemplates.org/docs/usage.html#usage_lookup] and accepts several arguments to configure it.

Mako Directories

The value(s) supplied here are passed in as the template directories. They should be in asset specification format, for example: my.package:templates.

Config File Setting Name

mako.directories

Mako Module Directory

The value supplied here tells Mako where to store compiled Mako templates. If omitted, compiled templates will be stored in memory. This value should be an absolute path, for example: %(here)s/data/templates would use a directory called data/templates in the same parent directory as the INI file.

Config File Setting Name

mako.module_directory

Mako Input Encoding

The encoding that Mako templates are assumed to have. By default this is set to utf-8. If you wish to use a different template encoding, this value should be changed accordingly.

Config File Setting Name

mako.input_encoding

Mako Error Handler

Python callable which is called whenever Mako compile or runtime exceptions occur. The callable is passed the current context as well as the exception. If the callable returns True, the exception is considered to be handled, else it is re-raised after the function completes. Is used to provide custom error-rendering functions.

Config File Setting Name

mako.error_handler

Mako Default Filters

List of string filter names that will be applied to all Mako expressions.

Config File Setting Name

mako.default_filters

Mako Import

String list of Python statements, typically individual “import” lines, which will be placed into the module level preamble of all generated Python modules.

Config File Setting Name

mako.imports

Mako Strict Undefined

true or false, representing the “strict undefined” behavior of Mako (see Mako Context Variables [http://www.makotemplates.org/docs/runtime.html#context-variables]). By default, this is false.

Config File Setting Name

mako.strict_undefined

Examples

Let’s presume your configuration file is named MyProject.ini, and there is a section representing your application named [app:main] within the file that represents your Pyramid application. The configuration file settings documented in the above “Config File Setting Name” column would go in the [app:main] section. Here’s an example of such a section:

1
2
3
4

[app:main]
use = egg:MyProject#app
reload_templates = true
debug_authorization = true

You can also use environment variables to accomplish the same purpose for settings documented as such. For example, you might start your Pyramid application using the following command line:

$ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \
       bin/paster serve MyProject.ini

If you started your application this way, your Pyramid application would behave in the same manner as if you had placed the respective settings in the [app:main] section of your application’s .ini file.

If you want to turn all debug settings (every setting that starts with debug_). on in one fell swoop, you can use PYRAMID_DEBUG_ALL=1 as an environment variable setting or you may use debug_all=true in the config file. Note that this does not affect settings that do not start with debug_* such as reload_templates.

If you want to turn all reload settings (every setting that starts with reload_). on in one fell swoop, you can use PYRAMID_RELOAD_ALL=1 as an environment variable setting or you may use reload_all=true in the config file. Note that this does not affect settings that do not start with reload_* such as debug_notfound.

Note

Specifying configuration settings via environment variables is generally most useful during development, where you may wish to augment or override the more permanent settings in the configuration file. This is useful because many of the reload and debug settings may have performance or security (i.e., disclosure) implications that make them undesirable in a production environment.

Understanding the Distinction Between reload_templates and reload_assets

The difference between reload_assets and reload_templates is a bit subtle. Templates are themselves also treated by Pyramid as asset files (along with other static files), so the distinction can be confusing. It’s helpful to read Overriding Assets for some context about assets in general.

When reload_templates is true, Pyramid takes advantage of the underlying templating systems’ ability to check for file modifications to an individual template file. When reload_templates is true but reload_assets is not true, the template filename returned by the pkg_resources package (used under the hood by asset resolution) is cached by Pyramid on the first request. Subsequent requests for the same template file will return a cached template filename. The underlying templating system checks for modifications to this particular file for every request. Setting reload_templates to True doesn’t affect performance dramatically (although it should still not be used in production because it has some effect).

However, when reload_assets is true, Pyramid will not cache the template filename, meaning you can see the effect of changing the content of an overridden asset directory for templates without restarting the server after every change. Subsequent requests for the same template file may return different filenames based on the current state of overridden asset directories. Setting reload_assets to True affects performance dramatically, slowing things down by an order of magnitude for each template rendering. However, it’s convenient to enable when moving files around in overridden asset directories. reload_assets makes the system very slow when templates are in use. Never set reload_assets to True on a production system.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Unit, Integration, and Functional Testing

Unit testing is, not surprisingly, the act of testing a “unit” in your application. In this context, a “unit” is often a function or a method of a class instance. The unit is also referred to as a “unit under test”.

The goal of a single unit test is to test only some permutation of the “unit under test”. If you write a unit test that aims to verify the result of a particular codepath through a Python function, you need only be concerned about testing the code that lives in the function body itself. If the function accepts a parameter that represents a complex application “domain object” (such as a resource, a database connection, or an SMTP server), the argument provided to this function during a unit test need not be and likely should not be a “real” implementation object. For example, although a particular function implementation may accept an argument that represents an SMTP server object, and the function may call a method of this object when the system is operating normally that would result in an email being sent, a unit test of this codepath of the function does not need to test that an email is actually sent. It just needs to make sure that the function calls the method of the object provided as an argument that would send an email if the argument happened to be the “real” implementation of an SMTP server object.

An integration test, on the other hand, is a different form of testing in which the interaction between two or more “units” is explicitly tested. Integration tests verify that the components of your application work together. You might make sure that an email was actually sent in an integration test.

A functional test is a form of integration test in which the application is run “literally”. You would have to make sure that an email was actually sent in a functional test, because it tests your code end to end.

It is often considered best practice to write each type of tests for any given codebase. Unit testing often provides the opportunity to obtain better “coverage”: it’s usually possible to supply a unit under test with arguments and/or an environment which causes all of its potential codepaths to be executed. This is usually not as easy to do with a set of integration or functional tests, but integration and functional testing provides a measure of assurance that your “units” work together, as they will be expected to when your application is run in production.

The suggested mechanism for unit and integration testing of a Pyramid application is the Python unittest module. Although this module is named unittest, it is actually capable of driving both unit and integration tests. A good unittest tutorial is available within Dive Into Python [http://diveintopython.org/unit_testing/index.html] by Mark Pilgrim.

Pyramid provides a number of facilities that make unit, integration, and functional tests easier to write. The facilities become particularly useful when your code calls into Pyramid -related framework functions.

Test Set Up and Tear Down

Pyramid uses a “global” (actually thread local) data structure to hold on to two items: the current request and the current application registry. These data structures are available via the pyramid.threadlocal.get_current_request() and pyramid.threadlocal.get_current_registry() functions, respectively. See Thread Locals for information about these functions and the data structures they return.

If your code uses these get_current_* functions or calls Pyramid code which uses get_current_* functions, you will need to call pyramid.testing.setUp() in your test setup and you will need to call pyramid.testing.tearDown() in your test teardown. setUp() pushes a registry onto the thread local stack, which makes the get_current_* functions work. It returns a Configurator object which can be used to perform extra configuration required by the code under test. tearDown() pops the thread local stack.

Normally when a Configurator is used directly with the main block of a Pyramid application, it defers performing any “real work” until its .commit method is called (often implicitly by the pyramid.config.Configurator.make_wsgi_app() method). The Configurator returned by setUp() is an autocommitting Configurator, however, which performs all actions implied by methods called on it immediately. This is more convenient for unit-testing purposes than needing to call pyramid.config.Configurator.commit() in each test after adding extra configuration statements.

The use of the setUp() and tearDown() functions allows you to supply each unit test method in a test case with an environment that has an isolated registry and an isolated request for the duration of a single test. Here’s an example of using this feature:

1
2
3
4
5
6
7
8
9

import unittest
from pyramid import testing

class MyTest(unittest.TestCase):
    def setUp(self):
        self.config = testing.setUp()

    def tearDown(self):
        testing.tearDown()

The above will make sure that get_current_registry() called within a test case method of MyTest will return the application registry associated with the config Configurator instance. Each test case method attached to MyTest will use an isolated registry.

The setUp() and tearDown() functions accepts various arguments that influence the environment of the test. See the pyramid.testing chapter for information about the extra arguments supported by these functions.

If you also want to make get_current_request() return something other than None during the course of a single test, you can pass a request object into the pyramid.testing.setUp() within the setUp method of your test:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

import unittest
from pyramid import testing

class MyTest(unittest.TestCase):
    def setUp(self):
        request = testing.DummyRequest()
        self.config = testing.setUp(request=request)

    def tearDown(self):
        testing.tearDown()

If you pass a request object into pyramid.testing.setUp() within your test case’s setUp, any test method attached to the MyTest test case that directly or indirectly calls get_current_request() will receive the request object. Otherwise, during testing, get_current_request() will return None. We use a “dummy” request implementation supplied by pyramid.testing.DummyRequest because it’s easier to construct than a “real” Pyramid request object.

What?

Thread local data structures are always a bit confusing, especially when they’re used by frameworks. Sorry. So here’s a rule of thumb: if you don’t know whether you’re calling code that uses the get_current_registry() or get_current_request() functions, or you don’t care about any of this, but you still want to write test code, just always call pyramid.testing.setUp() in your test’s setUp method and pyramid.testing.tearDown() in your tests’ tearDown method. This won’t really hurt anything if the application you’re testing does not call any get_current* function.

Using the Configurator and pyramid.testing APIs in Unit Tests

The Configurator API and the pyramid.testing module provide a number of functions which can be used during unit testing. These functions make configuration declaration calls to the current application registry, but typically register a “stub” or “dummy” feature in place of the “real” feature that the code would call if it was being run normally.

For example, let’s imagine you want to unit test a Pyramid view function.

1
2
3
4
5
6
7

from pyramid.security import has_permission
from pyramid.exceptions import Forbidden

def view_fn(request):
    if not has_permission('edit', request.context, request):
        raise Forbidden
    return {'greeting':'hello'}

Without doing anything special during a unit test, the call to has_permission() in this view function will always return a True value. When a Pyramid application starts normally, it will populate a application registry using configuration declaration calls made against a Configurator. But if this application registry is not created and populated (e.g. by initializing the configurator with an authorization policy), like when you invoke application code via a unit test, Pyramid API functions will tend to either fail or return default results. So how do you test the branch of the code in this view function that raises Forbidden?

The testing API provided by Pyramid allows you to simulate various application registry registrations for use under a unit testing framework without needing to invoke the actual application configuration implied by its main function. For example, if you wanted to test the above view_fn (assuming it lived in the package named my.package), you could write a unittest.TestCase that used the testing API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

import unittest
from pyramid import testing

class MyTest(unittest.TestCase):
    def setUp(self):
        self.config = testing.setUp()

    def tearDown(self):
        testing.tearDown()

    def test_view_fn_forbidden(self):
        from pyramid.exceptions import Forbidden
        from my.package import view_fn
        self.config.testing_securitypolicy(userid='hank',
                                           permissive=False)
        request = testing.DummyRequest()
        request.context = testing.DummyResource()
        self.assertRaises(Forbidden, view_fn, request)

    def test_view_fn_allowed(self):
        from pyramid.exceptions import Forbidden
        from my.package import view_fn
        self.config.testing_securitypolicy(userid='hank',
                                           permissive=True)
        request = testing.DummyRequest()
        request.context = testing.DummyResource()
        response = view_fn(request)
        self.assertEqual(response, {'greeting':'hello'})

In the above example, we create a MyTest test case that inherits from unittest.TestCase. If it’s in our Pyramid application, it will be found when setup.py test is run. It has two test methods.

The first test method, test_view_fn_forbidden tests the view_fn when the authentication policy forbids the current user the edit permission. Its third line registers a “dummy” “non-permissive” authorization policy using the testing_securitypolicy() method, which is a special helper method for unit testing.

We then create a pyramid.testing.DummyRequest object which simulates a WebOb request object API. A pyramid.testing.DummyRequest is a request object that requires less setup than a “real” Pyramid request. We call the function being tested with the manufactured request. When the function is called, pyramid.security.has_permission() will call the “dummy” authentication policy we’ve registered through testing_securitypolicy(), which denies access. We check that the view function raises a Forbidden error.

The second test method, named test_view_fn_allowed tests the alternate case, where the authentication policy allows access. Notice that we pass different values to testing_securitypolicy() to obtain this result. We assert at the end of this that the view function returns a value.

Note that the test calls the pyramid.testing.setUp() function in its setUp method and the pyramid.testing.tearDown() function in its tearDown method. We assign the result of pyramid.testing.setUp() as config on the unittest class. This is a Configurator object and all methods of the configurator can be called as necessary within tests. If you use any of the Configurator APIs during testing, be sure to use this pattern in your test case’s setUp and tearDown; these methods make sure you’re using a “fresh” application registry per test run.

See the pyramid.testing chapter for the entire Pyramid -specific testing API. This chapter describes APIs for registering a security policy, registering resources at paths, registering event listeners, registering views and view permissions, and classes representing “dummy” implementations of a request and a resource.

See also the various methods of the Configurator documented in pyramid.config that begin with the testing_ prefix.

Creating Integration Tests

In Pyramid, a unit test typically relies on “mock” or “dummy” implementations to give the code under test only enough context to run.

“Integration testing” implies another sort of testing. In the context of a Pyramid, integration test, the test logic tests the functionality of some code and its integration with the rest of the Pyramid framework.

In Pyramid applications that are plugins to Pyramid, you can create an integration test by including it’s includeme function via pyramid.config.Configurator.include() in the test’s setup code. This causes the entire Pyramid environment to be set up and torn down as if your application was running “for real”. This is a heavy-hammer way of making sure that your tests have enough context to run properly, and it tests your code’s integration with the rest of Pyramid.

Let’s demonstrate this by showing an integration test for a view. The below test assumes that your application’s package name is myapp, and that there is a views module in the app with a function with the name my_view in it that returns the response ‘Welcome to this application’ after accessing some values that require a fully set up environment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

import unittest

from pyramid import testing

class ViewIntegrationTests(unittest.TestCase):
    def setUp(self):
        """ This sets up the application registry with the
        registrations your application declares in its ``includeme``
        function.
        """
        import myapp
        self.config = testing.setUp()
        self.config.include('myapp')

    def tearDown(self):
        """ Clear out the application registry """
        testing.tearDown()

    def test_my_view(self):
        from myapp.views import my_view
        request = testing.DummyRequest()
        result = my_view(request)
        self.assertEqual(result.status, '200 OK')
        body = result.app_iter[0]
        self.failUnless('Welcome to' in body)
        self.assertEqual(len(result.headerlist), 2)
        self.assertEqual(result.headerlist[0],
                         ('Content-Type', 'text/html; charset=UTF-8'))
        self.assertEqual(result.headerlist[1], ('Content-Length',
                                                str(len(body))))

Unless you cannot avoid it, you should prefer writing unit tests that use the Configurator API to set up the right “mock” registrations rather than creating an integration test. Unit tests will run faster (because they do less for each test) and the result of a unit test is usually easier to make assertions about.

Creating Functional Tests

Functional tests test your literal application.

The below test assumes that your application’s package name is myapp, and that there is view that returns an HTML body when the root URL is invoked. It further assumes that you’ve added a tests_require dependency on the WebTest package within your setup.py file. WebTest is a functional testing package written by Ian Bicking.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

import unittest

class FunctionalTests(unittest.TestCase):
    def setUp(self):
        from myapp import main
        app = main({})
        from webtest import TestApp
        self.testapp = TestApp(app)

    def test_root(self):
        res = self.testapp.get('/', status=200)
        self.failUnless('Pyramid' in res.body)

When this test is run, each test creates a “real” WSGI application using the main function in your myapp.__init__ module and uses WebTest to wrap that WSGI application. It assigns the result to self.testapp. In the test named test_root, we use the testapp’s get method to invoke the root URL. We then assert that the returned HTML has the string Pyramid in it.

See the WebTest documentation for further information about the methods available to a webtest.TestApp instance.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Using Hooks

“Hooks” can be used to influence the behavior of the Pyramid framework in various ways.

Changing the Not Found View

When Pyramid can’t map a URL to view code, it invokes a not found view, which is a view callable. A default notfound view exists. The default not found view can be overridden through application configuration.

The not found view callable is a view callable like any other. The view configuration which causes it to be a “not found” view consists only of naming the pyramid.exceptions.NotFound class as the context of the view configuration.

If your application uses imperative configuration, you can replace the Not Found view by using the pyramid.config.Configurator.add_view() method to register an “exception view”:

1
2
3

from pyramid.exceptions import NotFound
from helloworld.views import notfound_view
config.add_view(notfound_view, context=NotFound)

Replace helloworld.views.notfound_view with a reference to the view callable you want to use to represent the Not Found view.

Like any other view, the notfound view must accept at least a request parameter, or both context and request. The request is the current request representing the denied action. The context (if used in the call signature) will be the instance of the NotFound exception that caused the view to be called.

Here’s some sample code that implements a minimal NotFound view callable:

1
2
3
4

from pyramid.httpexceptions import HTTPNotFound

def notfound_view(request):
    return HTTPNotFound()

Note

When a NotFound view callable is invoked, it is passed a request. The exception attribute of the request will be an instance of the NotFound exception that caused the not found view to be called. The value of request.exception.args[0] will be a value explaining why the not found error was raised. This message will be different when the debug_notfound environment setting is true than it is when it is false.

Warning

When a NotFound view callable accepts an argument list as described in Alternate View Callable Argument/Calling Conventions, the context passed as the first argument to the view callable will be the NotFound exception instance. If available, the resource context will still be available as request.context.

Changing the Forbidden View

When Pyramid can’t authorize execution of a view based on the authorization policy in use, it invokes a forbidden view. The default forbidden response has a 403 status code and is very plain, but the view which generates it can be overridden as necessary.

The forbidden view callable is a view callable like any other. The view configuration which causes it to be a “not found” view consists only of naming the pyramid.exceptions.Forbidden class as the context of the view configuration.

You can replace the forbidden view by using the pyramid.config.Configurator.add_view() method to register an “exception view”:

1
2
3

from helloworld.views import forbidden_view
from pyramid.exceptions import Forbidden
config.add_view(forbidden_view, context=Forbidden)

Replace helloworld.views.forbidden_view with a reference to the Python view callable you want to use to represent the Forbidden view.

Like any other view, the forbidden view must accept at least a request parameter, or both context and request. The context (available as request.context if you’re using the request-only view argument pattern) is the context found by the router when the view invocation was denied. The request is the current request representing the denied action.

Here’s some sample code that implements a minimal forbidden view:

1
2
3
4
5

from pyramid.views import view_config
from pyramid.response import Response

def forbidden_view(request):
    return Response('forbidden')

Note

When a forbidden view callable is invoked, it is passed a request. The exception attribute of the request will be an instance of the Forbidden exception that caused the forbidden view to be called. The value of request.exception.args[0] will be a value explaining why the forbidden was raised. This message will be different when the debug_authorization environment setting is true than it is when it is false.

Changing the Request Factory

Whenever Pyramid handles a WSGI request, it creates a request object based on the WSGI environment it has been passed. By default, an instance of the pyramid.request.Request class is created to represent the request object.

The class (aka “factory”) that Pyramid uses to create a request object instance can be changed by passing a request_factory argument to the constructor of the configurator. This argument can be either a callable or a dotted Python name representing a callable.

1
2
3
4
5
6

from pyramid.request import Request

class MyRequest(Request):
    pass

config = Configurator(request_factory=MyRequest)

If you’re doing imperative configuration, and you’d rather do it after you’ve already constructed a configurator it can also be registered via the pyramid.config.Configurator.set_request_factory() method:

1
2
3
4
5
6
7
8

from pyramid.config import Configurator
from pyramid.request import Request

class MyRequest(Request):
    pass

config = Configurator()
config.set_request_factory(MyRequest)

Adding Renderer Globals

Whenever Pyramid handles a request to perform a rendering (after a view with a renderer= configuration attribute is invoked, or when the any of the methods beginning with render within the pyramid.renderers module are called), renderer globals can be injected into the system values sent to the renderer. By default, no renderer globals are injected, and the “bare” system values (such as request, context, and renderer_name) are the only values present in the system dictionary passed to every renderer.

A callback that Pyramid will call every time a renderer is invoked can be added by passing a renderer_globals_factory argument to the constructor of the configurator. This callback can either be a callable object or a dotted Python name representing such a callable.

1
2
3
4
5

def renderer_globals_factory(system):
    return {'a':1}

config = Configurator(
         renderer_globals_factory=renderer_globals_factory)

Such a callback must accept a single positional argument (notionally named system) which will contain the original system values. It must return a dictionary of values that will be merged into the system dictionary. See System Values Used During Rendering for discription of the values present in the system dictionary.

If you’re doing imperative configuration, and you’d rather do it after you’ve already constructed a configurator it can also be registered via the pyramid.config.Configurator.set_renderer_globals_factory() method:

1
2
3
4
5
6
7

from pyramid.config import Configurator

def renderer_globals_factory(system):
    return {'a':1}

config = Configurator()
config.set_renderer_globals_factory(renderer_globals_factory)

Another mechanism which allows event subscribers to add renderer global values exists in Using The Before Render Event.

Using The Before Render Event

Subscribers to the pyramid.events.BeforeRender event may introspect the and modify the set of renderer globals before they are passed to a renderer. This event object iself has a dictionary-like interface that can be used for this purpose. For example:

1
2
3
4
5
6

 from pyramid.events import subscriber
 from pyramid.events import BeforeRender

 @subscriber(BeforeRender)
 def add_global(event):
     event['mykey'] = 'foo'

An object of this type is sent as an event just before a renderer is invoked (but after the application-level renderer globals factory added via set_renderer_globals_factory, if any, has injected its own keys into the renderer globals dictionary).

If a subscriber attempts to add a key that already exist in the renderer globals dictionary, a KeyError is raised. This limitation is enforced because event subscribers do not possess any relative ordering. The set of keys added to the renderer globals dictionary by all pyramid.events.BeforeRender subscribers and renderer globals factories must be unique.

See the API documentation for the BeforeRender event interface at pyramid.interfaces.IBeforeRender.

Another mechanism which allows event subscribers more control when adding renderer global values exists in Adding Renderer Globals.

Using Response Callbacks

Unlike many other web frameworks, Pyramid does not eagerly create a global response object. Adding a response callback allows an application to register an action to be performed against a response object once it is created, usually in order to mutate it.

The pyramid.request.Request.add_response_callback() method is used to register a response callback.

A response callback is a callable which accepts two positional parameters: request and response. For example:

1
2
3
4
5

def cache_callback(request, response):
    """Set the cache_control max_age for the response"""
    if request.exception is not None:
        response.cache_control.max_age = 360
request.add_response_callback(cache_callback)

No response callback is called if an unhandled exception happens in application code, or if the response object returned by a view callable is invalid. Response callbacks are, however, invoked when a exception view is rendered successfully: in such a case, the request.exception attribute of the request when it enters a response callback will be an exception object instead of its default value of None.

Response callbacks are called in the order they’re added (first-to-most-recently-added). All response callbacks are called after the NewResponse event is sent. Errors raised by response callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

A response callback has a lifetime of a single request. If you want a response callback to happen as the result of every request, you must re-register the callback into every new request (perhaps within a subscriber of a NewRequest event).

Using Finished Callbacks

A finished callback is a function that will be called unconditionally by the Pyramid router at the very end of request processing. A finished callback can be used to perform an action at the end of a request unconditionally.

The pyramid.request.Request.add_finished_callback() method is used to register a finished callback.

A finished callback is a callable which accepts a single positional parameter: request. For example:

1
2
3
4
5
6
7
8
9

import transaction

def commit_callback(request):
    '''commit or abort the transaction associated with request'''
    if request.exception is not None:
        transaction.abort()
    else:
        transaction.commit()
request.add_finished_callback(commit_callback)

Finished callbacks are called in the order they’re added (first-to-most-recently-added). Finished callbacks (unlike a response callback) are always called, even if an exception happens in application code that prevents a response from being generated.

The set of finished callbacks associated with a request are called very late in the processing of that request; they are essentially the very last thing called by the router before a request “ends”. They are called after response processing has already occurred in a top-level finally: block within the router request processing code. As a result, mutations performed to the request provided to a finished callback will have no meaningful effect, because response processing will have already occurred, and the request’s scope will expire almost immediately after all finished callbacks have been processed.

It is often necessary to tell whether an exception occurred within view callable code from within a finished callback: in such a case, the request.exception attribute of the request when it enters a response callback will be an exception object instead of its default value of None.

Errors raised by finished callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

A finished callback has a lifetime of a single request. If you want a finished callback to happen as the result of every request, you must re-register the callback into every new request (perhaps within a subscriber of a NewRequest event).

Changing the Traverser

The default traversal algorithm that Pyramid uses is explained in The Traversal Algorithm. Though it is rarely necessary, this default algorithm can be swapped out selectively for a different traversal pattern via configuration.

1
2
3
4
5

from pyramid.interfaces import ITraverser
from zope.interface import Interface
from myapp.traversal import Traverser

config.registry.registerAdapter(Traverser, (Interface,), ITraverser)

In the example above, myapp.traversal.Traverser is assumed to be a class that implements the following interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

class Traverser(object):
    def __init__(self, root):
        """ Accept the root object returned from the root factory """

    def __call__(self, request):
        """ Return a dictionary with (at least) the keys ``root``,
        ``context``, ``view_name``, ``subpath``, ``traversed``,
        ``virtual_root``, and ``virtual_root_path``.  These values are
        typically the result of a resource tree traversal.  ``root``
        is the physical root object, ``context`` will be a resource
        object, ``view_name`` will be the view name used (a Unicode
        name), ``subpath`` will be a sequence of Unicode names that
        followed the view name but were not traversed, ``traversed``
        will be a sequence of Unicode names that were traversed
        (including the virtual root path, if any) ``virtual_root``
        will be a resource object representing the virtual root (or the
        physical root if traversal was not performed), and
        ``virtual_root_path`` will be a sequence representing the
        virtual root path (a sequence of Unicode names) or None if
        traversal was not performed.

        Extra keys for special purpose functionality can be added as
        necessary.

        All values returned in the dictionary will be made available
        as attributes of the ``request`` object.
        """

More than one traversal algorithm can be active at the same time. For instance, if your root factory returns more than one type of object conditionally, you could claim that an alternate traverser adapter is for only one particular class or interface. When the root factory returned an object that implemented that class or interface, a custom traverser would be used. Otherwise, the default traverser would be used. For example:

1
2
3
4
5
6

from pyramid.interfaces import ITraverser
from zope.interface import Interface
from myapp.traversal import Traverser
from myapp.resources import MyRoot

config.registry.registerAdapter(Traverser, (MyRoot,), ITraverser)

If the above stanza was added to a Pyramid __init__.py file’s main function, Pyramid would use the myapp.traversal.Traverser only when the application root factory returned an instance of the myapp.resources.MyRoot object. Otherwise it would use the default Pyramid traverser to do traversal.

Changing How pyramid.url.resource_url Generates a URL

When you add a traverser as described in Changing the Traverser, it’s often convenient to continue to use the pyramid.url.resource_url() API. However, since the way traversal is done will have been modified, the URLs it generates by default may be incorrect.

If you’ve added a traverser, you can change how resource_url() generates a URL for a specific type of resource by adding a registerAdapter call for pyramid.interfaces.IContextURL to your application:

1
2
3
4
5
6
7

from pyramid.interfaces import ITraverser
from zope.interface import Interface
from myapp.traversal import URLGenerator
from myapp.resources import MyRoot

config.registry.registerAdapter(URLGenerator, (MyRoot, Interface),
                                IContextURL)

In the above example, the myapp.traversal.URLGenerator class will be used to provide services to resource_url() any time the context passed to resource_url is of class myapp.resources.MyRoot. The second argument in the (MyRoot, Interface) tuple represents the type of interface that must be possessed by the request (in this case, any interface, represented by zope.interface.Interface).

The API that must be implemented by a class that provides IContextURL is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from zope.interface import Interface

class IContextURL(Interface):
    """ An adapter which deals with URLs related to a context.
    """
    def __init__(self, context, request):
        """ Accept the context and request """

    def virtual_root(self):
        """ Return the virtual root object related to a request and the
        current context"""

    def __call__(self):
        """ Return a URL that points to the context """

The default context URL generator is available for perusal as the class pyramid.traversal.TraversalContextURL in the traversal module [http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py] of the Pylons GitHub Pyramid repository.

Using a View Mapper

The default calling conventions for view callables are documented in the Views chapter. You can change the way users define view callbles by employing a view mapper.

A view mapper is an object that accepts a set of keyword arguments and which returns a callable. The returned callable is called with the view callable object. The returned callable should itself return another callable which can be called with the “internal calling protocol” (context, request).

You can use a view mapper in a number of ways:

by setting a __view_mapper__ attribute (which is the view mapper object) on the view callable itself

by passing the mapper object to pyramid.config.Configurator.add_view() (or its declarative/decorator equivalents) as the mapper argument.

by registering a default view mapper.

Here’s an example of a view mapper that emulates (somewhat) a Pylons “controller”. The mapper is initialized with some keyword arguments. Its __call__ method accepts the view object (which will be a class). It uses the attr keyword argument it is passed to determine which attribute should be used as an action method. The wrapper method it returns accepts (context, request) and returns the result of calling the action method with keyword arguments implied by the matchdict after popping the action out of it. This somewhat emulates the Pylons style of calling action methods with routing parameters pulled out of the route matching dict as keyword arguments.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# framework

class PylonsControllerViewMapper(object):
    def __init__(self, **kw):
        self.kw = kw

    def __call__(self, view):
        attr = self.kw['attr']
        def wrapper(context, request):
            matchdict = request.matchdict.copy()
            matchdict.pop('action', None)
            inst = view()
            meth = getattr(inst, attr)
            return meth(**matchdict)
        return wrapper

class BaseController(object):
    __view_mapper__ = PylonsControllerViewMapper

A user might make use of these framework components like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# user application

from webob import Response
from pyramid.config import Configurator
import pyramid_handlers
from paste.httpserver import serve

class MyController(BaseController):
    def index(self, id):
        return Response(id)

if __name__ == '__main__':
    config = Configurator()
    config.include(pyramid_handlers)
    config.add_handler('one', '/{id}', MyController, action='index')
    config.add_handler('two', '/{action}/{id}', MyController)
    serve(config.make_wsgi_app())

The pyramid.config.Configurator.set_default_mapper() method can be used to set a default view mapper (overriding the superdefault view mapper used by Pyramid itself).

A single view registration can use a view mapper by passing the mapper as the mapper argument to add_view().

Registering Configuration Decorators

Decorators such as view_config don’t change the behavior of the functions or classes they’re decorating. Instead, when a scan is performed, a modified version of the function or class is registered with Pyramid.

You may wish to have your own decorators that offer such behaviour. This is possible by using the Venusian package in the same way that it is used by Pyramid.

By way of example, let’s suppose you want to write a decorator that registers the function it wraps with a Zope Component Architecture “utility” within the application registry provided by Pyramid. The application registry and the utility inside the registry is likely only to be available once your application’s configuration is at least partially completed. A normal decorator would fail as it would be executed before the configuration had even begun.

However, using Venusian, the decorator could be written as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

import venusian
from pyramid.threadlocal import get_current_registry
from mypackage.interfaces import IMyUtility

class registerFunction(object):

    def __init__(self, path):
        self.path = path

    def register(self, scanner, name, wrapped):
        registry = scanner.config.registry
        registry.getUtility(IMyUtility).register(
            self.path, wrapped
            )

    def __call__(self, wrapped):
        venusian.attach(wrapped, self.register)
        return wrapped

This decorator could then be used to register functions throughout your code:

1
2
3

@registerFunction('/some/path')
def my_function():
   do_stuff()

However, the utility would only be looked up when a scan was performed, enabling you to set up the utility in advance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

from paste.httpserver import serve
from pyramid.config import Configurator

class UtilityImplementation:

    implements(ISomething)

    def __init__(self):
       self.registrations = {}

    def register(self,path,callable_):
       self.registrations[path]=callable_

if __name__ == '__main__':
    config = Configurator()
    config.registry.registerUtility(UtilityImplementation())
    config.scan()
    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

For full details, please read the Venusian documentation [http://docs.repoze.org/venusian].

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Advanced Configuration

To support application extensibility, the Pyramid Configurator, by default, detects configuration conflicts and allows you to include configuration imperatively from other packages or modules. It also, by default, performs configuration in two separate phases. This allows you to ignore relative configuration statement ordering in some circumstances.

Conflict Detection

Here’s a familiar example of one of the simplest Pyramid applications, configured imperatively:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from paste.httpserver import serve
from pyramid.config import Configurator
from pyramid.response import Response

def hello_world(request):
    return Response('Hello world!')

if __name__ == '__main__':
    config = Configurator()
    config.add_view(hello_world)
    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

When you start this application, all will be OK. However, what happens if we try to add another view to the configuration with the same set of predicate arguments as one we’ve already added?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from paste.httpserver import serve
from pyramid.config import Configurator
from pyramid.response import Response

def hello_world(request):
    return Response('Hello world!')

def goodbye_world(request):
    return Response('Goodbye world!')

if __name__ == '__main__':
    config = Configurator()

    config.add_view(hello_world, name='hello')

    # conflicting view configuration
    config.add_view(goodbye_world, name='hello')

    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

The application now has two conflicting view configuration statements. When we try to start it again, it won’t start. Instead, we’ll receive a traceback that ends something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

Traceback (most recent call last):
  File "app.py", line 12, in <module>
    app = config.make_wsgi_app()
  File "pyramid/config.py", line 839, in make_wsgi_app
    self.commit()
  File "pyramid/pyramid/config.py", line 473, in commit
    self._ctx.execute_actions()
  File "zope/configuration/config.py", line 600, in execute_actions
    for action in resolveConflicts(self.actions):
  File "zope/configuration/config.py", line 1507, in resolveConflicts
    raise ConfigurationConflictError(conflicts)
zope.configuration.config.ConfigurationConflictError:
        Conflicting configuration actions
  For: ('view', None, '', None, <InterfaceClass pyramid.interfaces.IView>,
        None, None, None, None, None, False, None, None, None)
 ('app.py', 14, '<module>', 'config.add_view(hello_world)')
 ('app.py', 17, '<module>', 'config.add_view(hello_world)')

This traceback is trying to tell us:

We’ve got conflicting information for a set of view configuration statements (The For: line).

There are two statements which conflict, shown beneath the For: line: config.add_view(hello_world. 'hello') on line 14 of app.py, and config.add_view(goodbye_world, 'hello') on line 17 of app.py.

These two configuration statements are in conflict because we’ve tried to tell the system that the set of predicate values for both view configurations are exactly the same. Both the hello_world and goodbye_world views are configured to respond under the same set of circumstances. This circumstance: the view name (represented by the name= predicate) is hello.

This presents an ambiguity that Pyramid cannot resolve. Rather than allowing the circumstance to go unreported, by default Pyramid raises a ConfigurationConflictError error and prevents the application from running.

Conflict detection happens for any kind of configuration: imperative configuration or configuration that results from the execution of a scan.

Manually Resolving Conflicts

There are a number of ways to manually resolve conflicts: the “right” way, by strategically using pyramid.config.Configurator.commit(), or by using an “autocommitting” configurator.

The Right Thing

The most correct way to resolve conflicts is to “do the needful”: change your configuration code to not have conflicting configuration statements. The details of how this is done depends entirely on the configuration statements made by your application. Use the detail provided in the ConfigurationConflictError to track down the offending conflicts and modify your configuration code accordingly.

If you’re getting a conflict while trying to extend an existing application, and that application has a function which performs configuration like this one:

1
2

def add_routes(config):
    config.add_route(...)

Don’t call this function directly with config as an argument. Instead, use pyramid.config.Configuration.include():

1

config.include(add_routes)

Using include() instead of calling the function directly provides a modicum of automated conflict resolution, with the configuration statements you define in the calling code overriding those of the included function. See also Automatic Conflict Resolution and Including Configuration from External Sources.

Using config.commit()

You can manually commit a configuration by using the commit() method between configuration calls. For example, we prevent conflicts from occurring in the application we examined previously as the result of adding a commit. Here’s the application that generates conflicts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from paste.httpserver import serve
from pyramid.config import Configurator
from pyramid.response import Response

def hello_world(request):
    return Response('Hello world!')

def goodbye_world(request):
    return Response('Goodbye world!')

if __name__ == '__main__':
    config = Configurator()

    config.add_view(hello_world, name='hello')

    # conflicting view configuration
    config.add_view(goodbye_world, name='hello')

    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

We can prevent the two add_view calls from conflicting by issuing a call to commit() between them:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from paste.httpserver import serve
from pyramid.config import Configurator
from pyramid.response import Response

def hello_world(request):
    return Response('Hello world!')

def goodbye_world(request):
    return Response('Goodbye world!')

if __name__ == '__main__':
    config = Configurator()

    config.add_view(hello_world, name='hello')

    config.commit() # commit any pending configuration actions

    # no-longer-conflicting view configuration
    config.add_view(goodbye_world, name='hello')

    app = config.make_wsgi_app()
    serve(app, host='0.0.0.0')

In the above example we’ve issued a call to commit() between the two add_view calls. commit() will cause any pending configuration statements.

Calling commit() is safe at any time. It executes all pending configuration actions and leaves the configuration action list “clean”.

Note that commit() has no effect when you’re using an autocommitting configurator (see Using An Autocommitting Configurator).

Using An Autocommitting Configurator

You can also use a heavy hammer to circumvent conflict detection by using a configurator constructor parameter: autocommit=True. For example:

1
2
3
4

from pyramid.config import Configurator

if __name__ == '__main__':
    config = Configurator(autocommit=True)

When the autocommit parameter passed to the Configurator is True, conflict detection (and Two-Phase Configuration) is disabled. Configuration statements will be executed immediately, and succeeding statements will override preceding ones.

commit() has no effect when autocommit is True.

If you use a Configurator in code that performs unit testing, it’s usually a good idea to use an autocommitting Configurator, because you are usually unconcerned about conflict detection or two-phase configuration in test code.

Automatic Conflict Resolution

If your code uses the include() method to include external configuration, some conflicts are automatically resolved. Configuration statements that are made as the result of an “include” will be overridden by configuration statements that happen within the caller of the “include” method.

Automatic conflict resolution supports this goal: if a user wants to reuse a Pyramid application, and they want to customize the configuration of this application without hacking its code “from outside”, they can “include” a configuration function from the package and override only some of its configuration statements within the code that does the include. No conflicts will be generated by configuration statements within the code which does the including, even if configuration statements in the included code would conflict if it was moved “up” to the calling code.

Methods Which Provide Conflict Detection

These are the methods of the configurator which provide conflict detection:

add_view(), add_route(), add_renderer(), set_request_factory(), set_renderer_globals_factory() set_locale_negotiator() and set_default_permission().

Some other methods of the configurator also indirectly provide conflict detection, because they’re implemented in terms of conflict-aware methods:

add_route() does a second type of conflict detection when a view parameter is passed (it calls add_view).

static_view(), a frontend for add_route and add_view.

Including Configuration from External Sources

Some application programmers will factor their configuration code in such a way that it is easy to reuse and override configuration statements. For example, such a developer might factor out a function used to add routes to his application:

1
2

def add_routes(config):
    config.add_route(...)

Rather than calling this function directly with config as an argument. Instead, use pyramid.config.Configuration.include():

1

config.include(add_routes)

Using include rather than calling the function directly will allow Automatic Conflict Resolution to work.

include() can also accept a module as an argument:

1
2
3

import myapp

config.include(myapp)

For this to work properly, the myapp module must contain a callable with the special name includeme, which should perform configuration (like the add_routes callable we showed above as an example).

include() can also accept a dotted Python name to a function or a module.

Two-Phase Configuration

When a non-autocommitting Configurator is used to do configuration (the default), configuration execution happens in two phases. In the first phase, “eager” configuration actions (actions that must happen before all others, such as registering a renderer) are executed, and discriminators are computed for each of the actions that depend on the result of the eager actions. In the second phase, the discriminators of all actions are compared to do conflict detection.

Due to this, for configuration methods that have no internal ordering constraints, execution order of configuration method calls is not important. For example, the relative ordering of add_view() and add_renderer() is unimportant when a non-autocommitting configurator is used. This code snippet:

1
2

config.add_view('some.view', renderer='path_to_custom/renderer.rn')
config.add_renderer('.rn', SomeCustomRendererFactory)

Has the same result as:

1
2

config.add_renderer('.rn', SomeCustomRendererFactory)
config.add_view('some.view', renderer='path_to_custom/renderer.rn')

Even though the view statement depends on the registration of a custom renderer, due to two-phase configuration, the order in which the configuration statements are issued is not important. add_view will be able to find the .rn renderer even if add_renderer is called after add_view.

The same is untrue when you use an autocommitting configurator (see Using An Autocommitting Configurator). When an autocommitting configurator is used, two-phase configuration is disabled, and configuration statements must be ordered in dependency order.

Some configuration methods, such as add_route() have internal ordering constraints: the routes they imply require relative ordering. Such ordering constraints are not absolved by two-phase configuration. Routes are still added in configuration execution order.

Adding Methods to the Configurator via add_directive

Framework extension writers can add arbitrary methods to a Configurator by using the pyramid.config.Configurator.add_directive() method of the configurator. This makes it possible to extend a Pyramid configurator in arbitrary ways, and allows it to perform application-specific tasks more succinctly.

The add_directive() method accepts two positional arguments: a method name and a callable object. The callable object is usually a function that takes the configurator instance as its first argument and accepts other arbitrary positional and keyword arguments. For example:

from pyramid.events import NewRequest
from pyramid.config import Configurator

def add_newrequest_subscriber(config, subscriber):
    config.add_subscriber(subscriber, NewRequest).

if __name__ == '__main__':
   config = Configurator()
   config.add_directive('add_newrequest_subscriber',
                        add_newrequest_subscriber)

Once add_directive() is called, a user can then call the method by its given name as if it were a built-in method of the Configurator:

1
2
3
4

def mysubscriber(event):
   print event.request

config.add_newrequest_subscriber(mysubscriber)

A call to add_directive() is often “hidden” within an includeme function within a “frameworky” package meant to be included as per Including Configuration from External Sources via include(). For example, if you put this code in a package named pyramid_subscriberhelpers:

def includeme(config)
   config.add_directive('add_newrequest_subscriber',
                        add_newrequest_subscriber)

The user of the add-on package pyramid_subscriberhelpers would then be able to install it and subsequently do:

1
2
3
4
5
6
7

def mysubscriber(event):
   print event.request

from pyramid.config import Configurator
config = Configurator()
config.include('pyramid_subscriberhelpers')
config.add_newrequest_subscriber(mysubscriber)

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Extending An Existing Pyramid Application

If a Pyramid developer has obeyed certain constraints while building an application, a third party should be able to change the application’s behavior without needing to modify its source code. The behavior of a Pyramid application that obeys certain constraints can be overridden or extended without modification.

We’ll define some jargon here for the benefit of identifying the parties involved in such an effort.

Developer

The original application developer.

Integrator

Another developer who wishes to reuse the application written by the original application developer in an unanticipated context. He may also wish to modify the original application without changing the original application’s source code.

The Difference Between “Extensible” and “Pluggable” Applications

Other web frameworks, such as Django, advertise that they allow developers to create “pluggable applications”. They claim that if you create an application in a certain way, it will be integratable in a sensible, structured way into another arbitrarily-written application or project created by a third-party developer.

Pyramid, as a platform, does not claim to provide such a feature. The platform provides no guarantee that you can create an application and package it up such that an arbitrary integrator can use it as a subcomponent in a larger Pyramid application or project. Pyramid does not mandate the constraints necessary for such a pattern to work satisfactorily. Because Pyramid is not very “opinionated”, developers are able to use wildly different patterns and technologies to build an application. A given Pyramid application may happen to be reusable by a particular third party integrator, because the integrator and the original developer may share similar base technology choices (such as the use of a particular relational database or ORM). But the same application may not be reusable by a different developer, because he has made different technology choices which are incompatible with the original developer’s.

As a result, the concept of a “pluggable application” is left to layers built above Pyramid, such as a “CMS” layer or “application server” layer. Such layers are apt to provide the necessary “opinions” (such as mandating a storage layer, a templating system, and a structured, well-documented pattern of registering that certain URLs map to certain bits of code) which makes the concept of a “pluggable application” possible. “Pluggable applications”, thus, should not plug in to Pyramid itself but should instead plug into a system written atop Pyramid.

Although it does not provide for “pluggable applications”, Pyramid does provide a rich set of mechanisms which allows for the extension of a single existing application. Such features can be used by frameworks built using Pyramid as a base. All Pyramid applications may not be pluggable, but all Pyramid applications are extensible.

Rules for Building An Extensible Application

There is only one rule you need to obey if you want to build a maximally extensible Pyramid application: as a developer, you should factor any overrideable imperative configuration you’ve created into functions which can be used via pyramid.config.Configurator.include() rather than inlined as calls to methods of a Configurator within the main function in your application’s __init__.py. For example, rather than:

1
2
3
4
5
6

from pyramid.config import Configurator

if __name__ == '__main__':
    config = Configurator()
    config.add_view('myapp.views.view1', name='view1')
    config.add_view('myapp.views.view2', name='view2')

You should do move the calls to add_view outside of the (non-reusable) if __name__ == '__main__' block, and into a reusable function:

1
2
3
4
5
6
7
8
9

from pyramid.config import Configurator

if __name__ == '__main__':
    config = Configurator()
    config.include(add_views)

def add_views(config):
    config.add_view('myapp.views.view1', name='view1')
    config.add_view('myapp.views.view2', name='view2')

Doing this allows an integrator to maximally reuse the configuration statements that relate to your application by allowing him to selectively include or disinclude the configuration functions you’ve created from an “override package”.

Alternately, you can use ZCML for the purpose of making configuration extensible and overrideable. ZCML declarations that belong to an application can be overridden and extended by integrators as necessary in a similar fashion. If you use only ZCML to configure your application, it will automatically be maximally extensible without any manual effort. See pyramid_zcml for information about using ZCML.

Fundamental Plugpoints

The fundamental “plug points” of an application developed using Pyramid are routes, views, and assets. Routes are declarations made using the pyramid.config.Configurator.add_route() method. Views are declarations made using the pyramid.config.Configurator.add_view() method. Assets are files that are accessed by Pyramid using the pkg_resources API such as static files and templates via a asset specification. Other directives and configurator methods also deal in routes, views, and assets. For example, add_handler directive of the pyramid_handlers package adds a single route, and some number of views.

Extending an Existing Application

The steps for extending an existing application depend largely on whether the application does or does not use configuration decorators and/or imperative code.

If The Application Has Configuration Decorations

You’ve inherited a Pyramid application which you’d like to extend or override that uses pyramid.view.view_config decorators or other configuration decoration decorators.

If you just want to extend the application, you can run a scan against the application’s package, then add additional configuration that registers more views or routes.

1
2
3

if __name__ == '__main__':
    config.scan('someotherpackage')
    config.add_view('mypackage.views.myview', name='myview')

If you want to override configuration in the application, you may need to run pyramid.config.Configurator.commit() after performing the scan of the original package, then add additional configuration that registers more views or routes which performs overrides.

if __name__ == '__main__':
    config.scan('someotherpackage')
    config.commit()
    config.add_view('mypackage.views.myview', name='myview'

Once this is done, you should be able to extend or override the application like any other (see Extending the Application).

You can alternately just prevent a scan from happening (by omitting any call to the pyramid.config.Configurator.scan() method). This will cause the decorators attached to objects in the target application to do nothing. At this point, you will need to convert all the configuration done in decorators into equivalent imperative configuration or ZCML and add that configuration or ZCML to a separate Python package as described in Extending the Application.

Extending the Application

To extend or override the behavior of an existing application, you will need to create a new package which includes the configuration of the old package, and you’ll perhaps need to create implementations of the types of things you’d like to override (such as views), which are referred to within the original package.

The general pattern for extending an existing application looks something like this:

Create a new Python package. The easiest way to do this is to create a new Pyramid application using the “paster” template mechanism. See Creating the Project for more information.

In the new package, create Python files containing views and other overridden elements, such as templates and static assets as necessary.

Install the new package into the same Python environment as the original application (e.g. python setup.py develop or python setup.py install).

Change the main function in the new package’s __init__py to include the original Pyramid application’s configuration functions via pyramid.config.Configurator.include() statements or a scan.

Wire the new views and assets created in the new package up using imperative registrations within the main function of the __init__.py file of the new application. These wiring should happen after including the configuration functions of the old application. These registrations will extend or override any registrations performed by the original application. See Overriding Views, Overriding Routes and Overriding Assets.

Overriding Views

The view configuration declarations you make which override application behavior will usually have the same view predicate attributes as the original you wish to override. These <view> declarations will point at “new” view code, in the override package you’ve created. The new view code itself will usually be cut-n-paste copies of view callables from the original application with slight tweaks.

For example, if the original application has the following configure_views configuration method:

1
2

 def configure_views(config):
     config.add_view('theoriginalapp.views.theview', name='theview')

You can override the first view configuration statement made by configure_views within the override package, after loading the original configuration function:

1
2
3
4
5
6
7

from pyramid.config import Configurator
from originalapp import configure_views

if __name == '__main__':
    config = Configurator()
    config.include(configure_views)
    config.add_view('theoverrideapp.views.theview', name='theview')

In this case, the theoriginalapp.views.theview view will never be executed. Instead, a new view, theoverrideapp.views.theview will be executed instead, when request circumstances dictate.

A similar pattern can be used to extend the application with add_view declarations. Just register a new view against some other set of predicates to make sure the URLs it implies are available on some other page rendering.

Overriding Routes

Route setup is currently typically performed in a sequence of ordered calls to add_route(). Because these calls are ordered relative to each other, and because this ordering is typically important, you should retain their relative ordering when performing an override. Typically, this means copying all the add_route statements into the override package’s file and changing them as necessary. Then disinclude any add_route statements from the original application.

Overriding Assets

Assets are files on the filesystem that are accessible within a Python package. An entire chapter is devoted to assets: Static Assets. Within this chapter is a section named Overriding Assets. This section of that chapter describes in detail how to override package assets with other assets by using the pyramid.config.Configurator.override_asset() method. Add such override_asset calls to your override package’s __init__.py to perform overrides.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Request Processing

Once a Pyramid application is up and running, it is ready to accept requests and return responses.

What happens from the time a WSGI request enters a Pyramid application through to the point that Pyramid hands off a response back to WSGI for upstream processing?

A user initiates a request from his browser to the hostname and port number of the WSGI server used by the Pyramid application.

The WSGI server used by the Pyramid application passes the WSGI environment to the __call__ method of the Pyramid router object.

A request object is created based on the WSGI environment.

The application registry and the request object created in the last step are pushed on to the thread local stack that Pyramid uses to allow the functions named get_current_request() and get_current_registry() to work.

A NewRequest event is sent to any subscribers.

If any route has been defined within application configuration, the Pyramid router calls a URL dispatch “route mapper.” The job of the mapper is to examine the request to determine whether any user-defined route matches the current WSGI environment. The router passes the request as an argument to the mapper.

If any route matches, the request is mutated; a matchdict and matched_route attributes are added to the request object; the former contains a dictionary representing the matched dynamic elements of the request’s PATH_INFO value, the latter contains the IRoute object representing the route which matched. The root object associated with the route found is also generated: if the route configuration which matched has an associated a factory argument, this factory is used to generate the root object, otherwise a default root factory is used.

If a route match was not found, and a root_factory argument was passed to the Configurator constructor, that callable is used to generate the root object. If the root_factory argument passed to the Configurator constructor was None, a default root factory is used to generate a root object.

The Pyramid router calls a “traverser” function with the root object and the request. The traverser function attempts to traverse the root object (using any existing __getitem__ on the root object and subobjects) to find a context. If the root object has no __getitem__ method, the root itself is assumed to be the context. The exact traversal algorithm is described in Traversal. The traverser function returns a dictionary, which contains a context and a view name as well as other ancillary information.

The request is decorated with various names returned from the traverser (such as context, view_name, and so forth), so they can be accessed via e.g. request.context within view code.

A ContextFound event is sent to any subscribers.

Pyramid looks up a view callable using the context, the request, and the view name. If a view callable doesn’t exist for this combination of objects (based on the type of the context, the type of the request, and the value of the view name, and any predicate attributes applied to the view configuration), Pyramid raises a NotFound exception, which is meant to be caught by a surrounding exception handler.

If a view callable was found, Pyramid attempts to call the view function.

If an authorization policy is in use, and the view was protected by a permission, Pyramid passes the context, the request, and the view_name to a function which determines whether the view being asked for can be executed by the requesting user, based on credential information in the request and security information attached to the context. If it returns True, Pyramid calls the view callable to obtain a response. If it returns False, it raises a Forbidden exception, which is meant to be called by a surrounding exception handler.

If any exception was raised within a root factory, by traversal, by a view callable or by Pyramid itself (such as when it raises NotFound or Forbidden), the router catches the exception, and attaches it to the request as the exception attribute. It then attempts to find a exception view for the exception that was caught. If it finds an exception view callable, that callable is called, and is presumed to generate a response. If an exception view that matches the exception cannot be found, the exception is reraised.

The following steps occur only when a response could be successfully generated by a normal view callable or an exception view callable. Pyramid will attempt to execute any response callback functions attached via add_response_callback(). A NewResponse event is then sent to any subscribers. The response object’s app_iter, status, and headerlist attributes are then used to generate a WSGI response. The response is sent back to the upstream WSGI server.

Pyramid will attempt to execute any finished callback functions attached via add_finished_callback().

The thread local stack is popped.

This is a very high-level overview that leaves out various details. For more detail about subsystems invoked by the Pyramid router such as traversal, URL dispatch, views, and event processing, see URL Dispatch, Views, and Using Events.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Thread Locals

A thread local variable is a variable that appears to be a “global” variable to an application which uses it. However, unlike a true global variable, one thread or process serving the application may receive a different value than another thread or process when that variable is “thread local”.

When a request is processed, Pyramid makes two thread local variables available to the application: a “registry” and a “request”.

Why and How Pyramid Uses Thread Local Variables

How are thread locals beneficial to Pyramid and application developers who use Pyramid? Well, usually they’re decidedly not. Using a global or a thread local variable in any application usually makes it a lot harder to understand for a casual reader. Use of a thread local or a global is usually just a way to avoid passing some value around between functions, which is itself usually a very bad idea, at least if code readability counts as an important concern.

For historical reasons, however, thread local variables are indeed consulted by various Pyramid API functions. For example, the implementation of the pyramid.security function named authenticated_userid() retrieves the thread local application registry as a matter of course to find an authentication policy. It uses the pyramid.threadlocal.get_current_registry() function to retrieve the application registry, from which it looks up the authentication policy; it then uses the authentication policy to retrieve the authenticated user id. This is how Pyramid allows arbitrary authentication policies to be “plugged in”.

When they need to do so, Pyramid internals use two API functions to retrieve the request and application registry: get_current_request() and get_current_registry(). The former returns the “current” request; the latter returns the “current” registry. Both get_current_* functions retrieve an object from a thread-local data structure. These API functions are documented in pyramid.threadlocal.

These values are thread locals rather than true globals because one Python process may be handling multiple simultaneous requests or even multiple Pyramid applications. If they were true globals, Pyramid could not handle multiple simultaneous requests or allow more than one Pyramid application instance to exist in a single Python process.

Because one Pyramid application is permitted to call another Pyramid application from its own view code (perhaps as a WSGI app with help from the pyramid.wsgi.wsgiapp2() decorator), these variables are managed in a stack during normal system operations. The stack instance itself is a threading.local [http://docs.python.org/library/threading.html#threading.local].

During normal operations, the thread locals stack is managed by a Router object. At the beginning of a request, the Router pushes the application’s registry and the request on to the stack. At the end of a request, the stack is popped. The topmost request and registry on the stack are considered “current”. Therefore, when the system is operating normally, the very definition of “current” is defined entirely by the behavior of a pyramid Router.

However, during unit testing, no Router code is ever invoked, and the definition of “current” is defined by the boundary between calls to the pyramid.config.Configurator.begin() and pyramid.config.Configurator.end() methods (or between calls to the pyramid.testing.setUp() and pyramid.testing.tearDown() functions). These functions push and pop the threadlocal stack when the system is under test. See Test Set Up and Tear Down for the definitions of these functions.

Scripts which use Pyramid machinery but never actually start a WSGI server or receive requests via HTTP such as scripts which use the pyramid.scripting API will never cause any Router code to be executed. However, the pyramid.scripting APIs also push some values on to the thread locals stack as a matter of course. Such scripts should expect the get_current_request() function to always return None, and should expect the get_current_registry() function to return exactly the same application registry for every request.

Why You Shouldn’t Abuse Thread Locals

You probably should almost never use the get_current_request() or get_current_registry() functions, except perhaps in tests. In particular, it’s almost always a mistake to use get_current_request or get_current_registry in application code because its usage makes it possible to write code that can be neither easily tested nor scripted. Inappropriate usage is defined as follows:

get_current_request should never be called within the body of a view callable, or within code called by a view callable. View callables already have access to the request (it’s passed in to each as request).

get_current_request should never be called in resource code. If a resource needs access to the request, it should be passed the request by a view callable.

get_current_request function should never be called because it’s “easier” or “more elegant” to think about calling it than to pass a request through a series of function calls when creating some API design. Your application should instead almost certainly pass data derived from the request around rather than relying on being able to call this function to obtain the request in places that actually have no business knowing about it. Parameters are meant to be passed around as function arguments, this is why they exist. Don’t try to “save typing” or create “nicer APIs” by using this function in the place where a request is required; this will only lead to sadness later.

Neither get_current_request nor get_current_registry should ever be called within application-specific forks of third-party library code. The library you’ve forked almost certainly has nothing to do with Pyramid, and making it dependent on Pyramid (rather than making your pyramid application depend upon it) means you’re forming a dependency in the wrong direction.

Use of the get_current_request() function in application code is still useful in very limited circumstances. As a rule of thumb, usage of get_current_request is useful within code which is meant to eventually be removed. For instance, you may find yourself wanting to deprecate some API that expects to be passed a request object in favor of one that does not expect to be passed a request object. But you need to keep implementations of the old API working for some period of time while you deprecate the older API. So you write a “facade” implementation of the new API which calls into the code which implements the older API. Since the new API does not require the request, your facade implementation doesn’t have local access to the request when it needs to pass it into the older API implementation. After some period of time, the older implementation code is disused and the hack that uses get_current_request is removed. This would be an appropriate place to use the get_current_request.

Use of the get_current_registry() function should be limited to testing scenarios. The registry made current by use of the pyramid.config.Configurator.begin() method during a test (or via pyramid.testing.setUp()) when you do not pass one in is available to you via this API.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Using the Zope Component Architecture in Pyramid

Under the hood, Pyramid uses a Zope Component Architecture component registry as its application registry. The Zope Component Architecture is referred to colloquially as the “ZCA.”

The zope.component API used to access data in a traditional Zope application can be opaque. For example, here is a typical “unnamed utility” lookup using the zope.component.getUtility() global API as it might appear in a traditional Zope application:

1
2
3

from pyramid.interfaces import ISettings
from zope.component import getUtility
settings = getUtility(ISettings)

After this code runs, settings will be a Python dictionary. But it’s unlikely that any “civilian” will be able to figure this out just by reading the code casually. When the zope.component.getUtility API is used by a developer, the conceptual load on a casual reader of code is high.

While the ZCA is an excellent tool with which to build a framework such as Pyramid, it is not always the best tool with which to build an application due to the opacity of the zope.component APIs. Accordingly, Pyramid tends to hide the the presence of the ZCA from application developers. You needn’t understand the ZCA to create a Pyramid application; its use is effectively only a framework implementation detail.

However, developers who are already used to writing Zope applications often still wish to use the ZCA while building a Pyramid application; pyramid makes this possible.

Using the ZCA Global API in a Pyramid Application

Zope uses a single ZCA registry – the “global” ZCA registry – for all Zope applications that run in the same Python process, effectively making it impossible to run more than one Zope application in a single process.

However, for ease of deployment, it’s often useful to be able to run more than a single application per process. For example, use of a Paste “composite” allows you to run separate individual WSGI applications in the same process, each answering requests for some URL prefix. This makes it possible to run, for example, a TurboGears application at /turbogears and a BFG application at /bfg, both served up using the same WSGI server within a single Python process.

Most production Zope applications are relatively large, making it impractical due to memory constraints to run more than one Zope application per Python process. However, a Pyramid application may be very small and consume very little memory, so it’s a reasonable goal to be able to run more than one BFG application per process.

In order to make it possible to run more than one Pyramid application in a single process, Pyramid defaults to using a separate ZCA registry per application.

While this services a reasonable goal, it causes some issues when trying to use patterns which you might use to build a typical Zope application to build a Pyramid application. Without special help, ZCA “global” APIs such as zope.component.getUtility and zope.component.getSiteManager will use the ZCA “global” registry. Therefore, these APIs will appear to fail when used in a Pyramid application, because they’ll be consulting the ZCA global registry rather than the component registry associated with your Pyramid application.

There are three ways to fix this: by disusing the ZCA global API entirely, by using pyramid.config.Configurator.hook_zca() or by passing the ZCA global registry to the Configurator constructor at startup time. We’ll describe all three methods in this section.

Disusing the Global ZCA API

ZCA “global” API functions such as zope.component.getSiteManager, zope.component.getUtility, zope.component.getAdapter, and zope.component.getMultiAdapter aren’t strictly necessary. Every component registry has a method API that offers the same functionality; it can be used instead. For example, presuming the registry value below is a Zope Component Architecture component registry, the following bit of code is equivalent to zope.component.getUtility(IFoo):

1

registry.getUtility(IFoo)

The full method API is documented in the zope.component package, but it largely mirrors the “global” API almost exactly.

If you are willing to disuse the “global” ZCA APIs and use the method interface of a registry instead, you need only know how to obtain the Pyramid component registry.

There are two ways of doing so:

use the pyramid.threadlocal.get_current_registry() function within Pyramid view or resource code. This will always return the “current” Pyramid application registry.

use the attribute of the request object named registry in your Pyramid view code, eg. request.registry. This is the ZCA component registry related to the running Pyramid application.

See Thread Locals for more information about pyramid.threadlocal.get_current_registry().

Enabling the ZCA Global API by Using hook_zca

Consider the following bit of idiomatic Pyramid startup code:

1
2
3
4
5
6
7

from zope.component import getGlobalSiteManager
from pyramid.config import Configurator

def app(global_settings, **settings):
    config = Configurator(settings=settings)
    config.include('some.other.package')
    return config.make_wsgi_app()

When the app function above is run, a Configurator is constructed. When the configurator is created, it creates a new application registry (a ZCA component registry). A new registry is constructed whenever the registry argument is omitted when a Configurator constructor is called, or when a registry argument with a value of None is passed to a Configurator constructor.

During a request, the application registry created by the Configurator is “made current”. This means calls to get_current_registry() in the thread handling the request will return the component registry associated with the application.

As a result, application developers can use get_current_registry to get the registry and thus get access to utilities and such, as per Disusing the Global ZCA API. But they still cannot use the global ZCA API. Without special treatment, the ZCA global APIs will always return the global ZCA registry (the one in zope.component.globalregistry.base).

To “fix” this and make the ZCA global APIs use the “current” BFG registry, you need to call hook_zca() within your setup code. For example:

1
2
3
4
5
6
7
8

from zope.component import getGlobalSiteManager
from pyramid.config import Configurator

def app(global_settings, **settings):
    config = Configurator(settings=settings)
    config.hook_zca()
    config.include('some.other.application')
    return config.make_wsgi_app()

We’ve added a line to our original startup code, line number 6, which calls config.hook_zca(). The effect of this line under the hood is that an analogue of the following code is executed:

1
2
3

from zope.component import getSiteManager
from pyramid.threadlocal import get_current_registry
getSiteManager.sethook(get_current_registry)

This causes the ZCA global API to start using the Pyramid application registry in threads which are running a Pyramid request.

Calling hook_zca is usually sufficient to “fix” the problem of being able to use the global ZCA API within a Pyramid application. However, it also means that a Zope application that is running in the same process may start using the Pyramid global registry instead of the Zope global registry, effectively inverting the original problem. In such a case, follow the steps in the next section, Enabling the ZCA Global API by Using The ZCA Global Registry.

Enabling the ZCA Global API by Using The ZCA Global Registry

You can tell your Pyramid application to use the ZCA global registry at startup time instead of constructing a new one:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from zope.component import getGlobalSiteManager
from pyramid.config import Configurator

def app(global_settings, **settings):
    globalreg = getGlobalSiteManager()
    config = Configurator(registry=globalreg)
    config.setup_registry(settings=settings)
    config.hook_zca()
    config.include('some.other.application')
    return config.make_wsgi_app()

Lines 5, 6, and 7 above are the interesting ones. Line 5 retrieves the global ZCA component registry. Line 6 creates a Configurator, passing the global ZCA registry into its constructor as the registry argument. Line 7 “sets up” the global registry with BFG-specific registrations; this is code that is normally executed when a registry is constructed rather than created, but we must call it “by hand” when we pass an explicit registry.

At this point, Pyramid will use the ZCA global registry rather than creating a new application-specific registry; since by default the ZCA global API will use this registry, things will work as you might expect a Zope app to when you use the global ZCA API.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial

This tutorial introduces a traversal -based Pyramid application to a developer familiar with Python. It will be most familiar to developers with previous Zope experience. When we’re done with the tutorial, the developer will have created a basic Wiki application with authentication.

For cut and paste purposes, the source code for all stages of this tutorial can be browsed at http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki.

Background

Installation

Preparation

Making a Project

Installing the Project in “Development Mode”

Running the Tests

Starting the Application

Exposing Test Coverage Information

Visit the Application in a Browser

Decisions the pyramid_zodb Template Has Made For You

Basic Layout

App Startup with __init__.py

Resources and Models with models.py

Views With views.py

The WSGI Pipeline in development.ini

Defining the Domain Model

Deleting the Database

Adding Model Classes

Looking at the Result of Our Edits to models.py

Removing View Configuration

Testing the Models

Declaring Dependencies in Our setup.py File

Running the Tests

Defining Views

Adding View Functions

Viewing the Result of Our Edits to views.py

Adding Templates

Testing the Views

Running the Tests

Viewing the Application in a Browser

Adding Authorization

Configuring a pyramid Authentication Policy

Giving Our Root Resource an ACL

Adding permission Declarations to our view_config Decorators

Viewing the Application in a Browser

Seeing Our Changes To views.py and our Templates

Revisiting the Application

Distributing Your Application

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial »

Background

This version of the Pyramid wiki tutorial presents a Pyramid application that uses technologies which will be familiar to someone with Zope experience. It uses ZODB as a persistence mechanism and traversal to map URLs to code. It can also be followed by people without any prior Python web framework experience.

To code along with this tutorial, the developer will need a UNIX machine with development tools (Mac OS X with XCode, any Linux or BSD variant, etc) or he will need a Windows system of any kind.

This tutorial targets Pyramid version 1.0.

Have fun!

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial »

Installation

For the most part, the installation process for this tutorial duplicates the steps described in Installing Pyramid and Creating a Pyramid Project, however it also explains how to install additional libraries for tutorial purposes.

Preparation

Please take the following steps to prepare for the tutorial. The steps to prepare for the tutorial are slightly different depending on whether you’re using UNIX or Windows.

Preparation, UNIX

If you don’t already have a Python 2.6 interpreter installed on your system, obtain, install, or find Python 2.6 [http://python.org/download/releases/2.6.6/] for your system.

Install the latest setuptools into the Python you obtained/installed/found in the step above: download ez_setup.py [http://peak.telecommunity.com/dist/ez_setup.py] and run it using the python interpreter of your Python 2.6 installation:

$ /path/to/my/Python-2.6/bin/python ez_setup.py

Use that Python’s bin/easy_install to install virtualenv:

$ /path/to/my/Python-2.6/bin/easy_install virtualenv

Use that Python’s virtualenv to make a workspace:

$ path/to/my/Python-2.6/bin/virtualenv --no-site-packages \
          pyramidtut

Switch to the pyramidtut directory:

$ cd pyramidtut

(Optional) Consider using source bin/activate to make your shell environment wired to use the virtualenv.

Use easy_install to get Pyramid and its direct dependencies installed:

$ bin/easy_install pyramid

Use easy_install to install docutils, repoze.tm, repoze.zodbconn, nose and coverage:

$ bin/easy_install docutils repoze.tm repoze.zodbconn \
          nose coverage

Preparation, Windows

Install, or find Python 2.6 [http://python.org/download/releases/2.6.6/] for your system.

Install the latest setuptools into the Python you obtained/installed/found in the step above: download ez_setup.py [http://peak.telecommunity.com/dist/ez_setup.py] and run it using the python interpreter of your Python 2.6 installation using a command prompt:

c:\> c:\Python26\python ez_setup.py

Use that Python’s bin/easy_install to install virtualenv:

c:\> c:\Python26\Scripts\easy_install virtualenv

Use that Python’s virtualenv to make a workspace:

c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut

Switch to the pyramidtut directory:

c:\> cd pyramidtut

(Optional) Consider using bin\activate.bat to make your shell environment wired to use the virtualenv.

Use easy_install to get Pyramid and its direct dependencies installed:

c:\pyramidtut> Scripts\easy_install pyramid

Use easy_install to install docutils, repoze.tm, repoze.zodbconn, nose and coverage:

c:\pyramidtut> Scripts\easy_install docutils repoze.tm \
      repoze.zodbconn nose coverage

Making a Project

Your next step is to create a project. Pyramid supplies a variety of templates to generate sample projects. For this tutorial, we will use the ZODB -oriented template named pyramid_zodb.

The below instructions assume your current working directory is the “virtualenv” named “pyramidtut”.

On UNIX:

$ bin/paster create -t pyramid_zodb tutorial

On Windows:

c:\pyramidtut> Scripts\paster create -t pyramid_zodb tutorial

Note

If you are using Windows, the pyramid_zodb Paster template doesn’t currently deal gracefully with installation into a location that contains spaces in the path. If you experience startup problems, try putting both the virtualenv and the project into directories that do not contain spaces in their paths.

Installing the Project in “Development Mode”

In order to do development on the project easily, you must “register” the project as a development egg in your workspace using the setup.py develop command. In order to do so, cd to the “tutorial” directory you created in Making a Project, and run the “setup.py develop” command using virtualenv Python interpreter.

On UNIX:

$ cd tutorial
$ ../bin/python setup.py develop

On Windows:

C:\pyramidtut> cd tutorial
C:\pyramidtut\tutorial> ..\Scripts\python setup.py develop

Running the Tests

After you’ve installed the project in development mode, you may run the tests for the project.

On UNIX:

$ ../bin/python setup.py test -q

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q

Starting the Application

Start the application.

On UNIX:

$ ../bin/paster serve development.ini --reload

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\paster serve development.ini --reload

Exposing Test Coverage Information

You can run the nosetests command to see test coverage information. This runs the tests in the same way that setup.py test does but provides additional “coverage” information, exposing which lines of your project are “covered” (or not covered) by the tests.

On UNIX:

$ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
     --cover-erase --with-coverage

Looks like the code in the pyramid_zodb template for ZODB projects is missing some test coverage, particularly in the file named models.py.

Visit the Application in a Browser

In a browser, visit http://localhost:6543/. You will see the generated application’s default page.

Decisions the pyramid_zodb Template Has Made For You

Creating a project using the pyramid_zodb template makes the following assumptions:

you are willing to use ZODB as persistent storage

you are willing to use traversal to map URLs to code.

you want to use imperative code plus a scan to perform configuration.

Note

Pyramid supports any persistent storage mechanism (e.g. a SQL database or filesystem files, etc). Pyramid also supports an additional mechanism to map URLs to code (URL dispatch). However, for the purposes of this tutorial, we’ll only be using traversal and ZODB.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial »

Basic Layout

The starter files generated by the pyramid_zodb template are basic, but they provide a good orientation for the high-level patterns common to most traversal -based Pyramid (and ZODB based) projects.

The source code for this tutorial stage can be browsed via http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/.

App Startup with __init__.py

A directory on disk can be turned into a Python package by containing an __init__.py file. Even if empty, this marks a directory as a Python package. Our application uses __init__.py as both a package marker, as well as to contain application configuration code.

When you run the application using the paster command using the development.ini generated config file, the application configuration points at an Setuptools entry point described as egg:tutorial. In our application, because the application’s setup.py file says so, this entry point happens to be the main function within the file named __init__.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from pyramid.config import Configurator
from repoze.zodbconn.finder import PersistentApplicationFinder
from tutorial.models import appmaker

def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    zodb_uri = settings.get('zodb_uri')
    if zodb_uri is None:
        raise ValueError("No 'zodb_uri' in application configuration.")

    finder = PersistentApplicationFinder(zodb_uri, appmaker)
    def get_root(request):
        return finder(request.environ)
    config = Configurator(root_factory=get_root, settings=settings)
    config.add_static_view('static', 'tutorial:static')
    config.scan('tutorial')
    return config.make_wsgi_app()

Lines 1-3. Perform some dependency imports.

Line 8. Get the ZODB configuration from the development.ini file’s [app:main] section represented by the settings dictionary passed to our app function. This will be a URI (something like file:///path/to/Data.fs).

Line 12. We create a “finder” object using the PersistentApplicationFinder helper class, passing it the ZODB URI and the “appmaker” we’ve imported from models.py.

Lines 13 - 14. We create a root factory which uses the finder to return a ZODB root object.

Line 15. We construct a Configurator with a root factory and the settings keywords parsed by PasteDeploy. The root factory is named get_root.

Line 16. Register a ‘static view’ which answers requests which start with with URL path /static using the pyramid.config.Configurator.add_static_view method(). This statement registers a view that will serve up static assets, such as CSS and image files, for us, in this case, at http://localhost:6543/static/ and below. The first argument is the “name” static, which indicates that the URL path prefix of the view will be /static. the The second argument of this tag is the “path”, which is an asset specification, so it finds the resources it should serve within the static directory inside the tutorial package.

Line 17. Perform a scan. A scan will find configuration decoration, such as view configuration decorators (e.g. @view_config) in the source code of the tutorial package and will take actions based on these decorators. The argument to scan() is the package name to scan, which is tutorial.

Line 18. Use the pyramid.config.Configurator.make_wsgi_app() method to return a WSGI application.

Resources and Models with models.py

Pyramid uses the word resource to describe objects arranged hierarchically in a resource tree. This tree is consulted by traversal to map URLs to code. In this application, the resource tree represents the site structure, but it also represents the domain model of the application, because each resource is a node stored persistently in a ZODB database. The models.py file is where the pyramid_zodb Paster template put the classes that implement our resource objects, each of which happens also to be a domain model object.

Here is the source for models.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from persistent.mapping import PersistentMapping

class MyModel(PersistentMapping):
    __parent__ = __name__ = None

def appmaker(zodb_root):
    if not 'app_root' in zodb_root:
        app_root = MyModel()
        zodb_root['app_root'] = app_root
        import transaction
        transaction.commit()
    return zodb_root['app_root']

Lines 3-4. The MyModel resource class is implemented here. Instances of this class will be capable of being persisted in ZODB because the class inherits from the persistent.mapping.PersistentMapping class. The __parent__ and __name__ are important parts of the traversal protocol. By default, have these as None indicating that this is the root object.

Lines 6-12. appmaker is used to return the application root object. It is called on every request to the Pyramid application. It also performs bootstrapping by creating an application root (inside the ZODB root object) if one does not already exist.

We do so by first seeing if the database has the persistent application root. If not, we make an instance, store it, and commit the transaction. We then return the application root object.

Views With views.py

Our paster template generated a default views.py on our behalf. It contains a single view, which is used to render the page shown when you visit the URL http://localhost:6543/.

Here is the source for views.py:

1
2
3
4
5
6
7

from pyramid.view import view_config
from tutorial.models import MyModel

@view_config(context=MyModel,
             renderer='tutorial:templates/mytemplate.pt')
def my_view(request):
    return {'project':'tutorial'}

Let’s try to understand the components in this module:

Lines 1-2. Perform some dependency imports.

Line 4. Use the pyramid.view.view_config() configuration decoration to perform a view configuration registration. This view configuration registration will be activated when the application is started. It will be activated by virtue of it being found as the result of a scan (when Line 17 of __init__.py is run).

The @view_config decorator accepts a number of keyword arguments. We use two keyword arguments here: context and renderer.

The context argument signifies that the decorated view callable should only be run when traversal finds the tutorial.models.MyModel resource to be the context of a request. In English, this means that when the URL / is visited, because MyModel is the root model, this view callable will be invoked.

The renderer argument names an asset specification of tutorial:templates/mytemplate.pt. This asset specification points at a Chameleon template which lives in the mytemplate.pt file within the templates directory of the tutorial package. And indeed if you look in the templates directory of this package, you’ll see a mytemplate.pt template file, which renders the default home page of the generated project.

Since this call to @view_config doesn’t pass a name argument, the my_view function which it decorates represents the “default” view callable used when the context is of the type MyModel.

Lines 5-6. We define a view callable named my_view, which we decorated in the step above. This view callable is a function we write generated by the pyramid_zodb template that is given a request and which returns a dictionary. The mytemplate.pt renderer named by the asset specification in the step above will convert this dictionary to a response on our behalf.

The function returns the dictionary {'project':'tutorial'}. This dictionary is used by the template named by the mytemplate.pt asset specification to fill in certain values on the page.

The WSGI Pipeline in development.ini

The development.ini (in the tutorial project directory, as opposed to the tutorial package directory) looks like this:

[app:tutorial]
use = egg:tutorial
reload_templates = true
debug_authorization = false
debug_notfound = false
debug_routematch = false
debug_templates = true
default_locale_name = en
zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000

[pipeline:main]
pipeline =
    egg:WebError#evalerror
    egg:repoze.zodbconn#closer
    egg:repoze.retry#retry
    tm
    tutorial

[filter:tm]
use = egg:repoze.tm2#tm
commit_veto = repoze.tm:default_commit_veto

[server:main]
use = egg:Paste#http
host = 0.0.0.0
port = 6543

# Begin logging configuration

[loggers]
keys = root

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s

# End logging configuration

Note the existence of a [pipeline:main] section which specifies our WSGI pipeline. This “pipeline” will be served up as our WSGI application. As far as the WSGI server is concerned the pipeline is our application. Simpler configurations don’t use a pipeline: instead they expose a single WSGI application as “main”. Our setup is more complicated, so we use a pipeline composed of middleware.

The egg:WebError#evalerror middleware is at the “top” of the pipeline. This is middleware which displays debuggable errors in the browser while you’re developing (not recommended for deployment).

The egg:repoze.zodbconn#closer middleware is in the middle of the pipeline. This is a piece of middleware which closes the ZODB connection opened by the PersistentApplicationFinder at the end of the request.

The egg:repoze.retry#retry middleware catches ConflictError exceptions from ZODB and retries the request up to three times (ZODB is an optimistic concurrency database that relies on application-level transaction retries when a conflict occurs).

The tm middleware is the last piece of middleware in the pipeline. This commits a transaction near the end of the request unless there’s an exception raised or the HTTP response code is an error code. The tm refers to the [filter:tm] section beneath the pipeline declaration, which configures the transaction manager.

The final line in the [pipeline:main] section is tutorial, which refers to the [app:tutorial] section above it. The [app:tutorial] section is the section which actually defines our application settings. The values within this section are passed as **settings to the main function we defined in __init__.py when the server is started via paster serve.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial »

Defining the Domain Model

The first change we’ll make to our bone-stock paster -generated application will be to define a number of resource constructors. Remember that, because we’re using ZODB to represent our resource tree, each of these resource constructors represents a domain model object, so we’ll call these constructors “model constructors”. For this application, which will be a Wiki, we will need two kinds of model constructors: a “Wiki” model constructor, and a “Page” model constructor. Both our Page and Wiki constructors will be class objects. A single instance of the “Wiki” class will serve as a container for “Page” objects, which will be instances of the “Page” class.

The source code for this tutorial stage can be browsed via http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/models/.

Deleting the Database

In a subsequent step, we’re going to remove the MyModel Python model class from our models.py file. Since this class is referred to within our persistent storage (represented on disk as a file named Data.fs), we’ll have strange things happen the next time we want to visit the application in a browser. Remove the Data.fs from the tutorial directory before proceeding any further. It’s always fine to do this as long as you don’t care about the content of the database; the database itself will be recreated as necessary.

Adding Model Classes

The next thing we want to do is remove the MyModel class from the generated models.py file. The MyModel class is only a sample and we’re not going to use it.

Note

There is nothing automagically special about the filename models.py. A project may have many models throughout its codebase in arbitrarily-named files. Files implementing models often have model in their filenames, or they may live in a Python subpackage of your application package named models, but this is only by convention.

Then, we’ll add a Wiki class. Because this is a ZODB application, this class should inherit from persistent.mapping.PersistentMapping. We want it to inherit from the persistent.mapping.PersistentMapping class because our Wiki class will be a mapping of wiki page names to Page objects. The persistent.mapping.PersistentMapping class provides our class with mapping behavior, and makes sure that our Wiki page is stored as a “first-class” persistent object in our ZODB database.

Our Wiki class should also have a __name__ attribute set to None at class scope, and should have a __parent__ attribute set to None at class scope as well. If a model has a __parent__ attribute of None in a traversal-based Pyramid application, it means that it’s the root model. The __name__ of the root model is also always None.

Then we’ll add a Page class. This class should inherit from the persistent.Persistent class. We’ll also give it an __init__ method that accepts a single parameter named data. This parameter will contain the ReStructuredText body representing the wiki page content. Note that Page objects don’t have an initial __name__ or __parent__ attribute. All objects in a traversal graph must have a __name__ and a __parent__ attribute. We don’t specify these here because both __name__ and __parent__ will be set by by a view function when a Page is added to our Wiki mapping.

As a last step, we want to change the appmaker function in our models.py file so that the root resource of our application is a Wiki instance. We’ll also slot a single page object (the front page) into the Wiki within the appmaker. This will provide traversal a resource tree to work against when it attempts to resolve URLs to resources.

We’re using a mini-framework callable named PersistentApplicationFinder in our application (see __init__.py). A PersistentApplicationFinder accepts a ZODB URL as well as an “appmaker” callback. This callback typically lives in the models.py file. We’ll just change this function, making the necessary edits.

Looking at the Result of Our Edits to models.py

The result of all of our edits to models.py will end up looking something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from persistent import Persistent
from persistent.mapping import PersistentMapping

class Wiki(PersistentMapping):
    __name__ = None
    __parent__ = None

class Page(Persistent):
    def __init__(self, data):
        self.data = data

def appmaker(zodb_root):
    if not 'app_root' in zodb_root:
        app_root = Wiki()
        frontpage = Page('This is the front page')
        app_root['FrontPage'] = frontpage
        frontpage.__name__ = 'FrontPage'
        frontpage.__parent__ = app_root
        zodb_root['app_root'] = app_root
        import transaction
        transaction.commit()
    return zodb_root['app_root']

Removing View Configuration

In a previous step in this chapter, we removed the tutorial.models.MyModel class. However, our views.py module still attempts to import this class. Temporarily, we’ll change views.py so that it no longer references MyModel by removing its imports and removing a reference to it from the arguments passed to the @view_config configuration decoration decorator which sits atop the my_view view callable.

The result of all of our edits to views.py will end up looking something like this:

1
2
3
4
5

from pyramid.view import view_config

@view_config(renderer='tutorial:templates/mytemplate.pt')
def my_view(request):
    return {'project':'tutorial'}

Testing the Models

To make sure the code we just wrote works, we write tests for the model classes and the appmaker. Changing tests.py, we’ll write a separate test class for each model class, and we’ll write a test class for the appmaker.

To do so, we’ll retain the tutorial.tests.ViewTests class provided as a result of the pyramid_zodb project generator. We’ll add three test classes: one for the Page model named PageModelTests, one for the Wiki model named WikiModelTests, and one for the appmaker named AppmakerTests.

When we’re done changing tests.py, it will look something like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

import unittest

from pyramid import testing

class PageModelTests(unittest.TestCase):

    def _getTargetClass(self):
        from tutorial.models import Page
        return Page

    def _makeOne(self, data=u'some data'):
        return self._getTargetClass()(data=data)

    def test_constructor(self):
        instance = self._makeOne()
        self.assertEqual(instance.data, u'some data')

class WikiModelTests(unittest.TestCase):

    def _getTargetClass(self):
        from tutorial.models import Wiki
        return Wiki

    def _makeOne(self):
        return self._getTargetClass()()

    def test_it(self):
        wiki = self._makeOne()
        self.assertEqual(wiki.__parent__, None)
        self.assertEqual(wiki.__name__, None)

class AppmakerTests(unittest.TestCase):

    def _callFUT(self, zodb_root):
        from tutorial.models import appmaker
        return appmaker(zodb_root)

    def test_no_app_root(self):
        root = {}
        self._callFUT(root)
        self.assertEqual(root['app_root']['FrontPage'].data,
                         'This is the front page')

    def test_w_app_root(self):
        app_root = object()
        root = {'app_root': app_root}
        self._callFUT(root)
        self.failUnless(root['app_root'] is app_root)

class ViewTests(unittest.TestCase):
    def setUp(self):
        self.config = testing.setUp()

    def tearDown(self):
        testing.tearDown()

    def test_my_view(self):
        from tutorial.views import my_view
        request = testing.DummyRequest()
        info = my_view(request)
        self.assertEqual(info['project'], 'tutorial')

Declaring Dependencies in Our setup.py File

Our application now depends on packages which are not dependencies of the original “tutorial” application as it was generated by the paster create command. We’ll add these dependencies to our tutorial package’s setup.py file by assigning these dependencies to both the install_requires and the tests_require parameters to the setup function. In particular, we require the docutils package.

Our resulting setup.py should look like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

import os

from setuptools import setup, find_packages

here = os.path.abspath(os.path.dirname(__file__))
README = open(os.path.join(here, 'README.txt')).read()
CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()

requires = [
    'pyramid',
    'repoze.zodbconn',
    'repoze.tm2>=1.0b1', # default_commit_veto
    'repoze.retry',
    'ZODB3',
    'WebError',
    'docutils',
    ]

setup(name='tutorial',
      version='0.0',
      description='tutorial',
      long_description=README + '\n\n' +  CHANGES,
      classifiers=[
        "Intended Audience :: Developers",
        "Framework :: Pylons",
        "Programming Language :: Python",
        "Topic :: Internet :: WWW/HTTP",
        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
        ],
      author='',
      author_email='',
      url='',
      keywords='web pylons pyramid',
      packages=find_packages(),
      include_package_data=True,
      zip_safe=False,
      install_requires=requires,
      tests_require=requires,
      test_suite="tutorial",
      entry_points = """\
      [paste.app_factory]
      main = tutorial:main
      """,
      paster_plugins=['pyramid'],
      )

Running the Tests

We can run these tests by using setup.py test in the same way we did in Running the Tests. Assuming our shell’s current working directory is the “tutorial” distribution directory:

On UNIX:

$ ../bin/python setup.py test -q

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q

The expected output is something like this:

.....
----------------------------------------------------------------------
Ran 5 tests in 0.008s

OK

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial »

Defining Views

Conventionally, view callable objects are defined within a views.py module in an Pyramid application. There is nothing automagically special about the filename views.py. Files implementing views often have view in their filenames (or may live in a Python subpackage of your application package named views), but this is only by convention. A project may have many views throughout its codebase in arbitrarily-named files. In this application, however, we’ll be continuing to use the views.py module, because there’s no reason to break convention.

A view callable in a Pyramid application is typically a simple Python function that accepts a single parameter: request. A view callable is assumed to return a response object.

However, a Pyramid view can also be defined as callable which accepts two arguments: a context and a request. In url dispatch based applications, the context resource is rarely used in the view body itself, so within code that uses URL-dispatch-only, it’s common to define views as callables that accept only a request to avoid the visual “noise” of a context argument. This application, however, uses traversal to map URLs to a context resource, and since our resource tree also represents our application’s “domain model”, we’re often interested in the context, because it represents the persistent storage of our application. For this reason, having context in the callable argument list is not “noise” to us; instead it’s actually rather important within the view code we’ll define in this application.

The single-arg (request -only) or two-arg (context and request) calling conventions will work in any Pyramid application for any view; they can be used interchangeably as necessary. We’ll be using the two-argument (context, request) view callable argument list syntax in this application.

We’re going to define several view callable functions then wire them into Pyramid using some view configuration.

The source code for this tutorial stage can be browsed via http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/views/.

Adding View Functions

We’re going to add four view callable functions to our views.py module. One view named view_wiki will display the wiki itself (it will answer on the root URL), another named view_page will display an individual page, another named add_page will allow a page to be added, and a final view named edit_page will allow a page to be edited.

The view_wiki view function

The view_wiki function will be configured to respond as the default view callable for a Wiki resource. We’ll provide it with a @view_config decorator which names the class tutorial.models.Wiki as its context. This means that when a Wiki resource is the context, and no view name exists in the request, this view will be used. The view configuration associated with view_wiki does not use a renderer because the view callable always returns a response object rather than a dictionary. No renderer is necessary when a view returns a response object.

The view_wiki view callable always redirects to the URL of a Page resource named “FrontPage”. To do so, it returns an instance of the pyramid.httpexceptions.HTTPFound class (instances of which implement the WebOb response interface). The pyramid.url.resource_url() API. pyramid.url.resource_url() constructs a URL to the FrontPage page resource (e.g. http://localhost:6543/FrontPage), and uses it as the “location” of the HTTPFound response, forming an HTTP redirect.

The view_page view function

The view_page function will be configured to respond as the default view of a Page resource. We’ll provide it with a @view_config decorator which names the class tutorial.models.Wiki as its context. This means that when a Page resource is the context, and no view name exists in the request, this view will be used. We inform Pyramid this view will use the templates/view.pt template file as a renderer.

The view_page function generates the ReStructuredText body of a page (stored as the data attribute of the context passed to the view; the context will be a Page resource) as HTML. Then it substitutes an HTML anchor for each WikiWord reference in the rendered HTML using a compiled regular expression.

The curried function named check is used as the first argument to wikiwords.sub, indicating that it should be called to provide a value for each WikiWord match found in the content. If the wiki (our page’s __parent__) already contains a page with the matched WikiWord name, the check function generates a view link to be used as the substitution value and returns it. If the wiki does not already contain a page with with the matched WikiWord name, the function generates an “add” link as the substitution value and returns it.

As a result, the content variable is now a fully formed bit of HTML containing various view and add links for WikiWords based on the content of our current page resource.

We then generate an edit URL (because it’s easier to do here than in the template), and we wrap up a number of arguments in a dictionary and return it.

The arguments we wrap into a dictionary include page, content, and edit_url. As a result, the template associated with this view callable (via renderer= in its configuration) will be able to use these names to perform various rendering tasks. The template associated with this view callable will be a template which lives in templates/view.pt.

Note the contrast between this view callable and the view_wiki view callable. In the view_wiki view callable, we unconditionally return a response object. In the view_page view callable, we return a dictionary. It is always fine to return a response object from a Pyramid view. Returning a dictionary is allowed only when there is a renderer associated with the view callable in the view configuration.

The add_page view function

The add_page function will be configured to respond when the context resource is a Wiki and the view name is add_page. We’ll provide it with a @view_config decorator which names the string add_page as its view name (via name=), the class tutorial.models.Wiki as its context, and the renderer named templates/edit.pt. This means that when a Wiki resource is the context, and a view name named add_page exists as the result of traversal, this view will be used. We inform Pyramid this view will use the templates/edit.pt template file as a renderer. We share the same template between add and edit views, thus edit.pt instead of add.pt.

The add_page function will be invoked when a user clicks on a WikiWord which isn’t yet represented as a page in the system. The check function within the view_page view generates URLs to this view. It also acts as a handler for the form that is generated when we want to add a page resource. The context of the add_page view is always a Wiki resource (not a Page resource).

The request subpath in Pyramid is the sequence of names that are found after the view name in the URL segments given in the PATH_INFO of the WSGI request as the result of traversal. If our add view is invoked via, e.g. http://localhost:6543/add_page/SomeName, the subpath will be a tuple: ('SomeName',).

The add view takes the zeroth element of the subpath (the wiki page name), and aliases it to the name attribute in order to know the name of the page we’re trying to add.

If the view rendering is not a result of a form submission (if the expression 'form.submitted' in request.params is False), the view renders a template. To do so, it generates a “save url” which the template use as the form post URL during rendering. We’re lazy here, so we’re trying to use the same template (templates/edit.pt) for the add view as well as the page edit view. To do so, we create a dummy Page resource object in order to satisfy the edit form’s desire to have some page object exposed as page, and we’ll render the template to a response.

If the view rendering is a result of a form submission (if the expression 'form.submitted' in request.params is True), we scrape the page body from the form data, create a Page object using the name in the subpath and the page body, and save it into “our context” (the Wiki) using the __setitem__ method of the context. We then redirect back to the view_page view (the default view for a page) for the newly created page.

The edit_page view function

The edit_page function will be configured to respond when the context is a Page resource and the view name is edit_page. We’ll provide it with a @view_config decorator which names the string edit_page as its view name (via name=), the class tutorial.models.Page as its context, and the renderer named templates/edit.pt. This means that when a Page resource is the context, and a view name exists as the result of traverasal named edit_page, this view will be used. We inform Pyramid this view will use the templates/edit.pt template file as a renderer.

The edit_page function will be invoked when a user clicks the “Edit this Page” button on the view form. It renders an edit form but it also acts as the form post view callable for the form it renders. The context of the edit_page view will always be a Page resource (never a Wiki resource).

If the view execution is not a result of a form submission (if the expression 'form.submitted' in request.params is False), the view simply renders the edit form, passing the request, the page resource, and a save_url which will be used as the action of the generated form.

If the view execution is a result of a form submission (if the expression 'form.submitted' in request.params is True), the view grabs the body element of the request parameter and sets it as the data attribute of the page context. It then redirects to the default view of the context (the page), which will always be the view_page view.

Viewing the Result of Our Edits to views.py

The result of all of our edits to views.py will leave it looking like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

from docutils.core import publish_parts
import re

from pyramid.httpexceptions import HTTPFound
from pyramid.url import resource_url
from pyramid.view import view_config

from tutorial.models import Page

# regular expression used to find WikiWords
wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")

@view_config(context='tutorial.models.Wiki')
def view_wiki(context, request):
    return HTTPFound(location=resource_url(context, request, 'FrontPage'))

@view_config(context='tutorial.models.Page',
             renderer='tutorial:templates/view.pt')
def view_page(context, request):
    wiki = context.__parent__

    def check(match):
        word = match.group(1)
        if word in wiki:
            page = wiki[word]
            view_url = resource_url(page, request)
            return '<a href="%s">%s</a>' % (view_url, word)
        else:
            add_url = request.application_url + '/add_page/' + word
            return '<a href="%s">%s</a>' % (add_url, word)

    content = publish_parts(context.data, writer_name='html')['html_body']
    content = wikiwords.sub(check, content)
    edit_url = resource_url(context, request, 'edit_page')
    return dict(page = context, content = content, edit_url = edit_url)

@view_config(name='add_page', context='tutorial.models.Wiki',
             renderer='tutorial:templates/edit.pt')
def add_page(context, request):
    name = request.subpath[0]
    if 'form.submitted' in request.params:
        body = request.params['body']
        page = Page(body)
        page.__name__ = name
        page.__parent__ = context
        context[name] = page
        return HTTPFound(location = resource_url(page, request))
    save_url = resource_url(context, request, 'add_page', name)
    page = Page('')
    page.__name__ = name
    page.__parent__ = context
    return dict(page = page, save_url = save_url)

@view_config(name='edit_page', context='tutorial.models.Page',
             renderer='tutorial:templates/edit.pt')
def edit_page(context, request):
    if 'form.submitted' in request.params:
        context.data = request.params['body']
        return HTTPFound(location = resource_url(context, request))

    return dict(page = context,
                save_url = resource_url(context, request, 'edit_page'))

Adding Templates

Most view callables we’ve added expected to be rendered via a template. The default templating systems in Pyramid are Chameleon and Mako. Chameleon is a variant of ZPT, which is an XML-based templating language. Mako is a non-XML-based templating language. Because we had to pick one, we chose Chameleon for this tutorial.

The templates we create will live in the templates directory of our tutorial package. Chameleon templates must have a .pt extension to be recognized as such.

The view.pt Template

The view.pt template is used for viewing a single Page. It is used by the view_page view function. It should have a div that is “structure replaced” with the content value provided by the view. It should also have a link on the rendered page that points at the “edit” URL (the URL which invokes the edit_page view for the page being viewed).

Once we’re done with the view.pt template, it will look a lot like the below:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.__name__} - Pyramid tutorial wiki (based on
      TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Viewing <b><span tal:replace="page.__name__">Page Name Goes
          Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right"></div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <div tal:replace="structure content">
          Page text goes here.
        </div>
        <p>
          <a tal:attributes="href edit_url" href="">
            Edit this page
          </a>
        </p>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Note

The names available for our use in a template are always those that are present in the dictionary returned by the view callable. But our templates make use of a request object that none of our tutorial views return in their dictionary. This value appears as if “by magic”. However, request is one of several names that are available “by default” in a template when a template renderer is used. See *.pt or *.txt: Chameleon Template Renderers for more information about other names that are available by default in a template when a template is used as a renderer.

The edit.pt Template

The edit.pt template is used for adding and editing a Page. It is used by the add_page and edit_page view functions. It should display a page containing a form that POSTs back to the “save_url” argument supplied by the view. The form should have a “body” textarea field (the page data), and a submit button that has the name “form.submitted”. The textarea in the form should be filled with any existing page data when it is rendered.

Once we’re done with the edit.pt template, it will look a lot like the below:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.__name__} - Pyramid tutorial wiki (based on
    TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Editing <b><span tal:replace="page.__name__">Page Name Goes
            Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right"></div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <form action="${save_url}" method="post">
          <textarea name="body" tal:content="page.data" rows="10"
                    cols="60"/><br/>
          <input type="submit" name="form.submitted" value="Save"/>
        </form>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Static Assets

Our templates name a single static asset named pylons.css. We don’t need to create this file within our package’s static directory because it was provided at the time we created the project. This file is a little too long to replicate within the body of this guide, however it is available online [http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki/src/views/tutorial/static/pylons.css].

This CSS file will be accessed via e.g. http://localhost:6543/static/pylons.css by virtue of the call to add_static_view directive we’ve made in the __init__ file. Any number and type of static assets can be placed in this directory (or subdirectories) and are just referred to by URL or by using the convenience method static_url e.g. request.static_url('{{package}}:static/foo.css') within templates.

Testing the Views

We’ll modify our tests.py file, adding tests for each view function we added above. As a result, we’ll delete the ViewTests test in the file, and add four other test classes: ViewWikiTests, ViewPageTests, AddPageTests, and EditPageTests. These test the view_wiki, view_page, add_page, and edit_page views respectively.

Once we’re done with the tests.py module, it will look a lot like the below:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

import unittest

from pyramid import testing

class PageModelTests(unittest.TestCase):

    def _getTargetClass(self):
        from tutorial.models import Page
        return Page

    def _makeOne(self, data=u'some data'):
        return self._getTargetClass()(data=data)

    def test_constructor(self):
        instance = self._makeOne()
        self.assertEqual(instance.data, u'some data')

class WikiModelTests(unittest.TestCase):

    def _getTargetClass(self):
        from tutorial.models import Wiki
        return Wiki

    def _makeOne(self):
        return self._getTargetClass()()

    def test_it(self):
        wiki = self._makeOne()
        self.assertEqual(wiki.__parent__, None)
        self.assertEqual(wiki.__name__, None)

class AppmakerTests(unittest.TestCase):
    def _callFUT(self, zodb_root):
        from tutorial.models import appmaker
        return appmaker(zodb_root)

    def test_it(self):
        root = {}
        self._callFUT(root)
        self.assertEqual(root['app_root']['FrontPage'].data,
                         'This is the front page')

class ViewWikiTests(unittest.TestCase):
    def test_it(self):
        from tutorial.views import view_wiki
        context = testing.DummyResource()
        request = testing.DummyRequest()
        response = view_wiki(context, request)
        self.assertEqual(response.location, 'http://example.com/FrontPage')

class ViewPageTests(unittest.TestCase):
    def _callFUT(self, context, request):
        from tutorial.views import view_page
        return view_page(context, request)

    def test_it(self):
        wiki = testing.DummyResource()
        wiki['IDoExist'] = testing.DummyResource()
        context = testing.DummyResource(data='Hello CruelWorld IDoExist')
        context.__parent__ = wiki
        context.__name__ = 'thepage'
        request = testing.DummyRequest()
        info = self._callFUT(context, request)
        self.assertEqual(info['page'], context)
        self.assertEqual(
            info['content'],
            '<div class="document">\n'
            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
            'CruelWorld</a> '
            '<a href="http://example.com/IDoExist/">'
            'IDoExist</a>'
            '</p>\n</div>\n')
        self.assertEqual(info['edit_url'],
                         'http://example.com/thepage/edit_page')

class AddPageTests(unittest.TestCase):
    def _callFUT(self, context, request):
        from tutorial.views import add_page
        return add_page(context, request)

    def test_it_notsubmitted(self):
        from pyramid.url import resource_url
        context = testing.DummyResource()
        request = testing.DummyRequest()
        request.subpath = ['AnotherPage']
        info = self._callFUT(context, request)
        self.assertEqual(info['page'].data,'')
        self.assertEqual(
            info['save_url'],
            resource_url(context, request, 'add_page', 'AnotherPage'))

    def test_it_submitted(self):
        context = testing.DummyResource()
        request = testing.DummyRequest({'form.submitted':True,
                                        'body':'Hello yo!'})
        request.subpath = ['AnotherPage']
        self._callFUT(context, request)
        page = context['AnotherPage']
        self.assertEqual(page.data, 'Hello yo!')
        self.assertEqual(page.__name__, 'AnotherPage')
        self.assertEqual(page.__parent__, context)

class EditPageTests(unittest.TestCase):
    def _callFUT(self, context, request):
        from tutorial.views import edit_page
        return edit_page(context, request)

    def test_it_notsubmitted(self):
        from pyramid.url import resource_url
        context = testing.DummyResource()
        request = testing.DummyRequest()
        info = self._callFUT(context, request)
        self.assertEqual(info['page'], context)
        self.assertEqual(info['save_url'],
                         resource_url(context, request, 'edit_page'))

    def test_it_submitted(self):
        context = testing.DummyResource()
        request = testing.DummyRequest({'form.submitted':True,
                                        'body':'Hello yo!'})
        response = self._callFUT(context, request)
        self.assertEqual(response.location, 'http://example.com/')
        self.assertEqual(context.data, 'Hello yo!')

Running the Tests

We can run these tests by using setup.py test in the same way we did in Running the Tests. Assuming our shell’s current working directory is the “tutorial” distribution directory:

On UNIX:

$ ../bin/python setup.py test -q

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q

The expected result looks something like:

.........
----------------------------------------------------------------------
Ran 9 tests in 0.203s

OK

Viewing the Application in a Browser

Once we’ve completed our edits, we can finally examine our application in a browser. The views we’ll try are as follows:

Visiting http://localhost:6543/ in a browser invokes the view_wiki view. This always redirects to the view_page view of the FrontPage Page resource.

Visiting http://localhost:6543/FrontPage/ in a browser invokes the view_page view of the front page resource. This is because it’s the default view (a view without a name) for Page resources.

Visiting http://localhost:6543/FrontPage/edit_page in a browser invokes the edit view for the FrontPage Page resource.

Visiting http://localhost:6543/add_page/SomePageName in a browser invokes the add view for a Page.

To generate an error, visit http://localhost:6543/add_page which will generate an IndexError for the expression request.subpath[0]. You’ll see an interactive traceback facility provided by WebError.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial »

Adding Authorization

Our application currently allows anyone with access to the server to view, edit, and add pages to our wiki. For purposes of demonstration we’ll change our application to allow people whom are members of a group named group:editors to add and edit wiki pages but we’ll continue allowing anyone with access to the server to view pages. Pyramid provides facilities for authorization and authentication. We’ll make use of both features to provide security to our application.

The source code for this tutorial stage can be browsed via http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/authorization/.

Configuring a pyramid Authentication Policy

For any Pyramid application to perform authorization, we need to add a security.py module and we’ll need to change our application registry to add an authentication policy and a authorization policy.

Adding Authentication and Authorization Policies

We’ll change our package’s __init__.py file to enable an AuthTktAuthenticationPolicy and an ACLAuthorizationPolicy to enable declarative security checking. When you’re done, your __init__.py will look like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

from repoze.zodbconn.finder import PersistentApplicationFinder

from pyramid.config import Configurator
from pyramid.authentication import AuthTktAuthenticationPolicy
from pyramid.authorization import ACLAuthorizationPolicy

from tutorial.models import appmaker
from tutorial.security import groupfinder

def main(global_config, **settings):
    """ This function returns a WSGI application.

    It is usually called by the PasteDeploy framework during
    ``paster serve``.
    """
    authn_policy = AuthTktAuthenticationPolicy(secret='sosecret',
                                               callback=groupfinder)
    authz_policy = ACLAuthorizationPolicy()
    zodb_uri = settings.get('zodb_uri')
    if zodb_uri is None:
        raise ValueError("No 'zodb_uri' in application configuration.")

    finder = PersistentApplicationFinder(zodb_uri, appmaker)
    def get_root(request):
        return finder(request.environ)
    config = Configurator(root_factory=get_root, settings=settings,
                          authentication_policy=authn_policy,
                          authorization_policy=authz_policy)
    config.add_static_view('static', 'tutorial:static')
    config.scan('tutorial')
    return config.make_wsgi_app()

Note that the creation of an AuthTktAuthenticationPolicy requires two arguments: secret and callback. secret is a string representing an encryption key used by the “authentication ticket” machinery represented by this policy: it is required. The callback is a reference to a groupfinder function in the tutorial package’s security.py file. We haven’t added that module yet, but we’re about to.

Adding security.py

Add a security.py module within your package (in the same directory as __init__.py, views.py, etc) with the following content:

1
2
3
4
5
6
7

USERS = {'editor':'editor',
          'viewer':'viewer'}
GROUPS = {'editor':['group:editors']}

def groupfinder(userid, request):
    if userid in USERS:
        return GROUPS.get(userid, [])

The groupfinder function defined here is an authorization policy “callback”; it is a callable that accepts a userid and a request. If the userid exists in the set of users known by the system, the callback will return a sequence of group identifiers (or an empty sequence if the user isn’t a member of any groups). If the userid does not exist in the system, the callback will return None. In a production system this data will most often come from a database, but here we use “dummy” data to represent user and groups sources. Note that the editor user is a member of the group:editors group in our dummy group data (the GROUPS data structure).

Adding Login and Logout Views

We’ll add a login view which renders a login form and processes the post from the login form, checking credentials.

We’ll also add a logout view to our application and provide a link to it. This view will clear the credentials of the logged in user and redirect back to the front page.

We’ll add a different file (for presentation convenience) to add login and logout views. Add a file named login.py to your application (in the same directory as views.py) with the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

from pyramid.httpexceptions import HTTPFound

from pyramid.security import remember
from pyramid.security import forget
from pyramid.view import view_config
from pyramid.url import resource_url

from tutorial.security import USERS

@view_config(context='tutorial.models.Wiki', name='login',
             renderer='templates/login.pt')
@view_config(context='pyramid.exceptions.Forbidden',
             renderer='templates/login.pt')
def login(request):
    login_url = resource_url(request.context, request, 'login')
    referrer = request.url
    if referrer == login_url:
        referrer = '/' # never use the login form itself as came_from
    came_from = request.params.get('came_from', referrer)
    message = ''
    login = ''
    password = ''
    if 'form.submitted' in request.params:
        login = request.params['login']
        password = request.params['password']
        if USERS.get(login) == password:
            headers = remember(request, login)
            return HTTPFound(location = came_from,
                             headers = headers)
        message = 'Failed login'

    return dict(
        message = message,
        url = request.application_url + '/login',
        came_from = came_from,
        login = login,
        password = password,
        )

@view_config(context='tutorial.models.Wiki', name='logout')
def logout(request):
    headers = forget(request)
    return HTTPFound(location = resource_url(request.context, request),
                     headers = headers)

Note that the login view callable in the login.py file has two view configuration decorators. The order of these decorators is unimportant. Each just adds a different view configuration for the login view callable.

The first view configuration decorator configures the login view callable so it will be invoked when someone visits /login (when the context is a Wiki and the view name is login). The second decorator (with context of pyramid.exceptions.Forbidden) specifies a forbidden view. This configures our login view to be presented to the user when Pyramid detects that a view invocation can not be authorized. Because we’ve configured a forbidden view, the login view callable will be invoked whenever one of our users tries to execute a view callable that they are not allowed to invoke as determined by the authorization policy in use. In our application, for example, this means that if a user has not logged in, and he tries to add or edit a Wiki page, he will be shown the login form. Before being allowed to continue on to the add or edit form, he will have to provide credentials that give him permission to add or edit via this login form.

Changing Existing Views

Then we need to change each of our view_page, edit_page and add_page views in views.py to pass a “logged in” parameter into its template. We’ll add something like this to each view body:

1
2

from pyramid.security import authenticated_userid
logged_in = authenticated_userid(request)

We’ll then change the return value of each view that has an associated renderer to pass the resulting `logged_in` value to the template. For example:

1
2
3
4

return dict(page = context,
            content = content,
            logged_in = logged_in,
            edit_url = edit_url)

Adding the login.pt Template

Add a login.pt template to your templates directory. It’s referred to within the login view we just added to login.py.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>Login - Pyramid tutorial wiki (based on TurboGears
    20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          <b>Login</b><br/>
          <span tal:replace="message"/>
        </div>
        <div id="right" class="app-welcome align-right"></div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <form action="${url}" method="post">
          <input type="hidden" name="came_from" value="${came_from}"/>
          <input type="text" name="login" value="${login}"/><br/>
          <input type="password" name="password"
                 value="${password}"/><br/>
          <input type="submit" name="form.submitted" value="Log In"/>
        </form>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Change view.pt and edit.pt

We’ll also need to change our edit.pt and view.pt templates to display a “Logout” link if someone is logged in. This link will invoke the logout view.

To do so we’ll add this to both templates within the <div id="right" class="app-welcome align-right"> div:

<span tal:condition="logged_in">
   <a href="${request.application_url}/logout">Logout</a>
</span>

Giving Our Root Resource an ACL

We need to give our root resource object an ACL. This ACL will be sufficient to provide enough information to the Pyramid security machinery to challenge a user who doesn’t have appropriate credentials when he attempts to invoke the add_page or edit_page views.

We need to perform some imports at module scope in our models.py file:

1
2

from pyramid.security import Allow
from pyramid.security import Everyone

Our root resource object is a Wiki instance. We’ll add the following line at class scope to our Wiki class:

1
2

__acl__ = [ (Allow, Everyone, 'view'),
            (Allow, 'group:editors', 'edit') ]

It’s only happenstance that we’re assigning this ACL at class scope. An ACL can be attached to an object instance too; this is how “row level security” can be achieved in Pyramid applications. We actually only need one ACL for the entire system, however, because our security requirements are simple, so this feature is not demonstrated.

Our resulting models.py file will now look like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

from persistent import Persistent
from persistent.mapping import PersistentMapping

from pyramid.security import Allow
from pyramid.security import Everyone

class Wiki(PersistentMapping):
    __name__ = None
    __parent__ = None
    __acl__ = [ (Allow, Everyone, 'view'),
                (Allow, 'group:editors', 'edit') ]

class Page(Persistent):
    def __init__(self, data):
        self.data = data

def appmaker(zodb_root):
    if not 'app_root' in zodb_root:
        app_root = Wiki()
        frontpage = Page('This is the front page')
        app_root['FrontPage'] = frontpage
        frontpage.__name__ = 'FrontPage'
        frontpage.__parent__ = app_root
        zodb_root['app_root'] = app_root
        import transaction
        transaction.commit()
    return zodb_root['app_root']

Adding permission Declarations to our view_config Decorators

To protect each of our views with a particular permission, we need to pass a permission argument to each of our pyramid.view.view_config decorators. To do so, within views.py:

We add permission='view' to the decorator attached to the view_wiki view function. This makes the assertion that only users who possess the view permission against the context resource at the time of the request may invoke this view. We’ve granted pyramid.security.Everyone the view permission at the root model via its ACL, so everyone will be able to invoke the view_wiki view.

We add permission='view' to the decorator attached to the view_page view function. This makes the assertion that only users who possess the effective view permission against the context resource at the time of the request may invoke this view. We’ve granted pyramid.security.Everyone the view permission at the root model via its ACL, so everyone will be able to invoke the view_page view.

We add permission='edit' to the decorator attached to the add_page view function. This makes the assertion that only users who possess the effective edit permission against the context resource at the time of the request may invoke this view. We’ve granted the group:editors principal the edit permission at the root model via its ACL, so only the a user whom is a member of the group named group:editors will able to invoke the add_page view. We’ve likewise given the editor user membership to this group via thes security.py file by mapping him to the group:editors group in the GROUPS data structure (GROUPS = {'editor':['group:editors']}); the groupfinder function consults the GROUPS data structure. This means that the editor user can add pages.

We add permission='edit' to the decorator attached to the edit_page view function. This makes the assertion that only users who possess the effective edit permission against the context resource at the time of the request may invoke this view. We’ve granted the group:editors principal the edit permission at the root model via its ACL, so only the a user whom is a member of the group named group:editors will able to invoke the edit_page view. We’ve likewise given the editor user membership to this group via thes security.py file by mapping him to the group:editors group in the GROUPS data structure (GROUPS = {'editor':['group:editors']}); the groupfinder function consults the GROUPS data structure. This means that the editor user can edit pages.

Viewing the Application in a Browser

We can finally examine our application in a browser. The views we’ll try are as follows:

Visiting http://localhost:6543/ in a browser invokes the view_wiki view. This always redirects to the view_page view of the FrontPage page resource. It is executable by any user.

Visiting http://localhost:6543/FrontPage/ in a browser invokes the view_page view of the FrontPage Page resource. This is because it’s the default view (a view without a name) for Page resources. It is executable by any user.

Visiting http://localhost:6543/FrontPage/edit_page in a browser invokes the edit view for the FrontPage Page resource. It is executable by only the editor user. If a different user (or the anonymous user) invokes it, a login form will be displayed. Supplying the credentials with the username editor, password editor will show the edit page form being displayed.

Visiting http://localhost:6543/add_page/SomePageName in a browser invokes the add view for a page. It is executable by only the editor user. If a different user (or the anonymous user) invokes it, a login form will be displayed. Supplying the credentials with the username editor, password editor will show the edit page form being displayed.

Seeing Our Changes To views.py and our Templates

Our views.py module will look something like this when we’re done:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

from docutils.core import publish_parts
import re

from pyramid.httpexceptions import HTTPFound
from pyramid.url import resource_url
from pyramid.view import view_config
from pyramid.security import authenticated_userid

from tutorial.models import Page

# regular expression used to find WikiWords
wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")

@view_config(context='tutorial.models.Wiki', permission='view')
def view_wiki(context, request):
    return HTTPFound(location=resource_url(context, request, 'FrontPage'))

@view_config(context='tutorial.models.Page',
             renderer='templates/view.pt', permission='view')
def view_page(context, request):
    wiki = context.__parent__

    def check(match):
        word = match.group(1)
        if word in wiki:
            page = wiki[word]
            view_url = resource_url(page, request)
            return '<a href="%s">%s</a>' % (view_url, word)
        else:
            add_url = request.application_url + '/add_page/' + word
            return '<a href="%s">%s</a>' % (add_url, word)

    content = publish_parts(context.data, writer_name='html')['html_body']
    content = wikiwords.sub(check, content)
    edit_url = resource_url(context, request, 'edit_page')

    logged_in = authenticated_userid(request)

    return dict(page = context, content = content, edit_url = edit_url,
                logged_in = logged_in)

@view_config(name='add_page', context='tutorial.models.Wiki',
             renderer='templates/edit.pt',
             permission='edit')
def add_page(context, request):
    name = request.subpath[0]
    if 'form.submitted' in request.params:
        body = request.params['body']
        page = Page(body)
        page.__name__ = name
        page.__parent__ = context
        context[name] = page
        return HTTPFound(location = resource_url(page, request))
    save_url = resource_url(context, request, 'add_page', name)
    page = Page('')
    page.__name__ = name
    page.__parent__ = context

    logged_in = authenticated_userid(request)

    return dict(page = page, save_url = save_url, logged_in = logged_in)

@view_config(name='edit_page', context='tutorial.models.Page',
             renderer='templates/edit.pt',
             permission='edit')
def edit_page(context, request):
    if 'form.submitted' in request.params:
        context.data = request.params['body']
        return HTTPFound(location = resource_url(context, request))

    logged_in = authenticated_userid(request)

    return dict(page = context,
                save_url = resource_url(context, request, 'edit_page'),
                logged_in = logged_in)

Our edit.pt template will look something like this when we’re done:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.__name__} - Pyramid tutorial wiki (based on
      TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Editing <b><span tal:replace="page.__name__">Page Name
            Goes Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right">
          <span tal:condition="logged_in">
              <a href="${request.application_url}/logout">Logout</a>
          </span>
        </div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <form action="${save_url}" method="post">
          <textarea name="body" tal:content="page.data" rows="10"
                    cols="60"/><br/>
          <input type="submit" name="form.submitted" value="Save"/>
        </form>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Our view.pt template will look something like this when we’re done:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.__name__} - Pyramid tutorial wiki (based on
    TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Viewing <b><span tal:replace="page.__name__">Page Name
            Goes Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right">
          <span tal:condition="logged_in">
            <a href="${request.application_url}/logout">Logout</a>
          </span>
        </div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <div tal:replace="structure content">
          Page text goes here.
        </div>
        <p>
          <a tal:attributes="href edit_url" href="">
            Edit this page
          </a>
        </p>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Revisiting the Application

When we revisit the application in a browser, and log in (as a result of hitting an edit or add page and submitting the login form with the editor credentials), we’ll see a Logout link in the upper right hand corner. When we click it, we’re logged out, and redirected back to the front page.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

ZODB + Traversal Wiki Tutorial »

Distributing Your Application

Once your application works properly, you can create a “tarball” from it by using the setup.py sdist command. The following commands assume your current working directory is the tutorial package we’ve created and that the parent directory of the tutorial package is a virtualenv representing a Pyramid environment.

On UNIX:

$ ../bin/python setup.py sdist

On Windows:

c:\pyramidtut> ..\Scripts\python setup.py sdist

The output of such a command will be something like:

running sdist
# .. more output ..
creating dist
tar -cf dist/tutorial-0.1.tar tutorial-0.1
gzip -f9 dist/tutorial-0.1.tar
removing 'tutorial-0.1' (and everything under it)

Note that this command creates a tarball in the “dist” subdirectory named tutorial-0.1.tar.gz. You can send this file to your friends to show them your cool new application. They should be able to install it by pointing the easy_install command directly at it. Or you can upload it to PyPI [http://pypi.python.org] and share it with the rest of the world, where it can be downloaded via easy_install remotely like any other package people download from PyPI.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial

This tutorial introduces a SQLAlchemy and url dispatch -based Pyramid application to a developer familiar with Python, and will be most familiar to developers who have used the Pylons 1.X web framework. When the tutorial is finished, the developer will have created a basic Wiki application with authentication.

For cut and paste purposes, the source code for all stages of this tutorial can be browsed at http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/.

Background

Installation

Preparation

Making a Project

Installing the Project in “Development Mode”

Running the Tests

Starting the Application

Exposing Test Coverage Information

Visit the Application in a Browser

Decisions the pyramid_routesalchemy Template Has Made For You

Basic Layout

App Startup with __init__.py

Content Models with models.py

Defining the Domain Model

Making Edits to models.py

Looking at the Result of Our Edits to models.py

Viewing the Application in a Browser

Defining Views

Declaring Dependencies in Our setup.py File

Adding View Functions

Viewing the Result of Our Edits to views.py

Adding Templates

Mapping Views to URLs in __init__.py

Viewing the Application in a Browser

Adding Tests

Adding Authorization

Changing __init__.py For Authorization

Viewing the Application in a Browser

Seeing Our Changes To views.py and our Templates

Revisiting the Application

Distributing Your Application

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial »

Background

This tutorial presents a Pyramid application that uses technologies which will be familiar to someone with Pylons experience. It uses SQLAlchemy as a persistence mechanism and url dispatch to map URLs to code. It can also be followed by people without any prior Python web framework experience.

To code along with this tutorial, the developer will need a UNIX machine with development tools (Mac OS X with XCode, any Linux or BSD variant, etc) or he will need a Windows system of any kind.

This tutorial is targeted at Pyramid version 1.0.

Have fun!

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial »

Installation

For the most part, the installation process for this tutorial duplicates the steps described in Installing Pyramid and Creating a Pyramid Project, however it also explains how to install additional libraries for tutorial purposes.

Preparation

Please take the following steps to prepare for the tutorial. The steps are slightly different depending on whether you’re using UNIX or Windows.

Preparation, UNIX

Install SQLite3 and its development packages if you don’t already have them installed. Usually this is via your system’s package manager. For example, on a Debian Linux system, do sudo apt-get install libsqlite3-dev.

If you don’t already have a Python 2.6 interpreter installed on your system, obtain, install, or find Python 2.6 [http://www.python.org/download/releases/2.6.6/] for your system.

Install the latest setuptools into the Python you obtained/installed/found in the step above: download ez_setup.py [http://peak.telecommunity.com/dist/ez_setup.py] and run it using the python interpreter of your Python 2.6 installation:

$ /path/to/my/Python-2.6/bin/python ez_setup.py

Use that Python’s bin/easy_install to install virtualenv:

$ /path/to/my/Python-2.6/bin/easy_install virtualenv

Use that Python’s virtualenv to make a workspace:

$ path/to/my/Python-2.6/bin/virtualenv --no-site-packages pyramidtut

Switch to the pyramidtut directory:

$ cd pyramidtut

(Optional) Consider using source bin/activate to make your shell environment wired to use the virtualenv.

Use easy_install to get Pyramid and its direct dependencies installed:

$ bin/easy_install pyramid

Use easy_install to install various packages from PyPI.

$ bin/easy_install docutils nose coverage zope.sqlalchemy \
          SQLAlchemy repoze.tm2

Preparation, Windows

Install, or find Python 2.6.6 [http://python.org/download/releases/2.6.6/] for your system.

Install the latest setuptools into the Python you obtained/installed/found in the step above: download ez_setup.py [http://peak.telecommunity.com/dist/ez_setup.py] and run it using the python interpreter of your Python 2.6 installation using a command prompt:

c:\> c:\Python26\python ez_setup.py

Use that Python’s bin/easy_install to install virtualenv:

c:\> c:\Python26\Scripts\easy_install virtualenv

Use that Python’s virtualenv to make a workspace:

c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut

Switch to the pyramidtut directory:

c:\> cd pyramidtut

(Optional) Consider using bin\activate.bat to make your shell environment wired to use the virtualenv.

Use easy_install to get Pyramid and its direct dependencies installed:

c:\pyramidtut> Scripts\easy_install pyramid

Use easy_install to install various packages from PyPI.

c:\pyramidtut> Scripts\easy_install -i docutils \
         nose coverage zope.sqlalchemy SQLAlchemy repoze.tm2

Making a Project

Your next step is to create a project. Pyramid supplies a variety of templates to generate sample projects. We will use the pyramid_routesalchemy template, which generates an application that uses SQLAlchemy and URL dispatch.

The below instructions assume your current working directory is the “virtualenv” named “pyramidtut”.

On UNIX:

$ bin/paster create -t pyramid_routesalchemy tutorial

On Windows:

c:\pyramidtut> Scripts\paster create -t pyramid_routesalchemy tutorial

Note

If you are using Windows, the pyramid_routesalchemy Paster template may not deal gracefully with installation into a location that contains spaces in the path. If you experience startup problems, try putting both the virtualenv and the project into directories that do not contain spaces in their paths.

Installing the Project in “Development Mode”

In order to do development on the project easily, you must “register” the project as a development egg in your workspace using the setup.py develop command. In order to do so, cd to the “tutorial” directory you created in Making a Project, and run the “setup.py develop” command using virtualenv Python interpreter.

On UNIX:

$ cd tutorial
$ ../bin/python setup.py develop

On Windows:

c:\pyramidtut> cd tutorial
c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop

Running the Tests

After you’ve installed the project in development mode, you may run the tests for the project.

On UNIX:

$ ../bin/python setup.py test -q

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q

Starting the Application

Start the application.

On UNIX:

$ ../bin/paster serve development.ini --reload

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\paster serve development.ini --reload

Exposing Test Coverage Information

You can run the nosetests command to see test coverage information. This runs the tests in the same way that setup.py test does but provides additional “coverage” information, exposing which lines of your project are “covered” (or not covered) by the tests.

To get this functionality working, we’ll need to install a couple of other packages into our virtualenv: nose and coverage:

On UNIX:

$ ../bin/easy_install nose coverage

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\easy_install nose coverage

Once nose and coverage are installed, we can actually run the coverage tests.

On UNIX:

$ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage

On Windows:

c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
      --cover-erase --with-coverage

Looks like our package’s models module doesn’t quite have 100% test coverage.

Visit the Application in a Browser

In a browser, visit http://localhost:6543/. You will see the generated application’s default page.

Decisions the pyramid_routesalchemy Template Has Made For You

Creating a project using the pyramid_routesalchemy template makes the following assumptions:

you are willing to use SQLAlchemy as a database access tool

you are willing to use url dispatch to map URLs to code.

you want to configure your application imperatively (no declarative configuration such as ZCML).

Note

Pyramid supports any persistent storage mechanism (e.g. object database or filesystem files, etc). It also supports an additional mechanism to map URLs to code (traversal). However, for the purposes of this tutorial, we’ll only be using url dispatch and SQLAlchemy.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial »

Basic Layout

The starter files generated by the pyramid_routesalchemy template are basic, but they provide a good orientation for the high-level patterns common to most url dispatch -based Pyramid projects.

The source code for this tutorial stage can be browsed at http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/.

App Startup with __init__.py

A directory on disk can be turned into a Python package by containing an __init__.py file. Even if empty, this marks a directory as a Python package. We use __init__.py both as a package marker and to contain configuration code.

The generated development.ini file is read by paster which looks for the application module in the use variable of the app:tutorial section. The entry point is defined in the Setuptools configuration of this module, specifically in the setup.py file. For this tutorial, the entry point is defined as tutorial:main and points to the following main function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from pyramid.config import Configurator
from sqlalchemy import engine_from_config

from tutorial.models import initialize_sql

def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    engine = engine_from_config(settings, 'sqlalchemy.')
    initialize_sql(engine)
    config = Configurator(settings=settings)
    config.add_static_view('static', 'tutorial:static')
    config.add_route('home', '/', view='tutorial.views.my_view',
                     view_renderer='templates/mytemplate.pt')
    return config.make_wsgi_app()

Lines 1-4. Imports to support later code.

Line 9. Create a SQLAlchemy database engine from the sqlalchemy. prefixed settings in the development.ini file’s [app:tutorial] section. This will be a URI (something like sqlite://).

Line 10. We initialize our SQL database using SQLAlchemy, passing it the engine

Line 11. We construct a Configurator. settings is passed as a keyword argument with the dictionary values passed by PasteDeploy as the settings argument. This will be a dictionary of settings parsed by PasteDeploy, which contains deployment-related values such as reload_templates, db_string, etc.

Line 12. We call pyramid.config.Configurator.add_static_view() with the arguments static (the name), and tutorial:static (the path). This registers a static resource view which will match any URL that starts with /static/. This will serve up static resources for us from within the static directory of our tutorial package, in this case, via http://localhost:6543/static/ and below. With this declaration, we’re saying that any URL that starts with /static should go to the static view; any remainder of its path (e.g. the /foo in /static/foo) will be used to compose a path to a static file resource, such as a CSS file.

Lines 13-14. Register a route configuration via the pyramid.config.Configurator.add_route() method that will be used when the URL is /. Since this route has a pattern equalling / it is the “default” route. The argument named view with the value tutorial.views.my_view is the dotted name to a function we write (generated by the pyramid_routesalchemy template) that is given a request object and which returns a response or a dictionary. You will use pyramid.config.Configurator.add_route() statements in a URL dispatch based application to map URLs to code. This route also names a view_renderer, which is a template which lives in the templates subdirectory of the package. When the tutorial.views.my_view view returns a dictionary, a renderer will use this template to create a response.

Line 15. We use the pyramid.config.Configurator.make_wsgi_app() method to return a WSGI application.

Content Models with models.py

In a SQLAlchemy-based application, a model object is an object composed by querying the SQL database which backs an application. SQLAlchemy is an “object relational mapper” (an ORM). The models.py file is where the pyramid_routesalchemy Paster template put the classes that implement our models.

Here is the source for models.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

import transaction

from sqlalchemy import Column
from sqlalchemy import Integer
from sqlalchemy import Unicode

from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.declarative import declarative_base

from sqlalchemy.orm import scoped_session
from sqlalchemy.orm import sessionmaker

from zope.sqlalchemy import ZopeTransactionExtension

DBSession = scoped_session(sessionmaker(
                             extension=ZopeTransactionExtension()))
Base = declarative_base()

class MyModel(Base):
    __tablename__ = 'models'
    id = Column(Integer, primary_key=True)
    name = Column(Unicode(255), unique=True)
    value = Column(Integer)

    def __init__(self, name, value):
        self.name = name
        self.value = value

def populate():
    session = DBSession()
    model = MyModel(name=u'root',value=55)
    session.add(model)
    session.flush()
    transaction.commit()

def initialize_sql(engine):
    DBSession.configure(bind=engine)
    Base.metadata.bind = engine
    Base.metadata.create_all(engine)
    try:
        populate()
    except IntegrityError:
        pass

Lines 1-13. Imports to support later code.

Line 15. We set up a SQLAlchemy “DBSession” object here. We specify that we’d like to use the “ZopeTransactionExtension”. This extension is an extension which allows us to use a transaction manager instead of controlling commits and aborts to database operations by hand.

Line 16. We create a declarative Base object to use as a base class for our model.

Lines 18-26. A model class named MyModel. It has an __init__ that takes a two arguments (name, and value). It stores these values as self.name and self.value within the __init__ function itself. The MyModel class also has a __tablename__ attribute. This informs SQLAlchemy which table to use to store the data representing instances of this class.

Lines 28-33. A function named populate which adds a single model instance into our SQL storage and commits a transaction.

Lines 35-42. A function named initialize_sql which receives a SQL database engine and binds it to our SQLAlchemy DBSession object. It also calls the populate function, to do initial database population.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial »

Defining the Domain Model

The first change we’ll make to our stock paster-generated application will be to define a domain model constructor representing a wiki page. We’ll do this inside our models.py file.

The source code for this tutorial stage can be browsed at http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/models/.

Making Edits to models.py

Note

There is nothing automagically special about the filename models.py. A project may have many models throughout its codebase in arbitrarily-named files. Files implementing models often have model in their filenames (or they may live in a Python subpackage of your application package named models) , but this is only by convention.

The first thing we want to do is remove the stock MyModel class from the generated models.py file. The MyModel class is only a sample and we’re not going to use it.

Then, we’ll add a Page class. Because this is a SQLAlchemy application, this class should inherit from an instance of sqlalchemy.ext.declarative.declarative_base. Declarative SQLAlchemy models are easier to use than directly-mapped ones.

Our Page class will have a class level attribute __tablename__ which equals the string pages. This means that SQLAlchemy will store our wiki data in a SQL table named pages. Our Page class will also have class-level attributes named id, pagename and data (all instances of sqlalchemy.Column). These will map to columns in the pages table. The id attribute will be the primary key in the table. The name attribute will be a text attribute, each value of which needs to be unique within the column. The data attribute is a text attribute that will hold the body of each page.

We’ll also remove our populate function. We’ll inline the populate step into initialize_sql, changing our initialize_sql function to add a FrontPage object to our database at startup time. We’re also going to use slightly different binding syntax. It will will otherwise largely be the same as the initialize_sql in the paster-generated models.py.

Our DBSession assignment stays the same as the original generated models.py.

Looking at the Result of Our Edits to models.py

The result of all of our edits to models.py will end up looking something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

import transaction

from sqlalchemy import Column
from sqlalchemy import Integer
from sqlalchemy import Text

from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.declarative import declarative_base

from sqlalchemy.orm import scoped_session
from sqlalchemy.orm import sessionmaker

from zope.sqlalchemy import ZopeTransactionExtension

DBSession = scoped_session(sessionmaker(
                             extension=ZopeTransactionExtension()))
Base = declarative_base()

class Page(Base):
    """ The SQLAlchemy declarative model class for a Page object. """
    __tablename__ = 'pages'
    id = Column(Integer, primary_key=True)
    name = Column(Text, unique=True)
    data = Column(Text)

    def __init__(self, name, data):
       self.name = name
       self.data = data

def initialize_sql(engine):
    DBSession.configure(bind=engine)
    Base.metadata.bind = engine
    Base.metadata.create_all(engine)
    try:
        session = DBSession()
        page = Page('FrontPage', 'initial data')
        session.add(page)
        transaction.commit()
    except IntegrityError:
        # already created
        pass

Viewing the Application in a Browser

We can’t. At this point, our system is in a “non-runnable” state; we’ll need to change view-related files in the next chapter to be able to start the application successfully. If you try to start the application, you’ll wind up with a Python traceback on your console that ends with this exception:

ImportError: cannot import name MyModel

This will also happen if you attempt to run the tests.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial »

Defining Views

A view callable in a url dispatch -based Pyramid application is typically a simple Python function that accepts a single parameter named request. A view callable is assumed to return a response object.

Note

A Pyramid view can also be defined as callable which accepts two arguments: a context and a request. You’ll see this two-argument pattern used in other Pyramid tutorials and applications. Either calling convention will work in any Pyramid application; the calling conventions can be used interchangeably as necessary. In url dispatch based applications, however, the context object is rarely used in the view body itself, so within this tutorial we define views as callables that accept only a request to avoid the visual “noise”. If you do need the context within a view function that only takes the request as a single argument, you can obtain it via request.context.

The request passed to every view that is called as the result of a route match has an attribute named matchdict that contains the elements placed into the URL by the pattern of a route statement. For instance, if a call to pyramid.config.Configurator.add_route() in __init__.py had the pattern {one}/{two}, and the URL at http://example.com/foo/bar was invoked, matching this pattern, the matchdict dictionary attached to the request passed to the view would have a one key with the value foo and a two key with the value bar.

The source code for this tutorial stage can be browsed at http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/views/.

Declaring Dependencies in Our setup.py File

The view code in our application will depend on a package which is not a dependency of the original “tutorial” application. The original “tutorial” application was generated by the paster create command; it doesn’t know about our custom application requirements. We need to add a dependency on the docutils package to our tutorial package’s setup.py file by assigning this dependency to the install_requires parameter in the setup function.

Our resulting setup.py should look like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

import os
import sys

from setuptools import setup, find_packages

here = os.path.abspath(os.path.dirname(__file__))
README = open(os.path.join(here, 'README.txt')).read()
CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()

requires = [
    'pyramid',
    'SQLAlchemy',
    'transaction',
    'repoze.tm2>=1.0b1', # default_commit_veto
    'zope.sqlalchemy',
    'WebError',
    'docutils',
    ]

if sys.version_info[:3] < (2,5,0):
    requires.append('pysqlite')

setup(name='tutorial',
      version='0.0',
      description='tutorial',
      long_description=README + '\n\n' +  CHANGES,
      classifiers=[
        "Programming Language :: Python",
        "Framework :: Pylons",
        "Topic :: Internet :: WWW/HTTP",
        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
        ],
      author='',
      author_email='',
      url='',
      keywords='web wsgi bfg pylons pyramid',
      packages=find_packages(),
      include_package_data=True,
      zip_safe=False,
      test_suite='tutorial',
      install_requires = requires,
      entry_points = """\
      [paste.app_factory]
      main = tutorial:main
      """,
      paster_plugins=['pyramid'],
      )

Note

After these new dependencies are added, you will need to rerun python setup.py develop inside the root of the tutorial package to obtain and register the newly added dependency package.

Adding View Functions

We’ll get rid of our my_view view function in our views.py file. It’s only an example and isn’t relevant to our application.

Then we’re going to add four view callable functions to our views.py module. One view callable (named view_wiki) will display the wiki itself (it will answer on the root URL), another named view_page will display an individual page, another named add_page will allow a page to be added, and a final view callable named edit_page will allow a page to be edited. We’ll describe each one briefly and show the resulting views.py file afterward.

Note

There is nothing special about the filename views.py. A project may have many view callables throughout its codebase in arbitrarily-named files. Files implementing view callables often have view in their filenames (or may live in a Python subpackage of your application package named views), but this is only by convention.

The view_wiki view function

The view_wiki function will respond as the default view of a Wiki model object. It always redirects to a URL which represents the path to our “FrontPage”. It returns an instance of the pyramid.httpexceptions.HTTPFound class (instances of which implement the WebOb response interface), It will use the pyramid.url.route_url() API to construct a URL to the FrontPage page (e.g. http://localhost:6543/FrontPage), and will use it as the “location” of the HTTPFound response, forming an HTTP redirect.

The view_page view function

The view_page function will respond as the default view of a Page object. The view_page function renders the ReStructuredText body of a page (stored as the data attribute of a Page object) as HTML. Then it substitutes an HTML anchor for each WikiWord reference in the rendered HTML using a compiled regular expression.

The curried function named check is used as the first argument to wikiwords.sub, indicating that it should be called to provide a value for each WikiWord match found in the content. If the wiki already contains a page with the matched WikiWord name, the check function generates a view link to be used as the substitution value and returns it. If the wiki does not already contain a page with with the matched WikiWord name, the function generates an “add” link as the substitution value and returns it.

As a result, the content variable is now a fully formed bit of HTML containing various view and add links for WikiWords based on the content of our current page object.

We then generate an edit URL (because it’s easier to do here than in the template), and we return a dictionary with a number of arguments. The fact that this view returns a dictionary (as opposed to a response object) is a cue to Pyramid that it should try to use a renderer associated with the view configuration to render a template. In our case, the template which will be rendered will be the templates/view.pt template, as per the configuration put into effect in __init__.py.

The add_page view function

The add_page function will be invoked when a user clicks on a WikiWord which isn’t yet represented as a page in the system. The check function within the view_page view generates URLs to this view. It also acts as a handler for the form that is generated when we want to add a page object. The matchdict attribute of the request passed to the add_page view will have the values we need to construct URLs and find model objects.

The matchdict will have a pagename key that matches the name of the page we’d like to add. If our add view is invoked via, e.g. http://localhost:6543/add_page/SomeName, the pagename value in the matchdict will be SomeName.

If the view execution is not a result of a form submission (if the expression 'form.submitted' in request.params is False), the view callable renders a template. To do so, it generates a “save url” which the template use as the form post URL during rendering. We’re lazy here, so we’re trying to use the same template (templates/edit.pt) for the add view as well as the page edit view, so we create a dummy Page object in order to satisfy the edit form’s desire to have some page object exposed as page, and Pyramid will render the template associated with this view to a response.

If the view execution is a result of a form submission (if the expression 'form.submitted' in request.params is True), we scrape the page body from the form data, create a Page object using the name in the matchdict pagename, and obtain the page body from the request, and save it into the database using session.add. We then redirect back to the view_page view (the default view for a Page) for the newly created page.

The edit_page view function

The edit_page function will be invoked when a user clicks the “Edit this Page” button on the view form. It renders an edit form but it also acts as the handler for the form it renders. The matchdict attribute of the request passed to the add_page view will have a pagename key matching the name of the page the user wants to edit.

If the view execution is not a result of a form submission (if the expression 'form.submitted' in request.params is False), the view simply renders the edit form, passing the request, the page object, and a save_url which will be used as the action of the generated form.

If the view execution is a result of a form submission (if the expression 'form.submitted' in request.params is True), the view grabs the body element of the request parameter and sets it as the data key in the matchdict. It then redirects to the default view of the wiki page, which will always be the view_page view.

Viewing the Result of Our Edits to views.py

The result of all of our edits to views.py will leave it looking like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

import re

from docutils.core import publish_parts

from pyramid.httpexceptions import HTTPFound
from pyramid.url import route_url

from tutorial.models import DBSession
from tutorial.models import Page

# regular expression used to find WikiWords
wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")

def view_wiki(request):
    return HTTPFound(location = route_url('view_page', request,
                                          pagename='FrontPage'))

def view_page(request):
    matchdict = request.matchdict
    session = DBSession()
    page = session.query(Page).filter_by(name=matchdict['pagename']).one()

    def check(match):
        word = match.group(1)
        exists = session.query(Page).filter_by(name=word).all()
        if exists:
            view_url = route_url('view_page', request, pagename=word)
            return '<a href="%s">%s</a>' % (view_url, word)
        else:
            add_url = route_url('add_page', request, pagename=word)
            return '<a href="%s">%s</a>' % (add_url, word)

    content = publish_parts(page.data, writer_name='html')['html_body']
    content = wikiwords.sub(check, content)
    edit_url = route_url('edit_page', request,
                         pagename=matchdict['pagename'])
    return dict(page=page, content=content, edit_url=edit_url)

def add_page(request):
    name = request.matchdict['pagename']
    if 'form.submitted' in request.params:
        session = DBSession()
        body = request.params['body']
        page = Page(name, body)
        session.add(page)
        return HTTPFound(location = route_url('view_page', request,
                                              pagename=name))
    save_url = route_url('add_page', request, pagename=name)
    page = Page('', '')
    return dict(page=page, save_url=save_url)

def edit_page(request):
    name = request.matchdict['pagename']
    session = DBSession()
    page = session.query(Page).filter_by(name=name).one()
    if 'form.submitted' in request.params:
        page.data = request.params['body']
        session.add(page)
        return HTTPFound(location = route_url('view_page', request,
                                              pagename=name))
    return dict(
        page=page,
        save_url = route_url('edit_page', request, pagename=name),
        )

Adding Templates

The views we’ve added all reference a template. Each template is a Chameleon ZPT template. These templates will live in the templates directory of our tutorial package.

The view.pt Template

The view.pt template is used for viewing a single wiki page. It is used by the view_page view function. It should have a div that is “structure replaced” with the content value provided by the view. It should also have a link on the rendered page that points at the “edit” URL (the URL which invokes the edit_page view for the page being viewed).

Once we’re done with the view.pt template, it will look a lot like the below:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.name} - Pyramid tutorial wiki (based on
    TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Viewing <b><span tal:replace="page.name">Page Name
              Goes Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right"></div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <div tal:replace="structure content">
          Page text goes here.
        </div>
        <p>
          <a tal:attributes="href edit_url" href="">
            Edit this page
          </a>
        </p>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Note

The names available for our use in a template are always those that are present in the dictionary returned by the view callable. But our templates make use of a request object that none of our tutorial views return in their dictionary. This value appears as if “by magic”. However, request is one of several names that are available “by default” in a template when a template renderer is used. See *.pt or *.txt: Chameleon Template Renderers for more information about other names that are available by default in a template when a Chameleon template is used as a renderer.

The edit.pt Template

The edit.pt template is used for adding and editing a wiki page. It is used by the add_page and edit_page view functions. It should display a page containing a form that POSTs back to the “save_url” argument supplied by the view. The form should have a “body” textarea field (the page data), and a submit button that has the name “form.submitted”. The textarea in the form should be filled with any existing page data when it is rendered.

Once we’re done with the edit.pt template, it will look a lot like the below:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.name} - Pyramid tutorial wiki (based on
    TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Editing <b><span tal:replace="page.name">Page Name Goes
            Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right"></div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <form action="${save_url}" method="post">
          <textarea name="body" tal:content="page.data" rows="10"
                    cols="60"/><br/>
          <input type="submit" name="form.submitted" value="Save"/>
        </form>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Static Assets

Our templates name a single static asset named pylons.css. We don’t need to create this file within our package’s static directory because it was provided at the time we created the project. This file is a little too long to replicate within the body of this guide, however it is available online [http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css].

This CSS file will be accessed via e.g. http://localhost:6543/static/pylons.css by virtue of the call to add_static_view directive we’ve made in the __init__ file. Any number and type of static assets can be placed in this directory (or subdirectories) and are just referred to by URL or by using the convenience method static_url e.g. request.static_url('{{package}}:static/foo.css') within templates.

Mapping Views to URLs in __init__.py

The __init__.py file contains pyramid.config.Configurator.add_route() calls which serve to map URLs via url dispatch to view functions. First, we’ll get rid of the existing route created by the template using the name home. It’s only an example and isn’t relevant to our application.

We then need to add four calls to add_route. Note that the ordering of these declarations is very important. route declarations are matched in the order they’re found in the __init__.py file.

Add a declaration which maps the pattern / (signifying the root URL) to the view named view_wiki in our views.py file with the name view_wiki. This is the default view for the wiki.

Add a declaration which maps the pattern /{pagename} to the view named view_page in our views.py file with the view name view_page. This is the regular view for a page.

Add a declaration which maps the pattern /add_page/{pagename} to the view named add_page in our views.py file with the name add_page. This is the add view for a new page.

Add a declaration which maps the pattern /{pagename}/edit_page to the view named edit_page in our views.py file with the name edit_page. This is the edit view for a page.

As a result of our edits, the __init__.py file should look something like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

from pyramid.config import Configurator
from sqlalchemy import engine_from_config

from tutorial.models import initialize_sql

def main(global_config, **settings):
    """ This function returns a WSGI application.
    """
    engine = engine_from_config(settings, 'sqlalchemy.')
    initialize_sql(engine)
    config = Configurator(settings=settings)
    config.add_static_view('static', 'tutorial:static')
    config.add_route('view_wiki', '/', view='tutorial.views.view_wiki')
    config.add_route('view_page', '/{pagename}',
                     view='tutorial.views.view_page',
                     view_renderer='tutorial:templates/view.pt')
    config.add_route('add_page', '/add_page/{pagename}',
                     view='tutorial.views.add_page',
                     view_renderer='tutorial:templates/edit.pt')
    config.add_route('edit_page', '/{pagename}/edit_page',
                     view='tutorial.views.edit_page',
                     view_renderer='tutorial:templates/edit.pt')
    return config.make_wsgi_app()

Viewing the Application in a Browser

We can finally examine our application in a browser. The views we’ll try are as follows:

Visiting http://localhost:6543 in a browser invokes the view_wiki view. This always redirects to the view_page view of the FrontPage page object.

Visiting http://localhost:6543/FrontPage in a browser invokes the view_page view of the front page page object.

Visiting http://localhost:6543/FrontPage/edit_page in a browser invokes the edit view for the front page object.

Visiting http://localhost:6543/add_page/SomePageName in a browser invokes the add view for a page.

Try generating an error within the body of a view by adding code to the top of it that generates an exception (e.g. raise Exception('Forced Exception')). Then visit the error-raising view in a browser. You should see an interactive exception handler in the browser which allows you to examine values in a post-mortem mode.

Adding Tests

Since we’ve added a good bit of imperative code here, it’s useful to define tests for the views we’ve created. We’ll change our tests.py module to look like this:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

import unittest

from pyramid import testing

def _initTestingDB():
    from tutorial.models import DBSession
    from tutorial.models import Base
    from sqlalchemy import create_engine
    engine = create_engine('sqlite://')
    DBSession.configure(bind=engine)
    Base.metadata.bind = engine
    Base.metadata.create_all(engine)
    return DBSession

def _registerRoutes(config):
    config.add_route('view_page', '{pagename}')
    config.add_route('edit_page', '{pagename}/edit_page')
    config.add_route('add_page', 'add_page/{pagename}')

class ViewWikiTests(unittest.TestCase):
    def setUp(self):
        self.config = testing.setUp()

    def tearDown(self):
        testing.tearDown()

    def test_it(self):
        from tutorial.views import view_wiki
        self.config.add_route('view_page', '{pagename}')
        request = testing.DummyRequest()
        response = view_wiki(request)
        self.assertEqual(response.location, 'http://example.com/FrontPage')

class ViewPageTests(unittest.TestCase):
    def setUp(self):
        self.session = _initTestingDB()
        self.config = testing.setUp()

    def tearDown(self):
        self.session.remove()
        testing.tearDown()

    def _callFUT(self, request):
        from tutorial.views import view_page
        return view_page(request)

    def test_it(self):
        from tutorial.models import Page
        request = testing.DummyRequest()
        request.matchdict['pagename'] = 'IDoExist'
        page = Page('IDoExist', 'Hello CruelWorld IDoExist')
        self.session.add(page)
        _registerRoutes(self.config)
        info = self._callFUT(request)
        self.assertEqual(info['page'], page)
        self.assertEqual(
            info['content'],
            '<div class="document">\n'
            '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
            'CruelWorld</a> '
            '<a href="http://example.com/IDoExist">'
            'IDoExist</a>'
            '</p>\n</div>\n')
        self.assertEqual(info['edit_url'],
                         'http://example.com/IDoExist/edit_page')

class AddPageTests(unittest.TestCase):
    def setUp(self):
        self.session = _initTestingDB()
        self.config = testing.setUp()
        self.config.begin()

    def tearDown(self):
        self.session.remove()
        testing.tearDown()

    def _callFUT(self, request):
        from tutorial.views import add_page
        return add_page(request)

    def test_it_notsubmitted(self):
        _registerRoutes(self.config)
        request = testing.DummyRequest()
        request.matchdict = {'pagename':'AnotherPage'}
        info = self._callFUT(request)
        self.assertEqual(info['page'].data,'')
        self.assertEqual(info['save_url'],
                         'http://example.com/add_page/AnotherPage')

    def test_it_submitted(self):
        from tutorial.models import Page
        _registerRoutes(self.config)
        request = testing.DummyRequest({'form.submitted':True,
                                        'body':'Hello yo!'})
        request.matchdict = {'pagename':'AnotherPage'}
        self._callFUT(request)
        page = self.session.query(Page).filter_by(name='AnotherPage').one()
        self.assertEqual(page.data, 'Hello yo!')

class EditPageTests(unittest.TestCase):
    def setUp(self):
        self.session = _initTestingDB()
        self.config = testing.setUp()

    def tearDown(self):
        self.session.remove()
        testing.tearDown()

    def _callFUT(self, request):
        from tutorial.views import edit_page
        return edit_page(request)

    def test_it_notsubmitted(self):
        from tutorial.models import Page
        _registerRoutes(self.config)
        request = testing.DummyRequest()
        request.matchdict = {'pagename':'abc'}
        page = Page('abc', 'hello')
        self.session.add(page)
        info = self._callFUT(request)
        self.assertEqual(info['page'], page)
        self.assertEqual(info['save_url'],
                         'http://example.com/abc/edit_page')

    def test_it_submitted(self):
        from tutorial.models import Page
        _registerRoutes(self.config)
        request = testing.DummyRequest({'form.submitted':True,
                                        'body':'Hello yo!'})
        request.matchdict = {'pagename':'abc'}
        page = Page('abc', 'hello')
        self.session.add(page)
        response = self._callFUT(request)
        self.assertEqual(response.location, 'http://example.com/abc')
        self.assertEqual(page.data, 'Hello yo!')

We can then run the tests using something like:

1

 $ python setup.py test -q

The expected output is something like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

running test
running egg_info
writing requirements to tutorial.egg-info/requires.txt
writing tutorial.egg-info/PKG-INFO
writing top-level names to tutorial.egg-info/top_level.txt
writing dependency_links to tutorial.egg-info/dependency_links.txt
writing entry points to tutorial.egg-info/entry_points.txt
unrecognized .svn/entries format in
reading manifest file 'tutorial.egg-info/SOURCES.txt'
writing manifest file 'tutorial.egg-info/SOURCES.txt'
running build_ext
......
----------------------------------------------------------------------
Ran 6 tests in 0.181s

OK

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial »

Adding Authorization

Our application currently allows anyone with access to the server to view, edit, and add pages to our wiki. For purposes of demonstration we’ll change our application to allow only people whom possess a specific username (editor) to add and edit wiki pages but we’ll continue allowing anyone with access to the server to view pages. Pyramid provides facilities for authorization and authentication. We’ll make use of both features to provide security to our application.

The source code for this tutorial stage can be browsed at http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/.

Changing __init__.py For Authorization

We’re going to be making several changes to our __init__.py file which will help us configure an authorization policy.

Adding A Root Factory

We’re going to start to use a custom root factory within our __init__.py file. The objects generated by the root factory will be used as the context of each request to our application. In order for Pyramid declarative security to work properly, the context object generated during a request must be decorated with security declarations; when we begin to use a custom root factory to generate our contexts, we can begin to make use of the declarative security features of Pyramid.

We’ll modify our __init__.py, passing in a root factory to our Configurator constructor. We’ll point it at a new class we create inside our models.py file. Add the following statements to your models.py file:

from pyramid.security import Allow
from pyramid.security import Everyone

class RootFactory(object):
    __acl__ = [ (Allow, Everyone, 'view'),
                (Allow, 'group:editors', 'edit') ]
    def __init__(self, request):
        pass

The RootFactory class we’ve just added will be used by Pyramid to construct a context object. The context is attached to the request object passed to our view callables as the context attribute.

All of our context objects will possess an __acl__ attribute that allows pyramid.security.Everyone (a special principal) to view all pages, while allowing only a principal named group:editors to edit and add pages. The __acl__ attribute attached to a context is interpreted specially by Pyramid as an access control list during view callable execution. See Assigning ACLs to your Resource Objects for more information about what an ACL represents.

We’ll pass the RootFactory we created in the step above in as the root_factory argument to a Configurator.

Configuring an Authorization Policy

For any Pyramid application to perform authorization, we need to add a security.py module (we’ll do that shortly) and we’ll need to change our __init__.py file to add an authentication policy and an authorization policy which uses the security.py file for a callback.

We’ll change our __init__.py file to enable an AuthTktAuthenticationPolicy and an ACLAuthorizationPolicy to enable declarative security checking. We’ll also change __init__.py to add a pyramid.config.Configurator.add_view() call to points at our login view callable, also known as a forbidden view. This configures our newly created login view to show up when Pyramid detects that a view invocation can not be authorized. Also, we’ll add view_permission arguments with the value edit to the edit_page and add_page routes. This indicates that the view callables which these routes reference cannot be invoked without the authenticated user possessing the edit permission with respect to the current context.

This makes the assertion that only users who possess the effective edit permission at the time of the request may invoke those two views. We’ve granted the group:editors principal the edit permission at the root model via its ACL, so only the a user whom is a member of the group named group:editors will able to invoke the views associated with the add_page or edit_page routes.

Viewing Your Changes

When we’re done configuring a root factory, adding an authorization policy, and adding views, your application’s __init__.py will look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

from pyramid.config import Configurator
from pyramid.authentication import AuthTktAuthenticationPolicy
from pyramid.authorization import ACLAuthorizationPolicy

from sqlalchemy import engine_from_config

from tutorial.models import initialize_sql
from tutorial.security import groupfinder

def main(global_config, **settings):
    """ This function returns a WSGI application.
    """
    engine = engine_from_config(settings, 'sqlalchemy.')
    initialize_sql(engine)
    authn_policy = AuthTktAuthenticationPolicy(
        'sosecret', callback=groupfinder)
    authz_policy = ACLAuthorizationPolicy()
    config = Configurator(settings=settings,
                          root_factory='tutorial.models.RootFactory',
                          authentication_policy=authn_policy,
                          authorization_policy=authz_policy)
    config.add_static_view('static', 'tutorial:static')
    config.add_route('view_wiki', '/', view='tutorial.views.view_wiki')
    config.add_route('login', '/login',
                     view='tutorial.login.login',
                     view_renderer='tutorial:templates/login.pt')
    config.add_route('logout', '/logout',
                     view='tutorial.login.logout')
    config.add_route('view_page', '/{pagename}',
                     view='tutorial.views.view_page',
                     view_renderer='tutorial:templates/view.pt')
    config.add_route('add_page', '/add_page/{pagename}',
                     view='tutorial.views.add_page',
                     view_renderer='tutorial:templates/edit.pt',
                     view_permission='edit')
    config.add_route('edit_page', '/{pagename}/edit_page',
                     view='tutorial.views.edit_page',
                     view_renderer='tutorial:templates/edit.pt',
                     view_permission='edit')
    config.add_view('tutorial.login.login',
                    renderer='tutorial:templates/login.pt',
                    context='pyramid.exceptions.Forbidden')
    return config.make_wsgi_app()

Note that that the pyramid.authentication.AuthTktAuthenticationPolicy constructor accepts two arguments: secret and callback. secret is a string representing an encryption key used by the “authentication ticket” machinery represented by this policy: it is required. The callback is a string, representing a dotted Python name, which points at the groupfinder function in the current directory’s security.py file. We haven’t added that module yet, but we’re about to.

Adding security.py

Add a security.py module within your package (in the same directory as __init__.py, views.py, etc) with the following content:

1
2
3
4
5
6
7

USERS = {'editor':'editor',
          'viewer':'viewer'}
GROUPS = {'editor':['group:editors']}

def groupfinder(userid, request):
    if userid in USERS:
        return GROUPS.get(userid, [])

The groupfinder defined here is an authentication policy “callback”; it is a callable that accepts a userid and a request. If the userid exists in the system, the callback will return a sequence of group identifiers (or an empty sequence if the user isn’t a member of any groups). If the userid does not exist in the system, the callback will return None. In a production system, user and group data will most often come from a database, but here we use “dummy” data to represent user and groups sources. Note that the editor user is a member of the group:editors group in our dummy group data (the GROUPS data structure).

We’ve given the editor user membership to the group:editors by mapping him to this group in the GROUPS data structure (GROUPS = {'editor':['group:editors']}). Since the groupfinder function consults the GROUPS data structure, this will mean that, as a result of the ACL attached to the root returned by the root factory, and the permission associated with the add_page and edit_page views, the editor user should be able to add and edit pages.

Adding Login and Logout Views

We’ll add a login view callable which renders a login form and processes the post from the login form, checking credentials.

We’ll also add a logout view callable to our application and provide a link to it. This view will clear the credentials of the logged in user and redirect back to the front page.

We’ll add a different file (for presentation convenience) to add login and logout view callables. Add a file named login.py to your application (in the same directory as views.py) with the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

from pyramid.httpexceptions import HTTPFound
from pyramid.security import remember
from pyramid.security import forget
from pyramid.url import route_url

from tutorial.security import USERS

def login(request):
    login_url = route_url('login', request)
    referrer = request.url
    if referrer == login_url:
        referrer = '/' # never use the login form itself as came_from
    came_from = request.params.get('came_from', referrer)
    message = ''
    login = ''
    password = ''
    if 'form.submitted' in request.params:
        login = request.params['login']
        password = request.params['password']
        if USERS.get(login) == password:
            headers = remember(request, login)
            return HTTPFound(location = came_from,
                             headers = headers)
        message = 'Failed login'

    return dict(
        message = message,
        url = request.application_url + '/login',
        came_from = came_from,
        login = login,
        password = password,
        )

def logout(request):
    headers = forget(request)
    return HTTPFound(location = route_url('view_wiki', request),
                     headers = headers)

Changing Existing Views

Then we need to change each of our view_page, edit_page and add_page views in views.py to pass a “logged in” parameter to its template. We’ll add something like this to each view body:

1
2

from pyramid.security import authenticated_userid
logged_in = authenticated_userid(request)

We’ll then change the return value of these views to pass the resulting `logged_in` value to the template, e.g.:

1
2
3
4

return dict(page = context,
            content = content,
            logged_in = logged_in,
            edit_url = edit_url)

Adding the login.pt Template

Add a login.pt template to your templates directory. It’s referred to within the login view we just added to login.py.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>Login - Pyramid tutorial wiki (based on TurboGears
    20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          <b>Login</b><br/>
          <span tal:replace="message"/>
        </div>
        <div id="right" class="app-welcome align-right"></div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <form action="${url}" method="post">
          <input type="hidden" name="came_from" value="${came_from}"/>
          <input type="text" name="login" value="${login}"/><br/>
          <input type="password" name="password"
                 value="${password}"/><br/>
          <input type="submit" name="form.submitted" value="Log In"/>
        </form>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Change view.pt and edit.pt

We’ll also need to change our edit.pt and view.pt templates to display a “Logout” link if someone is logged in. This link will invoke the logout view.

To do so we’ll add this to both templates within the <div id="right" class="app-welcome align-right"> div:

<span tal:condition="logged_in">
   <a href="${request.application_url}/logout">Logout</a>
</span>

Viewing the Application in a Browser

We can finally examine our application in a browser. The views we’ll try are as follows:

Visiting http://localhost:6543/ in a browser invokes the view_wiki view. This always redirects to the view_page view of the FrontPage page object. It is executable by any user.

Visiting http://localhost:6543/FrontPage in a browser invokes the view_page view of the FrontPage page object.

Visiting http://localhost:6543/FrontPage/edit_page in a browser invokes the edit view for the FrontPage object. It is executable by only the editor user. If a different user (or the anonymous user) invokes it, a login form will be displayed. Supplying the credentials with the username editor, password editor will display the edit page form.

Visiting http://localhost:6543/add_page/SomePageName in a browser invokes the add view for a page. It is executable by only the editor user. If a different user (or the anonymous user) invokes it, a login form will be displayed. Supplying the credentials with the username editor, password editor will display the edit page form.

Seeing Our Changes To views.py and our Templates

Our views.py module will look something like this when we’re done:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

import re

from docutils.core import publish_parts

from pyramid.httpexceptions import HTTPFound
from pyramid.security import authenticated_userid
from pyramid.url import route_url

from tutorial.models import DBSession
from tutorial.models import Page

# regular expression used to find WikiWords
wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")

def view_wiki(request):
    return HTTPFound(location = route_url('view_page', request,
                                          pagename='FrontPage'))

def view_page(request):
    pagename = request.matchdict['pagename']
    session = DBSession()
    page = session.query(Page).filter_by(name=pagename).one()

    def check(match):
        word = match.group(1)
        exists = session.query(Page).filter_by(name=word).all()
        if exists:
            view_url = route_url('view_page', request, pagename=word)
            return '<a href="%s">%s</a>' % (view_url, word)
        else:
            add_url = route_url('add_page', request, pagename=word)
            return '<a href="%s">%s</a>' % (add_url, word)

    content = publish_parts(page.data, writer_name='html')['html_body']
    content = wikiwords.sub(check, content)
    edit_url = route_url('edit_page', request, pagename=pagename)
    logged_in = authenticated_userid(request)
    return dict(page=page, content=content, edit_url=edit_url,
                logged_in=logged_in)

def add_page(request):
    name = request.matchdict['pagename']
    if 'form.submitted' in request.params:
        session = DBSession()
        body = request.params['body']
        page = Page(name, body)
        session.add(page)
        return HTTPFound(location = route_url('view_page', request,
                                              pagename=name))
    save_url = route_url('add_page', request, pagename=name)
    page = Page('', '')
    logged_in = authenticated_userid(request)
    return dict(page=page, save_url=save_url, logged_in=logged_in)

def edit_page(request):
    name = request.matchdict['pagename']
    session = DBSession()
    page = session.query(Page).filter_by(name=name).one()
    if 'form.submitted' in request.params:
        page.data = request.params['body']
        session.add(page)
        return HTTPFound(location = route_url('view_page', request,
                                              pagename=name))

    logged_in = authenticated_userid(request)
    return dict(
        page=page,
        save_url = route_url('edit_page', request, pagename=name),
        logged_in = logged_in,
        )

Our edit.pt template will look something like this when we’re done:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.name} - Pyramid tutorial wiki (based on
    TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Editing <b><span tal:replace="page.name">Page Name
            Goes Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right">
          <span tal:condition="logged_in">
              <a href="${request.application_url}/logout">Logout</a>
          </span>
        </div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <form action="${save_url}" method="post">
          <textarea name="body" tal:content="page.data" rows="10"
                    cols="60"/><br/>
          <input type="submit" name="form.submitted" value="Save"/>
        </form>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Our view.pt template will look something like this when we’re done:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<head>
  <title>${page.name} - Pyramid tutorial wiki (based on
    TurboGears 20-Minute Wiki)</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
  <meta name="keywords" content="python web application" />
  <meta name="description" content="pyramid web application" />
  <link rel="shortcut icon"
        href="${request.static_url('tutorial:static/favicon.ico')}" />
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/pylons.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <!--[if lte IE 6]>
  <link rel="stylesheet"
        href="${request.static_url('tutorial:static/ie6.css')}"
        type="text/css" media="screen" charset="utf-8" />
  <![endif]-->
</head>
<body>
  <div id="wrap">
    <div id="top-small">
      <div class="top-small align-center">
        <div>
          <img width="220" height="50" alt="pyramid"
        src="${request.static_url('tutorial:static/pyramid-small.png')}" />
        </div>
      </div>
    </div>
    <div id="middle">
      <div class="middle align-right">
        <div id="left" class="app-welcome align-left">
          Viewing <b><span tal:replace="page.name">Page Name
            Goes Here</span></b><br/>
          You can return to the
          <a href="${request.application_url}">FrontPage</a>.<br/>
        </div>
        <div id="right" class="app-welcome align-right">
          <span tal:condition="logged_in">
            <a href="${request.application_url}/logout">Logout</a>
          </span>
        </div>
      </div>
    </div>
    <div id="bottom">
      <div class="bottom">
        <div tal:replace="structure content">
          Page text goes here.
        </div>
        <p>
          <a tal:attributes="href edit_url" href="">
            Edit this page
          </a>
        </p>
      </div>
    </div>
  </div>
  <div id="footer">
    <div class="footer"
         >&copy; Copyright 2008-2011, Agendaless Consulting.</div>
  </div>
</body>
</html>

Revisiting the Application

When we revisit the application in a browser, and log in (as a result of hitting an edit or add page and submitting the login form with the editor credentials), we’ll see a Logout link in the upper right hand corner. When we click it, we’re logged out, and redirected back to the front page.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

SQLAlchemy + URL Dispatch Wiki Tutorial »

Distributing Your Application

Once your application works properly, you can create a “tarball” from it by using the setup.py sdist command. The following commands assume your current working directory is the tutorial package we’ve created and that the parent directory of the tutorial package is a virtualenv representing a Pyramid environment.

On UNIX:

$ ../bin/python setup.py sdist

On Windows:

c:\pyramidtut> ..\Scripts\python setup.py sdist

The output of such a command will be something like:

running sdist
# ... more output ...
creating dist
tar -cf dist/tutorial-0.1.tar tutorial-0.1
gzip -f9 dist/tutorial-0.1.tar
removing 'tutorial-0.1' (and everything under it)

Note that this command creates a tarball in the “dist” subdirectory named tutorial-0.1.tar.gz. You can send this file to your friends to show them your cool new application. They should be able to install it by pointing the easy_install command directly at it. Or you can upload it to PyPI [http://pypi.python.org] and share it with the rest of the world, where it can be downloaded via easy_install remotely like any other package people download from PyPI.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Converting a repoze.bfg Application to Pyramid

Prior iterations of Pyramid were released as a package named repoze.bfg. repoze.bfg users are encouraged to upgrade their deployments to Pyramid, as, after the first final release of Pyramid, further feature development on repoze.bfg will cease.

Most existing repoze.bfg applications can be converted to a Pyramid application in a completely automated fashion. However, if your application depends on packages which are not “core” parts of repoze.bfg but which nonetheless have repoze.bfg in their names (e.g. repoze.bfg.skins, repoze.bfg.traversalwrapper, repoze.bfg.jinja2), you will need to find an analogue for each. For example, by the time you read this, there will be a pyramid_jinja2 package, which can be used instead of repoze.bfg.jinja2. If an analogue does not seem to exist for a repoze.bfg add-on package that your application uses, please email the Pylons-devel [http://groups.google.com/group/pylons-devel] maillist; we’ll convert the package to a Pyramid analogue for you.

Here’s how to convert a repoze.bfg application to a Pyramid application:

Ensure that your application works under repoze.bfg version 1.3 or better. See http://docs.repoze.org/bfg/1.3/narr/install.html for repoze.bfg 1.3 installation instructions. If your application has an automated test suite, run it while your application is using repoze.bfg 1.3+. Otherwise, test it manually. It is only safe to proceed to the next step once your application works under repoze.bfg 1.3+.

If your application has a proper set of dependencies, and a standard automated test suite, you might test your repoze.bfg application against repoze.bfg 1.3 like so:

$ bfgenv/bin/python setup.py test

bfgenv above will be the virtualenv into which you’ve installed repoze.bfg 1.3.

Install Pyramid into a separate virtualenv as per the instructions in Installing Pyramid. The Pyramid virtualenv should be separate from the one you’ve used to install repoze.bfg. A quick way to do this:

$ cd ~
$ virtualenv --no-site-packages pyramidenv
$ cd pyramidenv
$ bin/easy_install pyramid

Put a copy of your repoze.bfg application into a temporary location (perhaps by checking a fresh copy of the application out of a version control repository). For example:

$ cd /tmp
$ svn co http://my.server/my/bfg/application/trunk bfgapp

Use the bfg2pyramid script present in the bin directory of the Pyramid virtualenv to convert all repoze.bfg Python import statements into compatible Pyramid import statements. bfg2pyramid will also fix ZCML directive usages of common repoze.bfg directives. You invoke bfg2pyramid by passing it the path of the copy of your application. The path passed should contain a “setup.py” file, representing your repoze.bfg application’s setup script. bfg2pyramid will change the copy of the application in place.

$ ~/pyramidenv/bfg2pyramid /tmp/bfgapp

bfg2pyramid will convert the following repoze.bfg application aspects to Pyramid compatible analogues:

Python import statements naming repoze.bfg APIs will be converted to Pyramid compatible import statements. Every Python file beneath the top-level path will be visited and converted recursively, except Python files which live in directories which start with a . (dot).

Each ZCML file found (recursively) within the path will have the default xmlns attribute attached to the configure tag changed from http://namespaces.repoze.org/bfg to http://pylonshq.com/pyramid. Every ZCML file beneath the top-level path (files ending with .zcml) will be visited and converted recursively, except ZCML files which live in directories which start with a . (dot).

ZCML files which contain directives that have attributes which name a repoze.bfg API module or attribute of an API module (e.g. context="repoze.bfg.exceptions.NotFound") will be converted to Pyramid compatible ZCML attributes (e.g. context="pyramid.exceptions.NotFound). Every ZCML file beneath the top-level path (files ending with .zcml) will be visited and converted recursively, except ZCML files which live in directories which start with a . (dot).

Edit the setup.py file of the application you’ve just converted (if you’ve been using the example paths, this will be /tmp/bfgapp/setup.py) to depend on the pyramid distribution instead the of repoze.bfg distribution in its install_requires list. If you used a paster template to create the repoze.bfg application, you can do so by changing the requires line near the top of the setup.py file. The original may look like this:

requires = ['repoze.bfg', ... other dependencies ...]

Edit the setup.py so it has:

requires = ['pyramid', ... other dependencies ...]

All other install-requires and tests-requires dependencies save for the one on repoze.bfg can remain the same.

Convert any install_requires dependencies your application has on other add-on packages which have repoze.bfg in their names to Pyramid compatible analogues (e.g. repoze.bfg.jinja2 should be replaced with pyramid_jinja2). You may need to adjust configuration options and/or imports in your repoze.bfg application after replacing these add-ons. Read the documentation of the Pyramid add-on package for information.

Only if you use ZCML and add-ons which use ZCML: The default xmlns of the configure tag in ZCML has changed. The bfg2pyramid script effects the default namespace change (it changes the configure tag default xmlns from http://namespaces.repoze.org/bfg to http://pylonshq.com/pyramid).

This means that uses of add-ons which define ZCML directives in the http://namespaces.repoze.org/bfg namespace will begin to “fail” (they’re actually not really failing, but your ZCML assumes that they will always be used within a configure tag which names the http://namespaces.repoze.org/bfg namespace as its default xmlns). Symptom: when you attempt to start the application, an error such as ConfigurationError: ('Unknown directive', u'http://namespaces.repoze.org/bfg', u'workflow') is printed to the console and the application fails to start. In such a case, either add an xmlns="http://namespaces.repoze.org/bfg" attribute to each tag which causes a failure, or define a namespace alias in the configure tag and prefix each failing tag. For example, change this “failing” tag instance:

<configure xmlns="http://pylonshq.com/pyramid">
    <failingtag attr="foo"/>
</configure>

To this, which will begin to succeed:

<configure xmlns="http://pylonshq.com/pyramid"
           xmlns:bfg="http://namespaces.repoze.org/bfg">
    <bfg:failingtag attr="foo"/>
</configure>

You will also need to add the pyramid_zcml package to your setup.py install_requires list. In Pyramid, ZCML configuration became an optional add-on supported by the pyramid_zcml package.

Retest your application using Pyramid. This might be as easy as:

$ cd /tmp/bfgapp
$ ~/pyramidenv/bin/python setup.py test

Fix any test failures.

Fix any code which generates deprecation warnings.

Start using the converted version of your application. Celebrate.

Two terminological changes have been made to Pyramid which make its documentation and newer APIs different than those of repoze.bfg. The concept that BFG called model is called resource in Pyramid and the concept that BFG called resource is called asset in Pyramid. Various APIs have changed as a result (although all have backwards compatible shims). Additionally, the environment variables that influenced server behavior which used to be prefixed with BFG_ (such as BFG_DEBUG_NOTFOUND) must now be prefixed with PYRAMID_.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Running Pyramid on Google’s App Engine

It is possible to run a Pyramid application on Google’s App Engine [http://code.google.com/appengine/]. Content from this tutorial was contributed by YoungKing, based on the “appengine-monkey” tutorial for Pylons [http://code.google.com/p/appengine-monkey/wiki/Pylons]. This tutorial is written in terms of using the command line on a UNIX system; it should be possible to perform similar actions on a Windows system.

Download Google’s App Engine SDK [http://code.google.com/appengine/downloads.html] and install it on your system.

Use Subversion to check out the source code for appengine-monkey.

$ svn co http://appengine-monkey.googlecode.com/svn/trunk/ \
    appengine-monkey

Use appengine_homedir.py script in appengine-monkey to create a virtualenv for your application.

$ export GAE_PATH=/usr/local/google_appengine
$ python2.5 /path/to/appengine-monkey/appengine-homedir.py --gae \
  $GAE_PATH pyramidapp

Note that $GAE_PATH should be the path where you have unpacked the App Engine SDK. (On Mac OS X at least, /usr/local/google_appengine is indeed where the installer puts it).

This will set up an environment in pyramidapp/, with some tools installed in pyramidapp/bin. There will also be a directory pyramidapp/app/ which is the directory you will upload to appengine.

Install Pyramid into the virtualenv

$ cd pyramidapp/
$ bin/easy_install pyramid

This will install Pyramid in the environment.

Create your application

We’ll use the standard way to create a Pyramid application, but we’ll have to move some files around when we are done. The below commands assume your current working directory is the pyramidapp virtualenv directory you created in the third step above:

$ cd app
$ rm -rf pyramidapp
$ bin/paster create -t pyramid_starter pyramidapp
$ mv pyramidapp aside
$ mv aside/pyramidapp .
$ rm -rf aside

Edit config.py

Edit the APP_NAME and APP_ARGS settings within config.py. The APP_NAME must be pyramidapp:main, and the APP_ARGS must be ({},). Any other settings in config.py should remain the same.

APP_NAME = 'pyramidapp:main'
APP_ARGS = ({},)

Edit runner.py

To prevent errors for import site, add this code stanza before import site in app/runner.py:

import sys
sys.path = [path for path in sys.path if 'site-packages' not in path]
import site

You will also need to comment out the line that starts with assert sys.path in the file.

# comment the sys.path assertion out
# assert sys.path[:len(cur_sys_path)] == cur_sys_path, (
#   "addsitedir() caused entries to be prepended to sys.path")

For GAE development environment 1.3.0 or better, you will also need the following somewhere near the top of the runner.py file to fix a compatibility issue with appengine-monkey:

import os
os.mkdir = None

Run the application. dev_appserver.py is typically installed by the SDK in the global path but you need to be sure to run it with Python 2.5 (or whatever version of Python your GAE SDK expects).

1
2

$ cd ../..
$ python2.5 /usr/local/bin/dev_appserver.py pyramidapp/app/

Startup success looks something like this:

[chrism@vitaminf pyramid_gae]$ python2.5 \
              /usr/local/bin/dev_appserver.py \
              pyramidapp/app/
INFO     2009-05-03 22:23:13,887 appengine_rpc.py:157] # ... more...
Running application pyramidapp on port 8080: http://localhost:8080

You may need to run “Make Symlinks” from the Google App Engine Launcher GUI application if your system doesn’t already have the dev_appserver.py script sitting around somewhere.

Hack on your pyramid application, using a normal run, debug, restart process. For tips on how to use the pdb module within Google App Engine, see this blog post [http://jjinux.blogspot.com/2008/05/python-debugging-google-app-engine-apps.html]. In particular, you can create a function like so and call it to drop your console into a pdb trace:

1
2
3
4
5

def set_trace():
    import pdb, sys
    debugger = pdb.Pdb(stdin=sys.__stdin__,
        stdout=sys.__stdout__)
    debugger.set_trace(sys._getframe().f_back)

Sign up for a GAE account [http://code.google.com/appengine/] and create an application. You’ll need a mobile phone to accept an SMS in order to receive authorization.

Edit the application’s ID in app.yaml to match the application name you created during GAE account setup.

application: mycoolpyramidapp

Upload the application

$ python2.5 /usr/local/bin/appcfg.py update pyramidapp/app

You almost certainly won’t hit the 3000-file GAE file number limit when invoking this command. If you do, however, it will look like so:

HTTPError: HTTP Error 400: Bad Request
Rolling back the update.
Error 400: --- begin server output ---
Max number of files and blobs is 3000.
--- end server output ---

If you do experience this error, you will be able to get around this by zipping libraries. You can use pip to create zipfiles from packages. See Zipping Files Via Pip for more information about this.

A successful upload looks like so:

[chrism@vitaminf pyramidapp]$ python2.5 /usr/local/bin/appcfg.py \
                              update ../pyramidapp/app/
Scanning files on local disk.
Scanned 500 files.
# ... more output ...
Will check again in 16 seconds.
Checking if new version is ready to serve.
Closing update: new version is ready to start serving.
Uploading index definitions.

Visit http://<yourapp>.appspot.com in a browser.

Zipping Files Via Pip

If you hit the Google App Engine 3000-file limit, you may need to create zipfile archives out of some distributions installed in your application’s virtualenv.

First, see which packages are available for zipping:

$ bin/pip zip -l

This shows your zipped packages (by default, none) and your unzipped packages. You can zip a package like so:

$ bin/pip zip pytz-2009g-py2.5.egg

Note that it requires the whole egg file name. For a Pyramid app, the following packages are good candidates to be zipped.

Chameleon

zope.i18n

Once the zipping procedure is finished you can try uploading again.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Running a Pyramid Application under mod_wsgi

mod_wsgi is an Apache module developed by Graham Dumpleton. It allows WSGI programs to be served using the Apache web server.

This guide will outline broad steps that can be used to get a Pyramid application running under Apache via mod_wsgi. This particular tutorial was developed under Apple’s Mac OS X platform (Snow Leopard, on a 32-bit Mac), but the instructions should be largely the same for all systems, delta specific path information for commands and files.

Note

Unfortunately these instructions almost certainly won’t work for deploying a Pyramid application on a Windows system using mod_wsgi. If you have experience with Pyramid and mod_wsgi on Windows systems, please help us document this experience by submitting documentation to the Pylons-devel maillist [http://groups.google.com/group/pylons-devel].

The tutorial assumes you have Apache already installed on your system. If you do not, install Apache 2.X for your platform in whatever manner makes sense.

Once you have Apache installed, install mod_wsgi. Use the (excellent) installation instructions [http://code.google.com/p/modwsgi/wiki/InstallationInstructions] for your platform into your system’s Apache installation.

Install virtualenv into the Python which mod_wsgi will run using the easy_install program.

$ sudo /usr/bin/easy_install-2.6 virtualenv

This command may need to be performed as the root user.

Create a virtualenv which we’ll use to install our application.

$ cd ~
$ mkdir modwsgi
$ cd modwsgi
$ /usr/local/bin/virtualenv --no-site-packages env

Install Pyramid into the newly created virtualenv:

$ cd ~/modwsgi/env
$ bin/easy_install pyramid

Create and install your Pyramid application. For the purposes of this tutorial, we’ll just be using the pyramid_starter application as a baseline application. Substitute your existing Pyramid application as necessary if you already have one.

$ cd ~/modwsgi/env
$ bin/paster create -t pyramid_starter myapp
$ cd myapp
$ ../bin/python setup.py install

Within the virtualenv directory (~/modwsgi/env), create a script named pyramid.wsgi. Give it these contents:

from pyramid.paster import get_app
application = get_app(
  '/Users/chrism/modwsgi/env/myapp/production.ini', 'main')

The first argument to get_app is the project Paste configuration file name. It’s best to use the production.ini file provided by your Pyramid paster template, as it contains settings appropriate for production. The second is the name of the section within the .ini file that should be loaded by mod_wsgi. The assignment to the name application is important: mod_wsgi requires finding such an assignment when it opens the file.

Make the pyramid.wsgi script executable.

$ cd ~/modwsgi/env
$ chmod 755 pyramid.wsgi

Edit your Apache configuration and add some stuff. I happened to create a file named /etc/apache2/other/modwsgi.conf on my own system while installing Apache, so this stuff went in there.

# Use only 1 Python sub-interpreter.  Multiple sub-interpreters
# play badly with C extensions.
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On
WSGIDaemonProcess pyramid user=chrism group=staff processes=1 \
   threads=4 \
   python-path=/Users/chrism/modwsgi/env/lib/python2.6/site-packages
WSGIScriptAlias /myapp /Users/chrism/modwsgi/env/pyramid.wsgi

<Directory /Users/chrism/modwsgi/env>
  WSGIProcessGroup pyramid
  Order allow, deny
  Allow from all
</Directory>

Restart Apache

$ sudo /usr/sbin/apachectl restart

Visit http://localhost/myapp in a browser. You should see the sample application rendered in your browser.

mod_wsgi has many knobs and a great variety of deployment modes. This is just one representation of how you might use it to serve up a Pyramid application. See the mod_wsgi configuration documentation [http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines] for more in-depth configuration information.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation

Comprehensive reference material for every public API exposed by Pyramid is available within this chapter. The API documentation is organized alphabetically by module name.

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

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.authorization

class ACLAuthorizationPolicy

An authorization policy which consults an ACL object attached to a context to determine authorization information about a principal or multiple principals. If the context is part of a lineage, the context’s parents are consulted for ACL information too. The following is true about this security policy.

When checking whether the ‘current’ user is permitted (via the permits method), the security policy consults the context for an ACL first. If no ACL exists on the context, or one does exist but the ACL does not explicitly allow or deny access for any of the effective principals, consult the context’s parent ACL, and so on, until the lineage is exhausted or we determine that the policy permits or denies.

During this processing, if any pyramid.security.Deny ACE is found matching any principal in principals, stop processing by returning an pyramid.security.ACLDenied instance (equals False) immediately. If any pyramid.security.Allow ACE is found matching any principal, stop processing by returning an pyramid.security.ACLAllowed instance (equals True) immediately. If we exhaust the context’s lineage, and no ACE has explicitly permitted or denied access, return an instance of pyramid.security.ACLDenied (equals False).

When computing principals allowed by a permission via the pyramid.security.principals_allowed_by_permission() method, we compute the set of principals that are explicitly granted the permission in the provided context. We do this by walking ‘up’ the object graph from the root to the context. During this walking process, if we find an explicit pyramid.security.Allow ACE for a principal that matches the permission, the principal is included in the allow list. However, if later in the walking process that principal is mentioned in any pyramid.security.Deny ACE for the permission, the principal is removed from the allow list. If a pyramid.security.Deny to the principal pyramid.security.Everyone is encountered during the walking process that matches the permission, the allow list is cleared for all principals encountered in previous ACLs. The walking process ends after we’ve processed the any ACL directly attached to context; a set of principals is returned.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.authentication

Authentication Policies

class AuthTktAuthenticationPolicy(secret, callback=None, cookie_name='auth_tkt', secure=False, include_ip=False, timeout=None, reissue_time=None, max_age=None, path='/', http_only=False, wild_domain=True)

A Pyramid authentication policy which obtains data from an paste.auth.auth_tkt cookie.

Constructor Arguments

secret

The secret (a string) used for auth_tkt cookie signing. Required.

callback

Default: None. A callback passed the userid and the request, expected to return None if the userid doesn’t exist or a sequence of group identifiers (possibly empty) if the user does exist. If callback is None, the userid will be assumed to exist with no groups. Optional.

cookie_name

Default: auth_tkt. The cookie name used (string). Optional.

secure

Default: False. Only send the cookie back over a secure conn. Optional.

include_ip

Default: False. Make the requesting IP address part of the authentication data in the cookie. Optional.

timeout

Default: None. Maximum number of seconds which a newly issued ticket will be considered valid. After this amount of time, the ticket will expire (effectively logging the user out). If this value is None, the ticket never expires. Optional.

reissue_time

Default: None. If this parameter is set, it represents the number of seconds that must pass before an authentication token cookie is reissued. The duration is measured as the number of seconds since the last auth_tkt cookie was issued and ‘now’. If the timeout value is None, this parameter has no effect. If this parameter is provided, and the value of timeout is not None, the value of reissue_time must be smaller than value of timeout. A good rule of thumb: if you want auto-reissued cookies: set this to the timeout value divided by ten. If this value is 0, a new ticket cookie will be reissued on every request which needs authentication. Optional.

max_age

Default: None. The max age of the auth_tkt cookie, in seconds. This differs from timeout inasmuch as timeout represents the lifetime of the ticket contained in the cookie, while this value represents the lifetime of the cookie itself. When this value is set, the cookie’s Max-Age and Expires settings will be set, allowing the auth_tkt cookie to last between browser sessions. It is typically nonsensical to set this to a value that is lower than timeout or reissue_time, although it is not explicitly prevented. Optional.

path

Default: /. The path for which the auth_tkt cookie is valid. May be desirable if the application only serves part of a domain. Optional.

http_only

Default: False. Hide cookie from JavaScript by setting the HttpOnly flag. Not honored by all browsers. Optional.

wild_domain

Default: True. An auth_tkt cookie will be generated for the wildcard domain. Optional.

class RepozeWho1AuthenticationPolicy(identifier_name='auth_tkt', callback=None)

A Pyramid authentication policy which obtains data from the repoze.who 1.X WSGI ‘API’ (the repoze.who.identity key in the WSGI environment).

Constructor Arguments

identifier_name

Default: auth_tkt. The repoze.who plugin name that performs remember/forget. Optional.

callback

Default: None. A callback passed the repoze.who identity and the request, expected to return None if the user represented by the identity doesn’t exist or a sequence of group identifiers (possibly empty) if the user does exist. If callback is None, the userid will be assumed to exist with no groups.

class RemoteUserAuthenticationPolicy(environ_key='REMOTE_USER', callback=None)

A Pyramid authentication policy which obtains data from the REMOTE_USER WSGI environment variable.

Constructor Arguments

environ_key

Default: REMOTE_USER. The key in the WSGI environ which provides the userid.

callback

Default: None. A callback passed the userid and the request, expected to return None if the userid doesn’t exist or a sequence of group identifiers (possibly empty) if the user does exist. If callback is None, the userid will be assumed to exist with no groups.

Helper Classes

class AuthTktCookieHelper(secret, cookie_name='auth_tkt', secure=False, include_ip=False, timeout=None, reissue_time=None, max_age=None, http_only=False, path='/', wild_domain=True)

A helper class for use in third-party authentication policy implementations. See pyramid.authentication.AuthTktAuthenticationPolicy for the meanings of the constructor arguments.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.chameleon_text

get_template(path)

Return the underyling object representing a Chameleon text template using the template implied by the path argument. The path argument may be a package-relative path, an absolute path, or a asset specification.

Warning

This API is deprecated in Pyramid 1.0. Use the implementation() method of a template renderer retrieved via pyramid.renderers.get_renderer() instead.

render_template(path, **kw)

Render a Chameleon text template using the template implied by the path argument. The path argument may be a package-relative path, an absolute path, or a asset specification. The arguments in *kw are passed as top-level names to the template, and so may be used within the template itself. Returns a string.

Warning

This API is deprecated in Pyramid 1.0. Use pyramid.renderers.render() instead.

render_template_to_response(path, **kw)

Render a Chameleon text template using the template implied by the path argument. The path argument may be a package-relative path, an absolute path, or a asset specification. The arguments in *kw are passed as top-level names to the template, and so may be used within the template itself. Returns a Response object with the body as the template result.

Warning

This API is deprecated in Pyramid 1.0. Use pyramid.renderers.render_to_response() instead.

These APIs will will work against template files which contain simple ${Genshi} - style replacement markers.

The API of pyramid.chameleon_text is identical to that of pyramid.chameleon_zpt; only its import location is different. If you need to import an API functions from this module as well as the pyramid.chameleon_zpt module within the same view file, use the as feature of the Python import statement, e.g.:

1
2

from pyramid.chameleon_zpt import render_template as zpt_render
from pyramid.chameleon_text import render_template as text_render

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.chameleon_zpt

get_template(path)

Return the underyling object representing a Chameleon ZPT template using the template implied by the path argument. The path argument may be a package-relative path, an absolute path, or a asset specification.

Warning

This API is deprecated in Pyramid 1.0. Use the implementation() method of a template renderer retrieved via pyramid.renderers.get_renderer() instead.

render_template(path, **kw)

Render a Chameleon ZPT template using the template implied by the path argument. The path argument may be a package-relative path, an absolute path, or a asset specification. The arguments in *kw are passed as top-level names to the template, and so may be used within the template itself. Returns a string.

Warning

This API is deprecated in Pyramid 1.0. Use pyramid.renderers.render() instead.

render_template_to_response(path, **kw)

Render a Chameleon ZPT template using the template implied by the path argument. The path argument may be a package-relative path, an absolute path, or a asset specification. The arguments in *kw are passed as top-level names to the template, and so may be used within the template itself. Returns a Response object with the body as the template result.

Warning

This API is deprecated in Pyramid 1.0. Use pyramid.renderers.render_to_response() instead.

These APIs will work against files which supply template text which matches the ZPT specification.

The API of pyramid.chameleon_zpt is identical to that of pyramid.chameleon_text; only its import location is different. If you need to import an API functions from this module as well as the pyramid.chameleon_text module within the same view file, use the as feature of the Python import statement, e.g.:

1
2

from pyramid.chameleon_zpt import render_template as zpt_render
from pyramid.chameleon_text import render_template as text_render

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.config

class Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None, default_permission=None, session_factory=None, autocommit=False)

A Configurator is used to configure a Pyramid application registry.

The Configurator accepts a number of arguments: registry, package, settings, root_factory, authentication_policy, authorization_policy, renderers debug_logger, locale_negotiator, request_factory, renderer_globals_factory, default_permission, session_factory, and autocommit.

If the registry argument is passed as a non-None value, it must be an instance of the pyramid.registry.Registry class representing the registry to configure. If registry is None, the configurator will create a pyramid.registry.Registry instance itself; it will also perform some default configuration that would not otherwise be done. After construction, the configurator may be used to add configuration to the registry. The overall state of a registry is called the ‘configuration state’.

Warning

If a registry is passed to the Configurator constructor, all other constructor arguments except package are ignored.

If the package argument is passed, it must be a reference to a Python package (e.g. sys.modules['thepackage']) or a dotted Python name to same. This value is used as a basis to convert relative paths passed to various configuration methods, such as methods which accept a renderer argument, into absolute paths. If None is passed (the default), the package is assumed to be the Python package in which the caller of the Configurator constructor lives.

If the settings argument is passed, it should be a Python dictionary representing the deployment settings for this application. These are later retrievable using the pyramid.registry.Registry.settings attribute (aka request.registry.settings).

If the root_factory argument is passed, it should be an object representing the default root factory for your application or a dotted Python name to same. If it is None, a default root factory will be used.

If authentication_policy is passed, it should be an instance of an authentication policy or a dotted Python name to same.

If authorization_policy is passed, it should be an instance of an authorization policy or a dotted Python name to same.

Note

A ConfigurationError will be raised when an authorization policy is supplied without also supplying an authentication policy (authorization requires authentication).

If renderers is passed, it should be a list of tuples representing a set of renderer factories which should be configured into this application (each tuple representing a set of positional values that should be passed to pyramid.config.Configurator.add_renderer()). If it is not passed, a default set of renderer factories is used.

If debug_logger is not passed, a default debug logger that logs to stderr will be used. If it is passed, it should be an instance of the logging.Logger (PEP 282) standard library class or a dotted Python name to same. The debug logger is used by Pyramid itself to log warnings and authorization debugging information.

If locale_negotiator is passed, it should be a locale negotiator implementation or a dotted Python name to same. See Using a Custom Locale Negotiator.

If request_factory is passed, it should be a request factory implementation or a dotted Python name to same. See Changing the Request Factory. By default it is None, which means use the default request factory.

If renderer_globals_factory is passed, it should be a renderer globals factory implementation or a dotted Python name to same. See Adding Renderer Globals. By default, it is None, which means use no renderer globals factory.

If default_permission is passed, it should be a permission string to be used as the default permission for all view configuration registrations performed against this Configurator. An example of a permission string:'view'. Adding a default permission makes it unnecessary to protect each view configuration with an explicit permission, unless your application policy requires some exception for a particular view. By default, default_permission is None, meaning that view configurations which do not explicitly declare a permission will always be executable by entirely anonymous users (any authorization policy in effect is ignored). See also Setting a Default Permission.

If session_factory is passed, it should be an object which implements the session factory interface. If a nondefault value is passed, the session_factory will be used to create a session object when request.session is accessed. Note that the same outcome can be achieved by calling pyramid.config.Configurator.set_session_factory(). By default, this argument is None, indicating that no session factory will be configured (and thus accessing request.session will throw an error) unless set_session_factory is called later during configuration.

If autocommit is True, every method called on the configurator will cause an immediate action, and no configuration conflict detection will be used. If autocommit is False, most methods of the configurator will defer their action until pyramid.config.Configurator.commit() is called. When pyramid.config.Configurator.commit() is called, the actions implied by the called methods will be checked for configuration conflicts unless autocommit is True. If a conflict is detected a ConfigurationConflictError will be raised. Calling pyramid.config.Configurator.make_wsgi_app() always implies a final commit.

If default_view_mapper is passed, it will be used as the default view mapper factory for view configurations that don’t otherwise specify one (see pyramid.interfaces.IViewMapperFactory). If a default_view_mapper is not passed, a superdefault view mapper will be used.

registry

The application registry which holds the configuration associated with this configurator.

begin(request=None)

Indicate that application or test configuration has begun. This pushes a dictionary containing the application registry implied by registry attribute of this configurator and the request implied by the request argument on to the thread local stack consulted by various pyramid.threadlocal API functions.

end()

Indicate that application or test configuration has ended. This pops the last value pushed on to the thread local stack (usually by the begin method) and returns that value.

hook_zca()

Call zope.component.getSiteManager.sethook() with the argument pyramid.threadlocal.get_current_registry, causing the Zope Component Architecture ‘global’ APIs such as zope.component.getSiteManager(), zope.component.getAdapter() and others to use the Pyramid application registry rather than the Zope ‘global’ registry. If zope.component cannot be imported, this method will raise an ImportError.

unhook_zca()

Call zope.component.getSiteManager.reset() to undo the action of pyramid.config.Configurator.hook_zca(). If zope.component cannot be imported, this method will raise an ImportError.

get_settings()

Return a deployment settings object for the current application. A deployment settings object is a dictionary-like object that contains key/value pairs based on the dictionary passed as the settings argument to the pyramid.config.Configurator constructor or the pyramid.router.make_app() API.

Note

For backwards compatibility, dictionary keys can also be looked up as attributes of the settings object.

Note

the pyramid.registry.Registry.settings API performs the same duty.

commit()

Commit any pending configuration actions. If a configuration conflict is detected in the pending configuration actins, this method will raise a ConfigurationConflictError; within the traceback of this error will be information about the source of the conflict, usually including file names and line numbers of the cause of the configuration conflicts.

action(discriminator, callable=None, args=(), kw=None, order=0)

Register an action which will be executed when pyramid.config.Configuration.commit() is called (or executed immediately if autocommit is True).

Note

This method is typically only used by Pyramid framework extension authors, not by Pyramid application developers.

The discriminator uniquely identifies the action. It must be given, but it can be None, to indicate that the action never conflicts. It must be a hashable value.

The callable is a callable object which performs the action. It is optional. args and kw are tuple and dict objects respectively, which are passed to callable when this action is executed.

order is a crude order control mechanism, only rarely used (has no effect when autocommit is True).

include(*callables)

Include one or more configuration callables, to support imperative application extensibility.

A configuration callable should be a callable that accepts a single argument named config, which will be an instance of a Configurator (be warned that it will not be the same configurator instance on which you call this method, however). The code which runs as the result of calling the callable should invoke methods on the configurator passed to it which add configuration state. The return value of a callable will be ignored.

Values allowed to be presented via the *callables argument to this method: any callable Python object or any dotted Python name which resolves to a callable Python object. It may also be a Python module, in which case, the module will be searched for a callable named includeme, which will be treated as the configuration callable.

For example, if the includeme function below lives in a module named myapp.myconfig:

1
2
3
4
5
6
7
8

# myapp.myconfig module

def my_view(request):
    from pyramid.response import Response
    return Response('OK')

def includeme(config):
    config.add_view(my_view)

You might cause it be included within your Pyramid application like so:

1
2
3
4
5

from pyramid.config import Configurator

def main(global_config, **settings):
    config = Configurator()
    config.include('myapp.myconfig.includeme')

Because the function is named includeme, the function name can also be omitted from the dotted name reference:

1
2
3
4
5

from pyramid.config import Configurator

def main(global_config, **settings):
    config = Configurator()
    config.include('myapp.myconfig')

Included configuration statements will be overridden by local configuration statements if an included callable causes a configuration conflict by registering something with the same configuration parameters.

add_directive(name, directive, action_wrap=True)

Add a directive method to the configurator.

Framework extenders can add directive methods to a configurator by instructing their users to call config.add_directive('somename', 'some.callable'). This will make some.callable accessible as config.somename. some.callable should be a function which accepts config as a first argument, and arbitrary positional and keyword arguments following. It should use config.action as necessary to perform actions. Directive methods can then be invoked like ‘built-in’ directives such as add_view, add_route, etc.

The action_wrap argument should be True for directives which perform config.action with potentially conflicting discriminators. action_wrap will cause the directive to be wrapped in a decorator which provides more accurate conflict cause information.

add_directive does not participate in conflict detection, and later calls to add_directive will override earlier calls.

with_package(package)

Return a new Configurator instance with the same registry as this configurator using the package supplied as the package argument to the new configurator. package may be an actual Python package object or a Python dotted name representing a package.

maybe_dotted(dotted)

Resolve the dotted Python name dotted to a global Python object. If dotted is not a string, return it without attempting to do any name resolution. If dotted is a relative dotted name (e.g. .foo.bar, consider it relative to the package argument supplied to this Configurator’s constructor.

absolute_asset_spec(relative_spec)

Resolve the potentially relative asset specification string passed as relative_spec into an absolute asset specification string and return the string. Use the package of this configurator as the package to which the asset specification will be considered relative when generating an absolute asset specification. If the provided relative_spec argument is already absolute, or if the relative_spec is not a string, it is simply returned.

setup_registry(settings=None, root_factory=None, authentication_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None)

When you pass a non-None registry argument to the Configurator constructor, no initial ‘setup’ is performed against the registry. This is because the registry you pass in may have already been initialized for use under Pyramid via a different configurator. However, in some circumstances (such as when you want to use the Zope ‘global` registry instead of a registry created as a result of the Configurator constructor), or when you want to reset the initial setup of a registry, you do want to explicitly initialize the registry associated with a Configurator for use under Pyramid. Use setup_registry to do this initialization.

setup_registry configures settings, a root factory, security policies, renderers, a debug logger, a locale negotiator, and various other settings using the configurator’s current registry, as per the descriptions in the Configurator constructor.

add_renderer(name, factory)

Add a Pyramid renderer factory to the current configuration state.

The name argument is the renderer name. Use None to represent the default renderer (a renderer which will be used for all views unless they name another renderer specifically).

The factory argument is Python reference to an implementation of a renderer factory or a dotted Python name to same.

Note that this function must be called before any add_view invocation that names the renderer name as an argument. As a result, it’s usually a better idea to pass globally used renderers into the Configurator constructor in the sequence of renderers passed as renderer than it is to use this method.

add_route(name, pattern=None, view=None, view_for=None, permission=None, factory=None, for_=None, header=None, xhr=False, accept=None, path_info=None, request_method=None, request_param=None, traverse=None, custom_predicates=(), view_permission=None, renderer=None, view_renderer=None, view_context=None, view_attr=None, use_global_views=False, path=None, pregenerator=None)

Add a route configuration to the current configuration state, as well as possibly a view configuration to be used to specify a view callable that will be invoked when this route matches. The arguments to this method are divided into predicate, non-predicate, and view-related types. Route predicate arguments narrow the circumstances in which a route will be match a request; non-predicate arguments are informational.

Non-Predicate Arguments

name

The name of the route, e.g. myroute. This attribute is required. It must be unique among all defined routes in a given application.

factory

A Python object (often a function or a class) or a dotted Python name which refers to the same object that will generate a Pyramid root resource object when this route matches. For example, mypackage.resources.MyFactory. If this argument is not specified, a default root factory will be used.

traverse

If you would like to cause the context to be something other than the root object when this route matches, you can spell a traversal pattern as the traverse argument. This traversal pattern will be used as the traversal path: traversal will begin at the root object implied by this route (either the global root, or the object returned by the factory associated with this route).

The syntax of the traverse argument is the same as it is for pattern. For example, if the pattern provided to add_route is articles/{article}/edit, and the traverse argument provided to add_route is /{article}, when a request comes in that causes the route to match in such a way that the article match value is ‘1’ (when the request URI is /articles/1/edit), the traversal path will be generated as /1. This means that the root object’s __getitem__ will be called with the name 1 during the traversal phase. If the 1 object exists, it will become the context of the request. Traversal has more information about traversal.

If the traversal path contains segment marker names which are not present in the pattern argument, a runtime error will occur. The traverse pattern should not contain segment markers that do not exist in the pattern argument.

A similar combining of routing and traversal is available when a route is matched which contains a *traverse remainder marker in its pattern (see Using *traverse In a Route Pattern). The traverse argument to add_route allows you to associate route patterns with an arbitrary traversal path without using a a *traverse remainder marker; instead you can use other match information.

Note that the traverse argument to add_route is ignored when attached to a route that has a *traverse remainder marker in its pattern.

pregenerator

This option should be a callable object that implements the pyramid.interfaces.IRoutePregenerator interface. A pregenerator is a callable called by the pyramid.url.route_url function to augment or replace the arguments it is passed when generating a URL for the route. This is a feature not often used directly by applications, it is meant to be hooked by frameworks that use Pyramid as a base.

Predicate Arguments

pattern

The pattern of the route e.g. ideas/{idea}. This argument is required. See Route Pattern Syntax for information about the syntax of route patterns. If the pattern doesn’t match the current URL, route matching continues.

Note

For backwards compatibility purposes (as of Pyramid 1.0), a path keyword argument passed to this function will be used to represent the pattern value if the pattern argument is None. If both path and pattern are passed, pattern wins.

xhr

This value should be either True or False. If this value is specified and is True, the request must possess an HTTP_X_REQUESTED_WITH (aka X-Requested-With) header for this route to match. This is useful for detecting AJAX requests issued from jQuery, Prototype and other Javascript libraries. If this predicate returns False, route matching continues.

request_method

A string representing an HTTP method name, e.g. GET, POST, HEAD, DELETE, PUT. If this argument is not specified, this route will match if the request has any request method. If this predicate returns False, route matching continues.

path_info

This value represents a regular expression pattern that will be tested against the PATH_INFO WSGI environment variable. If the regex matches, this predicate will return True. If this predicate returns False, route matching continues.

request_param

This value can be any string. A view declaration with this argument ensures that the associated route will only match when the request has a key in the request.params dictionary (an HTTP GET or POST variable) that has a name which matches the supplied value. If the value supplied as the argument has a = sign in it, e.g. request_params="foo=123", then the key (foo) must both exist in the request.params dictionary, and the value must match the right hand side of the expression (123) for the route to “match” the current request. If this predicate returns False, route matching continues.

header

This argument represents an HTTP header name or a header name/value pair. If the argument contains a : (colon), it will be considered a name/value pair (e.g. User-Agent:Mozilla/.* or Host:localhost). If the value contains a colon, the value portion should be a regular expression. If the value does not contain a colon, the entire value will be considered to be the header name (e.g. If-Modified-Since). If the value evaluates to a header name only without a value, the header specified by the name must be present in the request for this predicate to be true. If the value evaluates to a header name/value pair, the header specified by the name must be present in the request and the regular expression specified as the value must match the header value. Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant. If this predicate returns False, route matching continues.

accept

This value represents a match query for one or more mimetypes in the Accept HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form text/plain, a wildcard mimetype match token in the form text/* or a match-all wildcard mimetype match token in the form */*. If any of the forms matches the Accept header of the request, this predicate will be true. If this predicate returns False, route matching continues.

custom_predicates

This value should be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates does what you need. Custom predicates can be combined with predefined predicates as necessary. Each custom predicate callable should accept two arguments: info and request and should return either True or False after doing arbitrary evaluation of the info and/or the request. If all custom and non-custom predicate callables return True the associated route will be considered viable for a given request. If any predicate callable returns False, route matching continues. Note that the value info passed to a custom route predicate is a dictionary containing matching information; see Custom Route Predicates for more information about info.

View-Related Arguments

view

A Python object or dotted Python name to the same object that will be used as a view callable when this route matches. e.g. mypackage.views.my_view.

view_context

A class or an interface or dotted Python name to the same object which the context of the view should match for the view named by the route to be used. This argument is only useful if the view attribute is used. If this attribute is not specified, the default (None) will be used.

If the view argument is not provided, this argument has no effect.

This attribute can also be spelled as for_ or view_for.

view_permission

The permission name required to invoke the view associated with this route. e.g. edit. (see Using Pyramid Security With URL Dispatch for more information about permissions).

If the view attribute is not provided, this argument has no effect.

This argument can also be spelled as permission.

view_renderer

This is either a single string term (e.g. json) or a string implying a path or asset specification (e.g. templates/views.pt). If the renderer value is a single term (does not contain a dot .), the specified term will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the view return value. If the renderer term contains a dot (.), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path. The renderer implementation will be used to construct a response from the view return value. See Writing View Callables Which Use a Renderer for more information.

If the view argument is not provided, this argument has no effect.

This argument can also be spelled as renderer.

view_attr

The view machinery defaults to using the __call__ method of the view callable (or the function itself, if the view callable is a function) to obtain a response dictionary. The attr value allows you to vary the method attribute used to obtain the response. For example, if your view was a class, and the class has a method named index and you wanted to use this method instead of the class’ __call__ method to return the response, you’d say attr="index" in the view configuration for the view. This is most useful when the view definition is a class.

If the view argument is not provided, this argument has no effect.

use_global_views

When a request matches this route, and view lookup cannot find a view which has a route_name predicate argument that matches the route, try to fall back to using a view that otherwise matches the context, request, and view name (but which does not match the route_name predicate).

add_static_view(name, path, **kw)

Add a view used to render static assets such as images and CSS files.

The name argument is a string representing an application-relative local URL prefix. It may alternately be a full URL.

The path argument is the path on disk where the static files reside. This can be an absolute path, a package-relative path, or a asset specification.

The cache_max_age keyword argument is input to set the Expires and Cache-Control headers for static assets served. Note that this argument has no effect when the name is a url prefix. By default, this argument is None, meaning that no particular Expires or Cache-Control headers are set in the response.

The permission keyword argument is used to specify the permission required by a user to execute the static view. By default, it is the string __no_permission_required__. The __no_permission_required__ string is a special sentinel which indicates that, even if a default permission exists for the current application, the static view should be renderered to completely anonymous users. This default value is permissive because, in most web apps, static assets seldom need protection from viewing.

Usage

The add_static_view function is typically used in conjunction with the pyramid.url.static_url() function. add_static_view adds a view which renders a static asset when some URL is visited; pyramid.url.static_url() generates a URL to that asset.

The name argument to add_static_view is usually a view name. When this is the case, the pyramid.url.static_url() API will generate a URL which points to a Pyramid view, which will serve up a set of assets that live in the package itself. For example:

add_static_view('images', 'mypackage:images/')

Code that registers such a view can generate URLs to the view via pyramid.url.static_url():

static_url('mypackage:images/logo.png', request)

When add_static_view is called with a name argument that represents a URL prefix, as it is above, subsequent calls to pyramid.url.static_url() with paths that start with the path argument passed to add_static_view will generate a URL something like http://<Pyramid app URL>/images/logo.png, which will cause the logo.png file in the images subdirectory of the mypackage package to be served.

add_static_view can alternately be used with a name argument which is a URL, causing static assets to be served from an external webserver. This happens when the name argument is a fully qualified URL (e.g. starts with http:// or similar). In this mode, the name is used as the prefix of the full URL when generating a URL using pyramid.url.static_url(). For example, if add_static_view is called like so:

add_static_view('http://example.com/images', 'mypackage:images/')

Subsequently, the URLs generated by pyramid.url.static_url() for that static view will be prefixed with http://example.com/images:

static_url('mypackage:images/logo.png', request)

When add_static_view is called with a name argument that is the URL http://example.com/images, subsequent calls to pyramid.url.static_url() with paths that start with the path argument passed to add_static_view will generate a URL something like http://example.com/logo.png. The external webserver listening on example.com must be itself configured to respond properly to such a request.

See Serving Static Assets for more information.

add_settings(settings=None, **kw)

Augment the settings argument passed in to the Configurator constructor with one or more ‘setting’ key/value pairs. A setting is a single key/value pair in the dictionary-ish object returned from the API pyramid.registry.Registry.settings and pyramid.config.Configurator.get_settings().

You may pass a dictionary:

config.add_settings({'external_uri':'http://example.com'})

Or a set of key/value pairs:

config.add_settings(external_uri='http://example.com')

This function is useful when you need to test code that accesses the pyramid.registry.Registry.settings API (or the pyramid.config.Configurator.get_settings() API) and which uses values from that API.

add_subscriber(subscriber, iface=None)

Add an event subscriber for the event stream implied by the supplied iface interface. The subscriber argument represents a callable object (or a dotted Python name which identifies a callable); it will be called with a single object event whenever Pyramid emits an event associated with the iface, which may be an interface or a class or a dotted Python name to a global object representing an interface or a class. Using the default iface value, None will cause the subscriber to be registered for all event types. See Using Events for more information about events and subscribers.

add_translation_dirs(*specs)

Add one or more translation directory paths to the current configuration state. The specs argument is a sequence that may contain absolute directory paths (e.g. /usr/share/locale) or asset specification names naming a directory path (e.g. some.package:locale) or a combination of the two.

Example:

config.add_translation_dirs('/usr/share/locale',
                            'some.package:locale')

add_view(view=None, name='', for_=None, permission=None, request_type=None, route_name=None, request_method=None, request_param=None, containment=None, attr=None, renderer=None, wrapper=None, xhr=False, accept=None, header=None, path_info=None, custom_predicates=(), context=None, decorator=None, mapper=None)

Add a view configuration to the current configuration state. Arguments to add_view are broken down below into predicate arguments and non-predicate arguments. Predicate arguments narrow the circumstances in which the view callable will be invoked when a request is presented to Pyramid; non-predicate arguments are informational.

Non-Predicate Arguments

view

A view callable or a dotted Python name which refers to a view callable. This argument is required unless a renderer argument also exists. If a renderer argument is passed, and a view argument is not provided, the view callable defaults to a callable that returns an empty dictionary (see Writing View Callables Which Use a Renderer).

permission

The name of a permission that the user must possess in order to invoke the view callable. See Configuring View Security for more information about view security and permissions. If permission is omitted, a default permission may be used for this view registration if one was named as the pyramid.config.Configurator constructor’s default_permission argument, or if pyramid.config.Configurator.set_default_permission() was used prior to this view registration. Pass the string __no_permission_required__ as the permission argument to explicitly indicate that the view should always be executable by entirely anonymous users, regardless of the default permission, bypassing any authorization policy that may be in effect.

attr

The view machinery defaults to using the __call__ method of the view callable (or the function itself, if the view callable is a function) to obtain a response. The attr value allows you to vary the method attribute used to obtain the response. For example, if your view was a class, and the class has a method named index and you wanted to use this method instead of the class’ __call__ method to return the response, you’d say attr="index" in the view configuration for the view. This is most useful when the view definition is a class.

renderer

This is either a single string term (e.g. json) or a string implying a path or asset specification (e.g. templates/views.pt) naming a renderer implementation. If the renderer value does not contain a dot ., the specified string will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the view return value. If the renderer value contains a dot (.), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path. The renderer implementation will be used to construct a response from the view return value.

Note that if the view itself returns a response (see View Callable Responses), the specified renderer implementation is never called.

When the renderer is a path, although a path is usually just a simple relative pathname (e.g. templates/foo.pt, implying that a template named “foo.pt” is in the “templates” directory relative to the directory of the current package of the Configurator), a path can be absolute, starting with a slash on UNIX or a drive letter prefix on Windows. The path can alternately be a asset specification in the form some.dotted.package_name:relative/path, making it possible to address template assets which live in a separate package.

The renderer attribute is optional. If it is not defined, the “null” renderer is assumed (no rendering is performed and the value is passed back to the upstream Pyramid machinery unmolested).

wrapper

The view name of a different view configuration which will receive the response body of this view as the request.wrapped_body attribute of its own request, and the response returned by this view as the request.wrapped_response attribute of its own request. Using a wrapper makes it possible to “chain” views together to form a composite response. The response of the outermost wrapper view will be returned to the user. The wrapper view will be found as any view is found: see View Lookup and Invocation. The “best” wrapper view will be found based on the lookup ordering: “under the hood” this wrapper view is looked up via pyramid.view.render_view_to_response(context, request, 'wrapper_viewname'). The context and request of a wrapper view is the same context and request of the inner view. If this attribute is unspecified, no view wrapping is done.

decorator

A dotted Python name to function (or the function itself) which will be used to decorate the registered view callable. The decorator function will be called with the view callable as a single argument. The view callable it is passed will accept (context, request). The decorator must return a replacement view callable which also accepts (context, request).

mapper

A Python object or dotted Python name which refers to a view mapper, or None. By default it is None, which indicates that the view should use the default view mapper. This plug-point is useful for Pyramid extension developers, but it’s not very useful for ‘civilians’ who are just developing stock Pyramid applications. Pay no attention to the man behind the curtain.

Predicate Arguments

name

The view name. Read Traversal to understand the concept of a view name.

context

An object or a dotted Python name referring to an interface or class object that the context must be an instance of, or the interface that the context must provide in order for this view to be found and called. This predicate is true when the context is an instance of the represented class or if the context provides the represented interface; it is otherwise false. This argument may also be provided to add_view as for_ (an older, still-supported spelling).

route_name

This value must match the name of a route configuration declaration (see URL Dispatch) that must match before this view will be called. Note that the route configuration referred to by route_name usually has a *traverse token in the value of its path, representing a part of the path that will be used by traversal against the result of the route’s root factory.

Warning

Using this argument services an advanced feature that isn’t often used unless you want to perform traversal after a route has matched. See Combining Traversal and URL Dispatch for more information on using this advanced feature.

request_type

This value should be an interface that the request must provide in order for this view to be found and called. This value exists only for backwards compatibility purposes.

request_method

This value can either be one of the strings GET, POST, PUT, DELETE, or HEAD representing an HTTP REQUEST_METHOD. A view declaration with this argument ensures that the view will only be called when the request’s method attribute (aka the REQUEST_METHOD of the WSGI environment) string matches the supplied value.

request_param

This value can be any string. A view declaration with this argument ensures that the view will only be called when the request has a key in the request.params dictionary (an HTTP GET or POST variable) that has a name which matches the supplied value. If the value supplied has a = sign in it, e.g. request_params="foo=123", then the key (foo) must both exist in the request.params dictionary, and the value must match the right hand side of the expression (123) for the view to “match” the current request.

containment

This value should be a Python class or interface or a dotted Python name to such an object that a parent object in the lineage must provide in order for this view to be found and called. The nodes in your object graph must be “location-aware” to use this feature. See Location-Aware Resources for more information about location-awareness.

xhr

This value should be either True or False. If this value is specified and is True, the request must possess an HTTP_X_REQUESTED_WITH (aka X-Requested-With) header that has the value XMLHttpRequest for this view to be found and called. This is useful for detecting AJAX requests issued from jQuery, Prototype and other Javascript libraries.

accept

The value of this argument represents a match query for one or more mimetypes in the Accept HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form text/plain, a wildcard mimetype match token in the form text/* or a match-all wildcard mimetype match token in the form */*. If any of the forms matches the Accept header of the request, this predicate will be true.

header

This value represents an HTTP header name or a header name/value pair. If the value contains a : (colon), it will be considered a name/value pair (e.g. User-Agent:Mozilla/.* or Host:localhost). The value portion should be a regular expression. If the value does not contain a colon, the entire value will be considered to be the header name (e.g. If-Modified-Since). If the value evaluates to a header name only without a value, the header specified by the name must be present in the request for this predicate to be true. If the value evaluates to a header name/value pair, the header specified by the name must be present in the request and the regular expression specified as the value must match the header value. Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant.

path_info

This value represents a regular expression pattern that will be tested against the PATH_INFO WSGI environment variable. If the regex matches, this predicate will be True.

custom_predicates

This value should be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates do what you need. Custom predicates can be combined with predefined predicates as necessary. Each custom predicate callable should accept two arguments: context and request and should return either True or False after doing arbitrary evaluation of the context and/or the request. If all callables return True, the associated view callable will be considered viable for a given request.

derive_view(view, attr=None, renderer=None)

Create a view callable using the function, instance, or class (or dotted Python name referring to the same) provided as view object.

This is API is useful to framework extenders who create pluggable systems which need to register ‘proxy’ view callables for functions, instances, or classes which meet the requirements of being a Pyramid view callable. For example, a some_other_framework function in another framework may want to allow a user to supply a view callable, but he may want to wrap the view callable in his own before registering the wrapper as a Pyramid view callable. Because a Pyramid view callable can be any of a number of valid objects, the framework extender will not know how to call the user-supplied object. Running it through derive_view normalizes it to a callable which accepts two arguments: context and request.

For example:

def some_other_framework(user_supplied_view):
    config = Configurator(reg)
    proxy_view = config.derive_view(user_supplied_view)
    def my_wrapper(context, request):
        do_something_that_mutates(request)
        return proxy_view(context, request)
    config.add_view(my_wrapper)

The view object provided should be one of the following:

A function or another non-class callable object that accepts a request as a single positional argument and which returns a response object.

A function or other non-class callable object that accepts two positional arguments, context, request and which returns a response object.

A class which accepts a single positional argument in its constructor named request, and which has a __call__ method that accepts no arguments that returns a response object.

A class which accepts two positional arguments named context, request, and which has a __call__ method that accepts no arguments that returns a response object.

A dotted Python name which refers to any of the kinds of objects above.

This API returns a callable which accepts the arguments context, request and which returns the result of calling the provided view object.

The attr keyword argument is most useful when the view object is a class. It names the method that should be used as the callable. If attr is not provided, the attribute effectively defaults to __call__. See Defining a View Callable as a Class for more information.

The renderer keyword argument should be a renderer name. If supplied, it will cause the returned callable to use a renderer to convert the user-supplied view result to a response object. If a renderer argument is not supplied, the user-supplied view must itself return a response object.

make_wsgi_app()

Commits any pending configuration statements, sends a pyramid.events.ApplicationCreated event to all listeners, and returns a Pyramid WSGI application representing the committed configuration state.

override_asset(to_override, override_with, _override=None)

Add a Pyramid asset override to the current configuration state.

to_override is a asset specification to the asset being overridden.

override_with is a asset specification to the asset that is performing the override.

See Static Assets for more information about asset overrides.

scan(package=None, categories=None)

Scan a Python package and any of its subpackages for objects marked with configuration decoration such as pyramid.view.view_config. Any decorated object found will influence the current configuration state.

The package argument should be a Python package or module object (or a dotted Python name which refers to such a package or module). If package is None, the package of the caller is used.

The categories argument, if provided, should be the Venusian ‘scan categories’ to use during scanning. Providing this argument is not often necessary; specifying scan categories is an extremely advanced usage. By default, categories is None which will execute all Venusian decorator callbacks including Pyramid-related decorators such as pyramid.view.view_config. See the Venusian documentation for more information about limiting a scan by using an explicit set of categories.

set_forbidden_view(view=None, attr=None, renderer=None, wrapper=None)

Add a default forbidden view to the current configuration state.

Warning

This method has been deprecated in Pyramid 1.0. Do not use it for new development; it should only be used to support older code bases which depend upon it. See Changing the Forbidden View to see how a forbidden view should be registered in new projects.

The view argument should be a view callable or a dotted Python name which refers to a view callable.

The attr argument should be the attribute of the view callable used to retrieve the response (see the add_view method’s attr argument for a description).

The renderer argument should be the name of (or path to) a renderer used to generate a response for this view (see the pyramid.config.Configurator.add_view() method’s renderer argument for information about how a configurator relates to a renderer).

The wrapper argument should be the name of another view which will wrap this view when rendered (see the add_view method’s wrapper argument for a description).

set_notfound_view(view=None, attr=None, renderer=None, wrapper=None)

Add a default not found view to the current configuration state.

Warning

This method has been deprecated in Pyramid 1.0. Do not use it for new development; it should only be used to support older code bases which depend upon it. See Changing the Not Found View to see how a not found view should be registered in new projects.

The view argument should be a view callable or a dotted Python name which refers to a view callable.

The attr argument should be the attribute of the view callable used to retrieve the response (see the add_view method’s attr argument for a description).

The renderer argument should be the name of (or path to) a renderer used to generate a response for this view (see the pyramid.config.Configurator.add_view() method’s renderer argument for information about how a configurator relates to a renderer).

The wrapper argument should be the name of another view which will wrap this view when rendered (see the add_view method’s wrapper argument for a description).

set_locale_negotiator(negotiator)

Set the locale negotiator for this application. The locale negotiator is a callable which accepts a request object and which returns a locale name. The negotiator argument should be the locale negotiator implementation or a dotted Python name which refers to such an implementation.

Later calls to this method override earlier calls; there can be only one locale negotiator active at a time within an application. See Activating Translation for more information.

Note

Using the locale_negotiator argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_default_permission(permission)

Set the default permission to be used by all subsequent view configuration registrations. permission should be a permission string to be used as the default permission. An example of a permission string:'view'. Adding a default permission makes it unnecessary to protect each view configuration with an explicit permission, unless your application policy requires some exception for a particular view.

If a default permission is not set, views represented by view configuration registrations which do not explicitly declare a permission will be executable by entirely anonymous users (any authorization policy is ignored).

Later calls to this method override will conflict with earlier calls; there can be only one default permission active at a time within an application.

Warning

If a default permission is in effect, view configurations meant to create a truly anonymously accessible view (even exception view views) must use the explicit permission string __no_permission_required__ as the permission. When this string is used as the permission for a view configuration, the default permission is ignored, and the view is registered, making it available to all callers regardless of their credentials.

See also Setting a Default Permission.

Note

Using the default_permission argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_session_factory(session_factory)

Configure the application with a session factory. If this method is called, the session_factory argument must be a session factory callable.

set_request_factory(factory)

The object passed as factory should be an object (or a dotted Python name which refers to an object) which will be used by the Pyramid router to create all request objects. This factory object must have the same methods and attributes as the pyramid.request.Request class (particularly __call__, and blank).

Note

Using the :meth:request_factory argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_renderer_globals_factory(factory)

The object passed as factory should be an callable (or a dotted Python name which refers to an callable) that will be used by the Pyramid rendering machinery as a renderers global factory (see Adding Renderer Globals).

The factory callable must accept a single argument named system (which will be a dictionary) and it must return a dictionary. When an application uses a renderer, the factory’s return dictionary will be merged into the system dictionary, and therefore will be made available to the code which uses the renderer.

Note

Using the renderer_globals_factory() argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

testing_securitypolicy(userid=None, groupids=(), permissive=True)

Unit/integration testing helper: Registers a pair of faux Pyramid security policies: a authentication policy and a authorization policy.

The behavior of the registered authorization policy depends on the permissive argument. If permissive is true, a permissive authorization policy is registered; this policy allows all access. If permissive is false, a nonpermissive authorization policy is registered; this policy denies all access.

The behavior of the registered authentication policy depends on the values provided for the userid and groupids argument. The authentication policy will return the userid identifier implied by the userid argument and the group ids implied by the groupids argument when the pyramid.security.authenticated_userid() or pyramid.security.effective_principals() APIs are used.

This function is most useful when testing code that uses the APIs named pyramid.security.has_permission(), pyramid.security.authenticated_userid(), pyramid.security.effective_principals(), and pyramid.security.principals_allowed_by_permission().

testing_resources(resources)

Unit/integration testing helper: registers a dictionary of resource objects that can be resolved via the pyramid.traversal.find_resource() API.

The pyramid.traversal.find_resource() API is called with a path as one of its arguments. If the dictionary you register when calling this method contains that path as a string key (e.g. /foo/bar or foo/bar), the corresponding value will be returned to find_resource (and thus to your code) when pyramid.traversal.find_resource() is called with an equivalent path string or tuple.

testing_add_subscriber(event_iface=None)

Unit/integration testing helper: Registers a subscriber which listens for events of the type event_iface. This method returns a list object which is appended to by the subscriber whenever an event is captured.

When an event is dispatched that matches the value implied by the event_iface argument, that event will be appended to the list. You can then compare the values in the list to expected event notifications. This method is useful when testing code that wants to call pyramid.registry.Registry.notify(), or zope.component.event.dispatch().

The default value of event_iface (None) implies a subscriber registered for any kind of event.

testing_add_renderer(path, renderer=None)

Unit/integration testing helper: register a renderer at path (usually a relative filename ala templates/foo.pt or an asset specification) and return the renderer object. If the renderer argument is None, a ‘dummy’ renderer will be used. This function is useful when testing code that calls the pyramid.renderers.render() function or pyramid.renderers.render_to_response() function or any other render_* or get_* API of the pyramid.renderers module.

Note that calling this method for with a path argument representing a renderer factory type (e.g. for foo.pt usually implies the chameleon_zpt renderer factory) clobbers any existing renderer factory registered for that type.

Note

This method is also available under the alias testing_add_template (an older name for it).

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.events

Functions

subscriber(*ifaces)

Decorator activated via a scan which treats the function being decorated as an event subscriber for the set of interfaces passed as *ifaces to the decorator constructor.

For example:

from pyramid.events import NewRequest
from pyramid.events import subscriber

@subscriber(NewRequest)
def mysubscriber(event):
    event.request.foo = 1

More than one event type can be passed as a construtor argument:

from pyramid.events import NewRequest, NewResponse
from pyramid.events import subscriber

@subscriber(NewRequest, NewResponse)
def mysubscriber(event):
    print event

When the subscriber decorator is used without passing an arguments, the function it decorates is called for every event sent:

from pyramid.events import subscriber

@subscriber()
def mysubscriber(event):
    print event

This method will have no effect until a scan is performed against the package or module which contains it, ala:

from pyramid.config import Configurator
config = Configurator()
config.scan('somepackage_containing_subscribers')

Event Types

class ApplicationCreated(app)

An instance of this class is emitted as an event when the pyramid.config.Configurator.make_wsgi_app() is called. The instance has an attribute, app, which is an instance of the router that will handle WSGI requests. This class implements the pyramid.interfaces.IApplicationCreated interface.

Note

For backwards compatibility purposes, this class can also be imported as pyramid.events.WSGIApplicationCreatedEvent. This was the name of the event class before Pyramid 1.0.

class NewRequest(request)

An instance of this class is emitted as an event whenever Pyramid begins to process a new request. The even instance has an attribute, request, which is a request object. This event class implements the pyramid.interfaces.INewRequest interface.

class ContextFound(request)

An instance of this class is emitted as an event after the Pyramid router finds a context object (after it performs traversal) but before any view code is executed. The instance has an attribute, request, which is the request object generated by Pyramid.

Notably, the request object will have an attribute named context, which is the context that will be provided to the view which will eventually be called, as well as other attributes attached by context-finding code.

This class implements the pyramid.interfaces.IContextFound interface.

Note

As of Pyramid 1.0, for backwards compatibility purposes, this event may also be imported as pyramid.events.AfterTraversal.

class NewResponse(request, response)

An instance of this class is emitted as an event whenever any Pyramid view or exception view returns a response.

The instance has two attributes:request, which is the request which caused the response, and response, which is the response object returned by a view or renderer.

If the response was generated by an exception view, the request will have an attribute named exception, which is the exception object which caused the exception view to be executed. If the response was generated by a ‘normal’ view, the request will not have this attribute.

This event will not be generated if a response cannot be created due to an exception that is not caught by an exception view (no response is created under this circumstace).

This class implements the pyramid.interfaces.INewResponse interface.

Note

Postprocessing a response is usually better handled in a WSGI middleware component than in subscriber code that is called by a pyramid.interfaces.INewResponse event. The pyramid.interfaces.INewResponse event exists almost purely for symmetry with the pyramid.interfaces.INewRequest event.

class BeforeRender(system)

get(k, default=None)

Return the value for key k from the renderer globals dictionary, or the default if no such value exists.

update(d)

Update the renderer globals dictionary with another dictionary d. If any of the key names in the source dictionary already exist in the target dictionary, a KeyError will be raised

See Using Events for more information about how to register code which subscribes to these events.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.exceptions

class Forbidden(message='')

Raise this exception within view code to immediately return the forbidden view to the invoking user. Usually this is a basic 403 page, but the forbidden view can be customized as necessary. See Changing the Forbidden View.

This exception’s constructor accepts a single positional argument, which should be a string. The value of this string will be placed onto the request by the router as the exception_message attribute, for availability to the Forbidden View.

class NotFound(message='')

Raise this exception within view code to immediately return the Not Found view to the invoking user. Usually this is a basic 404 page, but the Not Found view can be customized as necessary. See Changing the Not Found View.

This exception’s constructor accepts a single positional argument, which should be a string. The value of this string will be placed into the WSGI environment by the router as the exception_message attribute, for availability to the Not Found View.

class ConfigurationError

Raised when inappropriate input values are supplied to an API method of a Configurator

class URLDecodeError

This exception is raised when Pyramid cannot successfully decode a URL or a URL path segment. This exception it behaves just like the Python builtin UnicodeDecodeError. It is a subclass of the builtin UnicodeDecodeError exception only for identity purposes, mostly so an exception view can be registered when a URL cannot be decoded.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.httpexceptions

HTTP Exception

This module processes Python exceptions that relate to HTTP exceptions by defining a set of exceptions, all subclasses of HTTPException. Each exception, in addition to being a Python exception that can be raised and caught, is also a WSGI application and webob.Response object.

This module defines exceptions according to RFC 2068 [1] : codes with 100-300 are not really errors; 400’s are client errors, and 500’s are server errors. According to the WSGI specification [2] , the application can call start_response more then once only under two conditions: (a) the response has not yet been sent, or (b) if the second and subsequent invocations of start_response have a valid exc_info argument obtained from sys.exc_info(). The WSGI specification then requires the server or gateway to handle the case where content has been sent and then an exception was encountered.

Exception

HTTPException

HTTPOk

200 - HTTPOk

201 - HTTPCreated

202 - HTTPAccepted

203 - HTTPNonAuthoritativeInformation

204 - HTTPNoContent

205 - HTTPResetContent

206 - HTTPPartialContent

HTTPRedirection

300 - HTTPMultipleChoices

301 - HTTPMovedPermanently

302 - HTTPFound

303 - HTTPSeeOther

304 - HTTPNotModified

305 - HTTPUseProxy

306 - Unused (not implemented, obviously)

307 - HTTPTemporaryRedirect

HTTPError

HTTPClientError

400 - HTTPBadRequest

401 - HTTPUnauthorized

402 - HTTPPaymentRequired

403 - HTTPForbidden

404 - HTTPNotFound

405 - HTTPMethodNotAllowed

406 - HTTPNotAcceptable

407 - HTTPProxyAuthenticationRequired

408 - HTTPRequestTimeout

409 - HTTPConflict

410 - HTTPGone

411 - HTTPLengthRequired

412 - HTTPPreconditionFailed

413 - HTTPRequestEntityTooLarge

414 - HTTPRequestURITooLong

415 - HTTPUnsupportedMediaType

416 - HTTPRequestRangeNotSatisfiable

417 - HTTPExpectationFailed

HTTPServerError

500 - HTTPInternalServerError

501 - HTTPNotImplemented

502 - HTTPBadGateway

503 - HTTPServiceUnavailable

504 - HTTPGatewayTimeout

505 - HTTPVersionNotSupported

Subclass usage notes:

The HTTPException class is complicated by 4 factors:

The content given to the exception may either be plain-text or as html-text.

The template may want to have string-substitutions taken from the current environ or values from incoming headers. This is especially troublesome due to case sensitivity.

The final output may either be text/plain or text/html mime-type as requested by the client application.

Each exception has a default explanation, but those who raise exceptions may want to provide additional detail.

Subclass attributes and call parameters are designed to provide an easier path through the complications.

Attributes:

code

the HTTP status code for the exception

title

remainder of the status line (stuff after the code)

explanation

a plain-text explanation of the error message that is not subject to environment or header substitutions; it is accessible in the template via %(explanation)s

detail

a plain-text message customization that is not subject to environment or header substitutions; accessible in the template via %(detail)s

body_template

a content fragment (in HTML) used for environment and header substitution; the default template includes both the explanation and further detail provided in the message

Parameters:

detail

a plain-text override of the default detail

headers

a list of (k,v) header pairs

comment

a plain-text additional information which is usually stripped/hidden for end-users

body_template

a string.Template object containing a content fragment in HTML that frames the explanation and further detail

To override the template (which is HTML content) or the plain-text explanation, one must subclass the given exception; or customize it after it has been created. This particular breakdown of a message into explanation, detail and template allows both the creation of plain-text and html messages for various clients as well as error-free substitution of environment variables and headers.

The subclasses of _HTTPMove (HTTPMultipleChoices, HTTPMovedPermanently, HTTPFound, HTTPSeeOther, HTTPUseProxy and HTTPTemporaryRedirect) are redirections that require a Location field. Reflecting this, these subclasses have two additional keyword arguments: location and add_slash.

Parameters:

location

to set the location immediately

add_slash

set to True to redirect to the same URL as the request, except with a / appended

Relative URLs in the location will be resolved to absolute.

References:

[1]
http://www.python.org/peps/pep-0333.html#error-handling

[2]
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5

status_map

A mapping of integer status code to exception class (eg. the integer “401” maps to pyramid.httpexceptions.HTTPUnauthorized).

class HTTPException(message, wsgi_response)

Exception used on pre-Python-2.5, where new-style classes cannot be used as an exception.

class HTTPOk(detail=None, headers=None, comment=None, body_template=None, **kw)

Base class for the 200’s status code (successful responses)

code: 200, title: OK

class HTTPRedirection(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for 300’s status code (redirections)

This is an abstract base class for 3xx redirection. It indicates that further action needs to be taken by the user agent in order to fulfill the request. It does not necessarly signal an error condition.

class HTTPError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for status codes in the 400’s and 500’s

This is an exception which indicates that an error has occurred, and that any work in progress should not be committed. These are typically results in the 400’s and 500’s.

class HTTPClientError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for the 400’s, where the client is in error

This is an error condition in which the client is presumed to be in-error. This is an expected problem, and thus is not considered a bug. A server-side traceback is not warranted. Unless specialized, this is a ‘400 Bad Request’

class HTTPServerError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for the 500’s, where the server is in-error

This is an error condition in which the server is presumed to be in-error. This is usually unexpected, and thus requires a traceback; ideally, opening a support ticket for the customer. Unless specialized, this is a ‘500 Internal Server Error’

class HTTPCreated(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that request has been fulfilled and resulted in a new resource being created.

code: 201, title: Created

class HTTPAccepted(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the request has been accepted for processing, but the processing has not been completed.

code: 202, title: Accepted

class HTTPNonAuthoritativeInformation(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy.

code: 203, title: Non-Authoritative Information

class HTTPNoContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.

code: 204, title: No Content

class HTTPResetContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the the server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent.

code: 205, title: Reset Content

class HTTPPartialContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the server has fulfilled the partial GET request for the resource.

code: 206, title: Partial Content

class HTTPMultipleChoices(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource corresponds to any one of a set of representations, each with its own specific location, and agent-driven negotiation information is being provided so that the user can select a preferred representation and redirect its request to that location.

code: 300, title: Multiple Choices

class HTTPMovedPermanently(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs.

code: 301, title: Moved Permanently

class HTTPFound(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 302, title: Found

class HTTPSeeOther(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource.

code: 303, title: See Other

class HTTPNotModified(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPRedirection

This indicates that if the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code.

code: 304, title: Not Modified

class HTTPUseProxy(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource MUST be accessed through the proxy given by the Location field.

code: 305, title: Use Proxy

class HTTPTemporaryRedirect(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 307, title: Temporary Redirect

class HTTPBadRequest(detail=None, headers=None, comment=None, body_template=None, **kw)

class HTTPUnauthorized(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the request requires user authentication.

code: 401, title: Unauthorized

class HTTPPaymentRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

code: 402, title: Payment Required

class HTTPForbidden(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server understood the request, but is refusing to fulfill it.

code: 403, title: Forbidden

class HTTPNotFound(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server did not find anything matching the Request-URI.

code: 404, title: Not Found

class HTTPMethodNotAllowed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

code: 405, title: Method Not Allowed

class HTTPNotAcceptable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates the resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

code: 406, title: Not Acceptable

class HTTPProxyAuthenticationRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This is similar to 401, but indicates that the client must first authenticate itself with the proxy.

code: 407, title: Proxy Authentication Required

class HTTPRequestTimeout(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the client did not produce a request within the time that the server was prepared to wait.

code: 408, title: Request Timeout

class HTTPConflict(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the request could not be completed due to a conflict with the current state of the resource.

code: 409, title: Conflict

class HTTPGone(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the requested resource is no longer available at the server and no forwarding address is known.

code: 410, title: Gone

class HTTPLengthRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the the server refuses to accept the request without a defined Content-Length.

code: 411, title: Length Required

class HTTPPreconditionFailed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.

code: 412, title: Precondition Failed

class HTTPRequestEntityTooLarge(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to process a request because the request entity is larger than the server is willing or able to process.

code: 413, title: Request Entity Too Large

class HTTPRequestURITooLong(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.

code: 414, title: Request-URI Too Long

class HTTPUnsupportedMediaType(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

code: 415, title: Unsupported Media Type

class HTTPRequestRangeNotSatisfiable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

The server SHOULD return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field.

code: 416, title: Request Range Not Satisfiable

class HTTPExpectationFailed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indidcates that the expectation given in an Expect request-header field could not be met by this server.

code: 417, title: Expectation Failed

class HTTPInternalServerError(detail=None, headers=None, comment=None, body_template=None, **kw)

class HTTPNotImplemented(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server does not support the functionality required to fulfill the request.

code: 501, title: Not Implemented

class HTTPBadGateway(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

code: 502, title: Bad Gateway

class HTTPServiceUnavailable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

code: 503, title: Service Unavailable

class HTTPGatewayTimeout(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

code: 504, title: Gateway Timeout

class HTTPVersionNotSupported(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server does not support, or refuses to support, the HTTP protocol version that was used in the request message.

code: 505, title: HTTP Version Not Supported

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.i18n

class TranslationString

The constructor for a translation string. A translation string is a Unicode-like object that has some extra metadata.

This constructor accepts one required argument named msgid. msgid must be the message identifier for the translation string. It must be a unicode object or a str object encoded in the default system encoding.

Optional keyword arguments to this object’s constructor include domain, default, and mapping.

domain represents the translation domain. By default, the translation domain is None, indicating that this translation string is associated with the default translation domain (usually messages).

default represents an explicit default text for this translation string. Default text appears when the translation string cannot be translated. Usually, the msgid of a translation string serves double duty as as its default text. However, using this option you can provide a different default text for this translation string. This feature is useful when the default of a translation string is too complicated or too long to be used as a message identifier. If default is provided, it must be a unicode object or a str object encoded in the default system encoding (usually means ASCII). If default is None (its default value), the msgid value used by this translation string will be assumed to be the value of default.

mapping, if supplied, must be a dictionary-like object which represents the replacement values for any translation string replacement marker instances found within the msgid (or default) value of this translation string.

After a translation string is constructed, it behaves like most other unicode objects; its msgid value will be displayed when it is treated like a unicode object. Only when its ugettext method is called will it be translated.

Its default value is available as the default attribute of the object, its translation domain is available as the domain attribute, and the mapping is available as the mapping attribute. The object otherwise behaves much like a Unicode string.

class TranslationStringFactory

Create a factory which will generate translation strings without requiring that each call to the factory be passed a domain value. A single argument is passed to this class’ constructor: domain. This value will be used as the domain values of translationstring.TranslationString objects generated by the __call__ of this class. The msgid, mapping, and default values provided to the __call__ method of an instance of this class have the meaning as described by the constructor of the translationstring.TranslationString

class Localizer(locale_name, translations)

An object providing translation and pluralizations related to

the current request’s locale name. A pyramid.i18n.Localizer object is created using the pyramid.i18n.get_localizer() function.

locale_name

The locale name for this localizer (e.g. en or en_US).

pluralize(singular, plural, n, domain=None, mapping=None)

Return a Unicode string translation by using two message identifier objects as a singular/plural pair and an n value representing the number that appears in the message using gettext plural forms support. The singular and plural objects passed may be translation strings or unicode strings. n represents the number of elements. domain is the translation domain to use to do the pluralization, and mapping is the interpolation mapping that should be used on the result. Note that if the objects passed are translation strings, their domains and mappings are ignored. The domain and mapping arguments must be used instead. If the domain is not supplied, a default domain is used (usually messages).

Example:

num = 1
translated = localizer.pluralize('Add ${num} item',
                                 'Add ${num} items',
                                 num,
                                 mapping={'num':num})

translate(tstring, domain=None, mapping=None)

Translate a translation string to the current language and interpolate any replacement markers in the result. The translate method accepts three arguments: tstring (required), domain (optional) and mapping (optional). When called, it will translate the tstring translation string to a unicode object using the current locale. If the current locale could not be determined, the result of interpolation of the default value is returned. The optional domain argument can be used to specify or override the domain of the tstring (useful when tstring is a normal string rather than a translation string). The optional mapping argument can specify or override the tstring interpolation mapping, useful when the tstring argument is a simple string instead of a translation string.

Example:

from pyramid.18n import TranslationString
ts = TranslationString('Add ${item}', domain='mypackage',
                       mapping={'item':'Item'})
translated = localizer.translate(ts)

Example:

translated = localizer.translate('Add ${item}', domain='mypackage',
                                 mapping={'item':'Item'})

get_localizer(request)

Retrieve a pyramid.i18n.Localizer object corresponding to the current request’s locale name.

negotiate_locale_name(request)

Negotiate and return the locale name associated with the current request (never cached).

get_locale_name(request)

Return the locale name associated with the current request (possibly cached).

default_locale_negotiator(request)

The default locale negotiator. Returns a locale name or None.

First, the negotiator looks for the _LOCALE_ attribute of the request object (possibly set by a view or a listener for an event).

Then it looks for the request.params['_LOCALE_'] value.

Then it looks for the request.cookies['_LOCALE_'] value.

Finally, the negotiator returns None if the locale could not be determined via any of the previous checks (when a locale negotiator returns None, it signifies that the default locale name should be used.)

See Internationalization and Localization for more information about using Pyramid internationalization and localization services within an application.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.interfaces

Event-Related Interfaces

interface IApplicationCreated

Event issued when the pyramid.config.Configurator.make_wsgi_app() method is called. See the documentation attached to pyramid.events.ApplicationCreated for more information.

Note

For backwards compatibility with Pyramid versions before 1.0, this interface can also be imported as pyramid.interfaces.IWSGIApplicationCreatedEvent.

app

Created application

interface INewRequest

An event type that is emitted whenever Pyramid begins to process a new request. See the documentation attached to pyramid.events.NewRequest for more information.

request

The request object

interface IContextFound

An event type that is emitted after Pyramid finds a context object but before it calls any view code. See the documentation attached to pyramid.events.ContextFound for more information.

Note

For backwards compatibility with versions of Pyramid before 1.0, this event interface can also be imported as pyramid.interfaces.IAfterTraversal.

request

The request object

interface INewResponse

An event type that is emitted whenever any Pyramid view returns a response. See the documentation attached to pyramid.events.NewResponse for more information.

request

The request object

response

The response object

interface IBeforeRender

Subscribers to this event may introspect the and modify the set of renderer globals before they are passed to a renderer. This event object iself has a dictionary-like interface that can be used for this purpose. For example:

from repoze.events import subscriber
from pyramid.interfaces import IBeforeRender

@subscriber(IBeforeRender)
def add_global(event):
    event['mykey'] = 'foo'

See also Using The Before Render Event.

__getitem__(k)

Return the value for key k from the renderer globals dictionary.

__contains__(k)

Return True if k exists in the renderer globals dictionary.

get(k, default=None)

Return the value for key k from the renderer globals dictionary, or the default if no such value exists.

update(d)

Update the renderer globals dictionary with another dictionary d. If any of the key names in the source dictionary already exist in the target dictionary, a KeyError will be raised

__setitem__(name, value)

Set a name/value pair into the dictionary which is passed to a renderer as the renderer globals dictionary. If the name already exists in the target dictionary, a KeyError will be raised.

Other Interfaces

interface IExceptionResponse

Extends: pyramid.interfaces.IException, pyramid.interfaces.IResponse

An interface representing a WSGI response which is also an exception object. Register an exception view using this interface as a context to apply the registered view for all exception types raised by Pyramid internally (pyramid.exceptions.NotFound and pyramid.exceptions.Forbidden).

interface IRoute

Interface representing the type of object returned from IRoutesMapper.get_route

name

The route name

pattern

The route pattern

factory

The root factory used by the Pyramid router when this route matches (or None)

generate(kw)

Generate a URL based on filling in the dynamic segment markers in the pattern using the kw dictionary provided.

pregenerator

This attribute should either be None or a callable object implementing the IRoutePregenerator interface

predicates

A sequence of route predicate objects used to determine if a request matches this route or not or not after basic pattern matching has been completed.

match(path)

If the path passed to this function can be matched by the pattern of this route, return a dictionary (the ‘matchdict’), which will contain keys representing the dynamic segment markers in the pattern mapped to values extracted from the provided path.

If the path passed to this function cannot be matched by the pattern of this route, return None.

interface IRoutePregenerator

__call__(request, elements, kw)

A pregenerator is a function associated by a developer with a route. The pregenerator for a route is called by pyramid.url.route_url() in order to adjust the set of arguments passed to it by the user for special purposes, such as Pylons ‘subdomain’ support. It will influence the URL returned by route_url.

A pregenerator should return a two-tuple of (elements, kw) after examining the originals passed to this function, which are the arguments (request, elements, kw). The simplest pregenerator is:

def pregenerator(request, elements, kw):
    return elements, kw

You can employ a pregenerator by passing a pregenerator argument to the pyramid.config.Configurator.add_route() function.

interface ISession

An interface representing a session (a web session object, usually accessed via request.session.

Keys and values of a session must be pickleable.

invalidate()

Invalidate the session. The action caused by invalidate is implementation-dependent, but it should have the effect of completely dissociating any data stored in the session with the current request. It might set response values (such as one which clears a cookie), or it might not.

new_csrf_token()

Create and set into the session a new, random cross-site request forgery protection token. Return the token. It will be a string.

pop(k, *args)

remove specified key and return the corresponding value *args may contain a single default value, or may not be supplied. If key is not found, default is returned if given, otherwise KeyError is raised

get_csrf_token()

Return a random cross-site request forgery protection token. It will be a string. If a token was previously added to the session via new_csrf_token, that token will be returned. If no CSRF token was previously set into the session, new_csrf_token will be called, which will create and set a token, and this token will be returned.

__contains__(key)

Return true if a key exists in the mapping.

flash(msg, queue='', allow_duplicate=True)

Push a flash message onto the end of the flash queue represented by queue. An alternate flash message queue can used by passing an optional queue, which must be a string. If allow_duplicate is false, if the msg already exists in the queue, it will not be readded.

peek_flash(queue='')

Peek at a queue in the flash storage. The queue remains in flash storage after this message is called. The queue is returned; it is a list of flash messages added by pyramid.interfaces.ISesssion.flash()

itervalues()

iterate over values

new

Boolean attribute. If True, the session is new.

__len__()

Return the number of items in the session.

__getitem__(key)

Get a value for a key

A KeyError is raised if there is no value for the key.

get(key, default=None)

Get a value for a key

The default is returned if there is no value for the key.

keys()

Return the keys of the mapping object.

update(d)

Update D from E: for k in E.keys(): D[k] = E[k]

__setitem__(key, value)

Set a new item in the mapping.

iteritems()

iterate over items

popitem()

remove and return some (key, value) pair as a 2-tuple; but raise KeyError if mapping is empty

iterkeys()

iterate over keys; equivalent to __iter__

pop_flash(queue='')

Pop a queue from the flash storage. The queue is removed from flash storage after this message is called. The queue is returned; it is a list of flash messages added by pyramid.interfaces.ISesssion.flash()

__delitem__(key)

Delete a value from the mapping using the key.

A KeyError is raised if there is no value for the key.

setdefault(key, default=None)

D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D

created

Integer representing Epoch time when created.

items()

Return the items of the mapping object.

clear()

delete all items

changed()

Mark the session as changed. A user of a session should call this method after he or she mutates a mutable object that is a value of the session (it should not be required after mutating the session itself). For example, if the user has stored a dictionary in the session under the key foo, and he or she does session['foo'] = {}, changed() needn’t be called. However, if subsequently he or she does session['foo']['a'] = 1, changed() must be called for the sessioning machinery to notice the mutation of the internal dictionary.

__iter__()

Return an iterator for the keys of the mapping object.

values()

Return the values of the mapping object.

interface ISessionFactory

An interface representing a factory which accepts a request object and returns an ISession object

__call__(request)

Return an ISession object

interface IRendererInfo

An object implementing this interface is passed to every renderer factory constructor as its only argument (conventionally named info)

name

The value passed by the user as the renderer name

package

The “current package” when the renderer configuration statement was found

settings

The deployment settings dictionary related to the current application

registry

The “current” application registry when the renderer was created

type

The renderer type name

interface ITemplateRenderer

Extends: pyramid.interfaces.IRenderer

implementation()

Return the object that the underlying templating system uses to render the template; it is typically a callable that accepts arbitrary keyword arguments and returns a string or unicode object

interface IViewMapperFactory

__call__(self, **kw)

Return an object which implements pyramid.interfaces.IViewMapper. kw will be a dictionary containing view-specific arguments, such as permission, predicates, attr, renderer, and other items. An IViewMapperFactory is used by pyramid.config.Configurator.add_view() to provide a plugpoint to extension developers who want to modify potential view callable invocation signatures and response values.

interface IViewMapper

__call__(self, object)

Provided with an arbitrary object (a function, class, or instance), returns a callable with the call signature (context, request). The callable returned should itself return a Response object. An IViewMapper is returned by pyramid.interfaces.IViewMapperFactory.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.location

lineage(resource)

Return a generator representing the lineage of the resource object implied by the resource argument. The generator first returns resource unconditionally. Then, if resource supplies a __parent__ attribute, return the resource represented by resource.__parent__. If that resource has a __parent__ attribute, return that resource’s parent, and so on, until the resource being inspected either has no __parent__ attribute or which has a __parent__ attribute of None. For example, if the resource tree is:

thing1 = Thing()
thing2 = Thing()
thing2.__parent__ = thing1

Calling lineage(thing2) will return a generator. When we turn it into a list, we will get:

list(lineage(thing2))
[ <Thing object at thing2>, <Thing object at thing1> ]

inside(resource1, resource2)

Is resource1 ‘inside’ resource2? Return True if so, else False.

resource1 is ‘inside’ resource2 if resource2 is a lineage ancestor of resource1. It is a lineage ancestor if its parent (or one of its parent’s parents, etc.) is an ancestor.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.paster

get_app(config_file, name)

Return the WSGI application named name in the PasteDeploy config file config_file.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.registry

class Registry(name='', bases=())

A registry object is an application registry. The existence of a registry implementation detail of pyramid. It is used by the framework itself to perform mappings of URLs to view callables, as well as servicing other various duties. Despite being an implementation detail of the framework, it has a number of attributes that may be useful within application code.

For information about the purpose and usage of the application registry, see Using the Zope Component Architecture in Pyramid.

The application registry is usually accessed as request.registry in application code.

settings

The dictionary-like deployment settings object. See Deployment Settings for information. This object is often accessed as request.registry.settings or config.registry.settings in a typical Pyramid application.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.renderers

get_renderer(renderer_name, package=None)

Return the renderer object for the renderer named as renderer_name.

You may supply a relative asset spec as renderer_name. If the package argument is supplied, a relative renderer name will be converted to an absolute asset specification by combining the package supplied as package with the relative asset specification supplied as renderer_name. If you do not supply a package (or package is None) the package name of the caller of this function will be used as the package.

render(renderer_name, value, request=None, package=None)

Using the renderer specified as renderer_name (a template or a static renderer) render the value (or set of values) present in value. Return the result of the renderer’s __call__ method (usually a string or Unicode).

If the renderer name refers to a file on disk (such as when the renderer is a template), it’s usually best to supply the name as a asset specification (e.g. packagename:path/to/template.pt).

You may supply a relative asset spec as renderer_name. If the package argument is supplied, a relative renderer path will be converted to an absolute asset specification by combining the package supplied as package with the relative asset specification supplied as renderer_name. If you do not supply a package (or package is None) the package name of the caller of this function will be used as the package.

The value provided will be supplied as the input to the renderer. Usually, for template renderings, this should be a dictionary. For other renderers, this will need to be whatever sort of value the renderer expects.

The ‘system’ values supplied to the renderer will include a basic set of top-level system names, such as request, context, and renderer_name. If renderer globals have been specified, these will also be used to agument the value.

Supply a request parameter in order to provide the renderer with the most correct ‘system’ values (request and context in particular).

render_to_response(renderer_name, value, request=None, package=None)

Using the renderer specified as renderer_name (a template or a static renderer) render the value (or set of values) using the result of the renderer’s __call__ method (usually a string or Unicode) as the response body.

If the renderer name refers to a file on disk (such as when the renderer is a template), it’s usually best to supply the name as a asset specification.

You may supply a relative asset spec as renderer_name. If the package argument is supplied, a relative renderer name will be converted to an absolute asset specification by combining the package supplied as package with the relative asset specification supplied as renderer_name. If you do not supply a package (or package is None) the package name of the caller of this function will be used as the package.

The value provided will be supplied as the input to the renderer. Usually, for template renderings, this should be a dictionary. For other renderers, this will need to be whatever sort of value the renderer expects.

The ‘system’ values supplied to the renderer will include a basic set of top-level system names, such as request, context, and renderer_name. If renderer globals have been specified, these will also be used to agument the value.

Supply a request parameter in order to provide the renderer with the most correct ‘system’ values (request and context in particular).

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.request

class Request(environ=None, environ_getter=None, charset=(No Default), unicode_errors=(No Default), decode_param_names=(No Default), **kw)

A subclass of the WebOb Request class. An instance of this class is created by the router and is provided to a view callable (and to other subsystems) as the request argument.

The documentation below (save for the add_response_callback and add_finished_callback methods, which are defined in this subclass itself, and the attributes context, registry, root, subpath, traversed, view_name, virtual_root , and virtual_root_path, each of which is added to the request by the router at request ingress time) are autogenerated from the WebOb source code used when this documentation was generated.

Due to technical constraints, we can’t yet display the WebOb version number from which this documentation is autogenerated, but it will be the ‘prevailing WebOb version’ at the time of the release of this Pyramid version. See http://pythonpaste.org/webob/ for further information.

context

The context will be available as the context attribute of the request object. It will be the context object implied by the current request. See Traversal for information about context objects.

registry

The application registry will be available as the registry attribute of the request object. See Using the Zope Component Architecture in Pyramid for more information about the application registry.

root

The root object will be available as the root attribute of the request object. It will be the resource object at which traversal started (the root). See Traversal for information about root objects.

subpath

The traversal subpath will be available as the subpath attribute of the request object. It will be a sequence containing zero or more elements (which will be Unicode objects). See Traversal for information about the subpath.

traversed

The “traversal path” will be available as the traversed attribute of the request object. It will be a sequence representing the ordered set of names that were used to traverse to the context, not including the view name or subpath. If there is a virtual root associated with the request, the virtual root path is included within the traversal path. See Traversal for more information.

view_name

The view name will be available as the view_name attribute of the request object. It will be a single string (possibly the empty string if we’re rendering a default view). See Traversal for information about view names.

virtual_root

The virtual root will be available as the virtual_root attribute of the request object. It will be the virtual root object implied by the current request. See Virtual Hosting for more information about virtual roots.

virtual_root_path

The virtual root path will be available as the virtual_root_path attribute of the request object. It will be a sequence representing the ordered set of names that were used to traverse to the virtual root object. See Virtual Hosting for more information about virtual roots.

exception

If an exception was raised by a root factory or a view callable, or at various other points where Pyramid executes user-defined code during the processing of a request, the exception object which was caught will be available as the exception attribute of the request within a exception view, a response callback or a finished callback. If no exception occurred, the value of request.exception will be None within response and finished callbacks.

session

If a session factory has been configured, this attribute will represent the current user’s session object. If a session factory has not been configured, requesting the request.session attribute will cause a pyramid.exceptions.ConfigurationError to be raised.

tmpl_context

The template context for Pylons-style applications.

matchdict

If a route has matched during this request, this attribute will be a dictionary containing the values matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will be None. See The Matchdict.

matched_route

If a route has matched during this request, this attribute will be an obect representing the route matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will be None. See The Matched Route.

add_response_callback(callback)

Add a callback to the set of callbacks to be called by the router at a point after a response object is successfully created. Pyramid does not have a global response object: this functionality allows an application to register an action to be performed against the response once one is created.

A ‘callback’ is a callable which accepts two positional parameters: request and response. For example:

1
2
3
4

def cache_callback(request, response):
    'Set the cache_control max_age for the response'
    response.cache_control.max_age = 360
request.add_response_callback(cache_callback)

Response callbacks are called in the order they’re added (first-to-most-recently-added). No response callback is called if an exception happens in application code, or if the response object returned by view code is invalid.

All response callbacks are called after the pyramid.events.NewResponse event is sent.

Errors raised by callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

See also: Using Response Callbacks.

add_finished_callback(callback)

Add a callback to the set of callbacks to be called unconditionally by the router at the very end of request processing.

callback is a callable which accepts a single positional parameter: request. For example:

1
2
3
4
5
6
7
8
9

import transaction

def commit_callback(request):
    '''commit or abort the transaction associated with request'''
    if request.exception is not None:
        transaction.abort()
    else:
        transaction.commit()
request.add_finished_callback(commit_callback)

Finished callbacks are called in the order they’re added ( first- to most-recently- added). Finished callbacks (unlike response callbacks) are always called, even if an exception happens in application code that prevents a response from being generated.

The set of finished callbacks associated with a request are called very late in the processing of that request; they are essentially the last thing called by the router. They are called after response processing has already occurred in a top-level finally: block within the router request processing code. As a result, mutations performed to the request provided to a finished callback will have no meaningful effect, because response processing will have already occurred, and the request’s scope will expire almost immediately after all finished callbacks have been processed.

Errors raised by finished callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

See also: Using Finished Callbacks.

route_url(route_name, *elements, **kw)

Return the URL for the route named route_name, using *elements and **kw as modifiers.

This is a convenience method. The result of calling pyramid.request.Request.route_url() is the same as calling pyramid.url.route_url() with an explicit request parameter.

The pyramid.request.Request.route_url() method calls the pyramid.url.route_url() function using the Request object as the request argument. The route_name, *elements and *kw arguments passed to pyramid.request.Request.route_url() are passed through to pyramid.url.route_url() unchanged and its result is returned.

This call to pyramid.request.Request.route_url():

request.route_url('route_name')

Is completely equivalent to calling pyramid.url.route_url() like this:

from pyramid.url import route_url
route_url('route_name', request)

route_path(route_name, *elements, **kw)

Generates a path (aka a ‘relative URL’, a URL minus the host, scheme, and port) for a named Pyramid route configuration.

This is a convenience method. The result of calling pyramid.request.Request.route_path() is the same as calling pyramid.url.route_path() with an explicit request parameter.

This method accepts the same arguments as pyramid.request.Request.route_url() and performs the same duty. It just omits the host, port, and scheme information in the return value; only the path, query parameters, and anchor data are present in the returned string.

The pyramid.request.Request.route_path() method calls the pyramid.url.route_path() function using the Request object as the request argument. The *elements and *kw arguments passed to pyramid.request.Request.route_path() are passed through to pyramid.url.route_path() unchanged and its result is returned.

This call to pyramid.request.Request.route_path():

request.route_path('foobar')

Is completely equivalent to calling pyramid.url.route_path() like this:

from pyramid.url import route_path
route_path('foobar', request)

See pyramid.url.route_path() for more information

resource_url(resource, *elements, **kw)

Return the URL for the resource object named resource, using *elements and **kw as modifiers.

This is a convenience method. The result of calling pyramid.request.Request.resource_url() is the same as calling pyramid.url.resource_url() with an explicit request parameter.

The pyramid.request.Request.resource_url() method calls the pyramid.url.resource_url() function using the Request object as the request argument. The resource, *elements and *kw arguments passed to pyramid.request.Request.resource_url() are passed through to pyramid.url.resource_url() unchanged and its result is returned.

This call to pyramid.request.Request.resource_url():

request.resource_url(myresource)

Is completely equivalent to calling pyramid.url.resource_url() like this:

from pyramid.url import resource_url
resource_url(resource, request)

Note

For backwards compatibility purposes, this method can also be called as pyramid.request.Request.model_url().

static_url(path, **kw)

Generates a fully qualified URL for a static asset. The asset must live within a location defined via the pyramid.config.Configurator.add_static_view() configuration declaration directive (see Serving Static Assets).

This is a convenience method. The result of calling pyramid.request.Request.static_url() is the same as calling pyramid.url.static_url() with an explicit request parameter.

The pyramid.request.Request.static_url() method calls the pyramid.url.static_url() function using the Request object as the request argument. The *kw arguments passed to pyramid.request.Request.static_url() are passed through to pyramid.url.static_url() unchanged and its result is returned.

This call to pyramid.request.Request.static_url():

request.static_url('mypackage:static/foo.css')

Is completely equivalent to calling pyramid.url.static_url() like this:

from pyramid.url import static_url
static_url('mypackage:static/foo.css', request)

See pyramid.url.static_url() for more information

GET

Like .str_GET, but may decode values and keys

POST

Like .str_POST, but may decode values and keys

ResponseClass

alias of Response

accept

Gets and sets the ‘HTTP_ACCEPT’ key in the environment. For more information on Accept see section 14.1 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1]. Converts it as a MIME Accept.

accept_charset

Gets and sets the ‘HTTP_ACCEPT_CHARSET’ key in the environment. For more information on Accept-Charset see section 14.2 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.2]. Converts it as a accept header.

accept_encoding

Gets and sets the ‘HTTP_ACCEPT_ENCODING’ key in the environment. For more information on Accept-Encoding see section 14.3 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3]. Converts it as a accept header.

accept_language

Gets and sets the ‘HTTP_ACCEPT_LANGUAGE’ key in the environment. For more information on Accept-Language see section 14.4 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4]. Converts it as a accept header.

add_finished_callback(callback)

Add a callback to the set of callbacks to be called unconditionally by the router at the very end of request processing.

callback is a callable which accepts a single positional parameter: request. For example:

1
2
3
4
5
6
7
8
9

import transaction

def commit_callback(request):
    '''commit or abort the transaction associated with request'''
    if request.exception is not None:
        transaction.abort()
    else:
        transaction.commit()
request.add_finished_callback(commit_callback)

Finished callbacks are called in the order they’re added ( first- to most-recently- added). Finished callbacks (unlike response callbacks) are always called, even if an exception happens in application code that prevents a response from being generated.

The set of finished callbacks associated with a request are called very late in the processing of that request; they are essentially the last thing called by the router. They are called after response processing has already occurred in a top-level finally: block within the router request processing code. As a result, mutations performed to the request provided to a finished callback will have no meaningful effect, because response processing will have already occurred, and the request’s scope will expire almost immediately after all finished callbacks have been processed.

Errors raised by finished callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

See also: Using Finished Callbacks.

add_response_callback(callback)

Add a callback to the set of callbacks to be called by the router at a point after a response object is successfully created. Pyramid does not have a global response object: this functionality allows an application to register an action to be performed against the response once one is created.

A ‘callback’ is a callable which accepts two positional parameters: request and response. For example:

1
2
3
4

def cache_callback(request, response):
    'Set the cache_control max_age for the response'
    response.cache_control.max_age = 360
request.add_response_callback(cache_callback)

Response callbacks are called in the order they’re added (first-to-most-recently-added). No response callback is called if an exception happens in application code, or if the response object returned by view code is invalid.

All response callbacks are called after the pyramid.events.NewResponse event is sent.

Errors raised by callbacks are not handled specially. They will be propagated to the caller of the Pyramid router application.

See also: Using Response Callbacks.

application_url

The URL including SCRIPT_NAME (no PATH_INFO or query string)

authorization

Gets and sets the ‘HTTP_AUTHORIZATION’ key in the environment. For more information on Authorization see section 14.8 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8]. Converts it as a <function parse_auth at 0x29d4578> and <function serialize_auth at 0x29d45f0>.

classmethod blank(path, environ=None, base_url=None, headers=None, POST=None, **kw)

Create a blank request environ (and Request wrapper) with the given path (path should be urlencoded), and any keys from environ.

The path will become path_info, with any query string split off and used.

All necessary keys will be added to the environ, but the values you pass in will take precedence. If you pass in base_url then wsgi.url_scheme, HTTP_HOST, and SCRIPT_NAME will be filled in from that value.

Any extra keyword will be passed to __init__ (e.g., decode_param_names).

body

Return the content of the request body.

body_file

Access the body of the request (wsgi.input) as a file-like object.

If you set this value, CONTENT_LENGTH will also be updated (either set to -1, 0 if you delete the attribute, or if you set the attribute to a string then the length of the string).

cache_control

Get/set/modify the Cache-Control header (section 14.9 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9])

call_application(application, catch_exc_info=False)

Call the given WSGI application, returning (status_string, headerlist, app_iter)

Be sure to call app_iter.close() if it’s there.

If catch_exc_info is true, then returns (status_string, headerlist, app_iter, exc_info), where the fourth item may be None, but won’t be if there was an exception. If you don’t do this and there was an exception, the exception will be raised directly.

charset

Get the charset of the request.

If the request was sent with a charset parameter on the Content-Type, that will be used. Otherwise if there is a default charset (set during construction, or as a class attribute) that will be returned. Otherwise None.

Setting this property after request instantiation will always update Content-Type. Deleting the property updates the Content-Type to remove any charset parameter (if none exists, then deleting the property will do nothing, and there will be no error).

content_length

Gets and sets the ‘CONTENT_LENGTH’ key in the environment. For more information on CONTENT_LENGTH see section 14.13 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13]. Converts it as a int.

content_type

Return the content type, but leaving off any parameters (like charset, but also things like the type in application/atom+xml; type=entry)

If you set this property, you can include parameters, or if you don’t include any parameters in the value then existing parameters will be preserved.

cookies

Like .str_cookies, but may decode values and keys

copy()

Copy the request and environment object.

This only does a shallow copy, except of wsgi.input

copy_body()

Copies the body, in cases where it might be shared with another request object and that is not desired.

This copies the body in-place, either into a StringIO object or a temporary file.

copy_get()

Copies the request and environment object, but turning this request into a GET along the way. If this was a POST request (or any other verb) then it becomes GET, and the request body is thrown away.

date

Gets and sets the ‘HTTP_DATE’ key in the environment. For more information on Date see section 14.8 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8]. Converts it as a HTTP date.

classmethod from_file(fp)

Reads a request from a file-like object (it must implement .read(size) and .readline()).

It will read up to the end of the request, not the end of the file.

This reads the request as represented by str(req); it may not read every valid HTTP request properly.

get_response(application, catch_exc_info=False)

Like .call_application(application), except returns a response object with .status, .headers, and .body attributes.

This will use self.ResponseClass to figure out the class of the response object to return.

headers

All the request headers as a case-insensitive dictionary-like object.

host

Host name provided in HTTP_HOST, with fall-back to SERVER_NAME

host_url

The URL through the host (no path)

if_match

Gets and sets the ‘HTTP_IF_MATCH’ key in the environment. For more information on If-Match see section 14.24 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24]. Converts it as a Etag.

if_modified_since

Gets and sets the ‘HTTP_IF_MODIFIED_SINCE’ key in the environment. For more information on If-Modified-Since see section 14.25 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25]. Converts it as a HTTP date.

if_none_match

Gets and sets the ‘HTTP_IF_NONE_MATCH’ key in the environment. For more information on If-None-Match see section 14.26 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26]. Converts it as a Etag.

if_range

Gets and sets the ‘HTTP_IF_RANGE’ key in the environment. For more information on If-Range see section 14.27 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.27]. Converts it as a IfRange object.

if_unmodified_since

Gets and sets the ‘HTTP_IF_UNMODIFIED_SINCE’ key in the environment. For more information on If-Unmodified-Since see section 14.28 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28]. Converts it as a HTTP date.

is_xhr

Returns a boolean if X-Requested-With is present and XMLHttpRequest

Note: this isn’t set by every XMLHttpRequest request, it is only set if you are using a Javascript library that sets it (or you set the header yourself manually). Currently Prototype and jQuery are known to set this header.

make_body_seekable()

This forces environ['wsgi.input'] to be seekable. That is, if it doesn’t have a seek method already, the content is copied into a StringIO or temporary file.

The choice to copy to StringIO is made from self.request_body_tempfile_limit

max_forwards

Gets and sets the ‘HTTP_MAX_FORWARDS’ key in the environment. For more information on Max-Forwards see section 14.31 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.31]. Converts it as a int.

method

Gets and sets the ‘REQUEST_METHOD’ key in the environment.

model_url(resource, *elements, **kw)

Return the URL for the resource object named resource, using *elements and **kw as modifiers.

This is a convenience method. The result of calling pyramid.request.Request.resource_url() is the same as calling pyramid.url.resource_url() with an explicit request parameter.

The pyramid.request.Request.resource_url() method calls the pyramid.url.resource_url() function using the Request object as the request argument. The resource, *elements and *kw arguments passed to pyramid.request.Request.resource_url() are passed through to pyramid.url.resource_url() unchanged and its result is returned.

This call to pyramid.request.Request.resource_url():

request.resource_url(myresource)

Is completely equivalent to calling pyramid.url.resource_url() like this:

from pyramid.url import resource_url
resource_url(resource, request)

Note

For backwards compatibility purposes, this method can also be called as pyramid.request.Request.model_url().

params

Like .str_params, but may decode values and keys

path

The path of the request, without host or query string

path_info

Gets and sets the ‘PATH_INFO’ key in the environment.

path_info_peek()

Returns the next segment on PATH_INFO, or None if there is no next segment. Doesn’t modify the environment.

path_info_pop(pattern=None)

‘Pops’ off the next segment of PATH_INFO, pushing it onto SCRIPT_NAME, and returning the popped segment. Returns None if there is nothing left on PATH_INFO.

Does not return '' when there’s an empty segment (like /path//path); these segments are just ignored.

Optional pattern argument is a regexp to match the return value before returning. If there is no match, no changes are made to the request and None is returned.

path_qs

The path of the request, without host but with query string

path_url

The URL including SCRIPT_NAME and PATH_INFO, but not QUERY_STRING

postvars

Wraps a descriptor, with a deprecation warning or error

pragma

Gets and sets the ‘HTTP_PRAGMA’ key in the environment. For more information on Pragma see section 14.32 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32].

query_string

Gets and sets the ‘QUERY_STRING’ key in the environment.

queryvars

Wraps a descriptor, with a deprecation warning or error

range

Gets and sets the ‘HTTP_RANGE’ key in the environment. For more information on Range see section 14.35 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35]. Converts it as a Range object.

referer

Gets and sets the ‘HTTP_REFERER’ key in the environment. For more information on Referer see section 14.36 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.36].

referrer

Gets and sets the ‘HTTP_REFERER’ key in the environment. For more information on Referer see section 14.36 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.36].

relative_url(other_url, to_application=False)

Resolve other_url relative to the request URL.

If to_application is True, then resolve it relative to the URL with only SCRIPT_NAME

remote_addr

Gets and sets the ‘REMOTE_ADDR’ key in the environment.

remote_user

Gets and sets the ‘REMOTE_USER’ key in the environment.

remove_conditional_headers(remove_encoding=True, remove_range=True, remove_match=True, remove_modified=True)

Remove headers that make the request conditional.

These headers can cause the response to be 304 Not Modified, which in some cases you may not want to be possible.

This does not remove headers like If-Match, which are used for conflict detection.

resource_url(resource, *elements, **kw)

Return the URL for the resource object named resource, using *elements and **kw as modifiers.

This is a convenience method. The result of calling pyramid.request.Request.resource_url() is the same as calling pyramid.url.resource_url() with an explicit request parameter.

The pyramid.request.Request.resource_url() method calls the pyramid.url.resource_url() function using the Request object as the request argument. The resource, *elements and *kw arguments passed to pyramid.request.Request.resource_url() are passed through to pyramid.url.resource_url() unchanged and its result is returned.

This call to pyramid.request.Request.resource_url():

request.resource_url(myresource)

Is completely equivalent to calling pyramid.url.resource_url() like this:

from pyramid.url import resource_url
resource_url(resource, request)

Note

For backwards compatibility purposes, this method can also be called as pyramid.request.Request.model_url().

route_path(route_name, *elements, **kw)

Generates a path (aka a ‘relative URL’, a URL minus the host, scheme, and port) for a named Pyramid route configuration.

This is a convenience method. The result of calling pyramid.request.Request.route_path() is the same as calling pyramid.url.route_path() with an explicit request parameter.

This method accepts the same arguments as pyramid.request.Request.route_url() and performs the same duty. It just omits the host, port, and scheme information in the return value; only the path, query parameters, and anchor data are present in the returned string.

The pyramid.request.Request.route_path() method calls the pyramid.url.route_path() function using the Request object as the request argument. The *elements and *kw arguments passed to pyramid.request.Request.route_path() are passed through to pyramid.url.route_path() unchanged and its result is returned.

This call to pyramid.request.Request.route_path():

request.route_path('foobar')

Is completely equivalent to calling pyramid.url.route_path() like this:

from pyramid.url import route_path
route_path('foobar', request)

See pyramid.url.route_path() for more information

route_url(route_name, *elements, **kw)

Return the URL for the route named route_name, using *elements and **kw as modifiers.

This is a convenience method. The result of calling pyramid.request.Request.route_url() is the same as calling pyramid.url.route_url() with an explicit request parameter.

The pyramid.request.Request.route_url() method calls the pyramid.url.route_url() function using the Request object as the request argument. The route_name, *elements and *kw arguments passed to pyramid.request.Request.route_url() are passed through to pyramid.url.route_url() unchanged and its result is returned.

This call to pyramid.request.Request.route_url():

request.route_url('route_name')

Is completely equivalent to calling pyramid.url.route_url() like this:

from pyramid.url import route_url
route_url('route_name', request)

scheme

Gets and sets the ‘wsgi.url_scheme’ key in the environment.

script_name

Gets and sets the ‘SCRIPT_NAME’ key in the environment.

server_name

Gets and sets the ‘SERVER_NAME’ key in the environment.

server_port

Gets and sets the ‘SERVER_PORT’ key in the environment. Converts it as a int.

session

Obtain the session object associated with this request. If a session factory has not been registered during application configuration, a pyramid.exceptions.ConfigurationError will be raised

static_url(path, **kw)

Generates a fully qualified URL for a static asset. The asset must live within a location defined via the pyramid.config.Configurator.add_static_view() configuration declaration directive (see Serving Static Assets).

This is a convenience method. The result of calling pyramid.request.Request.static_url() is the same as calling pyramid.url.static_url() with an explicit request parameter.

The pyramid.request.Request.static_url() method calls the pyramid.url.static_url() function using the Request object as the request argument. The *kw arguments passed to pyramid.request.Request.static_url() are passed through to pyramid.url.static_url() unchanged and its result is returned.

This call to pyramid.request.Request.static_url():

request.static_url('mypackage:static/foo.css')

Is completely equivalent to calling pyramid.url.static_url() like this:

from pyramid.url import static_url
static_url('mypackage:static/foo.css', request)

See pyramid.url.static_url() for more information

str_GET

Return a MultiDict containing all the variables from the QUERY_STRING.

str_POST

Return a MultiDict containing all the variables from a form request. Returns an empty dict-like object for non-form requests.

Form requests are typically POST requests, however PUT requests with an appropriate Content-Type are also supported.

str_cookies

Return a plain dictionary of cookies as found in the request.

str_params

A dictionary-like object containing both the parameters from the query string and request body.

str_postvars

Wraps a descriptor, with a deprecation warning or error

str_queryvars

Wraps a descriptor, with a deprecation warning or error

tmpl_context

Template context (for Pylons apps)

upath_info

upath_property(‘PATH_INFO’)

url

The full request URL, including QUERY_STRING

urlargs

Return any positional variables matched in the URL.

Takes values from environ['wsgiorg.routing_args']. Systems like routes set this value.

urlvars

Return any named variables matched in the URL.

Takes values from environ['wsgiorg.routing_args']. Systems like routes set this value.

uscript_name

upath_property(‘SCRIPT_NAME’)

user_agent

Gets and sets the ‘HTTP_USER_AGENT’ key in the environment. For more information on User-Agent see section 14.43 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43].

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.response

class Response(body=None, status=None, headerlist=None, app_iter=None, request=None, content_type=None, conditional_response=None, **kw)

Represents a WSGI response

RequestClass

alias of Request

accept_ranges

Gets and sets and deletes the Accept-Ranges header. For more information on Accept-Ranges see section 14.5 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.5].

age

Gets and sets and deletes the Age header. For more information on Age see section 14.6 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.6]. Converts it as a int.

allow

Gets and sets and deletes the Allow header. For more information on Allow see section 14.7 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.7]. Converts it as a list.

app_iter

Returns the app_iter of the response.

If body was set, this will create an app_iter from that body (a single-item list)

app_iter_range(start, stop)

Return a new app_iter built from the response app_iter, that serves up only the given start:stop range.

body

The body of the response, as a str. This will read in the entire app_iter if necessary.

body_file

A file-like object that can be used to write to the body. If you passed in a list app_iter, that app_iter will be modified by writes.

cache_control

Get/set/modify the Cache-Control header (section 14.9 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9])

charset

Get/set the charset (in the Content-Type)

conditional_response_app(environ, start_response)

Like the normal __call__ interface, but checks conditional headers:

If-Modified-Since (304 Not Modified; only on GET, HEAD)

If-None-Match (304 Not Modified; only on GET, HEAD)

Range (406 Partial Content; only on GET, HEAD)

content_disposition

Gets and sets and deletes the Content-Disposition header. For more information on Content-Disposition see section 19.5.1 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1].

content_encoding

Gets and sets and deletes the Content-Encoding header. For more information on Content-Encoding see section 14.11 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11].

content_language

Gets and sets and deletes the Content-Language header. For more information on Content-Language see section 14.12 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.12]. Converts it as a list.

content_length

Gets and sets and deletes the Content-Length header. For more information on Content-Length see section 14.17 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17]. Converts it as a int.

content_location

Gets and sets and deletes the Content-Location header. For more information on Content-Location see section 14.14 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.14].

content_md5

Gets and sets and deletes the Content-MD5 header. For more information on Content-MD5 see section 14.14 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.14].

content_range

Gets and sets and deletes the Content-Range header. For more information on Content-Range see section 14.16 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16]. Converts it as a ContentRange object.

content_type

Get/set the Content-Type header (or None), without the charset or any parameters.

If you include parameters (or ; at all) when setting the content_type, any existing parameters will be deleted; otherwise they will be preserved.

content_type_params

A dictionary of all the parameters in the content type.

(This is not a view, set to change, modifications of the dict would not be applied otherwise)

copy()

Makes a copy of the response

date

Gets and sets and deletes the Date header. For more information on Date see section 14.18 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.18]. Converts it as a HTTP date.

delete_cookie(key, path='/', domain=None)

Delete a cookie from the client. Note that path and domain must match how the cookie was originally set.

This sets the cookie to the empty string, and max_age=0 so that it should expire immediately.

encode_content(encoding='gzip', lazy=False)

Encode the content with the given encoding (only gzip and identity are supported).

environ

Get/set the request environ associated with this response, if any.

etag

Gets and sets and deletes the ETag header. For more information on ETag see section 14.19 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19]. Converts it as a Entity tag.

expires

Gets and sets and deletes the Expires header. For more information on Expires see section 14.21 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21]. Converts it as a HTTP date.

classmethod from_file(fp)

Reads a response from a file-like object (it must implement .read(size) and .readline()).

It will read up to the end of the response, not the end of the file.

This reads the response as represented by str(resp); it may not read every valid HTTP response properly. Responses must have a Content-Length

headerlist

The list of response headers

headers

The headers in a dictionary-like object

last_modified

Gets and sets and deletes the Last-Modified header. For more information on Last-Modified see section 14.29 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.29]. Converts it as a HTTP date.

location

Gets and sets and deletes the Location header. For more information on Location see section 14.30 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30].

md5_etag(body=None, set_content_md5=False)

Generate an etag for the response object using an MD5 hash of the body (the body parameter, or self.body if not given)

Sets self.etag If set_content_md5 is True sets self.content_md5 as well

merge_cookies(resp)

Merge the cookies that were set on this response with the given resp object (which can be any WSGI application).

If the resp is a webob.Response object, then the other object will be modified in-place.

pragma

Gets and sets and deletes the Pragma header. For more information on Pragma see section 14.32 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32].

request

Return the request associated with this response if any.

retry_after

Gets and sets and deletes the Retry-After header. For more information on Retry-After see section 14.37 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.37]. Converts it as a HTTP date or delta seconds.

server

Gets and sets and deletes the Server header. For more information on Server see section 14.38 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.38].

set_cookie(key, value='', max_age=None, path='/', domain=None, secure=False, httponly=False, comment=None, expires=None, overwrite=False)

Set (add) a cookie for the response

status

The status string

status_code

Wraps a descriptor, with a deprecation warning or error

status_int

The status as an integer

ubody

Alias for unicode_body

unicode_body

Get/set the unicode value of the body (using the charset of the Content-Type)

unset_cookie(key, strict=True)

Unset a cookie with the given name (remove it from the response).

vary

Gets and sets and deletes the Vary header. For more information on Vary see section 14.44 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44]. Converts it as a list.

www_authenticate

Gets and sets and deletes the WWW-Authenticate header. For more information on WWW-Authenticate see section 14.47 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.47]. Converts it as a <function parse_auth at 0x29d4578> and <function serialize_auth at 0x29d45f0>.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.scripting

get_root(app, request=None)

Return a tuple composed of (root, closer) when provided a router instance as the app argument. The root returned is the application root object. The closer returned is a callable (accepting no arguments) that should be called when your scripting application is finished using the root. If request is not None, it is used as the request passed to the Pyramid application root factory. A request is constructed and passed to the root factory if request is None.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.security

Authentication API Functions

authenticated_userid(request)

Return the userid of the currently authenticated user or None if there is no authentication policy in effect or there is no currently authenticated user.

unauthenticated_userid(request)

Return an object which represents the claimed (not verified) user id of the credentials present in the request. None if there is no authentication policy in effect or there is no user data associated with the current request. This differs from authenticated_userid(), because the effective authentication policy will not ensure that a record associated with the userid exists in persistent storage.

effective_principals(request)

Return the list of ‘effective’ principal identifiers for the request. This will include the userid of the currently authenticated user if a user is currently authenticated. If no authentication policy is in effect, this will return an empty sequence.

forget(request)

Return a sequence of header tuples (e.g. [('Set-Cookie', 'foo=abc')]) suitable for ‘forgetting’ the set of credentials possessed by the currently authenticated user. A common usage might look like so within the body of a view function (response is assumed to be an WebOb -style response object computed previously by the view code):

from pyramid.security import forget
headers = forget(request)
response.headerlist.extend(headers)
return response

If no authentication policy is in use, this function will always return an empty sequence.

remember(request, principal, **kw)

Return a sequence of header tuples (e.g. [('Set-Cookie', 'foo=abc')]) suitable for ‘remembering’ a set of credentials implied by the data passed as principal and *kw using the current authentication policy. Common usage might look like so within the body of a view function (response is assumed to be a WebOb -style response object computed previously by the view code):

from pyramid.security import remember
headers = remember(request, 'chrism', password='123', max_age='86400')
response.headerlist.extend(headers)
return response

If no authentication policy is in use, this function will always return an empty sequence. If used, the composition and meaning of **kw must be agreed upon by the calling code and the effective authentication policy.

Authorization API Functions

has_permission(permission, context, request)

Provided a permission (a string or unicode object), a context (a resource instance) and a request object, return an instance of pyramid.security.Allowed if the permission is granted in this context to the user implied by the request. Return an instance of pyramid.security.Denied if this permission is not granted in this context to this user. This function delegates to the current authentication and authorization policies. Return pyramid.security.Allowed unconditionally if no authentication policy has been configured in this application.

principals_allowed_by_permission(context, permission)

Provided a context (a resource object), and a permission (a string or unicode object), if a authorization policy is in effect, return a sequence of principal ids that possess the permission in the context. If no authorization policy is in effect, this will return a sequence with the single value pyramid.security.Everyone (the special principal identifier representing all principals).

Note

even if an authorization policy is in effect, some (exotic) authorization policies may not implement the required machinery for this function; those will cause a NotImplementedError exception to be raised when this function is invoked.

view_execution_permitted(context, request, name='')

If the view specified by context and name is protected by a permission, check the permission associated with the view using the effective authentication/authorization policies and the request. Return a boolean result. If no authorization policy is in effect, or if the view is not protected by a permission, return True.

Constants

Everyone

The special principal id named ‘Everyone’. This principal id is granted to all requests. Its actual value is the string ‘system.Everyone’.

Authenticated

The special principal id named ‘Authenticated’. This principal id is granted to all requests which contain any other non-Everyone principal id (according to the authentication policy). Its actual value is the string ‘system.Authenticated’.

ALL_PERMISSIONS

An object that can be used as the permission member of an ACE which matches all permissions unconditionally. For example, an ACE that uses ALL_PERMISSIONS might be composed like so: ('Deny', 'system.Everyone', ALL_PERMISSIONS).

DENY_ALL

A convenience shorthand ACE that defines ('Deny', 'system.Everyone', ALL_PERMISSIONS). This is often used as the last ACE in an ACL in systems that use an “inheriting” security policy, representing the concept “don’t inherit any other ACEs”.

Return Values

Allow

The ACE “action” (the first element in an ACE e.g. (Allow, Everyone, 'read') that means allow access. A sequence of ACEs makes up an ACL. It is a string, and it’s actual value is “Allow”.

Deny

The ACE “action” (the first element in an ACE e.g. (Deny, 'george', 'read') that means deny access. A sequence of ACEs makes up an ACL. It is a string, and it’s actual value is “Deny”.

class ACLDenied

An instance of ACLDenied represents that a security check made explicitly against ACL was denied. It evaluates equal to all boolean false types. It also has attributes which indicate which acl, ace, permission, principals, and context were involved in the request. Its __str__ method prints a summary of these attributes for debugging purposes. The same summary is available as the msg attribute.

class ACLAllowed

An instance of ACLAllowed represents that a security check made explicitly against ACL was allowed. It evaluates equal to all boolean true types. It also has attributes which indicate which acl, ace, permission, principals, and context were involved in the request. Its __str__ method prints a summary of these attributes for debugging purposes. The same summary is available as the msg attribute.

class Denied

An instance of Denied is returned when a security-related API or other Pyramid code denies an action unrelated to an ACL check. It evaluates equal to all boolean false types. It has an attribute named msg describing the circumstances for the deny.

class Allowed

An instance of Allowed is returned when a security-related API or other Pyramid code allows an action unrelated to an ACL check. It evaluates equal to all boolean true types. It has an attribute named msg describing the circumstances for the allow.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.session

UnencryptedCookieSessionFactoryConfig(secret, timeout=1200, cookie_name='session', cookie_max_age=None, cookie_path='/', cookie_domain=None, cookie_secure=False, cookie_httponly=False, cookie_on_exception=True)

Configure a session factory which will provide unencrypted (but signed) cookie-based sessions. The return value of this function is a session factory, which may be provided as the session_factory argument of a pyramid.config.Configurator constructor, or used as the session_factory argument of the pyramid.config.Configurator.set_session_factory() method.

The session factory returned by this function will create sessions which are limited to storing fewer than 4000 bytes of data (as the payload must fit into a single cookie).

Parameters:

secret

A string which is used to sign the cookie.

timeout

A number of seconds of inactivity before a session times out.

cookie_name

The name of the cookie used for sessioning. Default: session.

cookie_max_age

The maximum age of the cookie used for sessioning (in seconds). Default: None (browser scope).

cookie_path

The path used for the session cookie. Default: /.

cookie_domain

The domain used for the session cookie. Default: None (no domain).

cookie_secure

The ‘secure’ flag of the session cookie. Default: False.

cookie_httponly

The ‘httpOnly’ flag of the session cookie. Default: False.

cookie_on_exception

If True, set a session cookie even if an exception occurs while rendering a view. Default: True.

signed_serialize(data, secret)

Serialize any pickleable structure (data) and sign it using the secret (must be a string). Return the serialization, which includes the signature as its first 40 bytes. The signed_deserialize method will deserialize such a value.

This function is useful for creating signed cookies. For example:

cookieval = signed_serialize({'a':1}, 'secret')
response.set_cookie('signed_cookie', cookieval)

signed_deserialize(serialized, secret, hmac=<module 'hmac' from '/usr/lib/python2.6/hmac.pyc'>)

Deserialize the value returned from signed_serialize. If the value cannot be deserialized for any reason, a ValueError exception will be raised.

This function is useful for deserializing a signed cookie value created by signed_serialize. For example:

cookieval = request.cookies['signed_cookie']
data = signed_deserialize(cookieval, 'secret')

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.settings

get_settings()

Return a deployment settings object for the current application. The object is a dictionary-like object that contains key/value pairs based on the dictionary passed as the settings argument to the pyramid.config.Configurator constructor or the pyramid.router.make_app() API.

Warning

This method is deprecated as of Pyramid 1.0. Use pyramid.threadlocals.get_current_registry().settings instead or use the settings attribute of the registry available from the request (request.registry.settings).

asbool(s)

Return the boolean value True if the case-lowered value of string input s is any of t, true, y, on, or 1, otherwise return the boolean value False. If s is the value None, return False. If s is already one of the boolean values True or False, return it.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.testing

setUp(registry=None, request=None, hook_zca=True, autocommit=True, settings=None)

Set Pyramid registry and request thread locals for the duration of a single unit test.

Use this function in the setUp method of a unittest test case which directly or indirectly uses:

any method of the pyramid.config.Configurator object returned by this function.

the pyramid.threadlocal.get_current_registry() or pyramid.threadlocal.get_current_request() functions.

If you use the get_current_* functions (or call Pyramid code that uses these functions) without calling setUp, pyramid.threadlocal.get_current_registry() will return a global application registry, which may cause unit tests to not be isolated with respect to registrations they perform.

If the registry argument is None, a new empty application registry will be created (an instance of the pyramid.registry.Registry class). If the registry argument is not None, the value passed in should be an instance of the pyramid.registry.Registry class or a suitable testing analogue.

After setUp is finished, the registry returned by the pyramid.threadlocal.get_current_request() function will be the passed (or constructed) registry until pyramid.testing.tearDown() is called (or pyramid.testing.setUp() is called again) .

If the hook_zca argument is True, setUp will attempt to perform the operation zope.component.getSiteManager.sethook( pyramid.threadlocal.get_current_registry), which will cause the Zope Component Architecture global API (e.g. zope.component.getSiteManager(), zope.component.getAdapter(), and so on) to use the registry constructed by setUp as the value it returns from zope.component.getSiteManager(). If the zope.component package cannot be imported, or if hook_zca is False, the hook will not be set.

If settings is not None, it must be a dictionary representing the values passed to a Configurator as its settings= argument.

This function returns an instance of the pyramid.config.Configurator class, which can be used for further configuration to set up an environment suitable for a unit or integration test. The registry attribute attached to the Configurator instance represents the ‘current’ application registry; the same registry will be returned by pyramid.threadlocal.get_current_registry() during the execution of the test.

tearDown(unhook_zca=True)

Undo the effects pyramid.testing.setUp(). Use this function in the tearDown method of a unit test that uses pyramid.testing.setUp() in its setUp method.

If the unhook_zca argument is True (the default), call zope.component.getSiteManager.reset(). This undoes the action of pyramid.testing.setUp() called with the argument hook_zca=True. If zope.component cannot be imported, ignore the argument.

cleanUp(*arg, **kw)

pyramid.testing.cleanUp() is an alias for pyramid.testing.setUp().

class DummyResource(__name__=None, __parent__=None, __provides__=None, **kw)

A dummy Pyramid resource object.

clone(__name__=<object object at 0x48250c0>, __parent__=<object object at 0x48250c0>, **kw)

Create a clone of the resource object. If __name__ or __parent__ arguments are passed, use these values to override the existing __name__ or __parent__ of the resource. If any extra keyword args are passed in via the kw argument, use these keywords to add to or override existing resource keywords (attributes).

items()

Return the items set by __setitem__

keys()

Return the keys set by __setitem__

values()

Return the values set by __setitem__

class DummyRequest(params=None, environ=None, headers=None, path='/', cookies=None, post=None, **kw)

A dummy request object (imitates a request object).

The params, environ, headers, path, and cookies arguments correspond to their :term`WebOb` equivalents.

The post argument, if passed, populates the request’s POST attribute, but not params, in order to allow testing that the app accepts data for a given view only from POST requests. This argument also sets self.method to “POST”.

Extra keyword arguments are assigned as attributes of the request itself.

class DummyTemplateRenderer(string_response='')

An instance of this class is returned from pyramid.config.Configurator.testing_add_renderer(). It has a helper function (assert_) that makes it possible to make an assertion which compares data passed to the renderer by the view function against expected key/value pairs.

assert_(**kw)

Accept an arbitrary set of assertion key/value pairs. For each assertion key/value pair assert that the renderer (eg. pyramid.renderer.render_to_response()) received the key with a value that equals the asserted value. If the renderer did not receive the key at all, or the value received by the renderer doesn’t match the assertion value, raise an AssertionError.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.threadlocal

get_current_request()

Return the currently active request or None if no request is currently active.

This function should be used extremely sparingly, usually only in unit testing code. it’s almost always usually a mistake to use get_current_request outside a testing context because its usage makes it possible to write code that can be neither easily tested nor scripted.

get_current_registry()

Return the currently active application registry or the global application registry if no request is currently active.

This function should be used extremely sparingly, usually only in unit testing code. it’s almost always usually a mistake to use get_current_registry outside a testing context because its usage makes it possible to write code that can be neither easily tested nor scripted.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.traversal

find_interface(resource, class_or_interface)

Return the first resource found in the lineage of resource which, a) if class_or_interface is a Python class object, is an instance of the class or any subclass of that class or b) if class_or_interface is a interface, provides the specified interface. Return None if no resource providing interface_or_class can be found in the lineage. The resource passed in must be location-aware.

find_resource(resource, path)

Given a resource object and a string or tuple representing a path (such as the return value of pyramid.traversal.resource_path() or pyramid.traversal.resource_path_tuple()), return a resource in this application’s resource tree at the specified path. The resource passed in must be location-aware. If the path cannot be resolved (if the respective node in the resource tree does not exist), a KeyError will be raised.

This function is the logical inverse of pyramid.traversal.resource_path() and pyramid.traversal.resource_path_tuple(); it can resolve any path string or tuple generated by either of those functions.

Rules for passing a string as the path argument: if the first character in the path string is the with the / character, the path will considered absolute and the resource tree traversal will start at the root resource. If the first character of the path string is not the / character, the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty string is passed as path, the resource passed in will be returned. Resource path strings must be escaped in the following manner: each Unicode path segment must be encoded as UTF-8 and as each path segment must escaped via Python’s urllib.quote. For example, /path/to%20the/La%20Pe%C3%B1a (absolute) or to%20the/La%20Pe%C3%B1a (relative). The pyramid.traversal.resource_path() function generates strings which follow these rules (albeit only absolute ones).

Rules for passing a tuple as the path argument: if the first element in the path tuple is the empty string (for example ('', 'a', 'b', 'c'), the path is considered absolute and the resource tree traversal will start at the resource tree root object. If the first element in the path tuple is not the empty string (for example ('a', 'b', 'c')), the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty sequence is passed as path, the resource passed in itself will be returned. No URL-quoting or UTF-8-encoding of individual path segments within the tuple is required (each segment may be any string or unicode object representing a resource name). Resource path tuples generated by pyramid.traversal.resource_path_tuple() can always be resolved by find_resource.

Note

For backwards compatibility purposes, this function can also be imported as pyramid.traversal.find_model(), although doing so will emit a deprecation warning.

find_root(resource)

Find the root node in the resource tree to which resource belongs. Note that resource should be location-aware. Note that the root resource is available in the request object by accessing the request.root attribute.

resource_path(resource, *elements)

Return a string object representing the absolute physical path of the resource object based on its position in the resource tree, e.g /foo/bar. Any positional arguments passed in as elements will be appended as path segments to the end of the resource path. For instance, if the resource’s path is /foo/bar and elements equals ('a', 'b'), the returned string will be /foo/bar/a/b. The first character in the string will always be the / character (a leading / character in a path string represents that the path is absolute).

Resource path strings returned will be escaped in the following manner: each unicode path segment will be encoded as UTF-8 and each path segment will be escaped via Python’s urllib.quote. For example, /path/to%20the/La%20Pe%C3%B1a.

This function is a logical inverse of pyramid.traversal.find_resource: it can be used to generate path references that can later be resolved via that function.

The resource passed in must be location-aware.

Note

Each segment in the path string returned will use the __name__ attribute of the resource it represents within the resource tree. Each of these segments should be a unicode or string object (as per the contract of location-awareness). However, no conversion or safety checking of resource names is performed. For instance, if one of the resources in your tree has a __name__ which (by error) is a dictionary, the pyramid.traversal.resource_path() function will attempt to append it to a string and it will cause a pyramid.exceptions.URLDecodeError.

Note

The root resource must have a __name__ attribute with a value of either None or the empty string for paths to be generated properly. If the root resource has a non-null __name__ attribute, its name will be prepended to the generated path rather than a single leading ‘/’ character.

Note

For backwards compatibility purposes, this function can also be imported as model_path, although doing so will cause a deprecation warning to be emitted.

resource_path_tuple(resource, *elements)

Return a tuple representing the absolute physical path of the resource object based on its position in a resource tree, e.g ('', 'foo', 'bar'). Any positional arguments passed in as elements will be appended as elements in the tuple representing the resource path. For instance, if the resource’s path is ('', 'foo', 'bar') and elements equals ('a', 'b'), the returned tuple will be ('', 'foo', 'bar', 'a', b'). The first element of this tuple will always be the empty string (a leading empty string element in a path tuple represents that the path is absolute).

This function is a logical inverse of pyramid.traversal.find_resource(): it can be used to generate path references that can later be resolved that function.

The resource passed in must be location-aware.

Note

Each segment in the path tuple returned will equal the __name__ attribute of the resource it represents within the resource tree. Each of these segments should be a unicode or string object (as per the contract of location-awareness). However, no conversion or safety checking of resource names is performed. For instance, if one of the resources in your tree has a __name__ which (by error) is a dictionary, that dictionary will be placed in the path tuple; no warning or error will be given.

Note

The root resource must have a __name__ attribute with a value of either None or the empty string for path tuples to be generated properly. If the root resource has a non-null __name__ attribute, its name will be the first element in the generated path tuple rather than the empty string.

Note

For backwards compatibility purposes, this function can also be imported as model_path_tuple, although doing so will cause a deprecation warning to be emitted.

quote_path_segment(segment)

Return a quoted representation of a ‘path segment’ (such as the string __name__ attribute of a resource) as a string. If the segment passed in is a unicode object, it is converted to a UTF-8 string, then it is URL-quoted using Python’s urllib.quote. If the segment passed in is a string, it is URL-quoted using Python’s urllib.quote. If the segment passed in is not a string or unicode object, an error will be raised. The return value of quote_path_segment is always a string, never Unicode.

Note

The return value for each segment passed to this function is cached in a module-scope dictionary for speed: the cached version is returned when possible rather than recomputing the quoted version. No cache emptying is ever done for the lifetime of an application, however. If you pass arbitrary user-supplied strings to this function (as opposed to some bounded set of values from a ‘working set’ known to your application), it may become a memory leak.

virtual_root(resource, request)

Provided any resource and a request object, return the resource object representing the virtual root of the current request. Using a virtual root in a traversal -based Pyramid application permits rooting, for example, the resource at the traversal path /cms at http://example.com/ instead of rooting it at http://example.com/cms/.

If the resource passed in is a context obtained via traversal, and if the HTTP_X_VHM_ROOT key is in the WSGI environment, the value of this key will be treated as a ‘virtual root path’: the pyramid.traversal.find_resource() API will be used to find the virtual root resource using this path; if the resource is found, it will be returned. If the HTTP_X_VHM_ROOT key is is not present in the WSGI environment, the physical root of the resource tree will be returned instead.

Virtual roots are not useful at all in applications that use URL dispatch. Contexts obtained via URL dispatch don’t really support being virtually rooted (each URL dispatch context is both its own physical and virtual root). However if this API is called with a resource argument which is a context obtained via URL dispatch, the resource passed in will be returned unconditionally.

traverse(resource, path)

Given a resource object as resource and a string or tuple representing a path as path (such as the return value of pyramid.traversal.resource_path() or pyramid.traversal.resource_path_tuple() or the value of request.environ['PATH_INFO']), return a dictionary with the keys context, root, view_name, subpath, traversed, virtual_root, and virtual_root_path.

A definition of each value in the returned dictionary:

context: The context (a resource object) found via traversal or url dispatch. If the path passed in is the empty string, the value of the resource argument passed to this function is returned.

root: The resource object at which traversal begins. If the resource passed in was found via url dispatch or if the path passed in was relative (non-absolute), the value of the resource argument passed to this function is returned.

view_name: The view name found during traversal or url dispatch; if the resource was found via traversal, this is usually a representation of the path segment which directly follows the path to the context in the path. The view_name will be a Unicode object or the empty string. The view_name will be the empty string if there is no element which follows the context path. An example: if the path passed is /foo/bar, and a resource object is found at /foo (but not at /foo/bar), the ‘view name’ will be u'bar'. If the resource was found via urldispatch, the view_name will be the name the route found was registered with.

subpath: For a resource found via traversal, this is a sequence of path segments found in the path that follow the view_name (if any). Each of these items is a Unicode object. If no path segments follow the view_name, the subpath will be the empty sequence. An example: if the path passed is /foo/bar/baz/buz, and a resource object is found at /foo (but not /foo/bar), the ‘view name’ will be u'bar' and the subpath will be [u'baz', u'buz']. For a resource found via url dispatch, the subpath will be a sequence of values discerned from *subpath in the route pattern matched or the empty sequence.

traversed: The sequence of path elements traversed from the root to find the context object during traversal. Each of these items is a Unicode object. If no path segments were traversed to find the context object (e.g. if the path provided is the empty string), the traversed value will be the empty sequence. If the resource is a resource found via url dispatch, traversed will be None.

virtual_root: A resource object representing the ‘virtual’ root of the resource tree being traversed during traversal. See Virtual Hosting for a definition of the virtual root object. If no virtual hosting is in effect, and the path passed in was absolute, the virtual_root will be the physical root resource object (the object at which traversal begins). If the resource passed in was found via URL dispatch or if the path passed in was relative, the virtual_root will always equal the root object (the resource passed in).

virtual_root_path – If traversal was used to find the resource, this will be the sequence of path elements traversed to find the virtual_root resource. Each of these items is a Unicode object. If no path segments were traversed to find the virtual_root resource (e.g. if virtual hosting is not in effect), the traversed value will be the empty list. If url dispatch was used to find the resource, this will be None.

If the path cannot be resolved, a KeyError will be raised.

Rules for passing a string as the path argument: if the first character in the path string is the with the / character, the path will considered absolute and the resource tree traversal will start at the root resource. If the first character of the path string is not the / character, the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty string is passed as path, the resource passed in will be returned. Resource path strings must be escaped in the following manner: each Unicode path segment must be encoded as UTF-8 and each path segment must escaped via Python’s urllib.quote. For example, /path/to%20the/La%20Pe%C3%B1a (absolute) or to%20the/La%20Pe%C3%B1a (relative). The pyramid.traversal.resource_path() function generates strings which follow these rules (albeit only absolute ones).

Rules for passing a tuple as the path argument: if the first element in the path tuple is the empty string (for example ('', 'a', 'b', 'c'), the path is considered absolute and the resource tree traversal will start at the resource tree root object. If the first element in the path tuple is not the empty string (for example ('a', 'b', 'c')), the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty sequence is passed as path, the resource passed in itself will be returned. No URL-quoting or UTF-8-encoding of individual path segments within the tuple is required (each segment may be any string or unicode object representing a resource name).

Explanation of the conversion of path segment values to Unicode during traversal: Each segment is URL-unquoted, and decoded into Unicode. Each segment is assumed to be encoded using the UTF-8 encoding (or a subset, such as ASCII); a pyramid.exceptions.URLDecodeError is raised if a segment cannot be decoded. If a segment name is empty or if it is ., it is ignored. If a segment name is .., the previous segment is deleted, and the .. is ignored. As a result of this process, the return values view_name, each element in the subpath, each element in traversed, and each element in the virtual_root_path will be Unicode as opposed to a string, and will be URL-decoded.

traversal_path(path)

Given a PATH_INFO string (slash-separated path segments), return a tuple representing that path which can be used to traverse a resource tree.

The PATH_INFO is split on slashes, creating a list of segments. Each segment is URL-unquoted, and subsequently decoded into Unicode. Each segment is assumed to be encoded using the UTF-8 encoding (or a subset, such as ASCII); a pyramid.exceptions.URLDecodeError is raised if a segment cannot be decoded. If a segment name is empty or if it is ., it is ignored. If a segment name is .., the previous segment is deleted, and the .. is ignored.

If this function is passed a Unicode object instead of a string, that Unicode object must directly encodeable to ASCII. For example, u’/foo’ will work but u’/<unprintable unicode>’ (a Unicode object with characters that cannot be encoded to ascii) will not.

Examples:

/

()

/foo/bar/baz

(u’foo’, u’bar’, u’baz’)

foo/bar/baz

(u’foo’, u’bar’, u’baz’)

/foo/bar/baz/

(u’foo’, u’bar’, u’baz’)

/foo//bar//baz/

(u’foo’, u’bar’, u’baz’)

/foo/bar/baz/..

(u’foo’, u’bar’)

/my%20archives/hello

(u’my archives’, u’hello’)

/archives/La%20Pe%C3%B1a

(u’archives’, u’<unprintable unicode>’)

Note

This function does not generate the same type of tuples that pyramid.traversal.resource_path_tuple() does. In particular, the leading empty string is not present in the tuple it returns, unlike tuples returned by pyramid.traversal.resource_path_tuple(). As a result, tuples generated by traversal_path are not resolveable by the pyramid.traversal.find_resource() API. traversal_path is a function mostly used by the internals of Pyramid and by people writing their own traversal machinery, as opposed to users writing applications in Pyramid.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.url

Utility functions for dealing with URLs in pyramid

resource_url(context, request, *elements, query=None, anchor=None)

Generate a string representing the absolute URL of the resource object based on the wsgi.url_scheme, HTTP_HOST or SERVER_NAME in the request, plus any SCRIPT_NAME. The overall result of this function is always a UTF-8 encoded string (never Unicode).

Note

Calling pyramid.Request.resource_url() can be used to achieve the same result as pyramid.url.resource_url().

Examples:

resource_url(context, request) =>

                           http://example.com/

resource_url(context, request, 'a.html') =>

                           http://example.com/a.html

resource_url(context, request, 'a.html', query={'q':'1'}) =>

                           http://example.com/a.html?q=1

resource_url(context, request, 'a.html', anchor='abc') =>

                           http://example.com/a.html#abc

Any positional arguments passed in as elements must be strings or Unicode objects. These will be joined by slashes and appended to the generated resource URL. Each of the elements passed in is URL-quoted before being appended; if any element is Unicode, it will converted to a UTF-8 bytestring before being URL-quoted.

Warning

if no elements arguments are specified, the resource URL will end with a trailing slash. If any elements are used, the generated URL will not end in trailing a slash.

If a keyword argument query is present, it will be used to compose a query string that will be tacked on to the end of the URL. The value of query must be a sequence of two-tuples or a data structure with an .items() method that returns a sequence of two-tuples (presumably a dictionary). This data structure will be turned into a query string per the documentation of pyramid.url.urlencode function. After the query data is turned into a query string, a leading ? is prepended, and the resulting string is appended to the generated URL.

Note

Python data structures that are passed as query which are sequences or dictionaries are turned into a string under the same rules as when run through urllib.urlencode() with the doseq argument equal to True. This means that sequences can be passed as values, and a k=v pair will be placed into the query string for each value.

If a keyword argument anchor is present, its string representation will be used as a named anchor in the generated URL (e.g. if anchor is passed as foo and the resource URL is http://example.com/resource/url, the resulting generated URL will be http://example.com/resource/url#foo).

Note

If anchor is passed as a string, it should be UTF-8 encoded. If anchor is passed as a Unicode object, it will be converted to UTF-8 before being appended to the URL. The anchor value is not quoted in any way before being appended to the generated URL.

If both anchor and query are specified, the anchor element will always follow the query element, e.g. http://example.com?foo=1#bar.

If the resource passed in has a __resource_url__ method, it will be used to generate the URL (scheme, host, port, path) that for the base resource which is operated upon by this function. See also Overriding Resource URL Generation.

Note

If the resource used is the result of a traversal, it must be location-aware. The resource can also be the context of a URL dispatch; contexts found this way do not need to be location-aware.

Note

If a ‘virtual root path’ is present in the request environment (the value of the WSGI environ key HTTP_X_VHM_ROOT), and the resource was obtained via traversal, the URL path will not include the virtual root prefix (it will be stripped off the left hand side of the generated URL).

Note

For backwards compatibility purposes, this function can also be imported as model_url, although doing so will emit a deprecation warning.

route_url(route_name, request, *elements, **kw)

Generates a fully qualified URL for a named Pyramid route configuration.

Note

Calling pyramid.Request.route_url() can be used to achieve the same result as pyramid.url.route_url().

Use the route’s name as the first positional argument. Use a request object as the second positional argument. Additional positional arguments are appended to the URL as path segments after it is generated.

Use keyword arguments to supply values which match any dynamic path elements in the route definition. Raises a KeyError exception if the URL cannot be generated for any reason (not enough arguments, for example).

For example, if you’ve defined a route named “foobar” with the path {foo}/{bar}/*traverse:

route_url('foobar', request, foo='1')          => <KeyError exception>
route_url('foobar', request, foo='1', bar='2') => <KeyError exception>
route_url('foobar', request, foo='1', bar='2',
          traverse=('a','b'))                  => http://e.com/1/2/a/b
route_url('foobar', request, foo='1', bar='2',
          traverse='/a/b')                     => http://e.com/1/2/a/b

Values replacing :segment arguments can be passed as strings or Unicode objects. They will be encoded to UTF-8 and URL-quoted before being placed into the generated URL.

Values replacing *remainder arguments can be passed as strings or tuples of Unicode/string values. If a tuple is passed as a *remainder replacement value, its values are URL-quoted and encoded to UTF-8. The resulting strings are joined with slashes and rendered into the URL. If a string is passed as a *remainder replacement value, it is tacked on to the URL untouched.

If a keyword argument _query is present, it will be used to compose a query string that will be tacked on to the end of the URL. The value of _query must be a sequence of two-tuples or a data structure with an .items() method that returns a sequence of two-tuples (presumably a dictionary). This data structure will be turned into a query string per the documentation of pyramid.encode.urlencode() function. After the query data is turned into a query string, a leading ? is prepended, and the resulting string is appended to the generated URL.

Note

Python data structures that are passed as _query which are sequences or dictionaries are turned into a string under the same rules as when run through urllib.urlencode() with the doseq argument equal to True. This means that sequences can be passed as values, and a k=v pair will be placed into the query string for each value.

If a keyword argument _anchor is present, its string representation will be used as a named anchor in the generated URL (e.g. if _anchor is passed as foo and the route URL is http://example.com/route/url, the resulting generated URL will be http://example.com/route/url#foo).

Note

If _anchor is passed as a string, it should be UTF-8 encoded. If _anchor is passed as a Unicode object, it will be converted to UTF-8 before being appended to the URL. The anchor value is not quoted in any way before being appended to the generated URL.

If both _anchor and _query are specified, the anchor element will always follow the query element, e.g. http://example.com?foo=1#bar.

If a keyword _app_url is present, it will be used as the protocol/hostname/port/leading path prefix of the generated URL. For example, using an _app_url of http://example.com:8080/foo would cause the URL http://example.com:8080/foo/fleeb/flub to be returned from this function if the expansion of the route pattern associated with the route_name expanded to /fleeb/flub. If _app_url is not specified, the result of request.application_url will be used as the prefix (the default).

This function raises a KeyError if the URL cannot be generated due to missing replacement names. Extra replacement names are ignored.

If the route object which matches the route_name argument has a pregenerator, the *elements and **kw arguments arguments passed to this function might be augmented or changed.

current_route_url(request, *elements, **kw)

Generates a fully qualified URL for a named Pyramid route configuration based on the ‘current route’.

This function supplements pyramid.url.route_url(). It presents an easy way to generate a URL for the ‘current route’ (defined as the route which matched when the request was generated).

The arguments to this function have the same meaning as those with the same names passed to pyramid.url.route_url(). It also understands an extra argument which route_url does not named _route_name.

The route name used to generate a URL is taken from either the _route_name keyword argument or the name of the route which is currently associated with the request if _route_name was not passed. Keys and values from the current request matchdict are combined with the kw arguments to form a set of defaults named newkw. Then route_url(route_name, request, *elements, **newkw) is called, returning a URL.

Examples follow.

If the ‘current route’ has the route pattern /foo/{page} and the current url path is /foo/1 , the matchdict will be {'page':'1'}. The result of current_route_url(request) in this situation will be /foo/1.

If the ‘current route’ has the route pattern /foo/{page} and the current current url path is /foo/1, the matchdict will be {'page':'1'}. The result of current_route_url(request, page='2') in this situation will be /foo/2.

Usage of the _route_name keyword argument: if our routing table defines routes /foo/{action} named ‘foo’ and /foo/{action}/{page} named fooaction, and the current url pattern is /foo/view (which has matched the /foo/{action} route), we may want to use the matchdict args to generate a URL to the fooaction route. In this scenario, current_url(request, _route_name='fooaction', page='5') Will return string like: /foo/view/5.

route_path(route_name, request, *elements, **kw)

Generates a path (aka a ‘relative URL’, a URL minus the host, scheme, and port) for a named Pyramid route configuration.

Note

Calling pyramid.Request.route_path() can be used to achieve the same result as pyramid.url.route_path().

This function accepts the same argument as pyramid.url.route_url() and performs the same duty. It just omits the host, port, and scheme information in the return value; only the path, query parameters, and anchor data are present in the returned string.

For example, if you’ve defined a route named ‘foobar’ with the path /{foo}/{bar}, this call to route_path:

route_path('foobar', request, foo='1', bar='2')

Will return the string /1/2.

Note

Calling route_path('route', request) is the same as calling route_url('route', request, _app_url=''). route_path is, in fact, implemented in terms of route_url in just this way. As a result, any _app_url pass within the **kw values to route_path will be ignored.

static_url(path, request, **kw)

Generates a fully qualified URL for a static asset. The asset must live within a location defined via the pyramid.config.Configurator.add_static_view() configuration declaration (see Serving Static Assets).

Note

Calling pyramid.Request.static_url() can be used to achieve the same result as pyramid.url.static_url().

Example:

static_url('mypackage:static/foo.css', request) =>

                        http://example.com/static/foo.css

The path argument points at a file or directory on disk which a URL should be generated for. The path may be either a relative path (e.g. static/foo.css) or a asset specification (e.g. mypackage:static/foo.css). A path may not be an absolute filesystem path (a ValueError will be raised if this function is supplied with an absolute path).

The request argument should be a request object.

The purpose of the **kw argument is the same as the purpose of the pyramid.url.route_url() **kw argument. See the documentation for that function to understand the arguments which you can provide to it. However, typically, you don’t need to pass anything as *kw when generating a static asset URL.

This function raises a ValueError if a static view definition cannot be found which matches the path specification.

urlencode(query, doseq=True)

An alternate implementation of Python’s stdlib urllib.urlencode function [http://docs.python.org/library/urllib.html] which accepts unicode keys and values within the query dict/sequence; all Unicode keys and values are first converted to UTF-8 before being used to compose the query string.

The value of query must be a sequence of two-tuples representing key/value pairs or an object (often a dictionary) with an .items() method that returns a sequence of two-tuples representing key/value pairs.

For minimal calling convention backwards compatibility, this version of urlencode accepts but ignores a second argument conventionally named doseq. The Python stdlib version behaves differently when doseq is False and when a sequence is presented as one of the values. This version always behaves in the doseq=True mode, no matter what the value of the second argument.

See the Python stdlib documentation for urllib.urlencode for more information.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.view

render_view_to_response(context, request, name='', secure=True)

Call the view callable configured with a view configuration that matches the view name name registered against the specified context and request and return a response object. This function will return None if a corresponding view callable cannot be found (when no view configuration matches the combination of name / context / and request).

If secure` is True, and the view callable found is protected by a permission, the permission will be checked before calling the view function. If the permission check disallows view execution (based on the current authorization policy), a pyramid.exceptions.Forbidden exception will be raised. The exception’s args attribute explains why the view access was disallowed.

If secure is False, no permission checking is done.

render_view_to_iterable(context, request, name='', secure=True)

Call the view callable configured with a view configuration that matches the view name name registered against the specified context and request and return an iterable object which represents the body of a response. This function will return None if a corresponding view callable cannot be found (when no view configuration matches the combination of name / context / and request). Additionally, this function will raise a ValueError if a view function is found and called but the view function’s result does not have an app_iter attribute.

You can usually get the string representation of the return value of this function by calling ''.join(iterable), or just use pyramid.view.render_view() instead.

If secure is True, and the view is protected by a permission, the permission will be checked before the view function is invoked. If the permission check disallows view execution (based on the current authentication policy), a pyramid.exceptions.Forbidden exception will be raised; its args attribute explains why the view access was disallowed.

If secure is False, no permission checking is done.

render_view(context, request, name='', secure=True)

Call the view callable configured with a view configuration that matches the view name name registered against the specified context and request and unwind the view response’s app_iter (see View Callable Responses) into a single string. This function will return None if a corresponding view callable cannot be found (when no view configuration matches the combination of name / context / and request). Additionally, this function will raise a ValueError if a view function is found and called but the view function’s result does not have an app_iter attribute. This function will return None if a corresponding view cannot be found.

If secure is True, and the view is protected by a permission, the permission will be checked before the view is invoked. If the permission check disallows view execution (based on the current authorization policy), a pyramid.exceptions.Forbidden exception will be raised; its args attribute explains why the view access was disallowed.

If secure is False, no permission checking is done.

is_response(ob)

Return True if ob implements the interface implied by View Callable Responses. False if not.

Note

This isn’t a true interface or subclass check. Instead, it’s a duck-typing check, as response objects are not obligated to be of a particular class or provide any particular Zope interface.

class view_config(name='', request_type=None, for_=None, permission=None, route_name=None, request_method=None, request_param=None, containment=None, attr=None, renderer=None, wrapper=None, xhr=False, accept=None, header=None, path_info=None, custom_predicates=(), context=None, decorator=None, mapper=None)

A function, class or method decorator which allows a developer to create view registrations nearer to a view callable definition than use imperative configuration to do the same.

For example, this code in a module views.py:

from resources import MyResource

@view_config(name='my_view', context=MyResource, permission='read',
             route_name='site1')
def my_view(context, request):
    return 'OK'

Might replace the following call to the pyramid.config.Configurator.add_view() method:

import views
from resources import MyResource
config.add_view(views.my_view, context=MyResource, name='my_view',
                permission='read', 'route_name='site1')

The following arguments are supported as arguments to pyramid.view.view_config: context, permission, name, request_type, route_name, request_method, request_param, containment, xhr, accept, header, path_info, custom_predicates, decorator, and mapper.

The meanings of these arguments are the same as the arguments passed to pyramid.config.Configurator.add_view().

See View Configuration Using the @view_config Decorator for details about using view_config.

class static(root_dir, cache_max_age=3600, package_name=None)

An instance of this class is a callable which can act as a Pyramid view callable; this view will serve static files from a directory on disk based on the root_dir you provide to its constructor.

The directory may contain subdirectories (recursively); the static view implementation will descend into these directories as necessary based on the components of the URL in order to resolve a path into a response.

You may pass an absolute or relative filesystem path or a asset specification representing the directory containing static files as the root_dir argument to this class’ constructor.

If the root_dir path is relative, and the package_name argument is None, root_dir will be considered relative to the directory in which the Python file which calls static resides. If the package_name name argument is provided, and a relative root_dir is provided, the root_dir will be considered relative to the Python package specified by package_name (a dotted path to a Python package).

cache_max_age influences the Expires and Max-Age response headers returned by the view (default is 3600 seconds or five minutes).

Note

If the root_dir is relative to a package, or is a asset specification the Pyramid pyramid.config.Configurator method can be used to override assets within the named root_dir package-relative directory. However, if the root_dir is absolute, configuration will not be able to override the assets it contains.

append_slash_notfound_view(context, request)

For behavior like Django’s APPEND_SLASH=True, use this view as the Not Found view in your application.

When this view is the Not Found view (indicating that no view was found), and any routes have been defined in the configuration of your application, if the value of the PATH_INFO WSGI environment variable does not already end in a slash, and if the value of PATH_INFO plus a slash matches any route’s path, do an HTTP redirect to the slash-appended PATH_INFO. Note that this will lose POST data information (turning it into a GET), so you shouldn’t rely on this to redirect POST requests.

Use the pyramid.config.Configurator.add_view() method to configure this view as the Not Found view:

from pyramid.exceptions import NotFound
from pyramid.view import append_slash_notfound_view
config.add_view(append_slash_notfound_view, context=NotFound)

See also Changing the Not Found View.

class AppendSlashNotFoundViewFactory(notfound_view=None)

There can only be one Not Found view in any Pyramid application. Even if you use pyramid.view.append_slash_notfound_view() as the Not Found view, Pyramid still must generate a 404 Not Found response when it cannot redirect to a slash-appended URL; this not found response will be visible to site users.

If you don’t care what this 404 response looks like, and you only need redirections to slash-appended route URLs, you may use the pyramid.view.append_slash_notfound_view() object as the Not Found view. However, if you wish to use a custom notfound view callable when a URL cannot be redirected to a slash-appended URL, you may wish to use an instance of this class as the Not Found view, supplying a view callable to be used as the custom notfound view as the first argument to its constructor. For instance:

from pyramid.exceptions import NotFound
from pyramid.view import AppendSlashNotFoundViewFactory

def notfound_view(context, request):
    return HTTPNotFound('It aint there, stop trying!')

custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
config.add_view(custom_append_slash, context=NotFound)

The notfound_view supplied must adhere to the two-argument view callable calling convention of (context, request) (context will be the exception object).

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

API Documentation »

pyramid.wsgi

wsgiapp(wrapped)

Decorator to turn a WSGI application into a Pyramid view callable. This decorator differs from the pyramid.wsgi.wsgiapp2() decorator inasmuch as fixups of PATH_INFO and SCRIPT_NAME within the WSGI environment are not performed before the application is invoked.

E.g., the following in a views.py module:

@wsgiapp
def hello_world(environ, start_response):
    body = 'Hello world'
    start_response('200 OK', [ ('Content-Type', 'text/plain'),
                               ('Content-Length', len(body)) ] )
    return [body]

Allows the following call to pyramid.config.Configurator.add_view():

from views import hello_world
config.add_view(hello_world, name='hello_world.txt')

The wsgiapp decorator will convert the result of the WSGI application to a Response and return it to Pyramid as if the WSGI app were a pyramid view.

wsgiapp2(wrapped)

Decorator to turn a WSGI application into a Pyramid view callable. This decorator differs from the pyramid.wsgi.wsgiapp() decorator inasmuch as fixups of PATH_INFO and SCRIPT_NAME within the WSGI environment are performed before the application is invoked.

E.g. the following in a views.py module:

@wsgiapp2
def hello_world(environ, start_response):
    body = 'Hello world'
    start_response('200 OK', [ ('Content-Type', 'text/plain'),
                               ('Content-Length', len(body)) ] )
    return [body]

Allows the following call to pyramid.config.Configurator.add_view():

from views import hello_world
config.add_view(hello_world, name='hello_world.txt')

The wsgiapp2 decorator will convert the result of the WSGI application to a Response and return it to Pyramid as if the WSGI app were a Pyramid view. The SCRIPT_NAME and PATH_INFO values present in the WSGI environment are fixed up before the application is invoked.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

next |

previous |

The Pyramid Web Application Development Framework v1.0 »

Pyramid Change History

1.0 (2011-01-30)

Documentation

Fixed bug in ZODB Wiki tutorial (missing dependency on docutils in “models” step within setup.py).

Removed API documentation for pyramid.testing APIs named registerDummySecurityPolicy, registerResources, registerModels, registerEventListener, registerTemplateRenderer, registerDummyRenderer, registerView, registerUtility, registerAdapter, registerSubscriber, registerRoute, and registerSettings.

Moved “Using ZODB With ZEO” and “Using repoze.catalog Within Pyramid” tutorials out of core documentation and into the Pyramid Tutorials site (http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/).

Changed “Cleaning up After a Request” section in the URL Dispatch chapter to use request.add_finished_callback instead of jamming an object with a __del__ into the WSGI environment.

Remove duplication of add_route API documentation from URL Dispatch narrative chapter.

Remove duplication of API and narrative documentation in pyramid.view.view_config API docs by pointing to pyramid.config.add_view documentation and narrative chapter documentation.

Removed some API documentation duplicated in narrative portions of documentation

Removed “Overall Flow of Authentication” from SQLAlchemy + URL Dispatch wiki tutorial due to print space concerns (moved to Pyramid Tutorials site).

Bug Fixes

Deprecated-since-BFG-1.2 APIs from pyramid.testing now properly emit deprecation warnings.

Added egg:repoze.retry#retry middleware to the WSGI pipeline in ZODB templates (retry ZODB conflict errors which occur in normal operations).

Removed duplicate implementations of is_response. Two competing implementations existed: one in pyramid.config and one in pyramid.view. Now the one defined in pyramid.view is used internally by pyramid.config and continues to be advertised as an API.

1.0b3 (2011-01-28)

Bug Fixes

Use &copy; instead of copyright symbol in paster templates / tutorial templates for the benefit of folks who cutnpaste and save to a non-UTF8 format.

pyramid.view.append_slash_notfound_view now preserves GET query parameters across redirects.

Documentation

Beef up documentation related to set_default_permission: explicitly mention that default permissions also protect exception views.

Paster templates and tutorials now use spaces instead of tabs in their HTML templates.

1.0b2 (2011-01-24)

Bug Fixes

The production.ini generated by all paster templates now have an effective logging level of WARN, which prevents e.g. SQLAlchemy statement logging and other inappropriate output.

The production.ini of the pyramid_routesalchemy and pyramid_alchemy paster templates did not have a sqlalchemy logger section, preventing paster serve production.ini from working.

The pyramid_routesalchemy and pyramid_alchemy paster templates used the {{package}} variable in a place where it should have used the {{project}} variable, causing applications created with uppercase letters e.g. paster create -t pyramid_routesalchemy Dibbus to fail to start when paster serve development.ini was used against the result. See https://github.com/Pylons/pyramid/issues/#issue/107

The render_view method of pyramid.renderers.RendererHelper passed an incorrect value into the renderer for renderer_info. It now passes an instance of RendererHelper instead of a dictionary, which is consistent with other usages. See https://github.com/Pylons/pyramid/issues#issue/106

A bug existed in the pyramid.authentication.AuthTktCookieHelper which would break any usage of an AuthTktAuthenticationPolicy when one was configured to reissue its tokens (reissue_time < timeout / max_age). Symptom: ValueError: ('Invalid token %r', ''). See https://github.com/Pylons/pyramid/issues#issue/108.

1.0b1 (2011-01-21)

Features

The AuthTktAuthenticationPolicy now accepts a tokens parameter via pyramid.security.remember. The value must be a sequence of strings. Tokens are placed into the auth_tkt “tokens” field and returned in the auth_tkt cookie.

Add wild_domain argument to AuthTktAuthenticationPolicy, which defaults to True. If it is set to False, the feature of the policy which sets a cookie with a wilcard domain will be turned off.

Add a MANIFEST.in file to each paster template. See https://github.com/Pylons/pyramid/issues#issue/95

Bug Fixes

testing.setUp now adds a settings attribute to the registry (both when it’s passed a registry without any settings and when it creates one).

The testing.setUp function now takes a settings argument, which should be a dictionary. Its values will subsequently be available on the returned config object as config.registry.settings.

Documentation

Added “What’s New in Pyramid 1.0” chapter to HTML rendering of documentation.

Merged caseman-master narrative editing branch, many wording fixes and extensions.

Fix deprecated example showing chameleon_zpt API call in testing narrative chapter.

Added “Adding Methods to the Configurator via add_directive” section to Advanced Configuration narrative chapter.

Add docs for add_finished_callback, add_response_callback, route_path, route_url, and static_url methods to pyramid.request.Request API docs.

Add (minimal) documentation about using I18N within Mako templates to “Internationalization and Localization” narrative chapter.

Move content of “Forms” chapter back to “Views” chapter; I can’t think of a better place to put it.

Slightly improved interface docs for IAuthorizationPolicy.

Minimally explain usage of custom regular expressions in URL dispatch replacement markers within URL Dispatch chapter.

Deprecations

Using the pyramid.view.bfg_view alias for pyramid.view.view_config (a backwards compatibility shim) now issues a deprecation warning.

Backwards Incompatibilities

When a pyramid.exceptions.Forbidden error is raised, its status code now 403 Forbidden. It was previously 401 Unauthorized, for backwards compatibility purposes with repoze.bfg. This change will cause problems for users of Pyramid with repoze.who, which intercepts 401 Unauthorized by default, but allows 403 Forbidden to pass through. Those deployments will need to configure repoze.who to also react to 403 Forbidden.

The default value for the cookie_on_exception parameter to pyramid.session.UnencyrptedCookieSessionFactory is now True. This means that when view code causes an exception to be raised, and the session has been mutated, a cookie will be sent back in the response. Previously its default value was False.

Paster Templates

The pyramid_zodb, pyramid_routesalchemy and pyramid_alchemy paster templates now use a default “commit veto” hook when configuring the repoze.tm2 transaction manager in development.ini. This prevents a transaction from being committed when the response status code is within the 400 or 500 ranges. See also http://docs.repoze.org/tm2/#using-a-commit-veto.

1.0a10 (2011-01-18)

Bug Fixes

URL dispatch now properly handles a .* or * appearing in a regex match when used inside brackets. Resolves issue #90.

Backwards Incompatibilities

The add_handler method of a Configurator has been removed from the Pyramid core. Handlers are now a feature of the pyramid_handlers package, which can be downloaded from PyPI. Documentation for the package should be available via http://pylonsproject.org/projects/pyramid_handlers/dev/, which describes how to add a configuration statement to your main block to reobtain this method. You will also need to add an install_requires dependency upon pyramid_handlers to your setup.py file.

The load_zcml method of a Configurator has been removed from the Pyramid core. Loading ZCML is now a feature of the pyramid_zcml package, which can be downloaded from PyPI. Documentation for the package should be available via http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how to add a configuration statement to your main block to reobtain this method. You will also need to add an install_requires dependency upon pyramid_zcml to your setup.py file.

The pyramid.includes subpackage has been removed. ZCML files which use include the package pyramid.includes (e.g. <include package="pyramid.includes"/>) now must include the pyramid_zcml package instead (e.g. <include package="pyramid_zcml"/>).

The pyramid.view.action decorator has been removed from the Pyramid core. Handlers are now a feature of the pyramid_handlers package. It should now be imported from pyramid_handlers e.g. from pyramid_handlers import action.

The handler ZCML directive has been removed. It is now a feature of the pyramid_handlers package.

The pylons_minimal, pylons_basic and pylons_sqla paster templates were removed. Use pyramid_sqla (available from PyPI) as a generic replacement for Pylons-esque development.

The make_app function has been removed from the pyramid.router module. It continues life within the pyramid_zcml package. This leaves the pyramid.router module without any API functions.

The configure_zcml setting within the deployment settings (within **settings passed to a Pyramid main function) has ceased to have any meaning.

Features

pyramid.testing.setUp and pyramid.testing.tearDown have been undeprecated. They are now the canonical setup and teardown APIs for test configuration, replacing “direct” creation of a Configurator. This is a change designed to provide a facade that will protect against any future Configurator deprecations.

Add charset attribute to pyramid.testing.DummyRequest (unconditionally UTF-8).

Add add_directive method to configurator, which allows framework extenders to add methods to the configurator (ala ZCML directives).

When Configurator.include is passed a module as an argument, it defaults to attempting to find and use a callable named includeme within that module. This makes it possible to use config.include('some.module') rather than config.include('some.module.somefunc') as long as the include function within some.module is named includeme.

The bfg2pyramid script now converts ZCML include tags that have repoze.bfg.includes as a package attribute to the value pyramid_zcml. For example, <include package="repoze.bfg.includes"> will be converted to <include package="pyramid_zcml">.

Paster Templates

All paster templates now use pyramid.testing.setUp and pyramid.testing.tearDown rather than creating a Configurator “by hand” within their tests.py module, as per decision in features above.

The starter_zcml paster template has been moved to the pyramid_zcml package.

Documentation

The wiki and wiki2 tutorials now use pyramid.testing.setUp and pyramid.testing.tearDown rather than creating a Configurator “by hand”, as per decision in features above.

The “Testing” narrative chapter now explains pyramid.testing.setUp and pyramid.testing.tearDown instead of Configurator creation and Configurator.begin() and Configurator.end().

Document the request.override_renderer attribute within the narrative “Renderers” chapter in a section named “Overriding A Renderer at Runtime”.

The “Declarative Configuration” narrative chapter has been removed (it was moved to the pyramid_zcml package).

Most references to ZCML in narrative chapters have been removed or redirected to pyramid_zcml locations.

Deprecations

Deprecation warnings related to import of the following API functions were added: pyramid.traversal.find_model, pyramid.traversal.model_path, pyramid.traversal.model_path_tuple, pyramid.url.model_url. The instructions emitted by the deprecation warnings instruct the developer to change these method spellings to their resource equivalents. This is a consequence of the mass concept rename of “model” to “resource” performed in 1.0a7.

1.0a9 (2011-01-08)

Bug Fixes

The proutes command tried too hard to resolve the view for printing, resulting in exceptions when an exceptional root factory was encountered. Instead of trying to resolve the view, if it cannot, it will now just print <unknown>.

The self argument was included in new methods of the ISession interface signature, causing pyramid_beaker tests to fail.

Readd pyramid.traversal.model_path_tuple as an alias for pyramid.traversal.resource_path_tuple for backwards compatibility.

Features

Add a new API pyramid.url.current_route_url, which computes a URL based on the “current” route (if any) and its matchdict values.

config.add_view now accepts a decorator keyword argument, a callable which will decorate the view callable before it is added to the registry.

If a handler class provides an __action_decorator__ attribute (usually a classmethod or staticmethod), use that as the decorator for each view registration for that handler.

The pyramid.interfaces.IAuthenticationPolicy interface now specifies an unauthenticated_userid method. This method supports an important optimization required by people who are using persistent storages which do not support object caching and whom want to create a “user object” as a request attribute.

A new API has been added to the pyramid.security module named unauthenticated_userid. This API function calls the unauthenticated_userid method of the effective security policy.

An unauthenticated_userid method has been added to the dummy authentication policy returned by pyramid.config.Configurator.testing_securitypolicy. It returns the same thing as that the dummy authentication policy’s authenticated_userid method.

The class pyramid.authentication.AuthTktCookieHelper is now an API. This class can be used by third-party authentication policy developers to help in the mechanics of authentication cookie-setting.

New constructor argument to Configurator: default_view_mapper. Useful to create systems that have alternate view calling conventions. A view mapper allows objects that are meant to be used as view callables to have an arbitrary argument list and an arbitrary result. The object passed as default_view_mapper should implement the pyramid.interfaces.IViewMapperFactory interface.

add a set_view_mapper API to Configurator. Has the same result as passing default_view_mapper to the Configurator constructor.

config.add_view now accepts a mapper keyword argument, which should either be None, a string representing a Python dotted name, or an object which is an IViewMapperFactory. This feature is not useful for “civilians”, only for extension writers.

Allow static renderer provided during view registration to be overridden at request time via a request attribute named override_renderer, which should be the name of a previously registered renderer. Useful to provide “omnipresent” RPC using existing rendered views.

Instances of pyramid.testing.DummyRequest now have a session object, which is mostly a dictionary, but also implements the other session API methods for flash and CSRF.

Backwards Incompatibilities

Since the pyramid.interfaces.IAuthenticationPolicy interface now specifies that a policy implementation must implement an unauthenticated_userid method, all third-party custom authentication policies now must implement this method. It, however, will only be called when the global function named pyramid.security.unauthenticated_userid is invoked, so if you’re not invoking that, you will not notice any issues.

pyramid.interfaces.ISession.get_csrf_token now mandates that an implementation should return a new token if one doesn’t already exist in the session (previously it would return None). The internal sessioning implementation has been changed.

Documentation

The (weak) “Converting a CMF Application to Pyramid” tutorial has been removed from the tutorials section. It was moved to the pyramid_tutorials Github repository.

The “Resource Location and View Lookup” chapter has been replaced with a variant of Rob Miller’s “Much Ado About Traversal” (originally published at http://blog.nonsequitarian.org/2010/much-ado-about-traversal/).

Many minor wording tweaks and refactorings (merged Casey Duncan’s docs fork, in which he is working on general editing).

Added (weak) description of new view mapper feature to Hooks narrative chapter.

Split views chapter into 2: View Callables and View Configuration.

Reorder Renderers and Templates chapters after View Callables but before View Configuration.

Merge Session Objects, Cross-Site Request Forgery, and Flash Messaging chapter into a single Sessions chapter.

The Wiki and Wiki2 tutorials now have much nicer CSS and graphics.

Internals

The “view derivation” code is now factored into a set of classes rather than a large number of standalone functions (a side effect of the view mapper refactoring).

The pyramid.renderer.RendererHelper class has grown a render_view method, which is used by the default view mapper (a side effect of the view mapper refactoring).

The object passed as renderer to the “view deriver” is now an instance of pyramid.renderers.RendererHelper rather than a dictionary (a side effect of view mapper refactoring).

The class used as the “page template” in pyramid.chameleon_text was removed, in preference to using a Chameleon-inbuilt version.

A view callable wrapper registered in the registry now contains an __original_view__ attribute which references the original view callable (or class).

The (non-API) method of all internal authentication policy implementations previously named _get_userid is now named unauthenticated_userid, promoted to an API method. If you were overriding this method, you’ll now need to override it as unauthenticated_userid instead.

Remove (non-API) function of config.py named _map_view.

1.0a8 (2010-12-27)

Bug Fixes

The name registry was not available in the paster pshell environment under IPython.

Features

If a resource implements a __resource_url__ method, it will be called as the result of invoking the pyramid.url.resource_url function to generate a URL, overriding the default logic. See the new “Generating The URL Of A Resource” section within the Resources narrative chapter.

Added flash messaging, as described in the “Flash Messaging” narrative documentation chapter.

Added CSRF token generation, as described in the narrative chapter entitled “Preventing Cross-Site Request Forgery Attacks”.

Prevent misunderstanding of how the view and view_permission arguments to add_route work by raising an exception during configuration if view-related arguments exist but no view argument is passed.

Add paster proute command which displays a summary of the routing table. See the narrative documentation section within the “URL Dispatch” chapter entitled “Displaying All Application Routes”.

Paster Templates

The pyramid_zodb Paster template no longer employs ZCML. Instead, it is based on scanning.

Documentation

Added “Generating The URL Of A Resource” section to the Resources narrative chapter (includes information about overriding URL generation using __resource_url__).

Added “Generating the Path To a Resource” section to the Resources narrative chapter.

Added “Finding a Resource by Path” section to the Resources narrative chapter.

Added “Obtaining the Lineage of a Resource” to the Resources narrative chapter.

Added “Determining if a Resource is In The Lineage of Another Resource” to Resources narrative chapter.

Added “Finding the Root Resource” to Resources narrative chapter.

Added “Finding a Resource With a Class or Interface in Lineage” to Resources narrative chapter.

Added a “Flash Messaging” narrative documentation chapter.

Added a narrative chapter entitled “Preventing Cross-Site Request Forgery Attacks”.

Changed the “ZODB + Traversal Wiki Tutorial” based on changes to pyramid_zodb Paster template.

Added “Advanced Configuration” narrative chapter which documents how to deal with configuration conflicts, two-phase configuration, include and commit.

Fix API documentation rendering for pyramid.view.static

Add “Pyramid Provides More Than One Way to Do It” to Design Defense documentation.

Changed “Static Assets” narrative chapter: clarify that name represents a prefix unless it’s a URL, added an example of a root-relative static view fallback for URL dispatch, added an example of creating a simple view that returns the body of a file.

Move ZCML usage in Hooks chapter to Declarative Configuration chapter.

Merge “Static Assets” chapter into the “Assets” chapter.

Added narrative documentation section within the “URL Dispatch” chapter entitled “Displaying All Application Routes” (for paster proutes command).

1.0a7 (2010-12-20)

Terminology Changes

The Pyramid concept previously known as “model” is now known as “resource”. As a result:

The following API changes have been made:

pyramid.url.model_url ->
                  pyramid.url.resource_url

pyramid.traversal.find_model ->
                  pyramid.url.find_resource

pyramid.traversal.model_path ->
                  pyramid.traversal.resource_path

pyramid.traversal.model_path_tuple ->
                  pyramid.traversal.resource_path_tuple

pyramid.traversal.ModelGraphTraverser ->
                  pyramid.traversal.ResourceTreeTraverser

pyramid.config.Configurator.testing_models ->
                  pyramid.config.Configurator.testing_resources

pyramid.testing.registerModels ->
                  pyramid.testing.registerResources

pyramid.testing.DummyModel ->
                  pyramid.testing.DummyResource

All documentation which previously referred to “model” now refers to “resource”.

The starter and starter_zcml paster templates now have a resources.py module instead of a models.py module.

Positional argument names of various APIs have been changed from model to resource.

Backwards compatibility shims have been left in place in all cases. They will continue to work “forever”.

The Pyramid concept previously known as “resource” is now known as “asset”. As a result:

The (non-API) module previously known as pyramid.resource is now known as pyramid.asset.

All docs that previously referred to “resource specification” now refer to “asset specification”.

The following API changes were made:

pyramid.config.Configurator.absolute_resource_spec ->
                  pyramid.config.Configurator.absolute_asset_spec

pyramid.config.Configurator.override_resource ->
                  pyramid.config.Configurator.override_asset

The ZCML directive previously known as resource is now known as asset.

The setting previously known as BFG_RELOAD_RESOURCES (envvar) or reload_resources (config file) is now known, respectively, as PYRAMID_RELOAD_ASSETS and reload_assets.

Backwards compatibility shims have been left in place in all cases. They will continue to work “forever”.

Bug Fixes

Make it possible to succesfully run all tests via nosetests command directly (rather than indirectly via python setup.py nosetests).

When a configuration conflict is encountered during scanning, the conflict exception now shows the decorator information that caused the conflict.

Features

Added debug_routematch configuration setting that logs matched routes (including the matchdict and predicates).

The name registry is now available in a pshell environment by default. It is the application registry object.

Environment

All environment variables which used to be prefixed with BFG_ are now prefixed with PYRAMID_ (e.g. BFG_DEBUG_NOTFOUND is now PYRAMID_DEBUG_NOTFOUND)

Documentation

Added “Debugging Route Matching” section to the urldispatch narrative documentation chapter.

Added reference to PYRAMID_DEBUG_ROUTEMATCH envvar and debug_routematch config file setting to the Environment narrative docs chapter.

Changed “Project” chapter slightly to expand on use of paster pshell.

Direct Jython users to Mako rather than Jinja2 in “Install” narrative chapter.

Many changes to support terminological renaming of “model” to “resource” and “resource” to “asset”.

Added an example of WebTest functional testing to the testing narrative chapter.

Rearranged chapter ordering by popular demand (URL dispatch first, then traversal). Put hybrid chapter after views chapter.

Split off “Renderers” as its own chapter from “Views” chapter in narrative documentation.

Paster Templates

Added debug_routematch = false to all paster templates.

Dependencies

Depend on Venusian >= 0.5 (for scanning conflict exception decoration).

1.0a6 (2010-12-15)

Bug Fixes

1.0a5 introduced a bug when pyramid.config.Configurator.scan was used without a package argument (e.g. config.scan() as opposed to config.scan('packagename'). The symptoms were: lots of deprecation warnings printed to the console about imports of deprecated Pyramid functions and classes and non-detection of view callables decorated with view_config decorators. This has been fixed.

Tests now pass on Windows (no bugs found, but a few tests in the test suite assumed UNIX path segments in filenames).

Documentation

If you followed it to-the-letter, the ZODB+Traversal Wiki tutorial would instruct you to run a test which would fail because the view callable generated by the pyramid_zodb tutorial used a one-arg view callable, but the test in the sample code used a two-arg call.

Updated ZODB+Traversal tutorial setup.py of all steps to match what’s generated by pyramid_zodb.

Fix reference to repoze.bfg.traversalwrapper in “Models” chapter (point at pyramid_traversalwrapper instead).

1.0a5 (2010-12-14)

Features

Add a handler ZCML directive. This directive does the same thing as pyramid.configuration.add_handler.

A new module named pyramid.config was added. It subsumes the duties of the older pyramid.configuration module.

The new pyramid.config.Configurator` class has API methods that the older ``pyramid.configuration.Configurator class did not: with_context (a classmethod), include, action, and commit. These methods exist for imperative application extensibility purposes.

The pyramid.testing.setUp function now accepts an autocommit keyword argument, which defaults to True. If it is passed False, the Config object returned by setUp will be a non-autocommiting Config object.

Add logging configuration to all paster templates.

pyramid_alchemy, pyramid_routesalchemy, and pylons_sqla paster templates now use idiomatic SQLAlchemy configuration in their respective .ini files and Python code.

pyramid.testing.DummyRequest now has a class variable, query_string, which defaults to the empty string.

Add support for json on GAE by catching NotImplementedError and importing simplejson from django.utils.

The Mako renderer now accepts a resource specification for mako.module_directory.

New boolean Mako settings variable mako.strict_undefined. See Mako Context Variables [http://www.makotemplates.org/docs/runtime.html#context-variables] for its meaning.

Dependencies

Depend on Mako 0.3.6+ (we now require the strict_undefined feature).

Bug Fixes

When creating a Configurator from within a paster pshell session, you were required to pass a package argument although package is not actually required. If you didn’t pass package, you would receive an error something like KeyError: '__name__' emanating from the pyramid.path.caller_module function. This has now been fixed.

The pyramid_routesalchemy paster template’s unit tests failed (AssertionError: 'SomeProject' != 'someproject'). This is fixed.

Make default renderer work (renderer factory registered with no name, which is active for every view unless the view names a specific renderer).

The Mako renderer did not properly turn the mako.imports, mako.default_filters, and mako.imports settings into lists.

The Mako renderer did not properly convert the mako.error_handler setting from a dotted name to a callable.

Documentation

Merged many wording, readability, and correctness changes to narrative documentation chapters from https://github.com/caseman/pyramid (up to and including “Models” narrative chapter).

“Sample Applications” section of docs changed to note existence of Cluegun, Shootout and Virginia sample applications, ported from their repoze.bfg origin packages.

SQLAlchemy+URLDispatch tutorial updated to integrate changes to pyramid_routesalchemy template.

Add pyramid.interfaces.ITemplateRenderer interface to Interfaces API chapter (has implementation() method, required to be used when getting at Chameleon macros).

Add a “Modifying Package Structure” section to the project narrative documentation chapter (explain turning a module into a package).

Documentation was added for the new handler ZCML directive in the ZCML section.

Deprecations

pyramid.configuration.Configurator is now deprecated. Use pyramid.config.Configurator, passing its constructor autocommit=True instead. The pyramid.configuration.Configurator alias will live for a long time, as every application uses it, but its import now issues a deprecation warning. The pyramid.config.Configurator class has the same API as pyramid.configuration.Configurator class, which it means to replace, except by default it is a non-autocommitting configurator. The now-deprecated pyramid.configuration.Configurator will autocommit every time a configuration method is called.

The pyramid.configuration module remains, but it is deprecated. Use pyramid.config instead.

1.0a4 (2010-11-21)

Features

URL Dispatch now allows for replacement markers to be located anywhere in the pattern, instead of immediately following a /.

URL Dispatch now uses the form {marker} to denote a replace marker in the route pattern instead of :marker. The old colon-style marker syntax is still accepted for backwards compatibility. The new format allows a regular expression for that marker location to be used instead of the default [^/]+, for example {marker:\d+} is now valid to require the marker to be digits.

Add a pyramid.url.route_path API, allowing folks to generate relative URLs. Calling route_path is the same as calling pyramid.url.route_url with the argument _app_url equal to the empty string.

Add a pyramid.request.Request.route_path API. This is a convenience method of the request which calls pyramid.url.route_url.

Make test suite pass on Jython (requires PasteScript trunk, presumably to be 1.7.4).

Make test suite pass on PyPy (Chameleon doesn’t work).

Surrounding application configuration with config.begin() and config.end() is no longer necessary. All paster templates have been changed to no longer call these functions.

Fix configurator to not convert ImportError to ConfigurationError if the import that failed was unrelated to the import requested via a dotted name when resolving dotted names (such as view dotted names).

Documentation

SQLAlchemy+URLDispatch and ZODB+Traversal tutorials have been updated to not call config.begin() or config.end().

Bug Fixes

Add deprecation warnings to import of pyramid.chameleon_text and pyramid.chameleon_zpt of get_renderer, get_template, render_template, and render_template_to_response.

Add deprecation warning for import of pyramid.zcml.zcml_configure and pyramid.zcml.file_configure.

The pyramid_alchemy paster template had a typo, preventing an import from working.

Fix apparent failures when calling pyramid.traversal.find_model(root, path) or pyramid.traversal.traverse(path) when path is (erroneously) a Unicode object. The user is meant to pass these APIs a string object, never a Unicode object. In practice, however, users indeed pass Unicode. Because the string that is passed must be ASCII encodeable, now, if they pass a Unicode object, its data is eagerly converted to an ASCII string rather than being passed along to downstream code as a convenience to the user and to prevent puzzling second-order failures from cropping up (all failures will occur within pyramid.traversal.traverse rather than later down the line as the result of calling e.g. traversal_path).

Backwards Incompatibilities

The pyramid.testing.zcml_configure API has been removed. It had been advertised as removed since repoze.bfg 1.2a1, but hadn’t actually been.

Deprecations

The pyramid.settings.get_settings API is now deprecated. Use pyramid.threadlocals.get_current_registry().settings instead or use the settings attribute of the registry available from the request (request.registry.settings).

Documentation

Removed zodbsessions tutorial chapter. It’s still useful, but we now have a SessionFactory abstraction which competes with it, and maintaining documentation on both ways to do it is a distraction.

Internal

Replace Twill with WebTest in internal integration tests (avoid deprecation warnings generated by Twill).

1.0a3 (2010-11-16)

Features

Added Mako TemplateLookup settings for mako.error_handler, mako.default_filters, and mako.imports.

Normalized all paster templates: each now uses the name main to represent the function that returns a WSGI application, each now uses WebError, each now has roughly the same shape of development.ini style.

Added class vars matchdict and matched_route to pyramid.request.Request. Each is set to None.

New API method: pyramid.settings.asbool.

New API methods for pyramid.request.Request: model_url, route_url, and static_url. These are simple passthroughs for their respective functions in pyramid.url.

The settings object which used to be available only when request.settings.get_settings was called is now available as registry.settings (e.g. request.registry.settings in view code).

Bug Fixes

The pylons_* paster templates erroneously used the {squiggly} routing syntax as the pattern supplied to add_route. This style of routing is not supported. They were replaced with :colon style route patterns.

The pylons_* paster template used the same string (your_app_secret_string) for the session.secret setting in the generated development.ini. This was a security risk if left unchanged in a project that used one of the templates to produce production applications. It now uses a randomly generated string.

Documentation

ZODB+traversal wiki (wiki) tutorial updated due to changes to pyramid_zodb paster template.

SQLAlchemy+urldispach wiki (wiki2) tutorial updated due to changes to pyramid_routesalchemy paster template.

Documented the matchdict and matched_route attributes of the request object in the Request API documentation.

Deprecations

Obtaining the settings object via registry.{get|query}Utility(ISettings) is now deprecated. Instead, obtain the settings object via the registry.settings attribute. A backwards compatibility shim was added to the registry object to register the settings object as an ISettings utility when setattr(registry, 'settings', foo) is called, but it will be removed in a later release.

Obtaining the settings object via pyramid.settings.get_settings is now deprecated. Obtain it as the settings attribute of the registry now (obtain the registry via pyramid.threadlocal.get_registry or as request.registry).

Behavior Differences

Internal: ZCML directives no longer call get_current_registry() if there’s a registry attribute on the ZCML context (kill off use of threadlocals).

Internal: Chameleon template renderers now accept two arguments: path and lookup. Lookup will be an instance of a lookup class which supplies (late-bound) arguments for debug, reload, and translate. Any third-party renderers which use (the non-API) function pyramid.renderers.template_renderer_factory will need to adjust their implementations to obey the new callback argument list. This change was to kill off inappropriate use of threadlocals.

1.0a2 (2010-11-09)

Documentation

All references to events by interface (e.g. pyramid.interfaces.INewRequest) have been changed to reference their concrete classes (e.g. pyramid.events.NewRequest) in documentation about making subscriptions.

All references to Pyramid-the-application were changed from mod-pyramid to app-Pyramid. A custom role setting was added to docs/conf.py to allow for this. (internal)

1.0a1 (2010-11-05)

Features (delta from BFG 1.3)

Mako templating renderer supports resource specification format for template lookups and within Mako templates. Absolute filenames must be used in Pyramid to avoid this lookup process.

Add pyramid.httpexceptions module, which is a facade for the webob.exc module.

Direct built-in support for the Mako templating language.

A new configurator method exists: add_handler. This method adds a Pylons-style “view handler” (such a thing used to be called a “controller” in Pylons 1.0).

New argument to configurator: session_factory.

New method on configurator: set_session_factory

Using request.session now returns a (dictionary-like) session object if a session factory has been configured.

The request now has a new attribute: tmpl_context for benefit of Pylons users.

The decorator previously known as pyramid.view.bfg_view is now known most formally as pyramid.view.view_config in docs and paster templates. An import of pyramid.view.bfg_view, however, will continue to work “forever”.

New API methods in pyramid.session: signed_serialize and signed_deserialize.

New interface: pyramid.interfaces.IRendererInfo. An object of this type is passed to renderer factory constructors (see “Backwards Incompatibilities”).

New event type: pyramid.interfaces.IBeforeRender. An object of this type is sent as an event before a renderer is invoked (but after the application-level renderer globals factory added via pyramid.configurator.configuration.set_renderer_globals_factory, if any, has injected its own keys). Applications may now subscribe to the IBeforeRender event type in order to introspect the and modify the set of renderer globals before they are passed to a renderer. The event object iself has a dictionary-like interface that can be used for this purpose. For example:

from repoze.events import subscriber
from pyramid.interfaces import IRendererGlobalsEvent

@subscriber(IRendererGlobalsEvent)
def add_global(event):
    event['mykey'] = 'foo'

If a subscriber attempts to add a key that already exist in the renderer globals dictionary, a KeyError is raised. This limitation is due to the fact that subscribers cannot be ordered relative to each other. The set of keys added to the renderer globals dictionary by all subscribers and app-level globals factories must be unique.

New class: pyramid.response.Response. This is a pure facade for webob.Response (old code need not change to use this facade, it’s existence is mostly for vanity and documentation-generation purposes).

All preexisting paster templates (except zodb) now use “imperative” configuration (starter, routesalchemy, alchemy).

A new paster template named pyramid_starter_zcml exists, which uses declarative configuration.

Documentation (delta from BFG 1.3)

Added a pyramid.httpexceptions API documentation chapter.

Added a pyramid.session API documentation chapter.

Added a Session Objects narrative documentation chapter.

Added an API chapter for the pyramid.personality module.

Added an API chapter for the pyramid.response module.

All documentation which previously referred to webob.Response now uses pyramid.response.Response instead.

The documentation has been overhauled to use imperative configuration, moving declarative configuration (ZCML) explanations to a separate narrative chapter declarative.rst.

The ZODB Wiki tutorial was updated to take into account changes to the pyramid_zodb paster template.

The SQL Wiki tutorial was updated to take into account changes to the pyramid_routesalchemy paster template.

Backwards Incompatibilities (with BFG 1.3)

There is no longer an IDebugLogger registered as a named utility with the name repoze.bfg.debug.

The logger which used to have the name of repoze.bfg.debug now has the name pyramid.debug.

The deprecated API pyramid.testing.registerViewPermission has been removed.

The deprecated API named pyramid.testing.registerRoutesMapper has been removed.

The deprecated API named pyramid.request.get_request was removed.

The deprecated API named pyramid.security.Unauthorized was removed.

The deprecated API named pyramid.view.view_execution_permitted was removed.

The deprecated API named pyramid.view.NotFound was removed.

The bfgshell paster command is now named pshell.

The Venusian “category” for all built-in Venusian decorators (e.g. subscriber and view_config/bfg_view) is now pyramid instead of bfg.

pyramid.renderers.rendered_response function removed; use render_pyramid.renderers.render_to_response instead.

Renderer factories now accept a renderer info object rather than an absolute resource specification or an absolute path. The object has the following attributes: name (the renderer= value), package (the ‘current package’ when the renderer configuration statement was found), type: the renderer type, registry: the current registry, and settings: the deployment settings dictionary.

Third-party repoze.bfg renderer implementations that must be ported to Pyramid will need to account for this.

This change was made primarily to support more flexible Mako template rendering.

The presence of the key repoze.bfg.message in the WSGI environment when an exception occurs is now deprecated. Instead, code which relies on this environ value should use the exception attribute of the request (e.g. request.exception[0]) to retrieve the message.

The values bfg_localizer and bfg_locale_name kept on the request during internationalization for caching purposes were never APIs. These however have changed to localizer and locale_name, respectively.

The default cookie_name value of the authtktauthenticationpolicy ZCML now defaults to auth_tkt (it used to default to repoze.bfg.auth_tkt).

The default cookie_name value of the pyramid.authentication.AuthTktAuthenticationPolicy constructor now defaults to auth_tkt (it used to default to repoze.bfg.auth_tkt).

The request_type argument to the view ZCML directive, the pyramid.configuration.Configurator.add_view method, or the pyramid.view.view_config decorator (nee bfg_view) is no longer permitted to be one of the strings GET, HEAD, PUT, POST or DELETE, and now must always be an interface. Accepting the method-strings as request_type was a backwards compatibility strategy servicing repoze.bfg 1.0 applications. Use the request_method parameter instead to specify that a view a string request-method predicate.

repoze.bfg Change History (previous name for Pyramid)

1.3b1 (2010-10-25)

Features

The paster template named bfg_routesalchemy has been updated to use SQLAlchemy declarative syntax. Thanks to Ergo^.

Bug Fixes

When a renderer factory could not be found, a misleading error message was raised if the renderer name was not a string.

Documentation

The “”bfgwiki2” (SQLAlchemy + url dispatch) tutorial has been updated slightly. In particular, the source packages no longer attempt to use a private index, and the recommended Python version is now 2.6. It was also updated to take into account the changes to the bfg_routesalchemy template used to set up an environment.

The “bfgwiki” (ZODB + traversal) tutorial has been updated slightly. In particular, the source packages no longer attempt to use a private index, and the recommended Python version is now 2.6.

1.3a15 (2010-09-30)

Features

The repoze.bfg.traversal.traversal_path API now eagerly attempts to encode a Unicode path into ASCII before attempting to split it and decode its segments. This is for convenience, effectively to allow a (stored-as-Unicode-in-a-database, or retrieved-as-Unicode-from-a-request-parameter) Unicode path to be passed to find_model, which eventually internally uses the traversal_path function under the hood. In version 1.2 and prior, if the path was Unicode, that Unicode was split on slashes and each resulting segment value was Unicode. An inappropriate call to the decode() method of a resulting Unicode path segment could cause a UnicodeDecodeError to occur even if the Unicode representation of the path contained no ‘high order’ characters (it effectively did a “double decode”). By converting the Unicode path argument to ASCII before we attempt to decode and split, genuine errors will occur in a more obvious place while also allowing us to handle (for convenience) the case that it’s a Unicode representation formed entirely from ASCII-compatible characters.

1.3a14 (2010-09-14)

Bug Fixes

If an exception view was registered through the legacy set_notfound_view or set_forbidden_view APIs, the context sent to the view was incorrect (could be None inappropriately).

Features

Compatibility with WebOb 1.0.

Requirements

Now requires WebOb >= 1.0.

Backwards Incompatibilities

Due to changes introduced WebOb 1.0, the repoze.bfg.request.make_request_ascii event subscriber no longer works, so it has been removed. This subscriber was meant to be used in a deployment so that code written before BFG 0.7.0 could run unchanged. At this point, such code will need to be rewritten to expect Unicode from request.GET, request.POST and request.params or it will need to be changed to use request.str_POST, request.str_GET and/or request.str_params instead of the non-str versions of same, as the non-str versions of the same APIs always now perform decoding to Unicode.

Errata

A prior changelog entry asserted that the INewResponse event was not sent to listeners if the response was not “valid” (if a view or renderer returned a response object that did not have a status/headers/app_iter). This is not true in this release, nor was it true in 1.3a13.

1.3a13 (2010-09-14)

Bug Fixes

The traverse route predicate could not successfully generate a traversal path.

Features

In support of making it easier to configure applications which are “secure by default”, a default permission feature was added. If supplied, the default permission is used as the permission string to all view registrations which don’t otherwise name a permission. These APIs are in support of that:

A new constructor argument was added to the Configurator: default_permission.

A new method was added to the Configurator: set_default_permission.

A new ZCML directive was added: default_permission.

Add a new request API: request.add_finished_callback. Finished callbacks are called by the router unconditionally near the very end of request processing. See the “Using Finished Callbacks” section of the “Hooks” narrative chapter of the documentation for more information.

A request.matched_route attribute is now added to the request when a route has matched. Its value is the “route” object that matched (see the IRoute interface within repoze.bfg.interfaces API documentation for the API of a route object).

The exception attribute of the request is now set slightly earlier and in a slightly different set of scenarios, for benefit of “finished callbacks” and “response callbacks”. In previous versions, the exception attribute of the request was not set at all if an exception view was not found. In this version, the request.exception attribute is set immediately when an exception is caught by the router, even if an exception view could not be found.

The add_route method of a Configurator now accepts a pregenerator argument. The pregenerator for the resulting route is called by route_url in order to adjust the set of arguments passed to it by the user for special purposes, such as Pylons ‘subdomain’ support. It will influence the URL returned by route_url. See the repoze.bfg.interfaces.IRoutePregenerator interface for more information.

Backwards Incompatibilities

The router no longer sets the value wsgiorg.routing_args into the environ when a route matches. The value used to be something like ((), matchdict). This functionality was only ever obliquely referred to in change logs; it was never documented as an API.

The exception attribute of the request now defaults to None. In prior versions, the request.exception attribute did not exist if an exception was not raised by user code during request processing; it only began existence once an exception view was found.

Deprecations

The repoze.bfg.interfaces.IWSGIApplicationCreatedEvent event interface was renamed to repoze.bfg.interfaces.IApplicationCreated. Likewise, the repoze.bfg.events.WSGIApplicationCreatedEvent class was renamed to repoze.bfg.events.ApplicationCreated. The older aliases will continue to work indefinitely.

The repoze.bfg.interfaces.IAfterTraversal event interface was renamed to repoze.bfg.interfaces.IContextFound. Likewise, the repoze.bfg.events.AfterTraversal class was renamed to repoze.bfg.events.ContextFound. The older aliases will continue to work indefinitely.

References to the WSGI environment values bfg.routes.matchdict and bfg.routes.route were removed from documentation. These will stick around internally for several more releases, but it is request.matchdict and request.matched_route are now the “official” way to obtain the matchdict and the route object which resulted in the match.

Documentation

Added documentation for the default_permission ZCML directive.

Added documentation for the default_permission constructor value and the set_default_permission method in the Configurator API documentation.

Added a new section to the “security” chapter named “Setting a Default Permission”.

Document renderer_globals_factory and request_factory arguments to Configurator constructor.

Added two sections to the “Hooks” chapter of the documentation: “Using Response Callbacks” and “Using Finished Callbacks”.

Added documentation of the request.exception attribute to the repoze.bfg.request.Request API documentation.

Added glossary entries for “response callback” and “finished callback”.

The “Request Processing” narrative chapter has been updated to note finished and response callback steps.

New interface in interfaces API documentation: IRoutePregenerator.

Added a “The Matched Route” section to the URL Dispatch narrative docs chapter, detailing the matched_route attribute.

1.3a12 (2010-09-08)

Bug Fixes

Fix a bug in repoze.bfg.url.static_url URL generation: if two resource specifications were used to create two separate static views, but they shared a common prefix, it was possible that static_url would generate an incorrect URL.

Fix another bug in repoze.bfg.static_url URL generation: too many slashes in generated URL.

Prevent a race condition which could result in a RuntimeError when rendering a Chameleon template that has not already been rendered once. This would usually occur directly after a restart, when more than one person or thread is trying to execute the same view at the same time: https://bugs.launchpad.net/karl3/+bug/621364

Features

The argument to repoze.bfg.configuration.Configurator.add_route which was previously called path is now called pattern for better explicability. For backwards compatibility purposes, passing a keyword argument named path to add_route will still work indefinitely.

The path attribute to the ZCML route directive is now named pattern for better explicability. The older path attribute will continue to work indefinitely.

Documentation

All narrative, API, and tutorial docs which referred to a route pattern as a path have now been updated to refer to them as a pattern.

The repoze.bfg.interfaces API documentation page is now rendered via repoze.sphinx.autointerface.

The URL Dispatch narrative chapter now refers to the interfaces chapter to explain the API of an IRoute object.

Paster Templates

The routesalchemy template has been updated to use pattern in its route declarations rather than path.

Dependencies

tests_require now includes repoze.sphinx.autointerface as a dependency.

Internal

Add an API to the Configurator named get_routes_mapper. This returns an object implementing the IRoutesMapper interface.

The repoze.bfg.urldispatch.RoutesMapper object now has a get_route method which returns a single Route object or None.

A new interface repoze.bfg.interfaces.IRoute was added. The repoze.bfg.urldispatch.Route object implements this interface.

The canonical attribute for accessing the routing pattern from a route object is now pattern rather than path.

Use hash() rather than id() when computing the “phash” of a custom route/view predicate in order to allow the custom predicate some control over which predicates are “equal”.

Use response.headerlist.append instead of response.headers.add in repoze.bfg.request.add_global_response_headers in case the response is not a WebOb response.

The repoze.bfg.urldispatch.Route constructor (not an API) now accepts a different ordering of arguments. Previously it was (pattern, name, factory=None, predicates=()). It is now (name, pattern, factory=None, predicates=()). This is in support of consistency with configurator.add_route.

The repoze.bfg.urldispatch.RoutesMapper.connect method (not an API) now accepts a different ordering of arguments. Previously it was (pattern, name, factory=None, predicates=()). It is now (name, pattern, factory=None, predicates=()). This is in support of consistency with configurator.add_route.

1.3a11 (2010-09-05)

Bug Fixes

Process the response callbacks and the NewResponse event earlier, to enable mutations to the response to take effect.

1.3a10 (2010-09-05)

Features

A new repoze.bfg.request.Request.add_response_callback API has been added. This method is documented in the new repoze.bfg.request API chapter. It can be used to influence response values before a concrete response object has been created.

The repoze.bfg.interfaces.INewResponse interface now includes a request attribute; as a result, a handler for INewResponse now has access to the request which caused the response.

Each of the follow methods of the Configurator now allow the below-named arguments to be passed as “dotted name strings” (e.g. “foo.bar.baz”) rather than as actual implementation objects that must be imported:

setup_registry

root_factory, authentication_policy, authorization_policy, debug_logger, locale_negotiator, request_factory, renderer_globals_factory

add_subscriber

subscriber, iface

derive_view

view

add_view

view, for_, context, request_type, containment

add_route()

view, view_for, factory, for_, view_context

scan

package

add_renderer

factory

set_forbidden_view

view

set_notfound_view

view

set_request_factory

factory

set_renderer_globals_factory()

factory

set_locale_negotiator

negotiator

testing_add_subscriber

event_iface

Bug Fixes

The route pattern registered internally for a a local “static view” (either via the static ZCML directive or via the add_static_view method of the configurator) was incorrect. It was regsistered for e.g. static*traverse, while it should have been registered for static/*traverse. Symptom: two static views could not reliably be added to a system when they both shared the same path prefix (e.g. /static and /static2).

Backwards Incompatibilities

The INewResponse event is now not sent to listeners if the response returned by view code (or a renderer) is not a “real” response (e.g. if it does not have .status, .headerlist and .app_iter attribtues).

Documentation

Add an API chapter for the repoze.bfg.request module, which includes documentation for the repoze.bfg.request.Request class (the “request object”).

Modify the “Request and Response” narrative chapter to reference the new repoze.bfg.request API chapter. Some content was moved from this chapter into the API documentation itself.

Various changes to denote that Python dotted names are now allowed as input to Configurator methods.

Internal

The (internal) feature which made it possible to attach a global_response_headers attribute to the request (which was assumed to contain a sequence of header key/value pairs which would later be added to the response by the router), has been removed. The functionality of repoze.bfg.request.Request.add_response_callback takes its place.

The repoze.bfg.events.NewResponse class’s construct has changed: it now must be created with (request, response) rather than simply (response).

1.3a9 (2010-08-22)

Features

The Configurator now accepts a dotted name string to a package as a package constructor argument. The package argument was previously required to be a package object (not a dotted name string).

The repoze.bfg.configuration.Configurator.with_package method was added. This method returns a new Configurator using the same application registry as the configurator object it is called upon. The new configurator is created afresh with its package constructor argument set to the value passed to with_package. This feature will make it easier for future BFG versions to allow dotted names as arguments in places where currently only object references are allowed (the work to allow dotted names isntead of object references everywhere has not yet been done, however).

The new repoze.bfg.configuration.Configurator.maybe_dotted method resolves a Python dotted name string supplied as its dotted argument to a global Python object. If the value cannot be resolved, a repoze.bfg.configuration.ConfigurationError is raised. If the value supplied as dotted is not a string, the value is returned unconditionally without any resolution attempted.

The new repoze.bfg.configuration.Configurator.absolute_resource_spec method resolves a potentially relative “resource specification” string into an absolute version. If the value supplied as relative_spec is not a string, the value is returned unconditionally without any resolution attempted.

Backwards Incompatibilities

The functions in repoze.bfg.renderers named render and render_to_response introduced in 1.3a6 previously took a set of **values arguments for the values to be passed to the renderer. This was wrong, as renderers don’t need to accept only dictionaries (they can accept any type of object). Now, the value sent to the renderer must be supplied as a positional argument named value. The request argument is still a keyword argument, however.

The functions in repoze.bfg.renderers named render and render_to_response now accept an additonal keyword argument named package.

The get_renderer API in repoze.bfg.renderers now accepts a package argument.

Documentation

The ZCML include directive docs were incorrect: they specified filename rather than (the correct) file as an allowable attribute.

Internal

The repoze.bfg.resource.resolve_resource_spec function can now accept a package object as its pname argument instead of just a package name.

The _renderer_factory_from_name and _renderer_from_name methods of the Configurator were removed. These were never APIs.

The _render, _render_to_response and _make_response functions with repoze.bfg.render (added in 1.3a6) have been removed.

A new helper class repoze.bfg.renderers.RendererHelper was added.

The _map_view function of repoze.bfg.configuration now takes only a renderer_name argument instead of both a renderer and renderer``_name argument.  It also takes a ``package argument now.

Use imp.get_suffixes indirection in repoze.bfg.path.package_name instead of hardcoded .py .pyc and .pyo to use for comparison when attemtping to decide if a directory is a package.

Make tests runnable again under Jython (although they do not all pass currently).

The reify decorator now maintains the docstring of the function it wraps.

1.3a8 (2010-08-08)

Features

New public interface: repoze.bfg.exceptions.IExceptionResponse. This interface is provided by all internal exception classes (such as repoze.bfg.exceptions.NotFound and repoze.bfg.exceptions.Forbidden), instances of which are both exception objects and can behave as WSGI response objects. This interface is made public so that exception classes which are also valid WSGI response factories can be configured to implement them or exception instances which are also or response instances can be configured to provide them.

New API class: repoze.bfg.view.AppendSlashNotFoundViewFactory.

There can only be one Not Found view in any repoze.bfg application. Even if you use repoze.bfg.view.append_slash_notfound_view as the Not Found view, repoze.bfg still must generate a 404 Not Found response when it cannot redirect to a slash-appended URL; this not found response will be visible to site users.

If you don’t care what this 404 response looks like, and you only need redirections to slash-appended route URLs, you may use the repoze.bfg.view.append_slash_notfound_view object as the Not Found view. However, if you wish to use a custom notfound view callable when a URL cannot be redirected to a slash-appended URL, you may wish to use an instance of the repoze.bfg.view.AppendSlashNotFoundViewFactory class as the Not Found view, supplying the notfound view callable as the first argument to its constructor. For instance:

from repoze.bfg.exceptions import NotFound
from repoze.bfg.view import AppendSlashNotFoundViewFactory

def notfound_view(context, request):
    return HTTPNotFound('It aint there, stop trying!')

custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
config.add_view(custom_append_slash, context=NotFound)

The notfound_view supplied must adhere to the two-argument view callable calling convention of (context, request) (context will be the exception object).

Documentation

Expanded the “Cleaning Up After a Request” section of the URL Dispatch narrative chapter.

Expanded the “Redirecting to Slash-Appended Routes” section of the URL Dispatch narrative chapter.

Internal

Previously, two default view functions were registered at Configurator setup (one for repoze.bfg.exceptions.NotFound named default_notfound_view and one for repoze.bfg.exceptions.Forbidden named default_forbidden_view) to render internal exception responses. Those default view functions have been removed, replaced with a generic default view function which is registered at Configurator setup for the repoze.bfg.interfaces.IExceptionResponse interface that simply returns the exception instance; the NotFound and Forbidden classes are now still exception factories but they are also response factories which generate instances that implement the new repoze.bfg.interfaces.IExceptionResponse interface.

1.3a7 (2010-08-01)

Features

The repoze.bfg.configuration.Configurator.add_route API now returns the route object that was added.

A repoze.bfg.events.subscriber decorator was added. This decorator decorates module-scope functions, which are then treated as event listeners after a scan() is performed. See the Events narrative documentation chapter and the repoze.bfg.events module documentation for more information.

Bug Fixes

When adding a view for a route which did not yet exist (“did not yet exist” meaning, temporally, a view was added with a route name for a route which had not yet been added via add_route), the value of the custom_predicate argument to add_view was lost. Symptom: wrong view matches when using URL dispatch and custom view predicates together.

Pattern matches for a :segment marker in a URL dispatch route pattern now always match at least one character. See “Backwards Incompatibilities” below in this changelog.

Backwards Incompatibilities

A bug existed in the regular expression to do URL matching. As an example, the URL matching machinery would cause the pattern /{foo} to match the root URL / resulting in a match dictionary of {'foo':u''} or the pattern /{fud}/edit might match the URL ``//edit resulting in a match dictionary of {'fud':u''}. It was always the intent that :segment markers in the pattern would need to match at least one character, and never match the empty string. This, however, means that in certain circumstances, a routing match which your application inadvertently depended upon may no longer happen.

Documentation

Added description of the repoze.bfg.events.subscriber decorator to the Events narrative chapter.

Added repoze.bfg.events.subscriber API documentation to repoze.bfg.events API docs.

Added a section named “Zope 3 Enforces ‘TTW’ Authorization Checks By Default; BFG Does Not” to the “Design Defense” chapter.

1.3a6 (2010-07-25)

Features

New argument to repoze.bfg.configuration.Configurator.add_route and the route ZCML directive: traverse. If you would like to cause the context to be something other than the root object when this route matches, you can spell a traversal pattern as the traverse argument. This traversal pattern will be used as the traversal path: traversal will begin at the root object implied by this route (either the global root, or the object returned by the factory associated with this route).

The syntax of the traverse argument is the same as it is for path. For example, if the path provided is articles/:article/edit, and the traverse argument provided is /:article, when a request comes in that causes the route to match in such a way that the article match value is ‘1’ (when the request URI is /articles/1/edit), the traversal path will be generated as /1. This means that the root object’s __getitem__ will be called with the name 1 during the traversal phase. If the 1 object exists, it will become the context of the request. The Traversal narrative has more information about traversal.

If the traversal path contains segment marker names which are not present in the path argument, a runtime error will occur. The traverse pattern should not contain segment markers that do not exist in the path.

A similar combining of routing and traversal is available when a route is matched which contains a *traverse remainder marker in its path. The traverse argument allows you to associate route patterns with an arbitrary traversal path without using a a *traverse remainder marker; instead you can use other match information.

Note that the traverse argument is ignored when attached to a route that has a *traverse remainder marker in its path.

A new method of the Configurator exists: set_request_factory. If used, this method will set the factory used by the repoze.bfg router to create all request objects.

The Configurator constructor takes an additional argument: request_factory. If used, this argument will set the factory used by the repoze.bfg router to create all request objects.

The Configurator constructor takes an additional argument: request_factory. If used, this argument will set the factory used by the repoze.bfg router to create all request objects.

A new method of the Configurator exists: set_renderer_globals_factory. If used, this method will set the factory used by the repoze.bfg router to create renderer globals.

A new method of the Configurator exists: get_settings. If used, this method will return the current settings object (performs the same job as the repoze.bfg.settings.get_settings API).

The Configurator constructor takes an additional argument: renderer_globals_factory. If used, this argument will set the factory used by the repoze.bfg router to create renderer globals.

Add repoze.bfg.renderers.render, repoze.bfg.renderers.render_to_response and repoze.bfg.renderers.get_renderer functions. These are imperative APIs which will use the same rendering machinery used by view configurations with a renderer= attribute/argument to produce a rendering or renderer. Because these APIs provide a central API for all rendering, they now form the preferred way to perform imperative template rendering. Using functions named render_* from modules such as repoze.bfg.chameleon_zpt and repoze.bfg.chameleon_text is now discouraged (although not deprecated). The code the backing older templating-system-specific APIs now calls into the newer repoze.bfg.renderer code.

The repoze.bfg.configuration.Configurator.testing_add_template has been renamed to testing_add_renderer. A backwards compatibility alias is present using the old name.

Documentation

The Hybrid narrative chapter now contains a description of the traverse route argument.

The Hooks narrative chapter now contains sections about changing the request factory and adding a renderer globals factory.

The API documentation includes a new module: repoze.bfg.renderers.

The Templates chapter was updated; all narrative that used templating-specific APIs within examples to perform rendering (such as the repoze.bfg.chameleon_zpt.render_template_to_response method) was changed to use repoze.bfg.renderers.render_* functions.

Bug Fixes

The header predicate (when used as either a view predicate or a route predicate) had a problem when specified with a name/regex pair. When the header did not exist in the headers dictionary, the regex match could be fed None, causing it to throw a TypeError: expected string or buffer exception. Now, the predicate returns False as intended.

Deprecations

The repoze.bfg.renderers.rendered_response function was never an official API, but may have been imported by extensions in the wild. It is officially deprecated in this release. Use repoze.bfg.renderers.render_to_response instead.

The following APIs are documentation deprecated (meaning they are officially deprecated in documentation but do not raise a deprecation error upon their usage, and may continue to work for an indefinite period of time):

In the repoze.bfg.chameleon_zpt module: get_renderer, get_template, render_template, render_template_to_response. The suggested alternatives are documented within the docstrings of those methods (which are still present in the documentation).

In the repoze.bfg.chameleon_text module: get_renderer, get_template, render_template, render_template_to_response. The suggested alternatives are documented within the docstrings of those methods (which are still present in the documentation).

In general, to perform template-related functions, one should now use the various methods in the repoze.bfg.renderers module.

Backwards Incompatibilities

A new internal exception class (not an API) named repoze.bfg.exceptions.PredicateMismatch now exists. This exception is currently raised when no constituent view of a multiview can be called (due to no predicate match). Previously, in this situation, a repoze.bfg.exceptions.NotFound was raised. We provide backwards compatibility for code that expected a NotFound to be raised when no predicates match by causing repoze.bfg.exceptions.PredicateMismatch to inherit from NotFound. This will cause any exception view registered for NotFound to be called when a predicate mismatch occurs, as was the previous behavior.

There is however, one perverse case that will expose a backwards incompatibility. If 1) you had a view that was registered as a member of a multiview 2) this view explicitly raised a NotFound exception in order to proceed to the next predicate check in the multiview, that code will now behave differently: rather than skipping to the next view match, a NotFound will be raised to the top-level exception handling machinery instead. For code to be depending upon the behavior of a view raising NotFound to proceed to the next predicate match, would be tragic, but not impossible, given that NotFound is a public interface. repoze.bfg.exceptions.PredicateMismatch is not a public API and cannot be depended upon by application code, so you should not change your view code to raise PredicateMismatch. Instead, move the logic which raised the NotFound exception in the view out into a custom view predicate.

If, when you run your application’s unit test suite under BFG 1.3, a KeyError naming a template or a ValueError indicating that a ‘renderer factory’ is not registered may is raised (e.g. ValueError: No factory for renderer named '.pt' when looking up karl.views:templates/snippets.pt), you may need to perform some extra setup in your test code.

The best solution is to use the repoze.bfg.configuration.Configurator.testing_add_renderer (or, alternately the deprecated repoze.bfg.testing.registerTemplateRenderer or registerDummyRenderer) API within the code comprising each individual unit test suite to register a “dummy” renderer for each of the templates and renderers used by code under test. For example:

config = Configurator()
config.testing_add_renderer('karl.views:templates/snippets.pt')

This will register a basic dummy renderer for this particular missing template. The testing_add_renderer API actually returns the renderer, but if you don’t care about how the render is used, you don’t care about having a reference to it either.

A more rough way to solve the issue exists. It causes the “real” template implementations to be used while the system is under test, which is suboptimal, because tests will run slower, and unit tests won’t actually be unit tests, but it is easier. Always ensure you call the setup_registry() method of the Configurator . Eg:

reg = MyRegistry()
config = Configurator(registry=reg)
config.setup_registry()

Calling setup_registry only has an effect if you’re passing in a registry argument to the Configurator constructor. setup_registry is called by the course of normal operations anyway if you do not pass in a registry.

If your test suite isn’t using a Configurator yet, and is still using the older repoze.bfg.testing APIs name setUp or cleanUp, these will register the renderers on your behalf.

A variant on the symptom for this theme exists: you may already be dutifully registering a dummy template or renderer for a template used by the code you’re testing using testing_register_renderer or registerTemplateRenderer, but (perhaps unbeknownst to you) the code under test expects to be able to use a “real” template renderer implementation to retrieve or render another template that you forgot was being rendered as a side effect of calling the code you’re testing. This happened to work because it found the real template while the system was under test previously, and now it cannot. The solution is the same.

It may also help reduce confusion to use a resource specification to specify the template path in the test suite and code rather than a relative path in either. A resource specification is unambiguous, while a relative path needs to be relative to “here”, where “here” isn’t always well-defined (“here” in a test suite may or may not be the same as “here” in the code under test).

1.3a5 (2010-07-14)

Features

New internal exception: repoze.bfg.exceptions.URLDecodeError. This URL is a subclass of the built-in Python exception named UnicodeDecodeError.

When decoding a URL segment to Unicode fails, the exception raised is now repoze.bfg.exceptions.URLDecodeError instead of UnicodeDecodeError. This makes it possible to register an exception view invoked specifically when repoze.bfg cannot decode a URL.

Bug Fixes

Fix regression in repoze.bfg.configuration.Configurator.add_static_view. Before 1.3a4, view names that contained a slash were supported as route prefixes. 1.3a4 broke this by trying to treat them as full URLs.

Documentation

The repoze.bfg.exceptions.URLDecodeError exception was added to the exceptions chapter of the API documentation.

Backwards Incompatibilities

in previous releases, when a URL could not be decoded from UTF-8 during traversal, a TypeError was raised. Now the error which is raised is a repoze.bfg.exceptions.URLDecodeError.

1.3a4 (2010-07-03)

Features

Undocumented hook: make get_app and get_root of the repoze.bfg.paster.BFGShellCommand hookable in cases where endware may interfere with the default versions.

In earlier versions, a custom route predicate associated with a url dispatch route (each of the predicate functions fed to the custom_predicates argument of repoze.bfg.configuration.Configurator.add_route) has always required a 2-positional argument signature, e.g. (context, request). Before this release, the context argument was always None.

As of this release, the first argument passed to a predicate is now a dictionary conventionally named info consisting of route, and match. match is a dictionary: it represents the arguments matched in the URL by the route. route is an object representing the route which was matched.

This is useful when predicates need access to the route match. For example:

def any_of(segment_name, *args):
    def predicate(info, request):
        if info['match'][segment_name] in args:
            return True
    return predicate

num_one_two_or_three = any_of('num, 'one', 'two', 'three')

add_route('num', '/:num', custom_predicates=(num_one_two_or_three,))

The route object is an object that has two useful attributes: name and path. The name attribute is the route name. The path attribute is the route pattern. An example of using the route in a set of route predicates:

def twenty_ten(info, request):
    if info['route'].name in ('ymd', 'ym', 'y'):
        return info['match']['year'] == '2010'

add_route('y', '/:year', custom_predicates=(twenty_ten,))
add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,))
add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,))

The repoze.bfg.url.route_url API has changed. If a keyword _app_url is present in the arguments passed to route_url, this value will be used as the protocol/hostname/port/leading path prefix of the generated URL. For example, using an _app_url of http://example.com:8080/foo would cause the URL http://example.com:8080/foo/fleeb/flub to be returned from this function if the expansion of the route pattern associated with the route_name expanded to /fleeb/flub.

It is now possible to use a URL as the name argument fed to repoze.bfg.configuration.Configurator.add_static_view. When the name argument is a URL, the repoze.bfg.url.static_url API will generate join this URL (as a prefix) to a path including the static file name. This makes it more possible to put static media on a separate webserver for production, while keeping static media package-internal and served by the development webserver during development.

Documentation

The authorization chapter of the ZODB Wiki Tutorial (docs/tutorials/bfgwiki) was changed to demonstrate authorization via a group rather than via a direct username (thanks to Alex Marandon).

The authorization chapter of the SQLAlchemy Wiki Tutorial (docs/tutorials/bfgwiki2) was changed to demonstrate authorization via a group rather than via a direct username.

Redirect requests for tutorial sources to http://docs.repoze.org/bfgwiki-1.3 and http://docs.repoze.org/bfgwiki2-1.3/ respectively.

A section named Custom Route Predicates was added to the URL Dispatch narrative chapter.

The Static Resources chapter has been updated to mention using static_url to generate URLs to external webservers.

Internal

Removed repoze.bfg.static.StaticURLFactory in favor of a new abstraction revolving around the (still-internal) repoze.bfg.static.StaticURLInfo helper class.

1.3a3 (2010-05-01)

Paster Templates

The bfg_alchemy and bfg_routesalchemy templates no longer register a handle_teardown event listener which calls DBSession.remove. This was found by Chris Withers to be unnecessary.

Documentation

The “bfgwiki2” (URL dispatch wiki) tutorial code and documentation was changed to remove the handle_teardown event listener which calls DBSession.remove.

Any mention of the handle_teardown event listener as used by the paster templates was removed from the URL Dispatch narrative chapter.

A section entitled Detecting Available Languages was added to the i18n narrative docs chapter.

1.3a2 (2010-04-28)

Features

A locale negotiator no longer needs to be registered explicitly. The default locale negotiator at repoze.bfg.i18n.default_locale_negotiator is now used unconditionally as... um, the default locale negotiator.

The default locale negotiator has become more complex.

First, the negotiator looks for the _LOCALE_ attribute of the request object (possibly set by a view or an event listener).

Then it looks for the request.params['_LOCALE_'] value.

Then it looks for the request.cookies['_LOCALE_'] value.

Backwards Incompatibilities

The default locale negotiator now looks for the parameter named _LOCALE_ rather than a parameter named locale in request.params.

Behavior Changes

A locale negotiator may now return None, signifying that the default locale should be used.

Documentation

Documentation concerning locale negotiation in the Internationalizationa and Localization chapter was updated.

Expanded portion of i18n narrative chapter docs which discuss working with gettext files.

1.3a1 (2010-04-26)

Features

Added “exception views”. When you use an exception (anything that inherits from the Python Exception builtin) as view context argument, e.g.:

from repoze.bfg.view import bfg_view
from repoze.bfg.exceptions import NotFound
from webob.exc import HTTPNotFound

@bfg_view(context=NotFound)
def notfound_view(request):
    return HTTPNotFound()

For the above example, when the repoze.bfg.exceptions.NotFound exception is raised by any view or any root factory, the notfound_view view callable will be invoked and its response returned.

Other normal view predicates can also be used in combination with an exception view registration:

from repoze.bfg.view import bfg_view
from repoze.bfg.exceptions import NotFound
from webob.exc import HTTPNotFound

@bfg_view(context=NotFound, route_name='home')
def notfound_view(request):
    return HTTPNotFound()

The above exception view names the route_name of home, meaning that it will only be called when the route matched has a name of home. You can therefore have more than one exception view for any given exception in the system: the “most specific” one will be called when the set of request circumstances which match the view registration. The only predicate that cannot be not be used successfully is name. The name used to look up an exception view is always the empty string.

Existing (pre-1.3) normal views registered against objects inheriting from Exception will continue to work. Exception views used for user-defined exceptions and system exceptions used as contexts will also work.

The feature can be used with any view registration mechanism (@bfg_view decorator, ZCML, or imperative config.add_view styles).

This feature was kindly contributed by Andrey Popp.

Use “Venusian” (http://docs.repoze.org/venusian) to perform bfg_view decorator scanning rather than relying on a BFG-internal decorator scanner. (Truth be told, Venusian is really just a generalization of the BFG-internal decorator scanner).

Internationalization and localization features as documented in the narrative documentation chapter entitled Internationalization and Localization.

A new deployment setting named default_locale_name was added. If this string is present as a Paster .ini file option, it will be considered the default locale name. The default locale name is used during locale-related operations such as language translation.

It is now possible to turn on Chameleon template “debugging mode” for all Chameleon BFG templates by setting a BFG-related Paster .ini file setting named debug_templates. The exceptions raised by Chameleon templates when a rendering fails are sometimes less than helpful. debug_templates allows you to configure your application development environment so that exceptions generated by Chameleon during template compilation and execution will contain more helpful debugging information. This mode is on by default in all new projects.

Add a new method of the Configurator named derive_view which can be used to generate a BFG view callable from a user-supplied function, instance, or class. This useful for external framework and plugin authors wishing to wrap callables supplied by their users which follow the same calling conventions and response conventions as objects that can be supplied directly to BFG as a view callable. See the derive_view method in the repoze.bfg.configuration.Configurator docs.

ZCML

Add a translationdir ZCML directive to support localization.

Add a localenegotiator ZCML directive to support localization.

Deprecations

The exception views feature replaces the need for the set_notfound_view and set_forbidden_view methods of the Configurator as well as the notfound and forbidden ZCML directives. Those methods and directives will continue to work for the foreseeable future, but they are deprecated in the documentation.

Dependencies

A new install-time dependency on the venusian distribution was added.

A new install-time dependency on the translationstring distribution was added.

Chameleon 1.2.3 or better is now required (internationalization and per-template debug settings).

Internal

View registrations and lookups are now done with three “requires” arguments instead of two to accomodate orthogonality of exception views.

The repoze.bfg.interfaces.IForbiddenView and repoze.bfg.interfaces.INotFoundView interfaces were removed; they weren’t APIs and they became vestigial with the addition of exception views.

Remove repoze.bfg.compat.pkgutil_26.py and import alias repoze.bfg.compat.walk_packages. These were only required by internal scanning machinery; Venusian replaced the internal scanning machinery, so these are no longer required.

Documentation

Exception view documentation was added to the Hooks narrative chapter.

A new narrative chapter entitled Internationalization and Localization was added.

The “Environment Variables and ini File Settings” chapter was changed: documentation about the default_locale_name setting was added.

A new API chapter for the repoze.bfg.i18n module was added.

Documentation for the new translationdir and localenegotiator ZCML directives were added.

A section was added to the Templates chapter entitled “Nicer Exceptions in Templates” describing the result of setting debug_templates = true.

Paster Templates

All paster templates now create a setup.cfg which includes commands related to nose testing and Babel message catalog extraction/compilation.

A default_locale_name = en setting was added to each existing paster template.

A debug_templates = true setting was added to each existing paster template.

Licensing

The Edgewall (BSD) license was added to the LICENSES.txt file, as some code in the repoze.bfg.i18n derives from Babel source.

1.2 (2010-02-10)

No changes from 1.2b6.

1.2b6 (2010-02-06)

Backwards Incompatibilities

Remove magical feature of repoze.bfg.url.model_url which prepended a fully-expanded urldispatch route URL before a the model’s path if it was noticed that the request had matched a route. This feature was ill-conceived, and didn’t work in all scenarios.

Bug Fixes

More correct conversion of provided renderer values to resource specification values (internal).

1.2b5 (2010-02-04)

Bug Fixes

1.2b4 introduced a bug whereby views added via a route configuration that named a view callable and also a view_attr became broken. Symptom: MyViewClass is not callable or the __call__ of a class was being called instead of the method named via view_attr.

Fix a bug whereby a renderer argument to the @bfg_view decorator that provided a package-relative template filename might not have been resolved properly. Symptom: inappropriate Missing template resource errors.

1.2b4 (2010-02-03)

Documentation

Update GAE tutorial to use Chameleon instead of Jinja2 (now that it’s possible).

Bug Fixes

Ensure that secure flag for AuthTktAuthenticationPolicy constructor does what it’s documented to do (merge Daniel Holth’s fancy-cookies-2 branch).

Features

Add path and http_only options to AuthTktAuthenticationPolicy constructor (merge Daniel Holth’s fancy-cookies-2 branch).

Backwards Incompatibilities

Remove view_header, view_accept, view_xhr, view_path_info, view_request_method, view_request_param, and view_containment predicate arguments from the Configurator.add_route argument list. These arguments were speculative. If you need the features exposed by these arguments, add a view associated with a route using the route_name argument to the add_view method instead.

Remove view_header, view_accept, view_xhr, view_path_info, view_request_method, view_request_param, and view_containment predicate arguments from the route ZCML directive attribute set. These attributes were speculative. If you need the features exposed by these attributes, add a view associated with a route using the route_name attribute of the view ZCML directive instead.

Dependencies

Remove dependency on sourcecodegen (not depended upon by Chameleon 1.1.1+).

1.2b3 (2010-01-24)

Bug Fixes

When “hybrid mode” (both traversal and urldispatch) is in use, default to finding route-related views even if a non-route-related view registration has been made with a more specific context. The default used to be to find views with a more specific context first. Use the new use_global_views argument to the route definition to get back the older behavior.

Features

Add use_global_views argument to add_route method of Configurator. When this argument is true, views registered for no route will be found if no more specific view related to the route is found.

Add use_global_views attribute to ZCML <route> directive (see above).

Internal

When registering a view, register the view adapter with the “requires” interfaces as (request_type, context_type) rather than (context_type, request_type). This provides for saner lookup, because the registration will always be made with a specific request interface, but registration may not be made with a specific context interface. In general, when creating multiadapters, you want to order the requires interfaces so that the the elements which are more likely to be registered using specific interfaces are ordered before those which are less likely.

1.2b2 (2010-01-21)

Bug Fixes

When the Configurator is passed an instance of zope.component.registry.Components as a registry constructor argument, fix the instance up to have the attributes we expect of an instance of repoze.bfg.registry.Registry when setup_registry is called. This makes it possible to use the global Zope component registry as a BFG application registry.

When WebOb 0.9.7.1 was used, a deprecation warning was issued for the class attribute named charset within repoze.bfg.request.Request. BFG now requires WebOb >= 0.9.7, and code was added so that this deprecation warning has disappeared.

Fix a view lookup ordering bug whereby a view with a larger number of predicates registered first (literally first, not “earlier”) for a triad would lose during view lookup to one registered with fewer.

Make sure views with exactly N custom predicates are always called before views with exactly N non-custom predicates given all else is equal in the view configuration.

Documentation

Change renderings of ZCML directive documentation.

Add a narrative documentation chapter: “Using the Zope Component Architecture in repoze.bfg”.

Dependencies

Require WebOb >= 0.9.7

1.2b1 (2010-01-18)

Bug Fixes

In bfg_routesalchemy, bfg_alchemy paster templates and the bfgwiki2 tutorial, clean up the SQLAlchemy connection by registering a repoze.tm.after_end callback instead of relying on a __del__ method of a Cleanup class added to the WSGI environment. The __del__ strategy was fragile and caused problems in the wild. Thanks to Daniel Holth for testing.

Features

Read logging configuration from PasteDeploy config file loggers section (and related) when paster bfgshell is invoked.

Documentation

Major rework in preparation for book publication.

1.2a11 (2010-01-05)

Bug Fixes

Make paster bfgshell and paster create -t bfg_xxx work on Jython (fix minor incompatibility with treatment of __doc__ at the class level).

Updated dependency on WebOb to require a version which supports features now used in tests.

Features

Jython compatibility (at least when repoze.bfg.jinja2 is used as the templating engine; Chameleon does not work under Jython).

Show the derived abspath of template resource specifications in the traceback when a renderer template cannot be found.

Show the original traceback when a Chameleon template cannot be rendered due to a platform incompatibility.

1.2a10 (2010-01-04)

Features

The Configurator.add_view method now accepts an argument named context. This is an alias for the older argument named for_; it is preferred over for_, but for_ will continue to be supported “forever”.

The view ZCML directive now accepts an attribute named context. This is an alias for the older attribute named for; it is preferred over for, but for will continue to be supported “forever”.

The Configurator.add_route method now accepts an argument named view_context. This is an alias for the older argument named view_for; it is preferred over view_for, but view_for will continue to be supported “forever”.

The route ZCML directive now accepts an attribute named view_context. This is an alias for the older attribute named view_for; it is preferred over view_for, but view_for will continue to be supported “forever”.

Documentation and Paster Templates

LaTeX rendering tweaks.

All uses of the Configurator.add_view method that used its for_ argument now use the context argument instead.

All uses of the Configurator.add_route method that used its view_for argument now use the view_context argument instead.

All uses of the view ZCML directive that used its for attribute now use the context attribute instead.

All uses of the route ZCML directive that used its view_for attribute now use the view_context attribute instead.

Add a (minimal) tutorial dealing with use of repoze.catalog in a repoze.bfg application.

Documentation Licensing

Loosen the documentation licensing to allow derivative works: it is now offered under the Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License [http://creativecommons.org/licenses/by-nc-sa/3.0/us/]. This is only a documentation licensing change; the repoze.bfg software continues to be offered under the Repoze Public License at http://repoze.org/license.html (BSD-like).

1.2a9 (2009-12-27)

Documentation Licensing

The documentation (the result of make <html|latex|htmlhelp> within the docs directory) in this release is now offered under the Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States License as described by http://creativecommons.org/licenses/by-nc-nd/3.0/us/ . This is only a licensing change for the documentation; the repoze.bfg software continues to be offered under the Repoze Public License at http://repoze.org/license.html (BSD-like).

Documentation

Added manual index entries to generated index.

Document the previously existing (but non-API) repoze.bfg.configuration.Configurator.setup_registry method as an official API of a Configurator.

Fix syntax errors in various documentation code blocks.

Created new top-level documentation section: “ZCML Directives”. This section contains detailed ZCML directive information, some of which was removed from various narrative chapters.

The LaTeX rendering of the documentation has been improved.

Added a “Fore-Matter” section with author, copyright, and licensing information.

1.2a8 (2009-12-24)

Features

Add a **kw arg to the Configurator.add_settings API.

Add hook_zca and unhook_zca methods to the Configurator API.

The repoze.bfg.testing.setUp method now returns a Configurator instance which can be used to do further configuration during unit tests.

Bug Fixes

The json renderer failed to set the response content type to application/json. It now does, by setting request.response_content_type unless this attribute is already set.

The string renderer failed to set the response content type to text/plain. It now does, by setting request.response_content_type unless this attribute is already set.

Documentation

General documentation improvements by using better Sphinx roles such as “class”, “func”, “meth”, and so on. This means that there are many more hyperlinks pointing to API documentation for API definitions in all narrative, tutorial, and API documentation elements.

Added a description of imperative configuration in various places which only described ZCML configuration.

A syntactical refreshing of various tutorials.

Added the repoze.bfg.authentication, repoze.bfg.authorization, and repoze.bfg.interfaces modules to API documentation.

Deprecations

The repoze.bfg.testing.registerRoutesMapper API (added in an early 1.2 alpha) was deprecated. Its import now generates a deprecation warning.

1.2a7 (2009-12-20)

Features

Add four new testing-related APIs to the repoze.bfg.configuration.Configurator class: testing_securitypolicy, testing_models, testing_add_subscriber, and testing_add_template. These were added in order to provide more direct access to the functionality of the repoze.bfg.testing APIs named registerDummySecurityPolicy, registerModels, registerEventListener, and registerTemplateRenderer when a configurator is used. The testing APIs named are nominally deprecated (although they will likely remain around “forever”, as they are in heavy use in the wild).

Add a new API to the repoze.bfg.configuration.Configurator class: add_settings. This API can be used to add “settings” (information returned within via the repoze.bfg.settings.get_settings API) after the configurator has been initially set up. This is most useful for testing purposes.

Add a custom_predicates argument to the Configurator add_view method, the bfg_view decorator and the attribute list of the ZCML view directive. If custom_predicates is specified, it must be a sequence of predicate callables (a predicate callable accepts two arguments: context and request and returns True or False). The associated view callable will only be invoked if all custom predicates return True. Use one or more custom predicates when no existing predefined predicate is useful. Predefined and custom predicates can be mixed freely.

Add a custom_predicates argument to the Configurator add_route and the attribute list of the ZCML route directive. If custom_predicates is specified, it must be a sequence of predicate callables (a predicate callable accepts two arguments: context and request and returns True or False). The associated route will match will only be invoked if all custom predicates return True, else route matching continues. Note that the value context will always be None when passed to a custom route predicate. Use one or more custom predicates when no existing predefined predicate is useful. Predefined and custom predicates can be mixed freely.

Internal

Remove the repoze.bfg.testing.registerTraverser function. This function was never an API.

Documenation

Doc-deprecated most helper functions in the repoze.bfg.testing module. These helper functions likely won’t be removed any time soon, nor will they generate a warning any time soon, due to their heavy use in the wild, but equivalent behavior exists in methods of a Configurator.

1.2a6 (2009-12-18)

Features

The Configurator object now has two new methods: begin and end. The begin method is meant to be called before any “configuration” begins (e.g. before add_view, et. al are called). The end method is meant to be called after all “configuration” is complete.

Previously, before there was imperative configuration at all (1.1 and prior), configuration begin and end was invariably implied by the process of loading a ZCML file. When a ZCML load happened, the threadlocal data structure containing the request and registry was modified before the load, and torn down after the load, making sure that all framework code that needed get_current_registry for the duration of the ZCML load was satisfied.

Some API methods called during imperative configuration, (such as Configurator.add_view when a renderer is involved) end up for historical reasons calling get_current_registry. However, in 1.2a5 and below, the Configurator supplied no functionality that allowed people to make sure that get_current_registry returned the registry implied by the configurator being used. begin now serves this purpose. Inversely, end pops the thread local stack, undoing the actions of begin.

We make this boundary explicit to reduce the potential for confusion when the configurator is used in different circumstances (e.g. in unit tests and app code vs. just in initial app setup).

Existing code written for 1.2a1-1.2a5 which does not call begin or end continues to work in the same manner it did before. It is however suggested that this code be changed to call begin and end to reduce the potential for confusion in the future.

All paster templates which generate an application skeleton now make use of the new begin and end methods of the Configurator they use in their respective copies of run.py and tests.py.

Documentation

All documentation that makes use of a Configurator object to do application setup and test setup now makes use of the new begin and end methods of the configurator.

Bug Fixes

When a repoze.bfg.exceptions.NotFound or repoze.bfg.exceptions.Forbidden class (as opposed to instance) was raised as an exception within a root factory (or route root factory), the exception would not be caught properly by the repoze.bfg. Router and it would propagate to up the call stack, as opposed to rendering the not found view or the forbidden view as would have been expected.

When Chameleon page or text templates used as renderers were added imperatively (via Configurator.add_view or some derivative), they too-eagerly attempted to look up the reload_templates setting via get_settings, meaning they were always registered in non-auto-reload-mode (the default). Each now waits until its respective template attribute is accessed to look up the value.

When a route with the same name as a previously registered route was added, the old route was not removed from the mapper’s routelist. Symptom: the old registered route would be used (and possibly matched) during route lookup when it should not have had a chance to ever be used.

1.2a5 (2009-12-10)

Features

When the repoze.bfg.exceptions.NotFound or repoze.bfg.exceptions.Forbidden error is raised from within a custom root factory or the factory of a route, the appropriate response is now sent to the requesting user agent (the result of the notfound view or the forbidden view, respectively). When these errors are raised from within a root factory, the context passed to the notfound or forbidden view will be None. Also, the request will not be decorated with view_name, subpath, context, etc. as would normally be the case if traversal had been allowed to take place.

Internals

The exception class representing the error raised by various methods of a Configurator is now importable as repoze.bfg.exceptions.ConfigurationError.

Documentation

General documentation freshening which takes imperative configuration into account in more places and uses glossary references more liberally.

Remove explanation of changing the request type in a new request event subscriber, as other predicates are now usually an easier way to get this done.

Added “Thread Locals” narrative chapter to documentation, and added a API chapter documenting the repoze.bfg.threadlocals module.

Added a “Special Exceptions” section to the “Views” narrative documentation chapter explaining the effect of raising repoze.bfg.exceptions.NotFound and repoze.bfg.exceptions.Forbidden from within view code.

Dependencies

A new dependency on the twill package was added to the setup.py tests_require argument (Twill will only be downloaded when repoze.bfg setup.py test or setup.py nosetests is invoked).

1.2a4 (2009-12-07)

Features

repoze.bfg.testing.DummyModel now accepts a new constructor keyword argument: __provides__. If this constructor argument is provided, it should be an interface or a tuple of interfaces. The resulting model will then provide these interfaces (they will be attached to the constructed model via zope.interface.alsoProvides).

Bug Fixes

Operation on GAE was broken, presumably because the repoze.bfg.configuration module began to attempt to import the repoze.bfg.chameleon_zpt and repoze.bfg.chameleon_text modules, and these cannot be used on non-CPython platforms. It now tolerates startup time import failures for these modules, and only raise an import error when a template from one of these packages is actually used.

1.2a3 (2009-12-02)

Bug Fixes

The repoze.bfg.url.route_url function inappropriately passed along _query and/or _anchor arguments to the mapper.generate function, resulting in blowups.

When two views were registered with differering for interfaces or classes, and the for of first view registered was a superclass of the second, the repoze.bfg view machinery would incorrectly associate the two views with the same “multiview”. Multiviews are meant to be collections of views that have exactly the same for/request/viewname values, without taking inheritance into account. Symptom: wrong view callable found even when you had correctly specified a for_ interface/class during view configuration for one or both view configurations.

Backwards Incompatibilities

The repoze.bfg.templating module has been removed; it had been deprecated in 1.1 and never actually had any APIs in it.

1.2a2 (2009-11-29)

Bug Fixes

The the long description of this package (as shown on PyPI) was not valid reStructuredText, and so was not renderable.

Trying to use an HTTP method name string such as GET as a request_type predicate argument caused a startup time failure when it was encountered in imperative configuration or in a decorator (symptom: Type Error: Required specification must be a specification). This now works again, although request_method is now the preferred predicate argument for associating a view configuration with an HTTP request method.

Documentation

Fixed “Startup” narrative documentation chapter; it was explaining “the old way” an application constructor worked.

1.2a1 (2009-11-28)

Features

An imperative configuration mode.

A repoze.bfg application can now begin its life as a single Python file. Later, the application might evolve into a set of Python files in a package. Even later, it might start making use of other configuration features, such as ZCML. But neither the use of a package nor the use of non-imperative configuration is required to create a simple repoze.bfg application any longer.

Imperative configuration makes repoze.bfg competetive with “microframeworks” such as Bottle [http://bottle.paws.de/] and Tornado [http://www.tornadoweb.org/]. repoze.bfg has a good deal of functionality that most microframeworks lack, so this is hopefully a “best of both worlds” feature.

The simplest possible repoze.bfg application is now:

from webob import Response
from wsgiref import simple_server
from repoze.bfg.configuration import Configurator

def hello_world(request):
    return Response('Hello world!')

if __name__ == '__main__':
    config = Configurator()
    config.add_view(hello_world)
    app = config.make_wsgi_app()
    simple_server.make_server('', 8080, app).serve_forever()

A new class now exists: repoze.bfg.configuration.Configurator. This class forms the basis for sharing machinery between “imperatively” configured applications and traditional declaratively-configured applications.

The repoze.bfg.testing.setUp function now accepts three extra optional keyword arguments: registry, request and hook_zca.

If the registry argument is not None, the argument will be treated as the registry that is set as the “current registry” (it will be returned by repoze.bfg.threadlocal.get_current_registry) for the duration of the test. If the registry argument is None (the default), a new registry is created and used for the duration of the test.

The value of the request argument is used as the “current request” (it will be returned by repoze.bfg.threadlocal.get_current_request) for the duration of the test; it defaults to None.

If hook_zca is True (the default), the zope.component.getSiteManager function will be hooked with a function that returns the value of registry (or the default-created registry if registry is None) instead of the registry returned by zope.component.getGlobalSiteManager, causing the Zope Component Architecture API (getSiteManager, getAdapter, getUtility, and so on) to use the testing registry instead of the global ZCA registry.

The repoze.bfg.testing.tearDown function now accepts an unhook_zca argument. If this argument is True (the default), zope.component.getSiteManager.reset() will be called. This will cause the result of the zope.component.getSiteManager function to be the global ZCA registry (the result of zope.component.getGlobalSiteManager) once again.

The run.py module in various repoze.bfg paster templates now use a repoze.bfg.configuration.Configurator class instead of the (now-legacy) repoze.bfg.router.make_app function to produce a WSGI application.

Documentation

The documentation now uses the “request-only” view calling convention in most examples (as opposed to the context, request convention). This is a documentation-only change; the context, request convention is also supported and documented, and will be “forever”.

repoze.bfg.configuration API documentation has been added.

A narrative documentation chapter entitled “Creating Your First repoze.bfg Application” has been added. This chapter details usage of the new repoze.bfg.configuration.Configurator class, and demonstrates a simplified “imperative-mode” configuration; doing repoze.bfg application configuration imperatively was previously much more difficult.

A narrative documentation chapter entitled “Configuration, Decorations and Code Scanning” explaining ZCML- vs. imperative- vs. decorator-based configuration equivalence.

The “ZCML Hooks” chapter has been renamed to “Hooks”; it documents how to override hooks now via imperative configuration and ZCML.

The explanation about how to supply an alternate “response factory” has been removed from the “Hooks” chapter. This feature may be removed in a later release (it still works now, it’s just not documented).

Add a section entitled “Test Set Up and Tear Down” to the unittesting chapter.

Bug Fixes

The ACL authorization policy debugging output when debug_authorization console debugging output was turned on wasn’t as clear as it could have been when a view execution was denied due to an authorization failure resulting from the set of principals passed never having matched any ACE in any ACL in the lineage. Now in this case, we report <default deny> as the ACE value and either the root ACL or <No ACL found on any object in model lineage> if no ACL was found.

When two views were registered with the same accept argument, but were otherwise registered with the same arguments, if a request entered the application which had an Accept header that accepted either of the media types defined by the set of views registered with predicates that otherwise matched, a more or less “random” one view would “win”. Now, we try harder to use the view callable associated with the view configuration that has the most specific accept argument. Thanks to Alberto Valverde for an initial patch.

Internals

The routes mapper is no longer a root factory wrapper. It is now consulted directly by the router.

The repoze.bfg.registry.make_registry callable has been removed.

The repoze.bfg.view.map_view callable has been removed.

The repoze.bfg.view.owrap_view callable has been removed.

The repoze.bfg.view.predicate_wrap callable has been removed.

The repoze.bfg.view.secure_view callable has been removed.

The repoze.bfg.view.authdebug_view callable has been removed.

The repoze.bfg.view.renderer_from_name callable has been removed. Use repoze.bfg.configuration.Configurator.renderer_from_name instead (still not an API, however).

The repoze.bfg.view.derive_view callable has been removed. Use repoze.bfg.configuration.Configurator.derive_view instead (still not an API, however).

The repoze.bfg.settings.get_options callable has been removed. Its job has been subsumed by the repoze.bfg.settings.Settings class constructor.

The repoze.bfg.view.requestonly function has been moved to repoze.bfg.configuration.requestonly.

The repoze.bfg.view.rendered_response function has been moved to repoze.bfg.configuration.rendered_response.

The repoze.bfg.view.decorate_view function has been moved to repoze.bfg.configuration.decorate_view.

The repoze.bfg.view.MultiView class has been moved to repoze.bfg.configuration.MultiView.

The repoze.bfg.zcml.Uncacheable class has been removed.

The repoze.bfg.resource.resource_spec function has been removed.

All ZCML directives which deal with attributes which are paths now use the path method of the ZCML context to resolve a relative name to an absolute one (imperative configuration requirement).

The repoze.bfg.scripting.get_root API now uses a ‘real’ WebOb request rather than a FakeRequest when it sets up the request as a threadlocal.

The repoze.bfg.traversal.traverse API now uses a ‘real’ WebOb request rather than a FakeRequest when it calls the traverser.

The repoze.bfg.request.FakeRequest class has been removed.

Most uses of the ZCA threadlocal API (the getSiteManager, getUtility, getAdapter, getMultiAdapter threadlocal API) have been removed from the core. Instead, when a threadlocal is necessary, the core uses the repoze.bfg.threadlocal.get_current_registry API to obtain the registry.

The internal ILogger utility named repoze.bfg.debug is now just an IDebugLogger unnamed utility. A named utility with the old name is registered for b/w compat.

The repoze.bfg.interfaces.ITemplateRendererFactory interface was removed; it has become unused.

Instead of depending on the martian package to do code scanning, we now just use our own scanning routines.

We now no longer have a dependency on repoze.zcml package; instead, the repoze.bfg package includes implementations of the adapter, subscriber and utility directives.

Relating to the following functions:

repoze.bfg.view.render_view

repoze.bfg.view.render_view_to_iterable

repoze.bfg.view.render_view_to_response

repoze.bfg.view.append_slash_notfound_view

repoze.bfg.view.default_notfound_view

repoze.bfg.view.default_forbidden_view

repoze.bfg.configuration.rendered_response

repoze.bfg.security.has_permission

repoze.bfg.security.authenticated_userid

repoze.bfg.security.effective_principals

repoze.bfg.security.view_execution_permitted

repoze.bfg.security.remember

repoze.bfg.security.forget

repoze.bfg.url.route_url

repoze.bfg.url.model_url

repoze.bfg.url.static_url

repoze.bfg.traversal.virtual_root

Each of these functions now expects to be called with a request object that has a registry attribute which represents the current repoze.bfg registry. They fall back to obtaining the registry from the threadlocal API.

Backwards Incompatibilites

Unit tests which use zope.testing.cleanup.cleanUp for the purpose of isolating tests from one another may now begin to fail due to lack of isolation between tests.

Here’s why: In repoze.bfg 1.1 and prior, the registry returned by repoze.bfg.threadlocal.get_current_registry when no other registry had been pushed on to the threadlocal stack was the zope.component.globalregistry.base global registry (aka the result of zope.component.getGlobalSiteManager()). In repoze.bfg 1.2+, however, the registry returned in this situation is the new module-scope repoze.bfg.registry.global_registry object. The zope.testing.cleanup.cleanUp function clears the zope.component.globalregistry.base global registry unconditionally. However, it does not know about the repoze.bfg.registry.global_registry object, so it does not clear it.

If you use the zope.testing.cleanup.cleanUp function in the setUp of test cases in your unit test suite instead of using the (more correct as of 1.1) repoze.bfg.testing.setUp, you will need to replace all calls to zope.testing.cleanup.cleanUp with a call to repoze.bfg.testing.setUp.

If replacing all calls to zope.testing.cleanup.cleanUp with a call to repoze.bfg.testing.setUp is infeasible, you can put this bit of code somewhere that is executed exactly once (not for each test in a test suite; in the `` __init__.py`` of your package or your package’s tests subpackage would be a reasonable place):

import zope.testing.cleanup
from repoze.bfg.testing import setUp
zope.testing.cleanup.addCleanUp(setUp)

When there is no “current registry” in the repoze.bfg.threadlocal.manager threadlocal data structure (this is the case when there is no “current request” or we’re not in the midst of a r.b.testing.setUp-bounded unit test), the .get method of the manager returns a data structure containing a global registry. In previous releases, this function returned the global Zope “base” registry: the result of zope.component.getGlobalSiteManager, which is an instance of the zope.component.registry.Component class. In this release, however, the global registry returns a globally importable instance of the repoze.bfg.registry.Registry class. This registry instance can always be imported as repoze.bfg.registry.global_registry.

Effectively, this means that when you call repoze.bfg.threadlocal.get_current_registry when no request or setUp bounded unit test is in effect, you will always get back the global registry that lives in repoze.bfg.registry.global_registry. It also means that repoze.bfg APIs that call get_current_registry will use this registry.

This change was made because repoze.bfg now expects the registry it uses to have a slightly different API than a bare instance of zope.component.registry.Components.

View registration no longer registers a repoze.bfg.interfaces.IViewPermission adapter (it is no longer checked by the framework; since 1.1, views have been responsible for providing their own security).

The repoze.bfg.router.make_app callable no longer accepts the authentication_policy nor the authorization_policy arguments. This feature was deprecated in version 1.0 and has been removed.

Obscure: the machinery which configured views with a request_type and a route_name would ignore the request interface implied by route_name registering a view only for the interface implied by request_type. In the unlikely event that you were trying to use these two features together, the symptom would have been that views that named a request_type but which were also associated with routes were not found when the route matched. Now if a view is configured with both a request_type and a route_name, an error is raised.

The route ZCML directive now no longer accepts the request_type or view_request_type attributes. These attributes didn’t actually work in any useful way (see entry above this one).

Because the repoze.bfg package now includes implementations of the adapter, subscriber and utility ZCML directives, it is now an error to have <include package="repoze.zcml" file="meta.zcml"/> in the ZCML of a repoze.bfg application. A ZCML conflict error will be raised if your ZCML does so. This shouldn’t be an issue for “normal” installations; it has always been the responsibility of the repoze.bfg.includes ZCML to include this file in the past; it now just doesn’t.

The repoze.bfg.testing.zcml_configure API was removed. Use the Configurator.load_zcml API instead.

Deprecations

The repoze.bfg.router.make_app function is now nominally deprecated. Its import and usage does not throw a warning, nor will it probably ever disappear. However, using a repoze.bfg.configuration.Configurator class is now the preferred way to generate a WSGI application.

Note that make_app calls zope.component.getSiteManager.sethook( repoze.bfg.threadlocal.get_current_registry) on the caller’s behalf, hooking ZCA global API lookups, for backwards compatibility purposes. If you disuse make_app, your calling code will need to perform this call itself, at least if your application uses the ZCA global API (getSiteManager, getAdapter, etc).

Dependencies

A dependency on the martian package has been removed (its functionality is replaced internally).

A dependency on the repoze.zcml package has been removed (its functionality is replaced internally).

1.1.1 (2009-11-21)

Bug Fixes

“Hybrid mode” applications (applications which explicitly used traversal after url dispatch via <route> paths containing the *traverse element) were broken in 1.1-final and all 1.1 alpha and beta releases. Views registered without a route_name route shadowed views registered with a route_name inappropriately.

1.1 (2009-11-15)

Internals

Remove dead IRouteRequirement interface from repoze.bfg.zcml module.

Documentation

Improve the “Extending an Existing Application” narrative chapter.

Add more sections to the “Defending Design” chapter.

1.1b4 (2009-11-12)

Bug Fixes

Use alsoProvides in the urldispatch module to attach an interface to the request rather than directlyProvides to avoid disturbing interfaces set in a NewRequest event handler.

Documentation

Move 1.0.1 and previous changelog to HISTORY.txt.

Add examples to repoze.bfg.url.model_url docstring.

Add “Defending BFG Design” chapter to frontpage docs.

Templates

Remove ez_setup.py and its import from all paster templates, samples, and tutorials for distribute compatibility. The documentation already explains how to install virtualenv (which will include some setuptools package), so these files, imports and usages were superfluous.

Deprecations

The options kw arg to the repoze.bfg.router.make_app function is deprecated. In its place is the keyword argument settings. The options keyword continues to work, and a deprecation warning is not emitted when it is detected. However, the paster templates, code samples, and documentation now make reference to settings rather than options. This change/deprecation was mainly made for purposes of clarity and symmetry with the get_settings() API and dicussions of “settings” in various places in the docs: we want to use the same name to refer to the same thing everywhere.

1.1b3 (2009-11-06)

Features

repoze.bfg.testing.registerRoutesMapper testing facility added. This testing function registers a routes “mapper” object in the registry, for tests which require its presence. This function is documented in the repoze.bfg.testing API documentation.

Bug Fixes

Compound statements that used an assignment entered into in an interactive IPython session invoked via paster bfgshell no longer fail to mutate the shell namespace correctly. For example, this set of statements used to fail:

In [2]: def bar(x): return x
  ...:
In [3]: list(bar(x) for x in 'abc')
Out[3]: NameError: 'bar'

In this release, the bar function is found and the correct output is now sent to the console. Thanks to Daniel Holth for the patch.

The bfgshell command did not function properly; it was still expecting to be able to call the root factory with a bare environ rather than a request object.

Backwards Incompatibilities

The repoze.bfg.scripting.get_root function now expects a request object as its second argument rather than an environ.

1.1b2 (2009-11-02)

Bug Fixes

Prevent PyPI installation failure due to easy_install trying way too hard to guess the best version of Paste. When easy_install pulls from PyPI it reads links off various pages to determine “more up to date” versions. It incorrectly picks up a link for an ancient version of a package named “Paste-Deploy-0.1” (note the dash) when trying to find the “Paste” distribution and somehow believes it’s the latest version of “Paste”. It also somehow “helpfully” decides to check out a version of this package from SVN. We pin the Paste dependency version to a version greater than 1.7 to work around this easy_install bug.

Documentation

Fix “Hybrid” narrative chapter: stop claiming that <view> statements that mention a route_name need to come afer (in XML order) the <route> statement which creates the route. This hasn’t been true since 1.1a1.

“What’s New in repoze.bfg 1.1” document added to narrative documentation.

Features

Add a new event type: repoze.bfg.events.AfterTraversal. Events of this type will be sent after traversal is completed, but before any view code is invoked. Like repoze.bfg.events.NewRequest, This event will have a single attribute: request representing the current request. Unlike the request attribute of repoze.bfg.events.NewRequest however, during an AfterTraversal event, the request object will possess attributes set by the traverser, most notably context, which will be the context used when a view is found and invoked. The interface repoze.bfg.events.IAfterTraversal can be used to subscribe to the event. For example:

<subscriber for="repoze.bfg.interfaces.IAfterTraversal"
            handler="my.app.handle_after_traverse"/>

Like any framework event, a subscriber function should expect one parameter: event.

Dependencies

Rather than depending on chameleon.core and chameleon.zpt distributions individually, depend on Malthe’s repackaged Chameleon distribution (which includes both chameleon.core and chameleon.zpt).

1.1b1 (2009-11-01)

Bug Fixes

The routes root factory called route factories and the default route factory with an environ rather than a request. One of the symptoms of this bug: applications generated using the bfg_zodb paster template in 1.1a9 did not work properly.

Reinstate renderer alias for view_renderer in the <route> ZCML directive (in-the-wild 1.1a bw compat).

bfg_routesalchemy paster template: change <route> declarations: rename renderer attribute to view_renderer.

Header values returned by the authtktauthenticationpolicy remember and forget methods would be of type unicode. This violated the WSGI spec, causing a TypeError to be raised when these headers were used under mod_wsgi.

If a BFG app that had a route matching the root URL was mounted under a path in modwsgi, ala WSGIScriptAlias /myapp /Users/chrism/projects/modwsgi/env/bfg.wsgi, the home route (a route with the path of '/' or '') would not match when the path /myapp was visited (only when the path /myapp/ was visited). This is now fixed: if the urldispatch root factory notes that the PATH_INFO is empty, it converts it to a single slash before trying to do matching.

Documentation

In <route> declarations in tutorial ZCML, rename renderer attribute to view_renderer (fwd compat).

Fix various tutorials broken by 1.1a9 <route> directive changes.

Internal

Deal with a potential circref in the traversal module.

1.1a9 (2009-10-31)

Bug Fixes

An incorrect ZCML conflict would be encountered when the request_param predicate attribute was used on the ZCML view directive if any two otherwise same-predicated views had the combination of a predicate value with an = sign and one without (e.g. a vs. a=123).

Features

In previous versions of BFG, the “root factory” (the get_root callable passed to make_app or a function pointed to by the factory attribute of a route) was called with a “bare” WSGI environment. In this version, and going forward, it will be called with a request object. The request object passed to the factory implements dictionary-like methods in such a way that existing root factory code which expects to be passed an environ will continue to work.

The __call__ of a plugin “traverser” implementation (registered as an adapter for ITraverser or ITraverserFactory) will now receive a request as the single argument to its __call__ method. In previous versions it was passed a WSGI environ object. The request object passed to the factory implements dictionary-like methods in such a way that existing traverser code which expects to be passed an environ will continue to work.

The ZCML route directive’s attributes xhr, request_method, path_info, request_param, header and accept are now route predicates rather than view predicates. If one or more of these predicates is specified in the route configuration, all of the predicates must return true for the route to match a request. If one or more of the route predicates associated with a route returns False when checked during a request, the route match fails, and the next match in the routelist is tried. This differs from the previous behavior, where no route predicates existed and all predicates were considered view predicates, because in that scenario, the next route was not tried.

Documentation

Various changes were made to narrative and API documentation supporting the change from passing a request rather than an environ to root factories and traversers.

Internal

The request implements dictionary-like methods that mutate and query the WSGI environ. This is only for the purpose of backwards compatibility with root factories which expect an environ rather than a request.

The repoze.bfg.request.create_route_request_factory function, which returned a request factory was removed in favor of a repoze.bfg.request.route_request_interface function, which returns an interface.

The repoze.bfg.request.Request class, which is a subclass of webob.Request now defines its own __setattr__, __getattr__ and __delattr__ methods, which override the default WebOb behavior. The default WebOb behavior stores attributes of the request in self.environ['webob.adhoc_attrs'], and retrieves them from that dictionary during a __getattr__. This behavior was undesirable for speed and “expectation” reasons. Now attributes of the request are stored in request.__dict__ (as you otherwise might expect from an object that did not override these methods).

The router no longer calls repoze.bfg.traversal._traverse and does its work “inline” (speed).

Reverse the order in which the router calls the request factory and the root factory. The request factory is now called first; the resulting request is passed to the root factory.

The repoze.bfg.request.request_factory function has been removed. Its functionality is no longer required.

The “routes root factory” that wraps the default root factory when there are routes mentioned in the configuration now attaches an interface to the request via zope.interface.directlyProvides. This replaces logic in the (now-gone) repoze.bfg.request.request_factory function.

The route and view ZCML directives now register an interface as a named utility (retrieved from repoze.bfg.request.route_request_interface) rather than a request factory (the previous return value of the now-missing repoze.bfg.request.create_route_request_factory.

The repoze.bfg.functional module was renamed to repoze.bfg.compat.

Backwards Incompatibilities

Explicitly revert the feature introduced in 1.1a8: where the name root is available as an attribute of the request before a NewRequest event is emitted. This makes some potential future features impossible, or at least awkward (such as grouping traversal and view lookup into a single adapter lookup).

The containment, attr and renderer attributes of the route ZCML directive were removed.

1.1a8 (2009-10-27)

Features

Add path_info view configuration predicate.

paster bfgshell now supports IPython if it’s available for import. Thanks to Daniel Holth for the initial patch.

Add repoze.bfg.testing.registerSettings API, which is documented in the “repoze.bfg.testing” API chapter. This allows for registration of “settings” values obtained via repoze.bfg.settings.get_settings() for use in unit tests.

The name root is available as an attribute of the request slightly earlier now (before a NewRequest event is emitted). root is the result of the application “root factory”.

Added max_age parameter to authtktauthenticationpolicy ZCML directive. If this value is set, it must be an integer representing the number of seconds which the auth tkt cookie will survive. Mainly, its existence allows the auth_tkt cookie to survive across browser sessions.

Bug Fixes

Fix bug encountered during “scan” (when <scan ..> directive is used in ZCML) introduced in 1.1a7. Symptom: AttributeError: object has no attribute __provides__ raised at startup time.

The reissue_time argument to the authtktauthenticationpolicy ZCML directive now actually works. When it is set to an integer value, an authticket set-cookie header is appended to the response whenever a request requires authentication and ‘now’ minus the authticket’s timestamp is greater than reissue_time seconds.

Documentation

Add a chapter titled “Request and Response” to the narrative documentation, content cribbed from the WebOb documentation.

Call out predicate attributes of ZCML directive within “Views” chapter.

Fix route_url documentation (_query argument documented as query and _anchor argument documented as anchor).

Backwards Incompatibilities

The authtkt authentication policy remember method now no longer honors token or userdata keyword arguments.

Internal

Change how bfg_view decorator works when used as a class method decorator. In 1.1a7, the``scan``directive actually tried to grope every class in scanned package at startup time, calling dir against each found class, and subsequently invoking getattr against each thing found by dir to see if it was a method. This led to some strange symptoms (e.g. AttributeError: object has no attribute __provides__), and was generally just a bad idea. Now, instead of groping classes for methods at startup time, we just cause the bfg_view decorator itself to populate the method’s class’ __dict__ when it is used as a method decorator. This also requires a nasty _getframe thing but it’s slightly less nasty than the startup time groping behavior. This is essentially a reversion back to 1.1a6 “grokking” behavior plus some special magic for using the bfg_view decorator as method decorator inside the bfg_view class itself.

The router now checks for a global_response_headers attribute of the request object before returning a response. If this value exists, it is presumed to be a sequence of two-tuples, representing a set of headers to append to the ‘normal’ response headers. This feature is internal, rather than exposed externally, because it’s unclear whether it will stay around in the long term. It was added to support the reissue_time feature of the authtkt authentication policy.

The interface ITraverserFactory is now just an alias for ITraverser.

1.1a7 (2009-10-18)

Features

More than one @bfg_view decorator may now be stacked on top of any number of others. Each invocation of the decorator registers a single view configuration. For instance, the following combination of decorators and a function will register two view configurations for the same view callable:

from repoze.bfg.view import bfg_view

@bfg_view(name='edit')
@bfg_view(name='change')
def edit(context, request):
    pass

This makes it possible to associate more than one view configuration with a single callable without requiring any ZCML.

The @bfg_view decorator can now be used against a class method:

from webob import Response
from repoze.bfg.view import bfg_view

class MyView(object):
    def __init__(self, context, request):
        self.context = context
        self.request = request

    @bfg_view(name='hello')
    def amethod(self):
        return Response('hello from %s!' % self.context)

When the bfg_view decorator is used against a class method, a view is registered for the class (it’s a “class view” where the “attr” happens to be the name of the method it is attached to), so the class it’s defined within must have a suitable constructor: one that accepts context, request or just request.

Documentation

Added Changing the Traverser and Changing How :mod:`repoze.bfg.url.model_url` Generates a URL to the “Hooks” narrative chapter of the docs.

Internal

Remove ez_setup.py and imports of it within setup.py. In the new world, and as per virtualenv setup instructions, people will already have either setuptools or distribute.

1.1a6 (2009-10-15)

Features

Add xhr, accept, and header view configuration predicates to ZCML view declaration, ZCML route declaration, and bfg_view decorator. See the Views narrative documentation chapter for more information about these predicates.

Add setUp and tearDown functions to the repoze.bfg.testing module. Using setUp in a test setup and tearDown in a test teardown is now the recommended way to do component registry setup and teardown. Previously, it was recommended that a single function named repoze.bfg.testing.cleanUp be called in both the test setup and tear down. repoze.bfg.testing.cleanUp still exists (and will exist “forever” due to its widespread use); it is now just an alias for repoze.bfg.testing.setUp and is nominally deprecated.

The BFG component registry is now available in view and event subscriber code as an attribute of the request ie. request.registry. This fact is currently undocumented except for this note, because BFG developers never need to interact with the registry directly anywhere else.

The BFG component registry now inherits from dict, meaning that it can optionally be used as a simple dictionary. Component registrations performed against it via e.g. registerUtility, registerAdapter, and similar API methods are kept in a completely separate namespace than its dict members, so using the its component API methods won’t effect the keys and values in the dictionary namespace. Likewise, though the component registry “happens to be” a dictionary, use of mutating dictionary methods such as __setitem__ will have no influence on any component registrations made against it. In other words, the registry object you obtain via e.g. repoze.bfg.threadlocal.get_current_registry or request.registry happens to be both a component registry and a dictionary, but using its component-registry API won’t impact data added to it via its dictionary API and vice versa. This is a forward compatibility move based on the goals of “marco”.

Expose and document repoze.bfg.testing.zcml_configure API. This function populates a component registry from a ZCML file for testing purposes. It is documented in the “Unit and Integration Testing” chapter.

Documentation

Virtual hosting narrative docs chapter updated with info about mod_wsgi.

Point all index URLs at the literal 1.1 index (this alpha cycle may go on a while).

Various tutorial test modules updated to use repoze.bfg.testing.setUp and repoze.bfg.testing.tearDown methods in order to encourage this as best practice going forward.

Added “Creating Integration Tests” section to unit testing narrative documentation chapter. As a result, the name of the unittesting chapter is now “Unit and Integration Testing”.

Backwards Incompatibilities

Importing getSiteManager and get_registry from repoze.bfg.registry is no longer supported. These imports were deprecated in repoze.bfg 1.0. Import of getSiteManager should be done as from zope.component import getSiteManager. Import of get_registry should be done as from repoze.bfg.threadlocal import get_current_registry. This was done to prevent a circular import dependency.

Code bases which alternately invoke both zope.testing.cleanup.cleanUp and repoze.bfg.testing.cleanUp (treating them equivalently, using them interchangeably) in the setUp/tearDown of unit tests will begin to experience test failures due to lack of test isolation. The “right” mechanism is repoze.bfg.testing.cleanUp (or the combination of repoze.bfg.testing.setUp and repoze.bfg.testing.tearDown). but a good number of legacy codebases will use zope.testing.cleanup.cleanUp instead. We support zope.testing.cleanup.cleanUp but not in combination with repoze.bfg.testing.cleanUp in the same codebase. You should use one or the other test cleanup function in a single codebase, but not both.

Internal

Created new repoze.bfg.configuration module which assumes responsibilities previously held by the repoze.bfg.registry and repoze.bfg.router modules (avoid a circular import dependency).

The result of the zope.component.getSiteManager function in unit tests set up with repoze.bfg.testing.cleanUp or repoze.bfg.testing.setUp will be an instance of repoze.bfg.registry.Registry instead of the global zope.component.globalregistry.base registry. This also means that the threadlocal ZCA API functions such as getAdapter and getUtility as well as internal BFG machinery (such as model_url and route_url) will consult this registry within unit tests. This is a forward compatibility move based on the goals of “marco”.

Removed repoze.bfg.testing.addCleanUp function and associated module-scope globals. This was never an API.

1.1a5 (2009-10-10)

Documentation

Change “Traversal + ZODB” and “URL Dispatch + SQLAlchemy” Wiki tutorials to make use of the new-to-1.1 “renderer” feature (return dictionaries from all views).

Add tests to the “URL Dispatch + SQLAlchemy” tutorial after the “view” step.

Added a diagram of model graph traversal to the “Traversal” narrative chapter of the documentation.

An exceptions API chapter was added, documenting the new repoze.bfg.exceptions module.

Describe “request-only” view calling conventions inside the urldispatch narrative chapter, where it’s most helpful.

Add a diagram which explains the operation of the BFG router to the “Router” narrative chapter.

Features

Add a new repoze.bfg.testing API: registerRoute, for registering routes to satisfy calls to e.g. repoze.bfg.url.route_url in unit tests.

The notfound and forbidden ZCML directives now accept the following addtional attributes: attr, renderer, and wrapper. These have the same meaning as they do in the context of a ZCML view directive.

For behavior like Django’s APPEND_SLASH=True, use the repoze.bfg.view.append_slash_notfound_view view as the Not Found view in your application. When this view is the Not Found view (indicating that no view was found), and any routes have been defined in the configuration of your application, if the value of PATH_INFO does not already end in a slash, and if the value of PATH_INFO plus a slash matches any route’s path, do an HTTP redirect to the slash-appended PATH_INFO. Note that this will lose POST data information (turning it into a GET), so you shouldn’t rely on this to redirect POST requests.

Speed up repoze.bfg.location.lineage slightly.

Speed up repoze.bfg.encode.urlencode (nee’ repoze.bfg.url.urlencode) slightly.

Speed up repoze.bfg.traversal.model_path.

Speed up repoze.bfg.traversal.model_path_tuple slightly.

Speed up repoze.bfg.traversal.traverse slightly.

Speed up repoze.bfg.url.model_url slightly.

Speed up repoze.bfg.url.route_url slightly.

Sped up repoze.bfg.traversal.ModelGraphTraverser:__call__ slightly.

Minor speedup of repoze.bfg.router.Router.__call__.

New repoze.bfg.exceptions module was created to house exceptions that were previously sprinkled through various modules.

Internal

Move repoze.bfg.traversal._url_quote into repoze.bfg.encode as url_quote.

Deprecations

The import of repoze.bfg.view.NotFound is deprecated in favor of repoze.bfg.exceptions.NotFound. The old location still functions, but emits a deprecation warning.

The import of repoze.bfg.security.Unauthorized is deprecated in favor of repoze.bfg.exceptions.Forbidden. The old location still functions but emits a deprecation warning. The rename from Unauthorized to Forbidden brings parity to the the name of the exception and the system view it invokes when raised.

Backwards Incompatibilities

We previously had a Unicode-aware wrapper for the urllib.urlencode function named repoze.bfg.url.urlencode which delegated to the stdlib function, but which marshalled all unicode values to utf-8 strings before calling the stdlib version. A newer replacement now lives in repoze.bfg.encode The replacement does not delegate to the stdlib.

The replacement diverges from the stdlib implementation and the previous repoze.bfg.url url implementation inasmuch as its doseq argument is now a decoy: it always behaves in the doseq=True way (which is the only sane behavior) for speed purposes.

The old import location (repoze.bfg.url.urlencode) still functions and has not been deprecated.

In 0.8a7, the return value expected from an object implementing ITraverserFactory was changed from a sequence of values to a dictionary containing the keys context, view_name, subpath, traversed, virtual_root, virtual_root_path, and root. Until now, old-style traversers which returned a sequence have continued to work but have generated a deprecation warning. In this release, traversers which return a sequence instead of a dictionary will no longer work.

1.1a4 (2009-09-23)

Bug Fixes

On 64-bit Linux systems, views that were members of a multiview (orderings of views with predicates) were not evaluated in the proper order. Symptom: in a configuration that had two views with the same name but one with a request_method=POST predicate and one without, the one without the predicate would be called unconditionally (even if the request was a POST request). Thanks much to Sebastien Douche for providing the buildbots that pointed this out.

Documentation

Added a tutorial which explains how to use repoze.session (ZODB-based sessions) in a ZODB-based repoze.bfg app.

Added a tutorial which explains how to add ZEO to a ZODB-based repoze.bfg application.

Added a tutorial which explains how to run a repoze.bfg application under mod_wsgi [http://code.google.com/p/modwsgi/]. See “Running a repoze.bfg Application under mod_wsgi” in the tutorials section of the documentation.

Features

Add a repoze.bfg.url.static_url API which is capable of generating URLs to static resources defined by the <static> ZCML directive. See the “Views” narrative chapter’s section titled “Generating Static Resource URLs” for more information.

Add a string renderer. This renderer converts a non-Response return value of any view callble into a string. It is documented in the “Views” narrative chapter.

Give the route ZCML directive the view_attr and view_renderer parameters (bring up to speed with 1.1a3 features). These can also be spelled as attr and renderer.

Backwards Incompatibilities

An object implementing the IRenderer interface (and ITemplateRenderer`, which is a subclass of ``IRenderer) must now accept an extra system argument in its __call__ method implementation. Values computed by the system (as opposed to by the view) are passed by the system in the system parameter, which will always be a dictionary. Keys in the dictionary include: view (the view object that returned the value), renderer_name (the template name or simple name of the renderer), context (the context object passed to the view), and request (the request object passed to the view). Previously only ITemplateRenderers received system arguments as elements inside the main value dictionary.

Internal

The way bfg_view declarations are scanned for has been modified. This should have no external effects.

Speed: do not register an ITraverserFactory in configure.zcml; instead rely on queryAdapter and a manual default to ModelGraphTraverser.

Speed: do not register an IContextURL in configure.zcml; instead rely on queryAdapter and a manual default to TraversalContextURL.

General speed microimprovements for helloworld benchmark: replace try/excepts with statements which use ‘in’ keyword.

1.1a3 (2009-09-16)

Documentation

The “Views” narrative chapter in the documentation has been updated extensively to discuss “renderers”.

Features

A renderer attribute has been added to view configurations, replacing the previous (1.1a2) version’s template attribute. A “renderer” is an object which accepts the return value of a view and converts it to a string. This includes, but is not limited to, templating systems.

A new interface named IRenderer was added. The existing interface, ITemplateRenderer now derives from this new interface. This interface is internal.

A new interface named IRendererFactory was added. An existing interface named ITemplateRendererFactory now derives from this interface. This interface is internal.

The view attribute of the view ZCML directive is no longer required if the ZCML directive also has a renderer attribute. This is useful when the renderer is a template renderer and no names need be passed to the template at render time.

A new zcml directive renderer has been added. It is documented in the “Views” narrative chapter of the documentation.

A ZCML view directive (and the associated bfg_view decorator) can now accept a “wrapper” value. If a “wrapper” value is supplied, it is the value of a separate view’s name attribute. When a view with a wrapper attribute is rendered, the “inner” view is first rendered normally. Its body is then attached to the request as “wrapped_body”, and then a wrapper view name is looked up and rendered (using repoze.bfg.render_view_to_response), passed the request and the context. The wrapper view is assumed to do something sensible with request.wrapped_body, usually inserting its structure into some other rendered template. This feature makes it possible to specify (potentially nested) “owrap” relationships between views using only ZCML or decorators (as opposed always using ZPT METAL and analogues to wrap view renderings in outer wrappers).

Dependencies

When used under Python < 2.6, BFG now has an installation time dependency on the simplejson package.

Deprecations

The repoze.bfg.testing.registerDummyRenderer API has been deprecated in favor of repoze.bfg.testing.registerTemplateRenderer. A deprecation warning is not issued at import time for the former name; it will exist “forever”; its existence has been removed from the documentation, however.

The repoze.bfg.templating.renderer_from_cache function has been moved to repoze.bfg.renderer.template_renderer_factory. This was never an API, but code in the wild was spotted that used it. A deprecation warning is issued at import time for the former.

Backwards Incompatibilities

The ITemplateRenderer interface has been changed. Previously its __call__ method accepted **kw. It now accepts a single positional parameter named kw (REVISED: it accepts two positional parameters as of 1.1a4: value and system). This is mostly an internal change, but it was exposed in APIs in one place: if you’ve used the repoze.bfg.testing.registerDummyRenderer API in your tests with a custom “renderer” argument with your own renderer implementation, you will need to change that renderer implementation to accept kw instead of **kw in its __call__ method (REVISED: make it accept value and system positional arguments as of 1.1a4).

The ITemplateRendererFactory interface has been changed. Previously its __call__ method accepted an auto_reload keyword parameter. Now its __call__ method accepts no keyword parameters. Renderers are now themselves responsible for determining details of auto-reload. This is purely an internal change. This interface was never external.

The template_renderer ZCML directive introduced in 1.1a2 has been removed. It has been replaced by the renderer directive.

The previous release (1.1a2) added a view configuration attribute named template. In this release, the attribute has been renamed to renderer. This signifies that the attribute is more generic: it can now be not just a template name but any renderer name (ala json).

In the previous release (1.1a2), the Chameleon text template renderer was used if the system didn’t associate the template view configuration value with a filename with a “known” extension. In this release, you must use a renderer attribute which is a path that ends with a .txt extension (e.g. templates/foo.txt) to use the Chameleon text renderer.

1.1a2 (2009-09-14)

Features

A ZCML view directive (and the associated bfg_view decorator) can now accept an “attr” value. If an “attr” value is supplied, it is considered a method named of the view object to be called when the response is required. This is typically only good for views that are classes or instances (not so useful for functions, as functions typically have no methods other than __call__).

A ZCML view directive (and the associated bfg_view decorator) can now accept a “template” value. If a “template” value is supplied, and the view callable returns a dictionary, the associated template is rendered with the dictionary as keyword arguments. See the section named “Views That Have a template” in the “Views” narrative documentation chapter for more information.

1.1a1 (2009-09-06)

Bug Fixes

“tests” module removed from the bfg_alchemy paster template; these tests didn’t work.

Bugfix: the discriminator for the ZCML “route” directive was incorrect. It was possible to register two routes that collided without the system spitting out a ConfigurationConflictError at startup time.

Features

Feature addition: view predicates. These are exposed as the request_method, request_param, and containment attributes of a ZCML view declaration, or the respective arguments to a @bfg_view decorator. View predicates can be used to register a view for a more precise set of environment parameters than was previously possible. For example, you can register two views with the same name with different request_param attributes. If the request.params dict contains ‘foo’ (request_param=”foo”), one view might be called; if it contains ‘bar’ (request_param=”bar”), another view might be called. request_param can also name a key/value pair ala foo=123. This will match only when the foo key is in the request.params dict and it has the value ‘123’. This particular example makes it possible to write separate view functions for different form submissions. The other predicates, containment and request_method work similarly. containment is a view predicate that will match only when the context’s graph lineage has an object possessing a particular class or interface, for example. request_method is a view predicate that will match when the HTTP REQUEST_METHOD equals some string (eg. ‘POST’).

The @bfg_view decorator now accepts three additional arguments: request_method, request_param, and containment. request_method is used when you’d like the view to match only a request with a particular HTTP REQUEST_METHOD; a string naming the REQUEST_METHOD can also be supplied as request_type for backwards compatibility. request_param is used when you’d like a view to match only a request that contains a particular request.params key (with or without a value). containment is used when you’d like to match a request that has a context that has some class or interface in its graph lineage. These are collectively known as “view predicates”.

The route ZCML directive now honors view_request_method, view_request_param and view_containment attributes, which pass along these values to the associated view if any is provided. Additionally, the request_type attribute can now be spelled as view_request_type, and permission can be spelled as view_permission. Any attribute which starts with view_ can now be spelled without the view_ prefix, so view_for can be spelled as for now, etc. Both forms are documented in the urldispatch narraitve documentation chapter.

The request_param ZCML view directive attribute (and its bfg_view decorator cousin) can now specify both a key and a value. For example, request_param="foo=123" means that the foo key must have a value of 123 for the view to “match”.

Allow repoze.bfg.traversal.find_interface API to use a class object as the argument to compare against the model passed in. This means you can now do find_interface(model, SomeClass) and the first object which is found in the lineage which has SomeClass as its class (or the first object found which has SomeClass as any of its superclasses) will be returned.

Added static ZCML directive which registers a route for a view that serves up files in a directory. See the “Views” narrative documentation chapter’s “Serving Static Resources Using a ZCML Directive” section for more information.

The repoze.bfg.view.static class now accepts a string as its first argument (“root_dir”) that represents a package-relative name e.g. somepackage:foo/bar/static. This is now the preferred mechanism for spelling package-relative static paths using this class. A package_name keyword argument has been left around for backwards compatibility. If it is supplied, it will be honored.

The API repoze.bfg.testing.registerView now takes a permission argument. Use this instead of using repoze.bfg.testing.registerViewPermission.

The ordering of route declarations vs. the ordering of view declarations that use a “route_name” in ZCML no longer matters. Previously it had been impossible to use a route_name from a route that had not yet been defined in ZCML (order-wise) within a “view” declaration.

The repoze.bfg router now catches both repoze.bfg.security.Unauthorized and repoze.bfg.view.NotFound exceptions while rendering a view. When the router catches an Unauthorized, it returns the registered forbidden view. When the router catches a NotFound, it returns the registered notfound view.

Internal

Change urldispatch internals: Route object is now constructed using a path, a name, and a factory instead of a name, a matcher, a generator, and a factory.

Move (non-API) default_view, default_forbidden_view, and default_notfound_view functions into the repoze.bfg.view module (moved from repoze.bfg.router).

Removed ViewPermissionFactory from repoze.bfg.security. View permission checking is now done by registering and looking up an ISecuredView.

The static ZCML directive now uses a custom root factory when constructing a route.

The interface IRequestFactories was removed from the repoze.bfg.interfaces module. This interface was never an API.

The function named named_request_factories and the data structure named DEFAULT_REQUEST_FACTORIES have been removed from the repoze.bfg.request module. These were never APIs.

The IViewPermissionFactory interface has been removed. This was never an API.

Documentation

Request-only-convention examples in the “Views” narrative documentation were broken.

Fixed documentation bugs related to forget and remember in security API docs.

Fixed documentation for repoze.bfg.view.static (in narrative Views chapter).

Deprecations

The API repoze.bfg.testing.registerViewPermission has been deprecated.

Backwards Incompatibilities

The interfaces IPOSTRequest, IGETRequest, IPUTRequest, IDELETERequest, and IHEADRequest have been removed from the repoze.bfg.interfaces module. These were not documented as APIs post-1.0. Instead of using one of these, use a request_method ZCML attribute or request_method bfg_view decorator parameter containing an HTTP method name (one of GET, POST, HEAD, PUT, DELETE) instead of one of these interfaces if you were using one explicitly. Passing a string in the set (GET, HEAD, PUT, POST, DELETE) as a request_type argument will work too. Rationale: instead of relying on interfaces attached to the request object, BFG now uses a “view predicate” to determine the request type.

Views registered without the help of the ZCML view directive are now responsible for performing their own authorization checking.

The registry_manager backwards compatibility alias importable from “repoze.bfg.registry”, deprecated since repoze.bfg 0.9 has been removed. If you are tring to use the registry manager within a debug script of your own, use a combination of the “repoze.bfg.paster.get_app” and “repoze.bfg.scripting.get_root” APIs instead.

The INotFoundAppFactory interface has been removed; it has been deprecated since repoze.bfg 0.9. If you have something like the following in your configure.zcml:

<utility provides="repoze.bfg.interfaces.INotFoundAppFactory"
         component="helloworld.factories.notfound_app_factory"/>

Replace it with something like:

<notfound
    view="helloworld.views.notfound_view"/>

See “Changing the Not Found View” in the “Hooks” chapter of the documentation for more information.

The IUnauthorizedAppFactory interface has been removed; it has been deprecated since repoze.bfg 0.9. If you have something like the following in your configure.zcml:

<utility provides="repoze.bfg.interfaces.IUnauthorizedAppFactory"
         component="helloworld.factories.unauthorized_app_factory"/>

Replace it with something like:

<forbidden
    view="helloworld.views.forbidden_view"/>

See “Changing the Forbidden View” in the “Hooks” chapter of the documentation for more information.

ISecurityPolicy-based security policies, deprecated since repoze.bfg 0.9, have been removed. If you have something like this in your configure.zcml, it will no longer work:

<utility
  provides="repoze.bfg.interfaces.ISecurityPolicy"
  factory="repoze.bfg.security.RemoteUserInheritingACLSecurityPolicy"
 />

If ZCML like the above exists in your application, you will receive an error at startup time. Instead of the above, you’ll need something like:

<remoteuserauthenticationpolicy/>
<aclauthorizationpolicy/>

This is just an example. See the “Security” chapter of the repoze.bfg documentation for more information about configuring security policies.

Custom ZCML directives which register an authentication or authorization policy (ala “authtktauthenticationpolicy” or “aclauthorizationpolicy”) should register the policy “eagerly” in the ZCML directive instead of from within a ZCML action. If an authentication or authorization policy is not found in the component registry by the view machinery during deferred ZCML processing, view security will not work as expected.

1.0.1 (2009-07-22)

Added support for has_resource, resource_isdir, and resource_listdir to the resource “OverrideProvider”; this fixes a bug with a symptom that a file could not be overridden in a resource directory unless a file with the same name existed in the original directory being overridden.

Fixed documentation bug showing invalid test for values from the matchdict: they are stored as attributes of the Article, rather than subitems.

Fixed documentation bug showing wrong environment key for the matchdict produced by the matching route.

Added a workaround for a bug in Python 2.6, 2.6.1, and 2.6.2 having to do with a recursion error in the mimetypes module when trying to serve static files from Paste’s FileApp: http://bugs.python.org/issue5853. Symptom: File “/usr/lib/python2.6/mimetypes.py”, line 244, in guess_type return guess_type(url, strict) RuntimeError: maximum recursion depth exceeded. Thanks to Armin Ronacher for identifying the symptom and pointing out a fix.

Minor edits to tutorials for accuracy based on feedback.

Declared Paste and PasteDeploy dependencies.

1.0 (2009-07-05)

Retested and added some content to GAE tutorial.

Edited “Extending” narrative docs chapter.

Added “Deleting the Database” section to the “Defining Models” chapter of the traversal wiki tutorial.

Spell checking of narratives and tutorials.

1.0b2 (2009-07-03)

remoteuserauthenticationpolicy ZCML directive didn’t work without an environ_key directive (didn’t match docs).

Fix configure_zcml filespec check on Windows. Previously if an absolute filesystem path including a drive letter was passed as filename (or as configure_zcml in the options dict) to repoze.bfg.router.make_app, it would be treated as a package:resource_name specification.

Fix inaccuracies and import errors in bfgwiki (traversal+ZODB) and bfgwiki2 (urldispatch+SA) tutorials.

Use bfgsite index for all tutorial setup.cfg files.

Full documentation grammar/style/spelling audit.

1.0b1 (2009-07-02)

Features

Allow a Paste config file (configure_zcml) value or an environment variable (BFG_CONFIGURE_ZCML) to name a ZCML file (optionally package-relative) that will be used to bootstrap the application. Previously, the integrator could not influence which ZCML file was used to do the boostrapping (only the original application developer could do so).

Documentation

Added a “Resources” chapter to the narrative documentation which explains how to override resources within one package from another package.

Added an “Extending” chapter to the narrative documentation which explains how to extend or modify an existing BFG application using another Python package and ZCML.

1.0a9 (2009-07-01)

Features

Make it possible to pass strings in the form “package_name:relative/path” to APIs like render_template, render_template_to_response, and get_template. Sometimes the package in which a caller lives is a direct namespace package, so the module which is returned is semi-useless for navigating from. In this way, the caller can control the horizontal and vertical of where things get looked up from.

1.0a8 (2009-07-01)

Deprecations

Deprecate the authentication_policy and authorization_policy arguments to repoze.bfg.router.make_app. Instead, developers should use the various authentication policy ZCML directives (repozewho1authenticationpolicy, remoteuserauthenticationpolicy and authtktauthenticationpolicy) and the aclauthorizationpolicy` authorization policy directive as described in the changes to the “Security” narrative documenation chapter and the wiki tutorials.

Features

Add three new ZCML directives which configure authentication policies:

repozewho1authenticationpolicy

remoteuserauthenticationpolicy

authtktauthenticationpolicy

Add a new ZCML directive which configures an ACL authorization policy named aclauthorizationpolicy.

Bug Fixes

Bug fix: when a repoze.bfg.resource.PackageOverrides class was instantiated, and the package it was overriding already had a __loader__ attribute, it would fail at startup time, even if the __loader__ attribute was another PackageOverrides instance. We now replace any __loader__ that is also a PackageOverrides instance. Symptom: ConfigurationExecutionError: <type 'exceptions.TypeError'>: Package <module 'karl.views' from '/Users/chrism/projects/osi/bfgenv/src/karl/karl/views/__init__.pyc'> already has a __loader__ (probably a module in a zipped egg).

1.0a7 (2009-06-30)

Features

Add a reload_resources configuration file setting (aka the BFG_RELOAD_RESOURCES environment variable). When this is set to true, the server never needs to be restarted when moving files between directory resource overrides (esp. for templates currently).

Add a reload_all configuration file setting (aka the BFG_RELOAD_ALL environment variable) that implies both reload_resources and reload_templates.

The static helper view class now uses a PackageURLParser in order to allow for the overriding of static resources (CSS / logo files, etc) using the resource ZCML directive. The PackageURLParser class was added to a (new) static module in BFG; it is a subclass of the StaticURLParser class in paste.urlparser.

The repoze.bfg.templating.renderer_from_cache function now checks for the reload_resources setting; if it’s true, it does not register a template renderer (it won’t use the registry as a template renderer cache).

Documentation

Add pkg_resources to the glossary.

Update the “Environment” docs to note the existence of reload_resources and reload_all.

Updated the bfg_alchemy paster template to include two views: the view on the root shows a list of links to records; the view on a record shows the details for that object.

Internal

Use a colon instead of a tab as the separator between package name and relpath to form the “spec” when register a ITemplateRenderer.

Register a repoze.bfg.resource.OverrideProvider as a pkg_resources provider only for modules which are known to have overrides, instead of globally, when a <resource> directive is used (performance).

1.0a6 (2009-06-29)

Bug Fixes

Use caller_package function instead of caller_module function within templating to avoid needing to name the caller module in resource overrides (actually match docs).

Make it possible to override templates stored directly in a module with templates in a subdirectory of the same module, stored directly within another module, or stored in a subdirectory of another module (actually match docs).

1.0a5 (2009-06-28)

Features

A new ZCML directive exists named “resource”. This ZCML directive allows you to override Chameleon templates within a package (both directories full of templates and individual template files) with other templates in the same package or within another package. This allows you to “fake out” a view’s use of a template, causing it to retrieve a different template than the one actually named by a relative path to a call like render_template_to_response('templates/mytemplate.pt'). For example, you can override a template file by doing:

<resource
  to_override="some.package:templates/mytemplate.pt"
  override_with="another.package:othertemplates/anothertemplate.pt"
 />

The string passed to “to_override” and “override_with” is named a “specification”. The colon separator in a specification separates the package name from a package-relative directory name. The colon and the following relative path are optional. If they are not specified, the override attempts to resolve every lookup into a package from the directory of another package. For example:

<resource
  to_override="some.package"
  override_with="another.package"
 />

Individual subdirectories within a package can also be overridden:

<resource
  to_override="some.package:templates/"
  override_with="another.package:othertemplates/"
 />

If you wish to override a directory with another directory, you must make sure to attach the slash to the end of both the to_override specification and the override_with specification. If you fail to attach a slash to the end of a specification that points a directory, you will get unexpected results. You cannot override a directory specification with a file specification, and vice versa (a startup error will occur if you try).

You cannot override a resource with itself (a startup error will occur if you try).

Only individual package resources may be overridden. Overrides will not traverse through subpackages within an overridden package. This means that if you want to override resources for both some.package:templates, and some.package.views:templates, you will need to register two overrides.

The package name in a specification may start with a dot, meaning that the package is relative to the package in which the ZCML file resides. For example:

<resource
  to_override=".subpackage:templates/"
  override_with="another.package:templates/"
 />

Overrides for the same to_overrides specification can be named multiple times within ZCML. Each override_with path will be consulted in the order defined within ZCML, forming an override search path.

Resource overrides can actually override resources other than templates. Any software which uses the pkg_resources get_resource_filename, get_resource_stream or get_resource_string APIs will obtain an overridden file when an override is used. However, the only built-in facility which uses the pkg_resources API within BFG is the templating stuff, so we only call out template overrides here.

Use the pkg_resources API to locate template filenames instead of dead-reckoning using the os.path module.

The repoze.bfg.templating module now uses pkg_resources to locate and register template files instead of using an absolute path name.

1.0a4 (2009-06-25)

Features

Cause :segment matches in route paths to put a Unicode-decoded and URL-dequoted value in the matchdict for the value matched. Previously a non-decoded non-URL-dequoted string was placed in the matchdict as the value.

Cause *remainder matches in route paths to put a tuple in the matchdict dictionary in order to be able to present Unicode-decoded and URL-dequoted values for the traversal path. Previously a non-decoded non-URL-dequoted string was placed in the matchdict as the value.

Add optional max_age keyword value to the remember method of repoze.bfg.authentication.AuthTktAuthenticationPolicy; if this value is passed to remember, the generated cookie will have a corresponding Max-Age value.

Documentation

Add information to the URL Dispatch narrative documentation about path pattern matching syntax.

Bug Fixes

Make route_url URL-quote segment replacements during generation. Remainder segments are not quoted.

1.0a3 (2009-06-24)

Implementation Changes

repoze.bfg no longer relies on the Routes package to interpret URL paths. All known existing path patterns will continue to work with the reimplemented logic, which lives in repoze.bfg.urldispatch. <route> ZCML directives which use certain attributes (uncommon ones) may not work (see “Backwards Incompatibilities” below).

Bug Fixes

model_url when passed a request that was generated as a result of a route match would fail in a call to route.generate.

BFG-on-GAE didn’t work due to a corner case bug in the fallback Python implementation of threading.local (symptom: “Initialization arguments are not supported”). Thanks to Michael Bernstein for the bug report.

Documentation

Added a “corner case” explanation to the “Hybrid Apps” chapter explaining what to do when “the wrong” view is matched.

Use repoze.bfg.url.route_url API in tutorials rather than Routes url_for API.

Features

Added the repoze.bfg.url.route_url API. This API allows you to generate URLs based on <route> declarations. See the URL Dispatch narrative chapter and the “repoze.bfg.url” module API documentation for more information.

Backwards Incompatibilities

As a result of disusing Routes, using the Routes url_for API inside a BFG application (as was suggested by previous iterations of tutorials) will no longer work. Use the repoze.bfg.url.route_url method instead.

The following attributes on the <route> ZCML directive no longer work: encoding, static, filter, condition_method, condition_subdomain, condition_function, explicit, or subdomains. These were all Routes features.

The <route> ZCML directive no longer supports the <requirement> subdirective. This was a Routes feature.

1.0a2 (2009-06-23)

Bug Fixes

The bfg_routesalchemy paster template app tests failed due to a mismatch between test and view signatures.

Features

Add a view_for attribute to the route ZCML directive. This attribute should refer to an interface or a class (ala the for attribute of the view ZCML directive).

Documentation

Conditional documentation in installation section (“how to install a Python interpreter”).

Backwards Incompatibilities

The callback argument of the repoze.bfg.authentication authentication policies named RepozeWho1AuthenticationPolicy, RemoteUserAuthenticationPolicy, and AuthTktAuthenticationPolicy now must accept two positional arguments: the orginal argument accepted by each (userid or identity) plus a second argument, which will be the current request. Apologies, this is required to service finding groups when there is no “global” database connection.

1.0a1 (2009-06-22)

Features

A new ZCML directive was added named notfound. This ZCML directive can be used to name a view that should be invoked when the request can’t otherwise be resolved to a view callable. For example:

<notfound
    view="helloworld.views.notfound_view"/>

A new ZCML directive was added named forbidden. This ZCML directive can be used to name a view that should be invoked when a view callable for a request is found, but cannot be invoked due to an authorization failure. For example:

<forbidden
    view="helloworld.views.forbidden_view"/>

Allow views to be optionally defined as callables that accept only a request object, instead of both a context and a request (which still works, and always will). The following types work as views in this style:

functions that accept a single argument request, e.g.:

def aview(request):
    pass

new and old-style classes that have an __init__ method that accepts self, request, e.g.:

def View(object):
    __init__(self, request):
       pass

Arbitrary callables that have a __call__ method that accepts self, request, e.g.:

def AView(object):
    def __call__(self, request):
       pass
view = AView()

This likely should have been the calling convention all along, as the request has context as an attribute already, and with views called as a result of URL dispatch, having the context in the arguments is not very useful. C’est la vie.

Cache the absolute path in the caller’s package globals within repoze.bfg.path to get rid of repeated (expensive) calls to os.path.abspath.

Add reissue_time and timeout parameters to repoze.bfg.authentication.AuthTktAuthenticationPolicy constructor. If these are passed, cookies will be reset every so often (cadged from the same change to repoze.who lately).

The matchdict related to the matching of a Routes route is available on the request as the matchdict attribute: request.matchdict. If no route matched, this attribute will be None.

Make 404 responses slightly cheaper by showing environ["PATH_INFO"] on the notfound result page rather than the fullly computed URL.

Move LRU cache implementation into a separate package (repoze.lru).

The concepts of traversal and URL dispatch have been unified. It is now possible to use the same sort of factory as both a traversal “root factory” and what used to be referred to as a urldispatch “context factory”.

When the root factory argument (as a first argument) passed to repoze.bfg.router.make_app is None, a default root factory is used. This is in support of using routes as “root finders”; it supplants the idea that there is a default IRoutesContextFactory.

The view` ZCML statement and the repoze.bfg.view.bfg_view decorator now accept an extra argument: route_name. If a route_name is specified, it must match the name of a previously defined route statement. When it is specified, the view will only be called when that route matches during a request.

It is now possible to perfom traversal after a route has matched. Use the pattern *traverse in a <route> path attribute within ZCML, and the path remainder which it matches will be used as a traversal path.

When any route defined matches, the WSGI environment will now contain a key bfg.routes.route (the Route object which matched), and a key bfg.routes.matchdict (the result of calling route.match).

Deprecations

Utility registrations against repoze.bfg.interfaces.INotFoundView and repoze.bfg.interfaces.IForbiddenView are now deprecated. Use the notfound and forbidden ZCML directives instead (see the “Hooks” chapter for more information). Such registrations will continue to work, but the notfound and forbidden directives do “extra work” to ensure that the callable named by the directive can be called by the router even if it’s a class or request-argument-only view.

Removals

The IRoutesContext, IRoutesContextFactory, and IContextNotFound interfaces were removed from repoze.bfg.interfaces. These were never APIs.

The repoze.bfg.urldispatch.RoutesContextNotFound, repoze.bfg.urldispatch.RoutesModelTraverser and repoze.bfg.urldispatch.RoutesContextURL classes were removed. These were also never APIs.

Backwards Incompatibilities

Moved the repoze.bfg.push module, which implemented the pushpage decorator, into a separate distribution, repoze.bfg.pushpage. Applications which used this decorator should continue to work after adding that distribution to their installation requirements.

Changing the default request factory via an IRequestFactory utility registration (as used to be documented in the “Hooks” chapter’s “Changing the request factory” section) is no longer supported. The dance to manufacture a request is complicated as a result of unifying traversal and url dispatch, making it highly unlikely for anyone to be able to override it properly. For those who just want to decorate or modify a request, use a NewRequestEvent subscriber (see the Events chapter in the documentation).

The repoze.bfg.IRequestFactory interface was removed. See the bullet above for why.

Routes “context factories” (spelled as the factory argument to a route statement in ZCML) must now expect the WSGI environ as a single argument rather than a set of keyword arguments. They can obtain the match dictionary by asking for environ[‘bfg.routes.matchdict’]. This is the same set of keywords that used to be passed to urldispatch “context factories” in BFG 0.9 and below.

Using the @zope.component.adapter decorator on a bfg view function no longer works. Use the @repoze.bfg.view.bfg_view decorator instead to mark a function (or a class) as a view.

The name under which the matching route object is found in the environ was changed from bfg.route to bfg.routes.route.

Finding the root is now done before manufacturing a request object (and sending a new request event) within the router (it used to be performed afterwards).

Adding *path_info to a route no longer changes the PATH_INFO for a request that matches using URL dispatch. This feature was only there to service the repoze.bfg.wsgi.wsgiapp2 decorator and it did it wrong; use *subpath instead now.

The values of subpath, traversed, and virtual_root_path attached to the request object are always now tuples instead of lists (performance).

Bug Fixes

The bfg_alchemy Paster template named “repoze.tm” in its pipeline rather than “repoze.tm2”, causing the startup to fail.

Move BBB logic for registering an IAuthenticationPolicy/IForbiddenView/INotFoundView based on older concepts from the router module’s make_app function into the repoze.bfg.zcml.zcml_configure callable, to service compatibility with scripts that use “zope.configuration.xmlconfig” (replace with repoze.bfg.zml.zcml_configure as necessary to get BBB logic)

Documentation

Add interface docs related to how to create authentication policies and authorization policies to the “Security” narrative chapter.

Added a (fairly sad) “Combining Traversal and URL Dispatch” chapter to the narrative documentation. This explains the usage of *traverse and *subpath in routes URL patters.

A “router” chapter explaining the request/response lifecycle at a high level was added.

Replaced all mentions and explanations of a routes “context factory” with equivalent explanations of a “root factory” (context factories have been disused).

Updated Routes bfgwiki2 tutorial to reflect the fact that context factories are now no longer used.

0.9.1 (2009-06-02)

Features

Add API named repoze.bfg.settings.get_settings which retrieves a derivation of values passed as the options value of repoze.bfg.router.make_app. This API should be preferred instead of using getUtility(ISettings). I added a new repoze.bfg.settings API document as well.

Bug Fixes

Restored missing entry point declaration for bfg_alchemy paster template, which was accidentally removed in 0.9.

Documentation

Fix a reference to wsgiapp in the wsgiapp2 API documentation within the repoze.bfg.wsgi module.

API Removals

The repoze.bfg.location.locate API was removed: it didn’t do enough to be very helpful and had a misleading name.

0.9 (2009-06-01)

Bug Fixes

It was not possible to register a custom IRoutesContextFactory for use as a default context factory as documented in the “Hooks” chapter.

Features

The request_type argument of ZCML view declarations and bfg_view decorators can now be one of the strings GET, POST, PUT, DELETE, or HEAD instead of a reference to the respective interface type imported from repoze.bfg.interfaces.

The route ZCML directive now accepts request_type as an alias for its condition_method argument for symmetry with the view directive.

The bfg_routesalchemy paster template now provides a unit test and actually uses the database during a view rendering.

Removals

Remove repoze.bfg.threadlocal.setManager. It was only used in unit tests.

Remove repoze.bfg.wsgi.HTTPException, repoze.bfg.wsgi.NotFound, and repoze.bfg.wsgi.Unauthorized. These classes were disused with the introduction of the IUnauthorizedView and INotFoundView machinery.

Documentation

Add description to narrative templating chapter about how to use Chameleon text templates.

Changed Views narrative chapter to use method strings rather than interface types, and moved advanced interface type usage to Events narrative chapter.

Added a Routes+SQLAlchemy wiki tutorial.

0.9a8 (2009-05-31)

Features

It is now possible to register a custom repoze.bfg.interfaces.INotFoundView for a given application. This feature replaces the repoze.bfg.interfaces.INotFoundAppFactory feature previously described in the Hooks chapter. The INotFoundView will be called when the framework detects that a view lookup done as a result of a request fails; it should accept a context object and a request object; it should return an IResponse object (a webob response, basically). See the Hooks narrative chapter of the BFG docs for more info.

The error presented when a view invoked by the router returns a non-response object now includes the view’s name for troubleshooting purposes.

Bug Fixes

A “new response” event is emitted for forbidden and notfound views.

Deprecations

The repoze.bfg.interfaces.INotFoundAppFactory interface has been deprecated in favor of using the new repoze.bfg.interfaces.INotFoundView mechanism.

Renames

Renamed repoze.bfg.interfaces.IForbiddenResponseFactory to repoze.bfg.interfaces.IForbiddenView.

0.9a7 (2009-05-30)

Features

Remove “context” argument from effective_principals and authenticated_userid function APIs in repoze.bfg.security, effectively a doing reversion to 0.8 and before behavior. Both functions now again accept only the request parameter.

0.9a6 (2009-05-29)

Documentation

Changed “BFG Wiki” tutorial to use AuthTktAuthenticationPolicy rather than repoze.who.

Features

Add an AuthTktAuthenticationPolicy. This policy retrieves credentials from an auth_tkt cookie managed by the application itself (instead of relying on an upstream data source for authentication data). See the Security API chapter of the documentation for more info.

Allow RemoteUserAuthenticationPolicy and RepozeWho1AuthenticationPolicy to accept various constructor arguments. See the Security API chapter of the documentation for more info.

0.9a5 (2009-05-28)

Features

Add a get_app API functions to the paster module. This obtains a WSGI application from a config file given a config file name and a section name. See the repoze.bfg.paster API docs for more information.

Add a new module named scripting. It contains a get_root API function, which, provided a Router instance, returns a traversal root object and a “closer”. See the repoze.bfg.scripting API docs for more info.

0.9a4 (2009-05-27)

Bug Fixes

Try checking for an “old style” security policy after we parse ZCML (thinko).

0.9a3 (2009-05-27)

Features

Allow IAuthenticationPolicy and IAuthorizationPolicy to be overridden via ZCML registrations (do ZCML parsing after registering these in router.py).

Documentation

Added “BFG Wiki” tutorial to documentation; it describes step-by-step how to create a traversal-based ZODB application with authentication.

Deprecations

Added deprecations for imports of ACLSecurityPolicy, InheritingACLSecurityPolicy, RemoteUserACLSecurityPolicy, RemoteUserInheritingACLSecurityPolicy, WhoACLSecurityPolicy, and WhoInheritingACLSecurityPolicy from the repoze.bfg.security module; for the meantime (for backwards compatibility purposes) these live in the repoze.bfg.secpols module. Note however, that the entire concept of a “security policy” is deprecated in BFG in favor of separate authentication and authorization policies, so any use of a security policy will generate additional deprecation warnings even if you do start using repoze.bfg.secpols. repoze.bfg.secpols will disappear in a future release of repoze.bfg.

Deprecated Import Alias Removals

Remove repoze.bfg.template module. All imports from this package have been deprecated since 0.3.8. Instead, import get_template, render_template, and render_template_to_response from the repoze.bfg.chameleon_zpt module.

Remove backwards compatibility import alias for repoze.bfg.traversal.split_path (deprecated since 0.6.5). This must now be imported as repoze.bfg.traversal.traversal_path).

Remove backwards compatibility import alias for repoze.bfg.urldispatch.RoutesContext (deprecated since 0.6.5). This must now be imported as repoze.bfg.urldispatch.DefaultRoutesContext.

Removed backwards compatibility import aliases for repoze.bfg.router.get_options and repoze.bfg.router.Settings (deprecated since 0.6.2). These both must now be imported from repoze.bfg.settings.

Removed backwards compatibility import alias for repoze.bfg.interfaces.IRootPolicy (deprecated since 0.6.2). It must be imported as repoze.bfg.interfaces.IRootFactory now.

Removed backwards compatibility import alias for repoze.bfg.interfaces.ITemplate (deprecated since 0.4.4). It must be imported as repoze.bfg.interfaces.ITemplateRenderer now.

Removed backwards compatibility import alias for repoze.bfg.interfaces.ITemplateFactory (deprecated since 0.4.4). It must be imported as repoze.bfg.interfaces.ITemplateRendererFactory now.

Removed backwards compatibility import alias for repoze.bfg.chameleon_zpt.ZPTTemplateFactory (deprecated since 0.4.4). This must be imported as repoze.bfg.ZPTTemplateRenderer now.

0.9a2 (2009-05-27)

Features

A paster command has been added named “bfgshell”. This command can be used to get an interactive prompt with your BFG root object in the global namespace. E.g.:

bin/paster bfgshell /path/to/myapp.ini myapp

See the Project chapter in the BFG documentation for more information.

Deprecations

The name repoze.bfg.registry.registry_manager was never an API, but scripts in the wild were using it to set up an environment for use under a debug shell. A backwards compatibility shim has been added for this purpose, but the feature is deprecated.

0.9a1 (2009-5-27)

Features

New API functions named forget and remember are available in the security module. The forget function returns headers which will cause the currently authenticated user to be logged out when set in a response. The remember function (when passed the proper arguments) will return headers which will cause a principal to be “logged in” when set in a response. See the Security API chapter of the docs for more info.

New keyword arguments to the repoze.bfg.router.make_app call have been added: authentication_policy and authorization_policy. These should, respectively, be an implementation of an authentication policy (an object implementing the repoze.bfg.interfaces.IAuthenticationPolicy interface) and an implementation of an authorization policy (an object implementing repoze.bfg.interfaces.IAuthorizationPolicy). Concrete implementations of authentication policies exist in repoze.bfg.authentication. Concrete implementations of authorization policies exist in repoze.bfg.authorization.

Both authentication_policy and authorization_policy default to None.

If authentication_policy is None, but authorization_policy is not None, then authorization_policy is ignored (the ability to do authorization depends on authentication).

If the authentication_policy argument is not None, and the authorization_policy argument is None, the authorization policy defaults to an authorization implementation that uses ACLs (repoze.bfg.authorization.ACLAuthorizationPolicy).

We no longer encourage configuration of “security policies” using ZCML, as previously we did for ISecurityPolicy. This is because it’s not uncommon to need to configure settings for concrete authorization or authentication policies using paste .ini parameters; the app entry point for your application is the natural place to do this.

Two new abstractions have been added in the way of adapters used by the system: an IAuthorizationPolicy and an IAuthenticationPolicy. A combination of these (as registered by the securitypolicy ZCML directive) take the place of the ISecurityPolicy abstraction in previous releases of repoze.who. The API functions in repoze.who.security (such as authentication_userid, effective_principals, has_permission, and so on) have been changed to try to make use of these new adapters. If you’re using an older ISecurityPolicy adapter, the system will still work, but it will print deprecation warnings when such a policy is used.

The way the (internal) IViewPermission utilities registered via ZCML are invoked has changed. They are purely adapters now, returning a boolean result, rather than returning a callable. You shouldn’t have been using these anyway. ;-)

New concrete implementations of IAuthenticationPolicy have been added to the repoze.bfg.authentication module: RepozeWho1AuthenticationPolicy which uses repoze.who identity to retrieve authentication data from and RemoteUserAuthenticationPolicy, which uses the REMOTE_USER value in the WSGI environment to retrieve authentication data.

A new concrete implementation of IAuthorizationPolicy has been added to the repoze.bfg.authorization module: ACLAuthorizationPolicy which uses ACL inheritance to do authorization.

It is now possible to register a custom repoze.bfg.interfaces.IForbiddenResponseFactory for a given application. This feature replaces the repoze.bfg.interfaces.IUnauthorizedAppFactory feature previously described in the Hooks chapter. The IForbiddenResponseFactory will be called when the framework detects an authorization failure; it should accept a context object and a request object; it should return an IResponse object (a webob response, basically). Read the below point for more info and see the Hooks narrative chapter of the BFG docs for more info.

Backwards Incompatibilities

Custom NotFound and Forbidden (nee’ Unauthorized) WSGI applications (registered as a utility for INotFoundAppFactory and IUnauthorizedAppFactory) could rely on an environment key named message describing the circumstance of the response. This key has been renamed to repoze.bfg.message (as per the WSGI spec, which requires environment extensions to contain dots).

Deprecations

The repoze.bfg.interfaces.IUnauthorizedAppFactory interface has been deprecated in favor of using the new repoze.bfg.interfaces.IForbiddenResponseFactory mechanism.

The view_execution_permitted API should now be imported from the repoze.bfg.security module instead of the repoze.bfg.view module.

The authenticated_userid and effective_principals APIs in repoze.bfg.security used to only take a single argument (request). They now accept two arguments (context and request). Calling them with a single argument is still supported but issues a deprecation warning. (NOTE: this change was reverted in 0.9a7; meaning the 0.9 versions of these functions again accept request only, just like 0.8 and before).

Use of “old-style” security policies (those base on ISecurityPolicy) is now deprecated. See the “Security” chapter of the docs for info about activating an authorization policy and an authentication poicy.

0.8.1 (2009-05-21)

Features

Class objects may now be used as view callables (both via ZCML and via use of the bfg_view decorator in Python 2.6 as a class decorator). The calling semantics when using a class as a view callable is similar to that of using a class as a Zope “browser view”: the class’ __init__ must accept two positional parameters (conventionally named context, and request). The resulting instance must be callable (it must have a __call__ method). When called, the instance should return a response. For example:

 from webob import Response

 class MyView(object):
     def __init__(self, context, request):
         self.context = context
         self.request = request

     def __call__(self):
         return Response('hello from %s!' % self.context)

See the "Views" chapter in the documentation and the
``repoze.bfg.view`` API documentation for more information.

Removed the pickling of ZCML actions (the code that wrote configure.zcml.cache next to configure.zcml files in projects). The code which managed writing and reading of the cache file was a source of subtle bugs when users switched between imperative (e.g. @bfg_view) registrations and declarative registrations (e.g. the view directive in ZCML) on the same project. On a moderately-sized project (535 ZCML actions and 15 ZCML files), executing actions read from the pickle was saving us only about 200ms (2.5 sec vs 2.7 sec average). On very small projects (1 ZCML file and 4 actions), startup time was comparable, and sometimes even slower when reading from the pickle, and both ways were so fast that it really just didn’t matter anyway.

0.8 (2009-05-18)

Features

Added a traverse function to the repoze.bfg.traversal module. This function may be used to retrieve certain values computed during path resolution. See the Traversal API chapter of the documentation for more information about this function.

Deprecations

Internal: ITraverser callables should now return a dictionary rather than a tuple. Up until 0.7.0, all ITraversers were assumed to return a 3-tuple. In 0.7.1, ITraversers were assumed to return a 6-tuple. As (by evidence) it’s likely we’ll need to add further information to the return value of an ITraverser callable, 0.8 assumes that an ITraverser return a dictionary with certain elements in it. See the repoze.bfg.interfaces.ITraverser interface for the list of keys that should be present in the dictionary. ITraversers which return tuples will still work, although a deprecation warning will be issued.

Backwards Incompatibilities

If your code used the ITraverser interface directly (not via an API function such as find_model) via an adapter lookup, you’ll need to change your code to expect a dictionary rather than a 3- or 6-tuple if your code ever gets return values from the default ModelGraphTraverser or RoutesModelTraverser adapters.

0.8a7 (2009-05-16)

Backwards Incompatibilities

The RoutesMapper class in repoze.bfg.urldispatch has been removed, as well as its documentation. It had been deprecated since 0.6.3. Code in repoze.bfg.urldispatch.RoutesModelTraverser which catered to it has also been removed.

The semantics of the route ZCML directive have been simplified. Previously, it was assumed that to use a route, you wanted to map a route to an externally registered view. The new route directive instead has a view attribute which is required, specifying the dotted path to a view callable. When a route directive is processed, a view is registered using the name attribute of the route directive as its name and the callable as its value. The view_name and provides attributes of the route directive are therefore no longer used. Effectively, if you were previously using the route directive, it means you must change a pair of ZCML directives that look like this:

<route
   name="home"
   path=""
   view_name="login"
   factory=".models.root.Root"
 />

<view
   for=".models.root.Root"
   name="login"
   view=".views.login_view"
 />

To a ZCML directive that looks like this:

<route
   name="home"
   path=""
   view=".views.login_view"
   factory=".models.root.Root"
 />

In other words, to make old code work, remove the view directives that were only there to serve the purpose of backing route directives, and move their view= attribute into the route directive itself.

This change also necessitated that the name attribute of the route directive is now required. If you were previously using route directives without a name attribute, you’ll need to add one (the name is arbitrary, but must be unique among all route and view statements).

The provides attribute of the route directive has also been removed. This directive specified a sequence of interface types that the generated context would be decorated with. Since route views are always generated now for a single interface (repoze.bfg.IRoutesContext) as opposed to being looked up arbitrarily, there is no need to decorate any context to ensure a view is found.

Documentation

Added API docs for the repoze.bfg.testing methods registerAdapter, registerUtiity, registerSubscriber, and cleanUp.

Added glossary entry for “root factory”.

Noted existence of repoze.bfg.pagetemplate template bindings in “Available Add On Template System Bindings” in Templates chapter in narrative docs.

Update “Templates” narrative chapter in docs (expand to show a sample template and correct macro example).

Features

Courtesty Carlos de la Guardia, added an alchemy Paster template. This paster template sets up a BFG project that uses SQAlchemy (with SQLite) and uses traversal to resolve URLs. (no Routes areused). This template can be used via paster create -t bfg_alchemy.

The Routes Route object used to resolve the match is now put into the environment as bfg.route when URL dispatch is used.

You can now change the default Routes “context factory” globally. See the “ZCML Hooks” chapter of the documentation (in the “Changing the Default Routes Context Factory” section).

0.8a6 (2009-05-11)

Features

Added a routesalchemy Paster template. This paster template sets up a BFG project that uses SQAlchemy (with SQLite) and uses Routes exclusively to resolve URLs (no traversal root factory is used). This template can be used via paster create -t bfg_routesalchemy.

Documentation

Added documentation to the URL Dispatch chapter about how to catch the root URL using a ZCML route directive.

Added documentation to the URL Dispatch chapter about how to perform a cleanup function at the end of a request (e.g. close the SQL connection).

Bug Fixes

In version 0.6.3, passing a get_root callback (a “root factory”) to repoze.bfg.router.make_app became optional if any route declaration was made in ZCML. The intent was to make it possible to disuse traversal entirely, instead relying entirely on URL dispatch (Routes) to resolve all contexts. However a compound set of bugs prevented usage of a Routes-based root view (a view which responds to “/”). One bug existed in repoze.bfg.urldispatch`, another existed in Routes itself.

To resolve this issue, the urldispatch module was fixed, and a fork of the Routes trunk was put into the “dev” index named Routes-1.11dev-chrism-home. The source for the fork exists at http://bitbucket.org/chrism/routes-home/; its contents have been merged into the Routes trunk (what will be Routes 1.11).

0.8a5 (2009-05-08)

Features

Two new security policies were added: RemoteUserInheritingACLSecurityPolicy and WhoInheritingACLSecurityPolicy. These are security policies which take into account all ACLs defined in the lineage of a context rather than stopping at the first ACL found in a lineage. See the “Security” chapter of the API documentation for more information.

The API and narrative documentation dealing with security was changed to introduce the new “inheriting” security policy variants.

Added glossary entry for “lineage”.

Deprecations

The security policy previously named RepozeWhoIdentityACLSecurityPolicy now has the slightly saner name of WhoACLSecurityPolicy. A deprecation warning is emitted when this policy is imported under the “old” name; usually this is due to its use in ZCML within your application. If you’re getting this deprecation warning, change your ZCML to use the new name, e.g. change:

<utility
  provides="repoze.bfg.interfaces.ISecurityPolicy"
  factory="repoze.bfg.security.RepozeWhoIdentityACLSecurityPolicy"
  />

To:

<utility
  provides="repoze.bfg.interfaces.ISecurityPolicy"
  factory="repoze.bfg.security.WhoACLSecurityPolicy"
  />

0.8a4 (2009-05-04)

Features

zope.testing is no longer a direct dependency, although our dependencies (such as zope.interface, repoze.zcml, etc) still depend on it.

Tested on Google App Engine. Added a tutorial to the documentation explaining how to deploy a BFG app to GAE.

Backwards Incompatibilities

Applications which rely on zope.testing.cleanup.cleanUp in unit tests can still use that function indefinitely. However, for maximum forward compatibility, they should import cleanUp from repoze.bfg.testing instead of from zope.testing.cleanup. The BFG paster templates and docs have been changed to use this function instead of the zope.testing.cleanup version.

0.8a3 (2009-05-03)

Features

Don’t require a successful import of zope.testing at BFG application runtime. This allows us to get rid of zope.testing on platforms like GAE which have file limits.

0.8a2 (2009-05-02)

Features

We no longer include the configure.zcml of the chameleon.zpt package within the configure.zcml of the “repoze.bfg.includes” package. This has been a no-op for some time now.

The repoze.bfg.chameleon_zpt package no longer imports from chameleon.zpt at module scope, deferring the import until later within a method call. The chameleon.zpt package can’t be imported on platforms like GAE.

0.8a1 (2009-05-02)

Deprecation Warning and Import Alias Removals

Since version 0.6.1, a deprecation warning has been emitted when the name model_url is imported from the repoze.bfg.traversal module. This import alias (and the deprecation warning) has been removed. Any import of the model_url function will now need to be done from repoze.bfg.url; any import of the name model_url from repoze.bfg.traversal will now fail. This was done to remove a dependency on zope.deferredimport.

Since version 0.6.5, a deprecation warning has been emitted when the name RoutesModelTraverser is imported from the repoze.bfg.traversal module. This import alias (and the deprecation warning) has been removed. Any import of the RoutesModelTraverser class will now need to be done from repoze.bfg.urldispatch; any import of the name RoutesModelTraverser from repoze.bfg.traversal will now fail. This was done to remove a dependency on zope.deferredimport.

Features

This release of repoze.bfg is “C-free”. This means it has no hard dependencies on any software that must be compiled from C source at installation time. In particular, repoze.bfg no longer depends on the lxml package.

This change has introduced some backwards incompatibilities, described in the “Backwards Incompatibilities” section below.

This release was tested on Windows XP. It appears to work fine and all the tests pass.

Backwards Incompatibilities

Incompatibilities related to making repoze.bfg “C-free”:

Removed the repoze.bfg.chameleon_genshi module, and thus support for Genshi-style chameleon templates. Genshi-style Chameleon templates depend upon lxml, which is implemented in C (as opposed to pure Python) and the repoze.bfg core is “C-free” as of this release. You may get Genshi-style Chameleon support back by installing the repoze.bfg.chameleon_genshi package availalable from http://svn.repoze.org/repoze.bfg.chameleon_genshi (also available in the index at http://dist.repoze.org/bfg/0.8/simple). All existing code that depended on the chameleon_genshi module prior to this release of repoze.bfg should work without change after this addon is installed.

Removed the repoze.bfg.xslt module and thus support for XSL templates. The repoze.bfg.xslt module depended upon lxml, which is implemented in C, and the repoze.bfg core is “C-free” as of this release. You bay get XSL templating back by installing the repoze.bfg.xslt package available from http://svn.repoze.org/repoze.bfg.xslt/ (also available in the index at http://dist.repoze.org/bfg/0.8/simple). All existing code that depended upon the xslt module prior to this release of repoze.bfg should work without modification after this addon is installed.

Removed the repoze.bfg.interfaces.INodeTemplateRenderer interface and the an old b/w compat aliases from that interface to repoze.bfg.interfaces.INodeTemplate. This interface must now be imported from the repoze.bfg.xslt.interfaces package after installation of the repoze.bfg.xslt addon package described above as repoze.bfg.interfaces.INodeTemplateRenderer. This interface was never part of any public API.

Other backwards incompatibilities:

The render_template function in repoze.bfg.chameleon_zpt returns Unicode instead of a string. Likewise, the individual values returned by the iterable created by the render_template_to_iterable function are also each Unicode. This is actually a backwards incompatibility inherited from our new use of the combination of chameleon.core 1.0b32 (the non-lxml-depending version) and chameleon.zpt 1.0b16+ ; the chameleon.zpt PageTemplateFile implementation used to return a string, but now returns Unicode.

0.7.1 (2009-05-01)

Index-Related

The canonical package index location for repoze.bfg has changed. The “old” index (http://dist.repoze.org/lemonade/dev/simple) has been superseded by a new index location (http://dist.repoze.org/bfg/current/simple). The installation documentation has been updated as well as the setup.cfg file in this package. The “lemonade” index still exists, but it is not guaranteed to have the latest BFG software in it, nor will it be maintained in the future.

Features

The “paster create” templates have been modified to use links to the new “bfg.repoze.org” and “docs.repoze.org” websites.

Added better documentation for virtual hosting at a URL prefix within the virtual hosting docs chapter.

The interface for repoze.bfg.interfaces.ITraverser and the built-in implementations that implement the interface (repoze.bfg.traversal.ModelGraphTraverser, and repoze.bfg.urldispatch.RoutesModelTraverser) now expect the __call__ method of an ITraverser to return 3 additional arguments: traversed, virtual_root, and virtual_root_path (the old contract was that the __call__ method of an ITraverser returned; three arguments, the contract new is that it returns six). traversed will be a sequence of Unicode names that were traversed (including the virtual root path, if any) or None if no traversal was performed, virtual_root will be a model object representing the virtual root (or the physical root if traversal was not performed), and virtual_root_path will be a sequence representing the virtual root path (a sequence of Unicode names) or None if traversal was not performed.

Six arguments are now returned from BFG ITraversers. They are returned in this order: context, view_name, subpath, traversed, virtual_root, and virtual_root_path.

Places in the BFG code which called an ITraverser continue to accept a 3-argument return value, although BFG will generate and log a warning when one is encountered.

The request object now has the following attributes: traversed (the sequence of names traversed or None if traversal was not performed), virtual_root (the model object representing the virtual root, including the virtual root path if any), and virtual_root_path (the seuquence of names representing the virtual root path or None if traversal was not performed).

A new decorator named wsgiapp2 was added to the repoze.bfg.wsgi module. This decorator performs the same function as repoze.bfg.wsgi.wsgiapp except it fixes up the SCRIPT_NAME, and PATH_INFO environment values before invoking the WSGI subapplication.

The repoze.bfg.testing.DummyRequest object now has default attributes for traversed, virtual_root, and virtual_root_path.

The RoutesModelTraverser now behaves more like the Routes “RoutesMiddleware” object when an element in the match dict is named path_info (usually when there’s a pattern like http://foo/*path_info). When this is the case, the PATH_INFO environment variable is set to the value in the match dict, and the SCRIPT_NAME is appended to with the prefix of the original PATH_INFO not including the value of the new variable.

The notfound debug now shows the traversed path, the virtual root, and the virtual root path too.

Speed up / clarify ‘traversal’ module’s ‘model_path’, ‘model_path_tuple’, and ‘_model_path_list’ functions.

Backwards Incompatibilities

In previous releases, the repoze.bfg.url.model_url, repoze.bfg.traversal.model_path and repoze.bfg.traversal.model_path_tuple functions always ignored the __name__ argument of the root object in a model graph ( effectively replacing it with a leading / in the returned value) when a path or URL was generated. The code required to perform this operation was not efficient. As of this release, the root object in a model graph must have a __name__ attribute that is either None or the empty string ('') for URLs and paths to be generated properly from these APIs. If your root model object has a __name__ argument that is not one of these values, you will need to change your code for URLs and paths to be generated properly. If your model graph has a root node with a string __name__ that is not null, the value of __name__ will be prepended to every path and URL generated.

The repoze.bfg.location.LocationProxy class and the repoze.bfg.location.ClassAndInstanceDescr class have both been removed in order to be able to eventually shed a dependency on zope.proxy. Neither of these classes was ever an API.

In all previous releases, the repoze.bfg.location.locate function worked like so: if a model did not explicitly provide the repoze.bfg.interfaces.ILocation interface, locate returned a LocationProxy object representing model with its __parent__ attribute assigned to parent and a __name__ attribute assigned to __name__. In this release, the repoze.bfg.location.locate function simply jams the __name__ and __parent__ attributes on to the supplied model unconditionally, no matter if the object implements ILocation or not, and it never returns a proxy. This was done because the LocationProxy behavior has now moved into an add-on package (repoze.bfg.traversalwrapper), in order to eventually be able to shed a dependency on zope.proxy.

In all previous releases, by default, if traversal was used (as opposed to URL-dispatch), and the root object supplied the``repoze.bfg.interfaces.ILocation`` interface, but the children returned via its __getitem__ returned an object that did not implement the same interface, repoze.bfg provided some implicit help during traversal. This traversal feature wrapped subobjects from the root (and thereafter) that did not implement ILocation in proxies which automatically provided them with a __name__ and __parent__ attribute based on the name being traversed and the previous object traversed. This feature has now been removed from the base repoze.bfg package for purposes of eventually shedding a dependency on zope.proxy.

In order to re-enable the wrapper behavior for older applications which cannot be changed, register the “traversalwrapper” ModelGraphTraverser as the traversal policy, rather than the default ModelGraphTraverser. To use this feature, you will need to install the repoze.bfg.traversalwrapper package (an add-on package, available at http://svn.repoze.org/repoze.bfg.traversalwrapper) Then change your application’s configure.zcml to include the following stanza:

<adapter

factory=”repoze.bfg.traversalwrapper.ModelGraphTraverser” provides=”repoze.bfg.interfaces.ITraverserFactory” for=”*” />

When this ITraverserFactory is used instead of the default, no object in the graph (even the root object) must supply a __name__ or __parent__ attribute. Even if subobjects returned from the root do implement the ILocation interface, these will still be wrapped in proxies that override the object’s “real” __parent__ and __name__ attributes.

See also changes to the “Models” chapter of the documentation (in the “Location-Aware Model Instances”) section.

0.7.0 (2009-04-11)

Bug Fixes

Fix a bug in repoze.bfg.wsgi.HTTPException: the content length was returned as an int rather than as a string.

Add explicit dependencies on zope.deferredimport, zope.deprecation, and zope.proxy for forward compatibility reasons (zope.component will stop relying on zope.deferredimport soon and although we use it directly, it’s only a transitive dependency, and ‘’zope.deprecation`` and zope.proxy are used directly even though they’re only transitive dependencies as well).

Using model_url or model_path against a broken model graph (one with models that had a non-root model with a __name__ of None) caused an inscrutable error to be thrown: ( if not _must_quote[cachekey].search(s): TypeError: expected string or buffer). Now URLs and paths generated against graphs that have None names in intermediate nodes will replace the None with the empty string, and, as a result, the error won’t be raised. Of course the URL or path will still be bogus.

Features

Make it possible to have testing.DummyTemplateRenderer return some nondefault string representation.

Added a new anchor keyword argument to model_url. If anchor is present, its string representation will be used as a named anchor in the generated URL (e.g. if anchor is passed as foo and the model URL is http://example.com/model/url, the generated URL will be http://example.com/model/url#foo).

Backwards Incompatibilities

The default request charset encoding is now utf-8. As a result, the request machinery will attempt to decode values from the utf-8 encoding to Unicode automatically when they are obtained via request.params, request.GET, and request.POST. The previous behavior of BFG was to return a bytestring when a value was accessed in this manner. This change will break form handling code in apps that rely on values from those APIs being considered bytestrings. If you are manually decoding values from form submissions in your application, you’ll either need to change the code that does that to expect Unicode values from request.params, request.GET and request.POST, or you’ll need to explicitly reenable the previous behavior. To reenable the previous behavior, add the following to your application’s configure.zcml:

<subscriber for="repoze.bfg.interfaces.INewRequest"
            handler="repoze.bfg.request.make_request_ascii"/>

See also the documentation in the “Views” chapter of the BFG docs entitled “Using Views to Handle Form Submissions (Unicode and Character Set Issues)”.

Documentation

Add a section to the narrative Views chapter entitled “Using Views to Handle Form Submissions (Unicode and Character Set Issues)” explaining implicit decoding of form data values.

0.6.9 (2009-02-16)

Bug Fixes

lru cache was unstable under concurrency (big surprise!) when it tried to redelete a key in the cache that had already been deleted. Symptom: line 64 in put:del data[oldkey]:KeyError: ‘/some/path’. Now we just ignore the key error if we can’t delete the key (it has already been deleted).

Empty location names in model paths when generating a URL using repoze.bfg.model_url based on a model obtained via traversal are no longer ignored in the generated URL. This means that if a non-root model object has a __name__ of '', the URL will reflect it (e.g. model_url will generate http://foo/bar//baz if an object with the __name__ of '' is a child of bar and the parent of baz). URLs generated with empty path segments are, however, still irresolveable by the model graph traverser on request ingress (the traverser strips empty path segment names).

Features

Microspeedups of repoze.bfg.traversal.model_path, repoze.bfg.traversal.model_path_tuple, repoze.bfg.traversal.quote_path_segment, and repoze.bfg.url.urlencode.

add zip_safe = false to setup.cfg.

Documentation

Add a note to the repoze.bfg.traversal.quote_path_segment API docs about caching of computed values.

Implementation Changes

Simplification of repoze.bfg.traversal.TraversalContextURL.__call__ (it now uses repoze.bfg.traversal.model_path instead of rolling its own path-generation).

0.6.8 (2009-02-05)

Backwards Incompatibilities

The repoze.bfg.traversal.model_path API now returns a quoted string rather than a string represented by series of unquoted elements joined via / characters. Previously it returned a string or unicode object representing the model path, with each segment name in the path joined together via / characters, e.g. /foo /bar. Now it returns a string, where each segment is a UTF-8 encoded and URL-quoted element e.g. /foo%20/bar. This change was (as discussed briefly on the repoze-dev maillist) necessary to accomodate model objects which themselves have __name__ attributes that contain the / character.

For people that have no models that have high-order Unicode __name__ attributes or __name__ attributes with values that require URL-quoting with in their model graphs, this won’t cause any issue. However, if you have code that currently expects model_path to return an unquoted string, or you have an existing application with data generated via the old method, and you’re too lazy to change anything, you may wish replace the BFG-imported model_path in your code with this function (this is the code of the “old” model_path implementation):

from repoze.bfg.location import lineage

def i_am_too_lazy_to_move_to_the_new_model_path(model, *elements):
    rpath = []
    for location in lineage(model):
        if location.__name__:
            rpath.append(location.__name__)
    path = '/' + '/'.join(reversed(rpath))
    if elements:
        suffix = '/'.join(elements)
        path = '/'.join([path, suffix])
    return path

The repoze.bfg.traversal.find_model API no longer implicitly converts unicode representations of a full path passed to it as a Unicode object into a UTF-8 string. Callers should either use prequoted path strings returned by repoze.bfg.traversal.model_path, or tuple values returned by the result of repoze.bfg.traversal.model_path_tuple or they should use the guidelines about passing a string path argument described in the find_model API documentation.

Bugfixes

Each argument contained in elements passed to repoze.bfg.traversal.model_path will now have any / characters contained within quoted to %2F in the returned string. Previously, / characters in elements were left unquoted (a bug).

Features

A repoze.bfg.traversal.model_path_tuple API was added. This API is an alternative to model_path (which returns a string); model_path_tuple returns a model path as a tuple (much like Zope’s getPhysicalPath).

A repoze.bfg.traversal.quote_path_segment API was added. This API will quote an individual path segment (string or unicode object). See the repoze.bfg.traversal API documentation for more information.

The repoze.bfg.traversal.find_model API now accepts “path tuples” (see the above note regarding model_path_tuple) as well as string path representations (from repoze.bfg.traversal.model_path) as a path argument.

Add ` renderer` argument (defaulting to None) to repoze.bfg.testing.registerDummyRenderer. This makes it possible, for instance, to register a custom renderer that raises an exception in a unit test.

Implementation Changes

Moved _url_quote function back to repoze.bfg.traversal from repoze.bfg.url. This is not an API.

0.6.7 (2009-01-27)

Features

The repoze.bfg.url.model_url API now works against contexts derived from Routes URL dispatch (Routes.util.url_for is called under the hood).

“Virtual root” support for traversal-based applications has been added. Virtual root support is useful when you’d like to host some model in a repoze.bfg model graph as an application under a URL pathname that does not include the model path itself. For more information, see the (new) “Virtual Hosting” chapter in the documentation.

A repoze.bfg.traversal.virtual_root API has been added. When called, it returns the virtual root object (or the physical root object if no virtual root has been specified).

Implementation Changes

repoze.bfg.traversal.RoutesModelTraverser has been moved to repoze.bfg.urldispatch.

model_url URL generation is now performed via an adapter lookup based on the context and the request.

ZCML which registers two adapters for the IContextURL interface has been added to the configure.zcml in repoze.bfg.includes.

0.6.6 (2009-01-26)

Implementation Changes

There is an indirection in repoze.bfg.url.model_url now that consults a utility to generate the base model url (without extra elements or a query string). Eventually this will service virtual hosting; for now it’s undocumented and should not be hooked.

0.6.5 (2009-01-26)

Features

You can now override the NotFound and Unauthorized responses that repoze.bfg generates when a view cannot be found or cannot be invoked due to lack of permission. See the “ZCML Hooks” chapter in the docs for more information.

Added Routes ZCML directive attribute explanations in documentation.

Added a traversal_path API to the traversal module; see the “traversal” API chapter in the docs. This was a function previously known as split_path that was not an API but people were using it anyway. Unlike split_path, it now returns a tuple instead of a list (as its values are cached).

Behavior Changes

The repoze.bfg.view.render_view_to_response API will no longer raise a ValueError if an object returned by a view function it calls does not possess certain attributes (headerlist, app_iter, status). This API used to attempt to perform a check using the is_response function in repoze.bfg.view, and raised a ValueError if the is_response check failed. The responsibility is now the caller’s to ensure that the return value from a view function is a “real” response.

WSGI environ dicts passed to repoze.bfg ‘s Router must now contain a REQUEST_METHOD key/value; if they do not, a KeyError will be raised (speed).

It is no longer permissible to pass a “nested” list of principals to repoze.bfg.ACLAuthorizer.permits (e.g. ['fred', ['larry', 'bob']]). The principals list must be fully expanded. This feature was never documented, and was never an API, so it’s not a backwards incompatibility.

It is no longer permissible for a security ACE to contain a “nested” list of permissions (e.g. (Allow, Everyone, ['read', ['view', ['write', 'manage']]])`)`.  The list must instead be fully expanded (e.g. ``(Allow, Everyone, ['read', 'view', 'write', 'manage])). This feature was never documented, and was never an API, so it’s not a backwards incompatibility.

The repoze.bfg.urldispatch.RoutesRootFactory now injects the wsgiorg.routing_args environment variable into the environ when a route matches. This is a tuple of ((), routing_args) where routing_args is the value that comes back from the routes mapper match (the “match dict”).

The repoze.bfg.traversal.RoutesModelTraverser class now wants to obtain the view_name and subpath from the wsgiorgs.routing_args environment variable. It falls back to obtaining these from the context for backwards compatibility.

Implementation Changes

Get rid of repoze.bfg.security.ACLAuthorizer: the ACLSecurityPolicy now does what it did inline.

Get rid of repoze.bfg.interfaces.NoAuthorizationInformation exception: it was used only by ACLAuthorizer.

Use a homegrown NotFound error instead of webob.exc.HTTPNotFound (the latter is slow).

Use a homegrown Unauthorized error instead of webob.exc.Unauthorized (the latter is slow).

the repoze.bfg.lru.lru_cached decorator now uses functools.wraps in order to make documentation of LRU-cached functions possible.

Various speed micro-tweaks.

Bug Fixes

repoze.bfg.testing.DummyModel did not have a get method; it now does.

0.6.4 (2009-01-23)

Backwards Incompatibilities

The unicode_path_segments configuration variable and the BFG_UNICODE_PATH_SEGMENTS configuration variable have been removed. Path segments are now always passed to model __getitem__ methods as unicode. “True” has been the default for this setting since 0.5.4, but changing this configuration setting to false allowed you to go back to passing raw path element strings to model __getitem__ methods. Removal of this knob services a speed goal (we get about +80 req/s by removing the check), and it’s clearer just to always expect unicode path segments in model __getitem__ methods.

Implementation Changes

repoze.bfg.traversal.split_path now also handles decoding path segments to unicode (for speed, because its results are cached).

repoze.bfg.traversal.step was made a method of the

ModelGraphTraverser.

Use “precooked” Request subclasses (e.g. repoze.bfg.request.GETRequest) that correspond to HTTP request methods within router.py when constructing a request object rather than using alsoProvides to attach the proper interface to an unsubclassed webob.Request. This pattern is purely an optimization (e.g. preventing calls to alsoProvides means the difference between 590 r/s and 690 r/s on a MacBook 2GHz).

Tease out an extra 4% performance boost by changing the Router; instead of using imported ZCA APIs, use the same APIs directly against the registry that is an attribute of the Router.

The registry used by BFG is now a subclass of zope.component.registry.Components (defined as repoze.bfg.registry.Registry); it has a notify method, a registerSubscriptionAdapter and a registerHandler method. If no subscribers are registered via registerHandler or registerSubscriptionAdapter, notify is a noop for speed.

The Allowed and Denied classes in repoze.bfg.security now are lazier about constructing the representation of a reason message for speed; repoze.bfg.view_execution_permitted takes advantage of this.

The is_response check was sped up by about half at the expense of making its code slightly uglier.

New Modules

repoze.bfg.lru implements an LRU cache class and a decorator for internal use.

0.6.3 (2009-01-19)

Bug Fixes

Readd root_policy attribute on Router object (as a property which returns the IRootFactory utility). It was inadvertently removed in 0.6.2. Code in the wild depended upon its presence (esp. scripts and “debug” helpers).

Features

URL-dispatch has been overhauled: it is no longer necessary to manually create a RoutesMapper in your application’s entry point callable in order to use URL-dispatch (aka Routes [http://routes.groovie.org]). A new route directive has been added to the available list of ZCML directives. Each route directive inserted into your application’s configure.zcml establishes a Routes mapper connection. If any route declarations are made via ZCML within a particular application, the get_root callable passed in to repoze.bfg.router.make_app will automatically be wrapped in the equivalent of a RoutesMapper. Additionally, the new route directive allows the specification of a context_interfaces attribute for a route, this will be used to tag the manufactured routes context with specific interfaces when a route specifying a context_interfaces attribute is matched.

A new interface repoze.bfg.interfaces.IContextNotFound was added. This interface is attached to a “dummy” context generated when Routes cannot find a match and there is no “fallback” get_root callable that uses traversal.

The bfg_starter and bfg_zodb “paster create” templates now contain images and CSS which are displayed when the default page is displayed after initial project generation.

Allow the repoze.bfg.view.static helper to be passed a relative root_path name; it will be considered relative to the file in which it was called.

The functionality of repoze.bfg.convention has been merged into the core. Applications which make use of repoze.bfg.convention will continue to work indefinitely, but it is recommended that apps stop depending upon it. To do so, substitute imports of repoze.bfg.convention.bfg_view with imports of repoze.bfg.view.bfg_view, and change the stanza in ZCML from <convention package="."> to <scan package=".">. As a result of the merge, bfg has grown a new dependency: martian.

View functions which use the pushpage decorator are now pickleable (meaning their use won’t prevent a configure.zcml.cache file from being written to disk).

Instead of invariably using webob.Request as the “request factory” (e.g. in the Router class) and webob.Response and the “response factory” (e.g. in render_template_to_response), allow both to be overridden via a ZCML utility hook. See the “Using ZCML Hooks” chapter of the documentation for more information.

Deprecations

The class repoze.bfg.urldispatch.RoutesContext has been renamed to repoze.bfg.urldispatch.DefaultRoutesContext. The class should be imported by the new name as necessary (although in reality it probably shouldn’t be imported from anywhere except internally within BFG, as it’s not part of the API).

Implementation Changes

The repoze.bfg.wsgi.wsgiapp decorator now uses webob.Request.get_response to do its work rather than relying on homegrown WSGI code.

The repoze.bfg.view.static helper now uses webob.Request.get_response to do its work rather than relying on homegrown WSGI code.

The repoze.bfg.urldispatch.RoutesModelTraverser class has been moved to repoze.bfg.traversal.RoutesModelTraverser.

The repoze.bfg.registry.makeRegistry function was renamed to repoze.bfg.registry.populateRegistry and now accepts a registry argument (which should be an instance of zope.component.registry.Components).

Documentation Additions

Updated narrative urldispatch chapter with changes required by <route..> ZCML directive.

Add a section on “Using BFG Security With URL Dispatch” into the urldispatch chapter of the documentation.

Better documentation of security policy implementations that ship with repoze.bfg.

Added a “Using ZPT Macros in repoze.bfg” section to the narrative templating chapter.

0.6.2 (2009-01-13)

Features

Tests can be run with coverage output if you’ve got nose installed in the interpreter which you use to run tests. Using an interpreter with nose installed, do python setup.py nosetests within a checkout of the repoze.bfg package to see test coverage output.

Added a post argument to the repoze.bfg.testing:DummyRequest constructor.

Added __len__ and __nonzero__ to repoze.bfg.testing:DummyModel.

The repoze.bfg.registry.get_options callable (now renamed to repoze.bfg.setings.get_options) used to return only framework-specific keys and values in the dictionary it returned. It now returns all the keys and values in the dictionary it is passed plus any framework-specific settings culled from the environment. As a side effect, all PasteDeploy application-specific config file settings are made available as attributes of the ISettings utility from within BFG.

Renamed the existing BFG paster template to bfg_starter. Added another template (bfg_zodb) showing default ZODB setup using repoze.zodbconn.

Add a method named assert_ to the DummyTemplateRenderer. This method accepts keyword arguments. Each key/value pair in the keyword arguments causes an assertion to be made that the renderer received this key with a value equal to the asserted value.

Projects generated by the paster templates now use the DummyTemplateRenderer.assert_ method in their view tests.

Make the (internal) thread local registry manager maintain a stack of registries in order to make it possible to call one BFG application from inside another.

An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is attached to each request object on ingress. The HTTP-verb-related interfaces are defined in repoze.bfg.interfaces and are IGETRequest, IPOSTRequest, IPUTRequest, IDELETERequest and IHEADRequest. These interfaces can be specified as the request_type attribute of a bfg view declaration. A view naming a specific HTTP-verb-matching interface will be found only if the view is defined with a request_type that matches the HTTP verb in the incoming request. The more general IRequest interface can be used as the request_type to catch all requests (and this is indeed the default). All requests implement IRequest. The HTTP-verb-matching idea was pioneered by repoze.bfg.restrequest [http://pypi.python.org/pypi/repoze.bfg.restrequest/1.0.1] . That package is no longer required, but still functions fine.

Bug Fixes

Fix a bug where the Paste configuration’s unicode_path_segments (and os.environ’s BFG_UNICODE_PATH_SEGMENTS) may have been defaulting to false in some circumstances. It now always defaults to true, matching the documentation and intent.

The repoze.bfg.traversal.find_model API did not work properly when passed a path argument which was unicode and contained high-order bytes when the unicode_path_segments or BFG_UNICODE_PATH_SEGMENTS configuration variables were “true”.

A new module was added: repoze.bfg.settings. This contains deployment-settings-related code.

Implementation Changes

The make_app callable within repoze.bfg.router now registers the root_policy argument as a utility (unnamed, using the new repoze.bfg.interfaces.IRootFactory as a provides interface) rather than passing it as the first argument to the repoze.bfg.router.Router class. As a result, the repoze.bfg.router.Router router class only accepts a single argument: registry. The repoze.bfg.router.Router class retrieves the root policy via a utility lookup now. The repoze.bfg.router.make_app API also now performs some important application registrations that were previously handled inside repoze.bfg.registry.makeRegistry.

New Modules

A repoze.bfg.settings module was added. It contains code related to deployment settings. Most of the code it contains was moved to it from the repoze.bfg.registry module.

Behavior Changes

The repoze.bfg.settings.Settings class (an instance of which is registered as a utility providing repoze.bfg.interfaces.ISettings when any application is started) now automatically calls repoze.bfg.settings.get_options on the options passed to its constructor. This means that usage of get_options within an application’s make_app function is no longer required (the “raw” options dict or None may be passed).

Remove old cold which attempts to recover from trying to unpickle a z3c.pt template; Chameleon has been the templating engine for a good long time now. Running repoze.bfg against a sandbox that has pickled z3c.pt templates it will now just fail with an unpickling error, but can be fixed by deleting the template cache files.

Deprecations

Moved the repoze.bfg.registry.Settings class. This has been moved to repoze.bfg.settings.Settings. A deprecation warning is issued when it is imported from the older location.

Moved the repoze.bfg.registry.get_options function This has been moved to repoze.bfg.settings.get_options. A deprecation warning is issued when it is imported from the older location.

The repoze.bfg.interfaces.IRootPolicy interface was renamed within the interfaces package. It has been renamed to IRootFactory. A deprecation warning is issued when it is imported from the older location.

0.6.1 (2009-01-06)

New Modules

A new module repoze.bfg.url has been added. It contains the model_url API (moved from repoze.bfg.traversal) and an implementation of urlencode (like Python’s urllib.urlencode) which can handle Unicode keys and values in parameters to the query argument.

Deprecations

The model_url function has been moved from repoze.bfg.traversal into repoze.bfg.url. It can still be imported from repoze.bfg.traversal but an import from repoze.bfg.traversal will emit a DeprecationWarning.

Features

A static helper class was added to the repoze.bfg.views module. Instances of this class are willing to act as BFG views which return static resources using files on disk. See the repoze.bfg.view docs for more info.

The repoze.bfg.url.model_url API (nee’ repoze.bfg.traversal.model_url) now accepts and honors a keyword argument named query. The value of this argument will be used to compose a query string, which will be attached to the generated URL before it is returned. See the API docs (in the docs directory or on the web [http://static.repoze.org/bfgdocs]) for more information.

0.6 (2008-12-26)

Backwards Incompatibilities

Rather than prepare the “stock” implementations of the ZCML directives from the zope.configuration package for use under repoze.bfg, repoze.bfg now makes available the implementations of directives from the repoze.zcml package (see http://static.repoze.org/zcmldocs). As a result, the repoze.bfg package now depends on the repoze.zcml package, and no longer depends directly on the zope.component, zope.configuration, zope.interface, or zope.proxy packages.

The primary reason for this change is to enable us to eventually reduce the number of inappropriate repoze.bfg Zope package dependencies, as well as to shed features of dependent package directives that don’t make sense for repoze.bfg.

Note that currently the set of requirements necessary to use bfg has not changed. This is due to inappropriate Zope package requirements in chameleon.zpt, which will hopefully be remedied soon. NOTE: in lemonade index a 1.0b8-repozezcml0 package exists which does away with these requirements.

BFG applications written prior to this release which expect the “stock” zope.component ZCML directive implementations (e.g. adapter, subscriber, or utility) to function now must either 1) include the meta.zcml file from zope.component manually (e.g. <include package="zope.component" file="meta.zcml">) and include the zope.security package as an install_requires dependency or 2) change the ZCML in their applications to use the declarations from repoze.zcml [http://static.repoze.org/zcmldocs/] instead of the stock declarations. repoze.zcml only makes available the adapter, subscriber and utility directives.

In short, if you’ve got an existing BFG application, after this update, if your application won’t start due to an import error for “zope.security”, the fastest way to get it working again is to add zope.security to the “install_requires” of your BFG application’s setup.py, then add the following ZCML anywhere in your application’s configure.zcml:

<include package="zope.component" file="meta.zcml">

Then re-setup.py develop or reinstall your application.

The http://namespaces.repoze.org/bfg XML namespace is now the default XML namespace in ZCML for paster-generated applications. The docs have been updated to reflect this.

The copies of BFG’s meta.zcml and configure.zcml were removed from the root of the repoze.bfg package. In 0.3.6, a new package named repoze.bfg.includes was added, which contains the “correct” copies of these ZCML files; the ones that were removed were for backwards compatibility purposes.

The BFG view ZCML directive no longer calls zope.component.interface.provideInterface for the for interface. We don’t support provideInterface in BFG because it mutates the global registry.

Other

The minimum requirement for chameleon.core is now 1.0b13. The minimum requirement for chameleon.zpt is now 1.0b8. The minimum requirement for chameleon.genshi is now 1.0b2.

Updated paster template “ez_setup.py” to one that requires setuptools 0.6c9.

Turn view_execution_permitted from the repoze.bfg.view module into a documented API.

Doc cleanups.

Documented how to create a view capable of serving static resources.

0.5.6 (2008-12-18)

Speed up traversal.model_url execution by using a custom url quoting function instead of Python’s urllib.quote, by caching URL path segment quoting and encoding results, by disusing Python’s urlparse.urljoin in favor of a simple string concatenation, and by using ob.__class__ is unicode rather than isinstance(ob, unicode) in one strategic place.

0.5.5 (2008-12-17)

Backwards Incompatibilities

In the past, during traversal, the ModelGraphTraverser (the default traverser) always passed each URL path segment to any __getitem__ method of a model object as a byte string (a str object). Now, by default the ModelGraphTraverser attempts to decode the path segment to Unicode (a unicode object) using the UTF-8 encoding before passing it to the __getitem__ method of a model object. This makes it possible for model objects to be dumber in __getitem__ when trying to resolve a subobject, as model objects themselves no longer need to try to divine whether or not to try to decode the path segment passed by the traverser.

Note that since 0.5.4, URLs generated by repoze.bfg’s model_url API will contain UTF-8 encoded path segments as necessary, so any URL generated by BFG itself will be decodeable by the traverser. If another application generates URLs to a BFG application, to be resolved successully, it should generate the URL with UTF-8 encoded path segments to be successfully resolved. The decoder is not at all magical: if a non-UTF-8-decodeable path segment (e.g. one encoded using UTF-16 or some other insanity) is passed in the URL, BFG will raise a TypeError with a message indicating it could not decode the path segment.

To turn on the older behavior, where path segments were not decoded to Unicode before being passed to model object __getitem__ by the traverser, and were passed as a raw byte string, set the unicode_path_segments configuration setting to a false value in your BFG application’s section of the paste .ini file, for example:

unicode_path_segments = False

Or start the application using the BFG_UNICODE_PATH_SEGMENT envvar set to a false value:

BFG_UNICODE_PATH_SEGMENTS=0

0.5.4 (2008-12-13)

Backwards Incompatibilities

URL-quote “extra” element names passed in as **elements to the traversal.model_url API. If any of these names is a Unicode string, encode it to UTF-8 before URL-quoting. This is a slight backwards incompatibility that will impact you if you were already UTF-8 encoding or URL-quoting the values you passed in as elements to this API.

Bugfixes

UTF-8 encode each segment in the model path used to generate a URL before url-quoting it within the traversal.model_url API. This is a bugfix, as Unicode cannot always be successfully URL-quoted.

Features

Make it possible to run unit tests using a buildout-generated Python “interpreter”.

Add request.root to router.Router in order to have easy access to the application root.

0.5.3 (2008-12-07)

Remove the ITestingTemplateRenderer interface. When testing.registerDummyRenderer is used, it instead registers a dummy implementation using ITemplateRenderer interface, which is checked for when the built-in templating facilities do rendering. This change also allows developers to make explcit named utility registrations in the ZCML registry against ITemplateRenderer; these will be found before any on-disk template is looked up.

0.5.2 (2008-12-05)

The component registration handler for views (functions or class instances) now observes component adaptation annotations (see zope.component.adaptedBy) and uses them before the fallback values for for_ and request_type. This change does not affect existing code insomuch as the code does not rely on these defaults when an annotation is set on the view (unlikely). This means that for a new-style class you can do zope.component.adapts(ISomeContext, ISomeRequest) at class scope or at module scope as a decorator to a bfg view function you can do @zope.component.adapter(ISomeContext, ISomeRequest). This differs from r.bfg.convention inasmuch as you still need to put something in ZCML for the registrations to get done; it’s only the defaults that will change if these declarations exist.

Strip all slashes from end and beginning of path in clean_path within traversal machinery.

0.5.1 (2008-11-25)

Add keys, items, and values methods to testing.DummyModel.

Add __delitem__ method to testing.DummyModel.

0.5.0 (2008-11-18)

Fix ModelGraphTraverser; don’t try to change the __name__ or __parent__ of an object that claims it implements ILocation during traversal even if the __name__ or __parent__ of the object traversed does not match the name used in the traversal step or the or the traversal parent . Rationale: it was insane to do so. This bug was only found due to a misconfiguration in an application that mistakenly had intermediate persistent non-ILocation objects; traversal was causing a persistent write on every request under this setup.

repoze.bfg.location.locate now unconditionally sets __name__ and __parent__ on objects which provide ILocation (it previously only set them conditionally if they didn’t match attributes already present on the object via equality).

0.4.9 (2008-11-17)

Add chameleon text template API (chameleon ${name} renderings where the template does not need to be wrapped in any containing XML).

Change docs to explain install in terms of a virtualenv (unconditionally).

Make pushpage decorator compatible with repoze.bfg.convention’s bfg_view decorator when they’re stacked.

Add content_length attribute to testing.DummyRequest.

Change paster template tests.py to include a true unit test. Retain old test as an integration test. Update documentation.

Document view registrations against classes and repoze.bfg.convention in context.

Change the default paster template to register its single view against a class rather than an interface.

Document adding a request type interface to the request via a subscriber function in the events narrative documentation.

0.4.8 (2008-11-12)

Backwards Incompatibilities

repoze.bfg.traversal.model_url now always appends a slash to all generated URLs unless further elements are passed in as the third and following arguments. Rationale: views often use model_url without the third-and-following arguments in order to generate a URL for a model in order to point at the default view of a model. The URL that points to the default view of the root model is technically http://mysite/ as opposed to http://mysite (browsers happen to ask for ‘/’ implicitly in the GET request). Because URLs are never automatically generated for anything except models by model_url, and because the root model is not really special, we continue this pattern. The impact of this change is minimal (at most you will have too many slashes in your URL, which BFG deals with gracefully anyway).

0.4.7 (2008-11-11)

Features

Allow testing.registerEventListener to be used with Zope 3 style “object events” (subscribers accept more than a single event argument). We extend the list with the arguments, rather than append.

0.4.6 (2008-11-10)

Bug Fixes

The model_path and model_url traversal APIs returned the wrong value for the root object (e.g. model_path returned '' for the root object, while it should have been returning '/').

0.4.5 (2008-11-09)

Features

Added a clone method and a __contains__ method to the DummyModel testing object.

Allow DummyModel objects to receive extra keyword arguments, which will be attached as attributes.

The DummyTemplateRenderer now returns self as its implementation.

0.4.4 (2008-11-08)

Features

Added a repoze.bfg.testing module to attempt to make it slightly easier to write unittest-based automated tests of BFG applications. Information about this module is in the documentation.

The default template renderer now supports testing better by looking for ITestingTemplateRenderer using a relative pathname. This is exposed indirectly through the API named registerTemplateRenderer in repoze.bfg.testing.

Deprecations

The names repoze.bfg.interfaces.ITemplate , repoze.bfg.interfaces.ITemplateFactory and repoze.bfg.interfaces.INodeTemplate have been deprecated. These should now be imported as repoze.bfg.interfaces.ITemplateRenderer and repoze.bfg.interfaces.ITemplateRendererFactory, and INodeTemplateRenderer respectively.

The name repoze.bfg.chameleon_zpt.ZPTTemplateFactory is deprecated. Use repoze.bfg.chameleon_zpt.ZPTTemplateRenderer.

The name repoze.bfg.chameleon_genshi.GenshiTemplateFactory is deprecated. Use repoze.bfg.chameleon_genshi.GenshiTemplateRenderer.

The name repoze.bfg.xslt.XSLTemplateFactory is deprecated. Use repoze.bfg.xslt.XSLTemplateRenderer.

0.4.3 (2008-11-02)

Bug Fixes

Not passing the result of “get_options” as the second argument of make_app could cause attribute errors when attempting to look up settings against the ISettings object (internal). Fixed by giving the Settings objects defaults for debug_authorization and debug_notfound.

Return an instance of Allowed (rather than True) from has_permission when no security policy is in use.

Fix bug where default deny in authorization check would throw a TypeError (use ACLDenied instead of Denied).

0.4.2 (2008-11-02)

Features

Expose a single ILogger named “repoze.bfg.debug” as a utility; this logger is registered unconditionally and is used by the authorization debug machinery. Applications may also make use of it as necessary rather than inventing their own logger, for convenience.

The BFG_DEBUG_AUTHORIZATION envvar and the debug_authorization config file value now only imply debugging of view-invoked security checks. Previously, information was printed for every call to has_permission as well, which made output confusing. To debug has_permission checks and other manual permission checks, use the debugger and print statements in your own code.

Authorization debugging info is now only present in the HTTP response body oif debug_authorization is true.

The format of authorization debug messages was improved.

A new BFG_DEBUG_NOTFOUND envvar was added and a symmetric debug_notfound config file value was added. When either is true, and a NotFound response is returned by the BFG router (because a view could not be found), debugging information is printed to stderr. When this value is set true, the body of HTTPNotFound responses will also contain the same debugging information.

Allowed and Denied responses from the security machinery are now specialized into two types: ACL types, and non-ACL types. The ACL-related responses are instances of repoze.bfg.security.ACLAllowed and repoze.bfg.security.ACLDenied. The non-ACL-related responses are repoze.bfg.security.Allowed and repoze.bfg.security.Denied. The allowed-type responses continue to evaluate equal to things that themselves evaluate equal to the True boolean, while the denied-type responses continue to evaluate equal to things that themselves evaluate equal to the False boolean. The only difference between the two types is the information attached to them for debugging purposes.

Added a new BFG_DEBUG_ALL envvar and a symmetric debug_all config file value. When either is true, all other debug-related flags are set true unconditionally (e.g. debug_notfound and debug_authorization).

Documentation

Added info about debug flag changes.

Added a section to the security chapter named “Debugging Imperative Authorization Failures” (for e.g. has_permssion).

Bug Fixes

Change default paster template generator to use Paste#http server rather than PasteScript#cherrpy server. The cherrypy server has a security risk in it when REMOTE_USER is trusted by the downstream application.

0.4.1 (2008-10-28)

Bug Fixes

If the render_view_to_response function was called, if the view was found and called, but it returned something that did not implement IResponse, the error would pass by unflagged. This was noticed when I created a view function that essentially returned None, but received a NotFound error rather than a ValueError when the view was rendered. This was fixed.

0.4.0 (2008-10-03)

Docs

An “Environment and Configuration” chapter was added to the narrative portion of the documentation.

Features

Ensure bfg doesn’t generate warnings when running under Python 2.6.

The environment variable BFG_RELOAD_TEMPLATES is now available (serves the same purpose as reload_templates in the config file).

A new configuration file option debug_authorization was added. This turns on printing of security authorization debug statements to sys.stderr. The BFG_DEBUG_AUTHORIZATION environment variable was also added; this performs the same duty.

Bug Fixes

The environment variable BFG_SECURITY_DEBUG did not always work. It has been renamed to BFG_DEBUG_AUTHORIZATION and fixed.

Deprecations

A deprecation warning is now issued when old API names from the repoze.bfg.templates module are imported.

Backwards incompatibilities

The BFG_SECURITY_DEBUG environment variable was renamed to BFG_DEBUG_AUTHORIZATION.

0.3.9 (2008-08-27)

Features

A repoze.bfg.location API module was added.

Backwards incompatibilities

Applications must now use the repoze.bfg.interfaces.ILocation interface rather than zope.location.interfaces.ILocation to represent that a model object is “location-aware”. We’ve removed a dependency on zope.location for cleanliness purposes: as new versions of zope libraries are released which have improved dependency information, getting rid of our dependence on zope.location will prevent a newly installed repoze.bfg application from requiring the zope.security, egg, which not truly used at all in a “stock” repoze.bfg setup. These dependencies are still required by the stack at this time; this is purely a futureproofing move.

The security and model documentation for previous versions of repoze.bfg recommended using the zope.location.interfaces.ILocation interface to represent that a model object is “location-aware”. This documentation has been changed to reflect that this interface should now be imported from repoze.bfg.interfaces.ILocation instead.

0.3.8 (2008-08-26)

Docs

Documented URL dispatch better in narrative form.

Bug fixes

Routes URL dispatch did not have access to the WSGI environment, so conditions such as method=GET did not work.

Features

Add principals_allowed_by_permission API to security module.

Replace z3c.pt support with support for chameleon.zpt. Chameleon is the new name for the package that used to be named z3c.pt. NOTE: If you update a repoze.bfg SVN checkout that you’re using for development, you will need to run “setup.py install” or “setup.py develop” again in order to obtain the proper Chameleon packages. z3c.pt is no longer supported by repoze.bfg. All API functions that used to render z3c.pt templates will work fine with the new packages, and your templates should render almost identically.

Add a repoze.bfg.chameleon_zpt module. This module provides Chameleon ZPT support.

Add a repoze.bfg.xslt module. This module provides XSLT support.

Add a repoze.bfg.chameleon_genshi module. This provides direct Genshi support, which did not exist previously.

Deprecations

Importing API functions directly from repoze.bfg.template is now deprecated. The get_template, render_template, render_template_to_response functions should now be imported from repoze.chameleon_zpt. The render_transform, and render_transform_to_response functions should now be imported from repoze.bfg.xslt. The repoze.bfg.template module will remain around “forever” to support backwards compatibility.

0.3.7 (2008-09-09)

Features

Add compatibility with z3c.pt 1.0a7+ (z3c.pt became a namespace package).

Bug fixes

repoze.bfg.traversal.find_model function did not function properly.

0.3.6 (2008-09-04)

Features

Add startup process docs.

Allow configuration cache to be bypassed by actions which include special “uncacheable” discriminators (for actions that have variable results).

Bug Fixes

Move core repoze.bfg ZCML into a repoze.bfg.includes package so we can use repoze.bfg better as a namespace package. Adjust the code generator to use it. We’ve left around the configure.zcml in the repoze.bfg package directly so as not to break older apps.

When a zcml application registry cache was unpickled, and it contained a reference to an object that no longer existed (such as a view), bfg would not start properly.

0.3.5 (2008-09-01)

Features

Event notification is issued after application is created and configured (IWSGIApplicationCreatedEvent).

New API module: repoze.bfg.view. This module contains the functions named render_view_to_response, render_view_to_iterable, render_view and is_response, which are documented in the API docs. These features aid programmatic (non-server-driven) view execution.

0.3.4 (2008-08-28)

Backwards incompatibilities

Make repoze.bfg a namespace package so we can allow folks to create subpackages (e.g. repoze.bfg.otherthing) within separate eggs. This is a backwards incompatible change which makes it impossible to import “make_app” and “get_options” from the repoze.bfg module directly. This change will break all existing apps generated by the paster code generator. Instead, you need to import these functions as repoze.bfg.router:make_app and repoze.bfg.registry:get_options, respectively. Sorry folks, it has to be done now or never, and definitely better now.

Features

Add model_path API function to traversal module.

Bugfixes

Normalize path returned by repoze.bfg.caller_path.

0.3.3 (2008-08-23)

Fix generated test.py module to use project name rather than package name.

0.3.2 (2008-08-23)

Remove sampleapp sample application from bfg package itself.

Remove dependency on FormEncode (only needed by sampleapp).

Fix paster template generation so that case-sensitivity is preserved for project vs. package name.

Depend on z3c.pt version 1.0a1 (which requires the [lxml] extra currently).

Read and write a pickled ZCML actions list, stored as configure.zcml.cache next to the applications’s “normal” configuration file. A given bfg app will usually start faster if it’s able to read the pickle data. It fails gracefully to reading the real ZCML file if it cannot read the pickle.

0.3.1 (2008-08-20)

Generated application differences: make_app entry point renamed to app in order to have a different name than the bfg function of the same name, to prevent confusion.

Add “options” processing to bfg’s make_app to support runtime options. A new API function named get_options was added to the registry module. This function is typically used in an application’s app entry point. The Paste config file section for the app can now supply the reload_templates option, which, if true, will prevent the need to restart the appserver in order for z3c.pt or XSLT template changes to be detected.

Use only the module name in generated project’s “test_suite” (run all tests found in the package).

Default port for generated apps changed from 5432 to 6543 (Postgres default port is 6543).

0.3.0 (2008-08-16)

Add get_template API to template module.

0.2.9 (2008-08-11)

0.2.8 was “brown bag” release. It didn’t work at all. Symptom: ComponentLookupError when trying to render a page.

0.2.8 (2008-08-11)

Add find_model and find_root traversal APIs. In the process, make ITraverser a uni-adapter (on context) rather than a multiadapter (on context and request).

0.2.7 (2008-08-05)

Add a request_type attribute to the available attributes of a bfg:view configure.zcml element. This attribute will have a value which is a dotted Python path, pointing at an interface. If the request object implements this interface when the view lookup is performed, the appropriate view will be called. This is meant to allow for simple “skinning” of sites based on request type. An event subscriber should attach the interface to the request on ingress to support skins.

Remove “template only” views. These were just confusing and were never documented.

Small url dispatch overhaul: the connect method of the urldispatch.RoutesMapper object now accepts a keyword parameter named context_factory. If this parameter is supplied, it must be a callable which returns an instance. This instance is used as the context for the request when a route is matched.

The registration of a RoutesModelTraverser no longer needs to be performed by the application; it’s in the bfg ZCML now.

0.2.6 (2008-07-31)

Add event sends for INewRequest and INewResponse. See the events.rst chapter in the documentation’s api directory.

0.2.5 (2008-07-28)

Add model_url API.

0.2.4 (2008-07-27)

Added url-based dispatch.

0.2.3 (2008-07-20)

Add API functions for authenticated_userid and effective_principals.

0.2.2 (2008-07-20)

Add authenticated_userid and effective_principals API to security policy.

0.2.1 (2008-07-20)

Add find_interface API.

0.2 (2008-07-19)

Add wsgiapp decorator.

The concept of “view factories” was removed in favor of always calling a view, which is a callable that returns a response directly (as opposed to returning a view). As a result, the factory attribute in the bfg:view ZCML statement has been renamed to view. Various interface names were changed also.

render_template and render_transform no longer return a Response object. Instead, these return strings. The old behavior can be obtained by using render_template_to_response and render_transform_to_response.

Added ‘repoze.bfg.push:pushpage’ decorator, which creates BFG views from callables which take (context, request) and return a mapping of top-level names.

Added ACL-based security.

Support for XSLT templates via a render_transform method

0.1 (2008-07-08)

Initial release.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

previous |

The Pyramid Web Application Development Framework v1.0 »

Defending Pyramid’s Design

From time to time, challenges to various aspects of Pyramid design are lodged. To give context to discussions that follow, we detail some of the design decisions and trade-offs here. In some cases, we acknowledge that the framework can be made better and we describe future steps which will be taken to improve it; in some cases we just file the challenge as “noted”, as obviously you can’t please everyone all of the time.

Pyramid Provides More Than One Way to Do It

A canon of Python popular culture is “TIOOWTDI” (“there is only one way to do it”, a slighting, tongue-in-cheek reference to Perl’s “TIMTOWTDI”, which is an acronym for “there is more than one way to do it”).

Pyramid is, for better or worse, a “TIMTOWTDI” system. For example, it includes more than one way to resolve a URL to a view callable: via url dispatch or traversal. Multiple methods of configuration exist: imperative configuration, configuration decoration, and ZCML (optionally via pyramid_zcml). It works with multiple different kinds of persistence and templating systems. And so on. However, the existence of most of these overlapping ways to do things are not without reason and purpose: we have a number of audiences to serve, and we believe that TIMTOWTI at the web framework level actually prevents a much more insidious and harmful set of duplication at higher levels in the Python web community.

Pyramid began its life as repoze.bfg, written by a team of people with many years of prior Zope experience. The idea of traversal and the way view lookup works was stolen entirely from Zope. The authorization subsystem provided by Pyramid is a derivative of Zope’s. The idea that an application can be extended without forking is also a Zope derivative.

Implementations of these features were required to allow the Pyramid authors to build the bread-and-butter CMS-type systems for customers in the way they were accustomed to building them. No other system save Zope itself had such features. And Zope itself was beginning to show signs of its age. We were becoming hampered by consequences of its early design mistakes. Zope’s lack of documentation was also difficult to work around: it was hard to hire smart people to work on Zope applications, because there was no comprehensive documentation set to point them at which explained “it all” in one consumble place, and it was too large and self-inconsistent to document properly. Before repoze.bfg went under development, its authors obviously looked around for other frameworks that fit the bill. But no non-Zope framework did. So we embarked on building repoze.bfg.

As the result of our research, however, it became apparent that, despite the fact that no one framework had all the features we required, lots of existing frameworks had good, and sometimes very compelling ideas. In particular, URL dispatch is a more direct mechanism to map URLs to code.

So although we couldn’t find a framework save for Zope that fit our needs, and while we incorporated a lot of Zope ideas into BFG, we also emulated the features we found compelling in other frameworks (such as url dispatch). After the initial public release of BFG, as time went on, features were added to support people allergic to various Zope-isms in the system, such as the ability to configure the application using imperative configuration rather than solely using ZCML, and the elimination of the required use of interface objects. It soon became clear that we had a system that was very generic, and was beginning to appeal to non-Zope users as well as ex-Zope users.

As the result of this generalization, it became obvious BFG shared 90% of its featureset with the featureset of Pylons 1, and thus had a very similar target market. Because they were so similar, choosing between the two systems was an exercise in frustration for an otherwise non-partisan developer. It was also strange for the Pylons and BFG development communities to be in competition for the same set of users, given how similar the two frameworks were. So the Pylons and BFG teams began to work together to form a plan to “merge”. The features missing from BFG (notably view handler classes, flash messaging, and other minor missing bits), were added, to provide familiarity to ex-Pylons users. The result is Pyramid.

The Python web framework space is currently notoriously balkanized. We’re truly hoping that the amalgamation of components in Pyramid will appeal to at least two currently very distinct sets of users: Pylons and BFG users. By unifying the best concepts from Pylons and BFG into a single codebase and leaving the bad concepts from their ancestors behind, we’ll be able to consolidate our efforts better, share more code, and promote our efforts as a unit rather than competing pointlessly. We hope to be able to shortcut the pack mentality which results in a much larger duplication of effort, represented by competing but incredibly similar applications and libraries, each built upon a specific low level stack that is incompatible with the other. We’ll also shrink the choice of credible Python web frameworks down by at least one. We’re also hoping to attract users from other communities (such as Zope’s and TurboGears’) by providing the features they require, while allowing enough flexibility to do things in a familiar fashion. Some overlap of functionality to achieve these goals is expected and unavoidable, at least if we aim to prevent pointless duplication at higher levels. If we’ve done our job well enough, the various audiences will be able to coexist and cooperate rather than firing at each other across some imaginary web framework “DMZ”.

Pyramid Uses A Zope Component Architecture (“ZCA”) Registry

Pyramid uses a Zope Component Architecture (ZCA) “component registry” as its application registry under the hood. This is a point of some contention. Pyramid is of a Zope pedigree, so it was natural for its developers to use a ZCA registry at its inception. However, we understand that using a ZCA registry has issues and consequences, which we’ve attempted to address as best we can. Here’s an introspection about Pyramid use of a ZCA registry, and the trade-offs its usage involves.

Problems

The “global” API that may be used to access data in a ZCA “component registry” is not particularly pretty or intuitive, and sometimes it’s just plain obtuse. Likewise, the conceptual load on a casual source code reader of code that uses the ZCA global API is somewhat high. Consider a ZCA neophyte reading the code that performs a typical “unnamed utility” lookup using the zope.component.getUtility() global API:

1
2
3

from pyramid.interfaces import ISettings
from zope.component import getUtility
settings = getUtility(ISettings)

After this code runs, settings will be a Python dictionary. But it’s unlikely that any “civilian” would know that just by reading the code. There are a number of comprehension issues with the bit of code above that are obvious.

First, what’s a “utility”? Well, for the purposes of this discussion, and for the purpose of the code above, it’s just not very important. If you really want to know, you can read this [http://www.muthukadan.net/docs/zca.html#utility]. However, still, readers of such code need to understand the concept in order to parse it. This is problem number one.

Second, what’s this ISettings thing? It’s an interface. Is that important here? Not really, we’re just using it as a “key” for some lookup based on its identity as a marker: it represents an object that has the dictionary API, but that’s not very important in this context. That’s problem number two.

Third of all, what does the getUtility function do? It’s performing a lookup for the ISettings “utility” that should return.. well, a utility. Note how we’ve already built up a dependency on the understanding of an interface and the concept of “utility” to answer this question: a bad sign so far. Note also that the answer is circular, a really bad sign.

Fourth, where does getUtility look to get the data? Well, the “component registry” of course. What’s a component registry? Problem number four.

Fifth, assuming you buy that there’s some magical registry hanging around, where is this registry? Homina homina... “around”? That’s sort of the best answer in this context (a more specific answer would require knowledge of internals). Can there be more than one registry? Yes. So which registry does it find the registration in? Well, the “current” registry of course. In terms of Pyramid, the current registry is a thread local variable. Using an API that consults a thread local makes understanding how it works non-local.

You’ve now bought in to the fact that there’s a registry that is just “hanging around”. But how does the registry get populated? Why, via code that calls directives like config.add_view. In this particular case, however, the registration of ISettings is made by the framework itself “under the hood”: it’s not present in any user configuration. This is extremely hard to comprehend. Problem number six.

Clearly there’s some amount of cognitive load here that needs to be borne by a reader of code that extends the Pyramid framework due to its use of the ZCA, even if he or she is already an expert Python programmer and whom is an expert in the domain of web applications. This is suboptimal.

Ameliorations

First, the primary amelioration: Pyramid does not expect application developers to understand ZCA concepts or any of its APIs. If an application developer needs to understand a ZCA concept or API during the creation of a Pyramid application, we’ve failed on some axis.

Instead, the framework hides the presence of the ZCA registry behind special-purpose API functions that do use ZCA APIs. Take for example the pyramid.security.authenticated_userid function, which returns the userid present in the current request or None if no userid is present in the current request. The application developer calls it like so:

1
2

from pyramid.security import authenticated_userid
userid = authenticated_userid(request)

He now has the current user id.

Under its hood however, the implementation of authenticated_userid is this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

def authenticated_userid(request):
    """ Return the userid of the currently authenticated user or
    ``None`` if there is no authentication policy in effect or there
    is no currently authenticated user. """

    registry = request.registry # the ZCA component registry
    policy = registry.queryUtility(IAuthenticationPolicy)
    if policy is None:
        return None
    return policy.authenticated_userid(request)

Using such wrappers, we strive to always hide the ZCA API from application developers. Application developers should just never know about the ZCA API: they should call a Python function with some object germane to the domain as an argument, and it should returns a result. A corollary that follows is that any reader of an application that has been written using Pyramid needn’t understand the ZCA API either.

Hiding the ZCA API from application developers and code readers is a form of enhancing “domain specificity”. No application developer wants to need to understand the minutiae of the mechanics of how a web framework does its thing. People want to deal in concepts that are closer to the domain they’re working in: for example, web developers want to know about users, not utilities. Pyramid uses the ZCA as an implementation detail, not as a feature which is exposed to end users.

However, unlike application developers, framework developers, including people who want to override Pyramid functionality via preordained framework plugpoints like traversal or view lookup must understand the ZCA registry API.

Pyramid framework developers were so concerned about conceptual load issues of the ZCA registry API for framework developers that a replacement registry implementation [http://svn.repoze.org/repoze.component/trunk] named repoze.component was actually developed. Though this package has a registry implementation which is fully functional and well-tested, and its API is much nicer than the ZCA registry API, work on it was largely abandoned and it is not used in Pyramid. We continued to use a ZCA registry within Pyramid because it ultimately proved a better fit.

Note

We continued using ZCA registry rather than disusing it in favor of using the registry implementation in repoze.component largely because the ZCA concept of interfaces provides for use of an interface hierarchy, which is useful in a lot of scenarios (such as context type inheritance). Coming up with a marker type that was something like an interface that allowed for this functionality seemed like it was just reinventing the wheel.

Making framework developers and extenders understand the ZCA registry API is a trade-off. We (the Pyramid developers) like the features that the ZCA registry gives us, and we have long-ago borne the weight of understanding what it does and how it works. The authors of Pyramid understand the ZCA deeply and can read code that uses it as easily as any other code.

But we recognize that developers who might want to extend the framework are not as comfortable with the ZCA registry API as the original developers are with it. So, for the purposes of being kind to third-party Pyramid framework developers in, we’ve drawn some lines in the sand.

In all “core” code, We’ve made use of ZCA global API functions such as zope.component.getUtility and zope.component.getAdapter the exception instead of the rule. So instead of:

1
2
3

from pyramid.interfaces import IAuthenticationPolicy
from zope.component import getUtility
policy = getUtility(IAuthenticationPolicy)

Pyramid code will usually do:

1
2
3
4

from pyramid.interfaces import IAuthenticationPolicy
from pyramid.threadlocal import get_current_registry
registry = get_current_registry()
policy = registry.getUtility(IAuthenticationPolicy)

While the latter is more verbose, it also arguably makes it more obvious what’s going on. All of the Pyramid core code uses this pattern rather than the ZCA global API.

Rationale

Here are the main rationales involved in the Pyramid decision to use the ZCA registry:

Pedigree. A nontrivial part of the answer to this question is “pedigree”. Much of the design of Pyramid is stolen directly from Zope. Zope uses the ZCA registry to do a number of tricks. Pyramid mimics these tricks, and, because the ZCA registry works well for that set of tricks, Pyramid uses it for the same purposes. For example, the way that Pyramid maps a request to a view callable using traversal is lifted almost entirely from Zope. The ZCA registry plays an important role in the particulars of how this request to view mapping is done.

Features. The ZCA component registry essentially provides what can be considered something like a “superdictionary”, which allows for more complex lookups than retrieving a value based on a single key. Some of this lookup capability is very useful for end users, such as being able to register a view that is only found when the context is some class of object, or when the context implements some interface.

Singularity. There’s only one “place” where “application configuration” lives in a Pyramid application: in a component registry. The component registry answers questions made to it by the framework at runtime based on the configuration of an application. Note: “an application” is not the same as “a process”, multiple independently configured copies of the same Pyramid application are capable of running in the same process space.

Composability. A ZCA component registry can be populated imperatively, or there’s an existing mechanism to populate a registry via the use of a configuration file (ZCML, via pyramid_zcml). We didn’t need to write a frontend from scratch to make use of configuration-file-driven registry population.

Pluggability. Use of the ZCA registry allows for framework extensibility via a well-defined and widely understood plugin architecture. As long as framework developers and extenders understand the ZCA registry, it’s possible to extend Pyramid almost arbitrarily. For example, it’s relatively easy to build a directive that registers several views “all at once”, allowing app developers to use that directive as a “macro” in code that they write. This is somewhat of a differentiating feature from other (non-Zope) frameworks.

Testability. Judicious use of the ZCA registry in framework code makes testing that code slightly easier. Instead of using monkeypatching or other facilities to register mock objects for testing, we inject dependencies via ZCA registrations and then use lookups in the code find our mock objects.

Speed. The ZCA registry is very fast for a specific set of complex lookup scenarios that Pyramid uses, having been optimized through the years for just these purposes. The ZCA registry contains optional C code for this purpose which demonstrably has no (or very few) bugs.

Ecosystem. Many existing Zope packages can be used in Pyramid with few (or no) changes due to our use of the ZCA registry.

Conclusion

If you only develop applications using Pyramid, there’s not much to complain about here. You just should never need to understand the ZCA registry API: use documented Pyramid APIs instead. However, you may be an application developer who doesn’t read API documentation because it’s unmanly. Instead you read the raw source code, and because you haven’t read the documentation, you don’t know what functions, classes, and methods even form the Pyramid API. As a result, you’ve now written code that uses internals and you’ve painted yourself into a conceptual corner as a result of needing to wrestle with some ZCA-using implementation detail. If this is you, it’s extremely hard to have a lot of sympathy for you. You’ll either need to get familiar with how we’re using the ZCA registry or you’ll need to use only the documented APIs; that’s why we document them as APIs.

If you extend or develop Pyramid (create new directives, use some of the more obscure “hooks” as described in Using Hooks, or work on the Pyramid core code), you will be faced with needing to understand at least some ZCA concepts. In some places it’s used unabashedly, and will be forever. We know it’s quirky, but it’s also useful and fundamentally understandable if you take the time to do some reading about it.

Pyramid Uses Interfaces Too Liberally

In this TOPP Engineering blog entry [http://www.coactivate.org/projects/topp-engineering/blog/2008/10/20/what-bothers-me-about-the-component-architecture/], Ian Bicking asserts that the way repoze.bfg used a Zope interface to represent an HTTP request method added too much indirection for not enough gain. We agreed in general, and for this reason, repoze.bfg version 1.1 (and subsequent versions including Pyramid 1.0+) added view predicate and route predicate modifiers to view configuration. Predicates are request-specific (or context -specific) matching narrowers which don’t use interfaces. Instead, each predicate uses a domain-specific string as a match value.

For example, to write a view configuration which matches only requests with the POST HTTP request method, you might write a @view_config decorator which mentioned the request_method predicate:

1
2
3
4

from pyramid.view import view_config
@view_config(name='post_view', request_method='POST', renderer='json')
def post_view(request):
    return 'POSTed'

You might further narrow the matching scenario by adding an accept predicate that narrows matching to something that accepts a JSON response:

1
2
3
4
5

from pyramid.view import view_config
@view_config(name='post_view', request_method='POST',
             accept='application/json', renderer='json')
def post_view(request):
    return 'POSTed'

Such a view would only match when the request indicated that HTTP request method was POST and that the remote user agent passed application/json (or, for that matter, application/*) in its Accept request header.

“Under the hood”, these features make no use of interfaces.

Many “prebaked” predicates exist. However, use of only “prebaked” predicates, however, doesn’t entirely meet Ian’s criterion. He would like to be able to match a request using a lambda or another function which interrogates the request imperatively. In repoze.bfg version 1.2, we acommodate this by allowing people to define “custom” view predicates:

1
2
3
4
5
6
7
8
9

from pyramid.view import view_config
from webob import Response

def subpath(context, request):
    return request.subpath and request.subpath[0] == 'abc'

@view_config(custom_predicates=(subpath,))
def aview(request):
    return Response('OK')

The above view will only match when the first element of the request’s subpath is abc.

Pyramid “Encourages Use of ZCML”

ZCML is a configuration language that can be used to configure the Zope Component Architecture registry that Pyramid uses for application configuration. Often people claim that Pyramid “needs ZCML”.

It doesn’t. In Pyramid 1.0, ZCML doesn’t ship as part of the core; instead it ships in the pyramid_zcml add-on package, which is completely optional. No ZCML is required at all to use Pyramid, nor any other sort of frameworky declarative frontend to application configuration.

Pyramid Uses “Model” To Represent A Node In The Graph of Objects Traversed

The repoze.bfg documentation used to refer to the graph being traversed when traversal is used as a “model graph”. A terminology overlap confused people who wrote applications that always use ORM packages such as SQLAlchemy, which has a different notion of the definition of a “model”. As a result, in Pyramid 1.0a7, the tree of objects traversed is now renamed to resource tree and its components are now named resource objects. Associated APIs have been changed. This hopefully alleviates the terminology confusion caused by overriding the term “model”.

Pyramid Does Traversal, And I Don’t Like Traversal

In Pyramid, traversal is the act of resolving a URL path to a resource object in a resource tree. Some people are uncomfortable with this notion, and believe it is wrong. Thankfully, if you use Pyramid, and you don’t want to model your application in terms of a resource tree, you needn’t use it at all. Instead, use URL dispatch to map URL paths to views.

The idea that some folks believe traversal is unilaterally “wrong” is understandable. The people who believe it is wrong almost invariably have all of their data in a relational database. Relational databases aren’t naturally hierarchical, so “traversing” one like a tree is not possible.

However, folks who deem traversal unilaterally wrong are neglecting to take into account that many persistence mechanisms are hierarchical. Examples include a filesystem, an LDAP database, a ZODB (or another type of graph) database, an XML document, and the Python module namespace. It is often convenient to model the frontend to a hierarchical data store as a graph, using traversal to apply views to objects that either are the resources in the tree being traversed (such as in the case of ZODB) or at least ones which stand in for them (such as in the case of wrappers for files from the filesystem).

Also, many website structures are naturally hierarchical, even if the data which drives them isn’t. For example, newspaper websites are often extremely hierarchical: sections within sections within sections, ad infinitum. If you want your URLs to indicate this structure, and the structure is indefinite (the number of nested sections can be “N” instead of some fixed number), a resource tree is an excellent way to model this, even if the backend is a relational database. In this situation, the resource tree a just a site structure.

Traversal also offers better composability of applications than URL dispatch, because it doesn’t rely on a fixed ordering of URL matching. You can compose a set of disparate functionality (and add to it later) around a mapping of view to resource more predictably than trying to get “the right” ordering of URL pattern matching.

But the point is ultimately moot. If you don’t want to use traversal, you needn’t. Use URL dispatch instead.

Pyramid Does URL Dispatch, And I Don’t Like URL Dispatch

In Pyramid, url dispatch is the act of resolving a URL path to a view callable by performing pattern matching against some set of ordered route definitions. The route definitions are examined in order: the first pattern which matches is used to associate the URL with a view callable.

Some people are uncomfortable with this notion, and believe it is wrong. These are usually people who are steeped deeply in Zope. Zope does not provide any mechanism except traversal to map code to URLs. This is mainly because Zope effectively requires use of ZODB, which is a hierarchical object store. Zope also supports relational databases, but typically the code that calls into the database lives somewhere in the ZODB object graph (or at least is a view related to a node in the object graph), and traversal is required to reach this code.

I’ll argue that URL dispatch is ultimately useful, even if you want to use traversal as well. You can actually combine URL dispatch and traversal in Pyramid (see Combining Traversal and URL Dispatch). One example of such a usage: if you want to emulate something like Zope 2’s “Zope Management Interface” UI on top of your object graph (or any administrative interface), you can register a route like <route name="manage" pattern="manage/*traverse"/> and then associate “management” views in your code by using the route_name argument to a view configuration, e.g. <view view=".some.callable" context=".some.Resource" route_name="manage"/>. If you wire things up this way someone then walks up to for example, /manage/ob1/ob2, they might be presented with a management interface, but walking up to /ob1/ob2 would present them with the default object view. There are other tricks you can pull in these hybrid configurations if you’re clever (and maybe masochistic) too.

Also, if you are a URL dispatch hater, if you should ever be asked to write an application that must use some legacy relational database structure, you might find that using URL dispatch comes in handy for one-off associations between views and URL paths. Sometimes it’s just pointless to add a node to the object graph that effectively represents the entry point for some bit of code. You can just use a route and be done with it. If a route matches, a view associated with the route will be called; if no route matches, Pyramid falls back to using traversal.

But the point is ultimately moot. If you use Pyramid, and you really don’t want to use URL dispatch, you needn’t use it at all. Instead, use traversal exclusively to map URL paths to views, just like you do in Zope.

Pyramid Views Do Not Accept Arbitrary Keyword Arguments

Many web frameworks (Zope, TurboGears, Pylons 1.X, Django) allow for their variant of a view callable to accept arbitrary keyword or positional arguments, which are “filled in” using values present in the request.POST or request.GET dictionaries or by values present in the “route match dictionary”. For example, a Django view will accept positional arguments which match information in an associated “urlconf” such as r'^polls/(?P<poll_id>\d+)/$:

1
2

def aview(request, poll_id):
    return HttpResponse(poll_id)

Zope, likewise allows you to add arbitrary keyword and positional arguments to any method of a resource object found via traversal:

1
2
3
4
5

from persistent import Persistent

class MyZopeObject(Persistent):
     def aview(self, a, b, c=None):
         return '%s %s %c' % (a, b, c)

When this method is called as the result of being the published callable, the Zope request object’s GET and POST namespaces are searched for keys which match the names of the positional and keyword arguments in the request, and the method is called (if possible) with its argument list filled with values mentioned therein. TurboGears and Pylons 1.X operate similarly.

Out of the box, Pyramid is configured to have none of these features. By default, pyramid view callables always accept only request and no other arguments. The rationale: this argument specification matching done aggressively can be costly, and Pyramid has performance as one of its main goals, so we’ve decided to make people, by default, obtain information by interrogating the request object within the view callable body instead of providing magic to do unpacking into the view argument list.

However, as of Pyramid 1.0a9, user code can influence the way view callables are expected to be called, making it possible to compose a system out of view callables which are called with arbitrary arguments. See Using a View Mapper.

Pyramid Provides Too Few “Rails”

By design, Pyramid is not a particularly “opinionated” web framework. It has a relatively parsimonious feature set. It contains no built in ORM nor any particular database bindings. It contains no form generation framework. It has no administrative web user interface. It has no built in text indexing. It does not dictate how you arrange your code.

Such opinionated functionality exists in applications and frameworks built on top of Pyramid. It’s intended that higher-level systems emerge built using Pyramid as a base. See also Pyramid Applications are Extensible; I Don’t Believe In Application Extensibility.

Pyramid Provides Too Many “Rails”

Pyramid provides some features that other web frameworks do not. These are features meant for use cases that might not make sense to you if you’re building a simple “bespoke” web application:

An optional way to map URLs to code using traversal which implies a walk of a resource tree.

The ability to aggregate Pyramid application configuration from multiple sources using pyramid.config.Configurator.include().

View and subscriber registrations made using interface objects instead of class objects (e.g. Using Resource Interfaces In View Configuration).

A declarative authorization system.

Multiple separate I18N translation string factories, each of which can name its own “domain”.

These features are important to the authors of Pyramid. The Pyramid authors are often commissioned to build CMS-style applications. Such applications are often “frameworky” because they have more than one deployment. Each deployment requires a slightly different composition of sub-applications, and the framework and sub-applications often need to be extensible. Because the application has more than one deployment, pluggability and extensibility is important, as maintaining multiple forks of the application, one per deployment, is extremely undesirable. Because it’s easier to extend a system that uses traversal “from the outside” than it is to do the same in a system that uses URL dispatch, each deployment uses a resource tree composed of a persistent tree of domain model objects, and uses traversal to map view callable code to resources in the tree. The resource tree contains very granular security declarations, as resources are owned and accessible by different sets of users. Interfaces are used to make unit testing and implementation substitutability easier.

In a bespoke web application, usually there’s a single canonical deployment, and therefore no possibility of multiple code forks. Extensibility is not required; the code is just changed in-place. Security requirements are often less granular. Using the features listed above will often be overkill for such an application.

If you don’t like these features, it doesn’t mean you can’t or shouldn’t use Pyramid. They are all optional, and a lot of time has been spent making sure you don’t need to know about them up-front. You can build “Pylons-1.X-style” applications using Pyramid that are purely bespoke by ignoring the features above. You may find these features handy later after building a “bespoke” web application that suddenly becomes popular and requires extensibility because it must be deployed in multiple locations.

Pyramid Is Too Big

“The Pyramid compressed tarball is almost 2MB. It must be enormous!”

No. We just ship it with test code and helper templates. Here’s a breakdown of what’s included in subdirectories of the package tree:

docs/

3.0MB

pyramid/tests/

1.1MB

pyramid/paster_templates/

804KB

pyramid/ (except for pyramd/tests and pyramid/paster_templates)

539K

The actual Pyramid runtime code is about 10% of the total size of the tarball omitting docs, helper templates used for package generation, and test code. Of the approximately 19K lines of Python code in the package, the code that actually has a chance of executing during normal operation, excluding tests and paster template Python files, accounts for approximately 5K lines of Python code. This is comparable to Pylons 1.X, which ships with a little over 2K lines of Python code, excluding tests.

Pyramid Has Too Many Dependencies

This is true. At the time of this writing, the total number of Python package distributions that Pyramid depends upon transitively is 18 if you use Python 2.6 or 2.7, or 16 if you use Python 2.4 or 2.5. This is a lot more than zero package distribution dependencies: a metric which various Python microframeworks and Django boast.

The zope.component and zope.configuration packages on which Pyramid depends have transitive dependencies on several other packages (zope.schema, zope.i18n, zope.event, zope.interface, zope.deprecation, zope.i18nmessageid). We’ve been working with the Zope community to try to collapse and untangle some of these dependencies. We’d prefer that these packages have fewer packages as transitive dependencies, and that much of the functionality of these packages was moved into a smaller number of packages.

Pyramid also has its own direct dependencies, such as Paste, Chameleon, Mako and WebOb, and some of these in turn have their own transitive dependencies.

It should be noted that Pyramid is positively lithe compared to Grok, a different Zope-based framework. As of this writing, in its default configuration, Grok has 109 package distribution dependencies. The number of dependencies required by Pyramid is many times fewer than Grok (or Zope itself, upon which Grok is based). Pyramid has a number of package distribution dependencies comparable to similarly-targeted frameworks such as Pylons 1.X.

We try not to reinvent too many wheels (at least the ones that don’t need reinventing), and this comes at the cost of some number of dependencies. However, “number of package distributions” is just not a terribly great metric to measure complexity. For example, the zope.event distribution on which Pyramid depends has a grand total of four lines of runtime code. As noted above, we’re continually trying to agitate for a collapsing of these sorts of packages into fewer distribution files.

Pyramid “Cheats” To Obtain Speed

Complaints have been lodged by other web framework authors at various times that Pyramid “cheats” to gain performance. One claimed cheating mechanism is our use (transitively) of the C extensions provided by zope.interface to do fast lookups. Another claimed cheating mechanism is the religious avoidance of extraneous function calls.

If there’s such a thing as cheating to get better performance, we want to cheat as much as possible. We optimize Pyramid aggressively. This comes at a cost: the core code has sections that could be expressed more readably. As an amelioration, we’ve commented these sections liberally.

Pyramid Gets Its Terminology Wrong (“MVC”)

“I’m a MVC web framework user, and I’m confused. Pyramid calls the controller a view! And it doesn’t have any controllers.”

If you are in this camp, you might have come to expect things about how your existing “MVC” framework uses its terminology. For example, you probably expect that models are ORM models, controllers are classes that have methods that map to URLs, and views are templates. Pyramid indeed has each of these concepts, and each probably works almost exactly like your existing “MVC” web framework. We just don’t use the “MVC” terminology, as we can’t square its usage in the web framework space with historical reality.

People very much want to give web applications the same properties as common desktop GUI platforms by using similar terminology, and to provide some frame of reference for how various components in the common web framework might hang together. But in the opinion of the author, “MVC” doesn’t match the web very well in general. Quoting from the Model-View-Controller Wikipedia entry [http://en.wikipedia.org/wiki/Model–view–controller]:

Though MVC comes in different flavors, control flow is generally as
follows:

  The user interacts with the user interface in some way (for
  example, presses a mouse button).

  The controller handles the input event from the user interface,
  often via a registered handler or callback and converts the event
  into appropriate user action, understandable for the model.

  The controller notifies the model of the user action, possibly
  resulting in a change in the model's state. (For example, the
  controller updates the user's shopping cart.)[5]

  A view queries the model in order to generate an appropriate
  user interface (for example, the view lists the shopping cart's
  contents). Note that the view gets its own data from the model.

  The controller may (in some implementations) issue a general
  instruction to the view to render itself. In others, the view is
  automatically notified by the model of changes in state
  (Observer) which require a screen update.

  The user interface waits for further user interactions, which
  restarts the cycle.

To the author, it seems as if someone edited this Wikipedia definition, tortuously couching concepts in the most generic terms possible in order to account for the use of the term “MVC” by current web frameworks. I doubt such a broad definition would ever be agreed to by the original authors of the MVC pattern. But even so, it seems most “MVC” web frameworks fail to meet even this falsely generic definition.

For example, do your templates (views) always query models directly as is claimed in “note that the view gets its own data from the model”? Probably not. My “controllers” tend to do this, massaging the data for easier use by the “view” (template). What do you do when your “controller” returns JSON? Do your controllers use a template to generate JSON? If not, what’s the “view” then? Most MVC-style GUI web frameworks have some sort of event system hooked up that lets the view detect when the model changes. The web just has no such facility in its current form: it’s effectively pull-only.

So, in the interest of not mistaking desire with reality, and instead of trying to jam the square peg that is the web into the round hole of “MVC”, we just punt and say there are two things: resources and views. The resource tree represents a site structure, the view presents a resource. The templates are really just an implementation detail of any given view: a view doesn’t need a template to return a response. There’s no “controller”: it just doesn’t exist. The “model” is either represented by the resource tree or by a “domain model” (like a SQLAlchemy model) that is separate from the framework entirely. This seems to us like more reasonable terminology, given the current constraints of the web.

Pyramid Applications are Extensible; I Don’t Believe In Application Extensibility

Any Pyramid application written obeying certain constraints is extensible. This feature is discussed in the Pyramid documentation chapters named Extending An Existing Pyramid Application and Advanced Configuration. It is made possible by the use of the Zope Component Architecture and within Pyramid.

“Extensible”, in this context, means:

The behavior of an application can be overridden or extended in a particular deployment of the application without requiring that the deployer modify the source of the original application.

The original developer is not required to anticipate any extensibility plugpoints at application creation time to allow fundamental application behavior to be overriden or extended.

The original developer may optionally choose to anticipate an application-specific set of plugpoints, which may be hooked by a deployer. If he chooses to use the facilities provided by the ZCA, the original developer does not need to think terribly hard about the mechanics of introducing such a plugpoint.

Many developers seem to believe that creating extensible applications is “not worth it”. They instead suggest that modifying the source of a given application for each deployment to override behavior is more reasonable. Much discussion about version control branching and merging typically ensues.

It’s clear that making every application extensible isn’t required. The majority of web applications only have a single deployment, and thus needn’t be extensible at all. However, some web applications have multiple deployments, and some have many deployments. For example, a generic “content management” system (CMS) may have basic functionality that needs to be extended for a particular deployment. That CMS system may be deployed for many organizations at many places. Some number of deployments of this CMS may be deployed centrally by a third party and managed as a group. It’s useful to be able to extend such a system for each deployment via preordained plugpoints than it is to continually keep each software branch of the system in sync with some upstream source: the upstream developers may change code in such a way that your changes to the same codebase conflict with theirs in fiddly, trivial ways. Merging such changes repeatedly over the lifetime of a deployment can be difficult and time consuming, and it’s often useful to be able to modify an application for a particular deployment in a less invasive way.

If you don’t want to think about Pyramid application extensibility at all, you needn’t. You can ignore extensibility entirely. However, if you follow the set of rules defined in Extending An Existing Pyramid Application, you don’t need to make your application extensible: any application you write in the framework just is automatically extensible at a basic level. The mechanisms that deployers use to extend it will be necessarily coarse: typically, views, routes, and resources will be capable of being overridden. But for most minor (and even some major) customizations, these are often the only override plugpoints necessary: if the application doesn’t do exactly what the deployment requires, it’s often possible for a deployer to override a view, route, or resource and quickly make it do what he or she wants it to do in ways not necessarily anticipated by the original developer. Here are some example scenarios demonstrating the benefits of such a feature.

If a deployment needs a different styling, the deployer may override the main template and the CSS in a separate Python package which defines overrides.

If a deployment needs an application page to do something differently needs it to expose more or different information, the deployer may override the view that renders the page within a separate Python package.

If a deployment needs an additional feature, the deployer may add a view to the override package.

As long as the fundamental design of the upstream package doesn’t change, these types of modifications often survive across many releases of the upstream package without needing to be revisited.

Extending an application externally is not a panacea, and carries a set of risks similar to branching and merging: sometimes major changes upstream will cause you to need to revisit and update some of your modifications. But you won’t regularly need to deal wth meaningless textual merge conflicts that trivial changes to upstream packages often entail when it comes time to update the upstream package, because if you extend an application externally, there just is no textual merge done. Your modifications will also, for whatever its worth, be contained in one, canonical, well-defined place.

Branching an application and continually merging in order to get new features and bugfixes is clearly useful. You can do that with a Pyramid application just as usefully as you can do it with any application. But deployment of an application written in Pyramid makes it possible to avoid the need for this even if the application doesn’t define any plugpoints ahead of time. It’s possible that promoters of competing web frameworks dismiss this feature in favor of branching and merging because applications written in their framework of choice aren’t extensible out of the box in a comparably fundamental way.

While Pyramid application are fundamentally extensible even if you don’t write them with specific extensibility in mind, if you’re moderately adventurous, you can also take it a step further. If you learn more about the Zope Component Architecture, you can optionally use it to expose other more domain-specific configuration plugpoints while developing an application. The plugpoints you expose needn’t be as coarse as the ones provided automatically by Pyramid itself. For example, you might compose your own directive that configures a set of views for a prebaked purpose (e.g. restview or somesuch) , allowing other people to refer to that directive when they make declarations in the includeme of their customization package. There is a cost for this: the developer of an application that defines custom plugpoints for its deployers will need to understand the ZCA or he will need to develop his own similar extensibility system.

Ultimately, any argument about whether the extensibility features lent to applications by Pyramid are “good” or “bad” is mostly pointless. You needn’t take advantage of the extensibility features provided by a particular Pyramid application in order to affect a modification for a particular set of its deployments. You can ignore the application’s extensibility plugpoints entirely, and instead use version control branching and merging to manage application deployment modifications instead, as if you were deploying an application written using any other web framework.

Zope 3 Enforces “TTW” Authorization Checks By Default; Pyramid Does Not

Challenge

Pyramid performs automatic authorization checks only at view execution time. Zope 3 wraps context objects with a security proxy [http://wiki.zope.org/zope3/WhatAreSecurityProxies], which causes Zope 3 to do also security checks during attribute access. I like this, because it means:

When I use the security proxy machinery, I can have a view that conditionally displays certain HTML elements (like form fields) or prevents certain attributes from being modified depending on the the permissions that the accessing user possesses with respect to a context object.

I want to also expose my resources via a REST API using Twisted Web. If Pyramid performed authorization based on attribute access via Zope3’s security proxies, I could enforce my authorization policy in both Pyramid and in the Twisted-based system the same way.

Defense

Pyramid was developed by folks familiar with Zope 2, which has a “through the web” security model. This “TTW” security model was the precursor to Zope 3’s security proxies. Over time, as the Pyramid developers (working in Zope 2) created such sites, we found authorization checks during code interpretation extremely useful in a minority of projects. But much of the time, TTW authorization checks usually slowed down the development velocity of projects that had no delegation requirements. In particular, if we weren’t allowing “untrusted” users to write arbitrary Python code to be executed by our application, the burden of “through the web” security checks proved too costly to justify. We (collectively) haven’t written an application on top of which untrusted developers are allowed to write code in many years, so it seemed to make sense to drop this model by default in a new web framework.

And since we tend to use the same toolkit for all web applications, it’s just never been a concern to be able to use the same set of restricted-execution code under two web different frameworks.

Justifications for disabling security proxies by default notwithstanding, given that Zope 3 security proxies are “viral” by nature, the only requirement to use one is to make sure you wrap a single object in a security proxy and make sure to access that object normally when you want proxy security checks to happen. It is possible to override the Pyramid “traverser” for a given application (see Changing the Traverser). To get Zope3-like behavior, it is possible to plug in a different traverser which returns Zope3-security-proxy-wrapped objects for each traversed object (including the context and the root). This would have the effect of creating a more Zope3-like environment without much effort.

Microframeworks Have Smaller Hello World Programs

Self-described “microframeworks” exist: Bottle [http://bottle.paws.de] and Flask [http://flask.pocoo.org/] are two that are becoming popular. Bobo [http://bobo.digicool.com/] doesn’t describe itself as a microframework, but its intended userbase is much the same. Many others exist. We’ve actually even (only as a teaching tool, not as any sort of official project) created one using BFG [http://bfg.repoze.org/videos#groundhog1] (the precursor to Pyramid). Microframeworks are small frameworks with one common feature: each allows its users to create a fully functional application that lives in a single Python file.

Some developers and microframework authors point out that Pyramid’s “hello world” single-file program is longer (by about five lines) than the equivalent program in their favorite microframework. Guilty as charged.

This loss isn’t for lack of trying. Pyramid is useful in the same circumstance in which microframeworks claim dominance: single-file applications. But Pyramid doesn’t sacrifice its ability to credibly support larger applications in order to achieve hello-world LoC parity with the current crop of microframeworks. Pyramid’s design instead tries to avoid some common pitfalls associated with naive declarative configuration schemes. The subsections which follow explain the rationale.

Application Programmers Don’t Control The Module-Scope Codepath (Import-Time Side-Effects Are Evil)

Please imagine a directory structure with a set of Python files in it:

.
|-- app.py
|-- app2.py
`-- config.py

The contents of app.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from config import decorator
from config import L
import pprint

@decorator
def foo():
    pass

if __name__ == '__main__':
    import app2
    pprint.pprint(L)

The contents of app2.py:

1
2
3
4
5

import app

@app.decorator
def bar():
    pass

The contents of config.py:

1
2
3
4
5

  L = []

  def decorator(func):
      L.append(func)
      return func

If we cd to the directory that holds these files and we run python app.py given the directory structure and code above, what happens? Presumably, our decorator decorator will be used twice, once by the decorated function foo in app.py and once by the decorated function bar in app2.py. Since each time the decorator is used, the list L in config.py is appended to, we’d expect a list with two elements to be printed, right? Sadly, no:

[chrism@thinko]$ python app.py
[<function foo at 0x7f4ea41ab1b8>,
 <function foo at 0x7f4ea41ab230>,
 <function bar at 0x7f4ea41ab2a8>]

By visual inspection, that outcome (three different functions in the list) seems impossible. We only defined two functions and we decorated each of those functions only once, so we believe that the decorator decorator will only run twice. However, what we believe is wrong because the code at module scope in our app.py module was executed twice. The code is executed once when the script is run as __main__ (via python app.py), and then it is executed again when app2.py imports the same file as app.

What does this have to do with our comparison to microframeworks? Many microframeworks in the current crop (e.g. Bottle, Flask) encourage you to attach configuration decorators to objects defined at module scope. These decorators execute arbitrarily complex registration code which populates a singleton registry that is a global defined in external Python module. This is analogous to the above example: the “global registry” in the above example is the list L.

Let’s see what happens when we use the same pattern with the Groundhog [https://github.com/Pylons/groundhog] microframework. Replace the contents of app.py above with this:

1
2
3
4
5
6
7
8
9

from config import gh

@gh.route('/foo/')
def foo():
    return 'foo'

if __name__ == '__main__':
    import app2
    pprint.pprint(L)

Replace the contents of app2.py above with this:

1
2
3
4
5

import app

@app.gh.route('/bar/')
def bar():
    'return bar'

Replace the contents of config.py above with this:

1
2

from groundhog import Groundhog
gh = Groundhog('myapp', 'seekrit')

How many routes will be registered within the routing table of the “gh” Groundhog application? If you answered three, you are correct. How many would a casual reader (and any sane developer) expect to be registered? If you answered two, you are correct. Will the double registration be a problem? With our Groundhog framework’s route method backing this application, not really. It will slow the application down a little bit, because it will need to miss twice for a route when it does not match. Will it be a problem with another framework, another application, or another decorator? Who knows. You need to understand the application in its totality, the framework in its totality, and the chronology of execution to be able to predict what the impact of unintentional code double-execution will be.

The encouragement to use decorators which perform population of an external registry has an unintended consequence: the application developer now must assert ownership of every codepath that executes Python module scope code. Module-scope code is presumed by the current crop of decorator-based microframeworks to execute once and only once; if it executes more than once, weird things will start to happen. It is up to the application developer to maintain this invariant. Unfortunately, however, in reality, this is an impossible task, because, Python programmers do not own the module scope codepath, and never will. Anyone who tries to sell you on the idea that they do is simply mistaken. Test runners that you may want to use to run your code’s tests often perform imports of arbitrary code in strange orders that manifest bugs like the one demonstrated above. API documentation generation tools do the same. Some people even think it’s safe to use the Python reload command or delete objects from sys.modules, each of which has hilarious effects when used against code that has import-time side effects.

Global-registry-mutating microframework programmers therefore will at some point need to start reading the tea leaves about what might happen if module scope code gets executed more than once like we do in the previous paragraph. When Python programmers assume they can use the module-scope codepath to run arbitrary code (especially code which populates an external registry), and this assumption is challenged by reality, the application developer is often required to undergo a painful, meticulous debugging process to find the root cause of an inevitably obscure symptom. The solution is often to rearrange application import ordering or move an import statement from module-scope into a function body. The rationale for doing so can never be expressed adequately in the checkin message which accompanies the fix and can’t be documented succinctly enough for the benefit of the rest of the development team so that the problem never happens again. It will happen again, especially if you are working on a project with other people who haven’t yet internalized the lessons you learned while you stepped through module-scope code using pdb. This is a really pretty poor situation to find yourself in as an application developer: you probably didn’t even know your or your team signed up for the job, because the documentation offered by decorator-based microframeworks don’t warn you about it.

Folks who have a large investment in eager decorator-based configuration that populates an external data structure (such as microframework authors) may argue that the set of circumstances I outlined above is anomalous and contrived. They will argue that it just will never happen. If you never intend your application to grow beyond one or two or three modules, that’s probably true. However, as your codebase grows, and becomes spread across a greater number of modules, the circumstances in which module-scope code will be executed multiple times will become more and more likely to occur and less and less predictable. It’s not responsible to claim that double-execution of module-scope code will never happen. It will; it’s just a matter of luck, time, and application complexity.

If microframework authors do admit that the circumstance isn’t contrived, they might then argue that “real” damage will never happen as the result of the double-execution (or triple-execution, etc) of module scope code. You would be wise to disbelieve this assertion. The potential outcomes of multiple execution are too numerous to predict because they involve delicate relationships between application and framework code as well as chronology of code execution. It’s literally impossible for a framework author to know what will happen in all circumstances. But even if given the gift of omniscience for some limited set of circumstances, the framework author almost certainly does not have the double-execution anomaly in mind when coding new features. He’s thinking of adding a feature, not protecting against problems that might be caused by the 1% multiple execution case. However, any 1% case may cause 50% of your pain on a project, so it’d be nice if it never occured.

Responsible microframeworks actually offer a back-door way around the problem. They allow you to disuse decorator based configuration entirely. Instead of requiring you to do the following:

1
2
3
4
5
6
7
8

gh = Groundhog('myapp', 'seekrit')

@gh.route('/foo/')
def foo():
    return 'foo'

if __name__ == '__main__':
    gh.run()

They allow you to disuse the decorator syntax and go almost-all-imperative:

1
2
3
4
5
6
7
8

def foo():
    return 'foo'

gh = Groundhog('myapp', 'seekrit')

if __name__ == '__main__':
    gh.add_route(foo, '/foo/')
    gh.run()

This is a generic mode of operation that is encouraged in the Pyramid documentation. Some existing microframeworks (Flask, in particular) allow for it as well. None (other than Pyramid) encourage it. If you never expect your application to grow beyond two or three or four or ten modules, it probably doesn’t matter very much which mode you use. If your application grows large, however, imperative configuration can provide better predictability.

Note

Astute readers may notice that Pyramid has configuration decorators too. Aha! Don’t these decorators have the same problems? No. These decorators do not populate an external Python module when they are executed. They only mutate the functions (and classes and methods) they’re attached to. These mutations must later be found during a “scan” process that has a predictable and structured import phase. Module-localized mutation is actually the best-case circumstance for double-imports; if a module only mutates itself and its contents at import time, if it is imported twice, that’s OK, because each decorator invocation will always be mutating an independent copy of the object its attached to, not a shared resource like a registry in another module. This has the effect that double-registrations will never be performed.

Routes (Usually) Need Relative Ordering

Consider the following simple Groundhog [https://github.com/Pylons/groundhog] application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

from groundhog import Groundhog
app = Groundhog('myapp', 'seekrit')

app.route('/admin')
def admin():
    return '<html>admin page</html>'

app.route('/:action')
def action():
    if action == 'add':
       return '<html>add</html>'
    if action == 'delete':
       return '<html>delete</html>'
    return app.abort(404)

if __name__ == '__main__':
    app.run()

If you run this application and visit the URL /admin, you will see “admin” page. This is the intended result. However, what if you rearrange the order of the function definitions in the file?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

from groundhog import Groundhog
app = Groundhog('myapp', 'seekrit')

app.route('/:action')
def action():
    if action == 'add':
       return '<html>add</html>'
    if action == 'delete':
       return '<html>delete</html>'
    return app.abort(404)

app.route('/admin')
def admin():
    return '<html>admin page</html>'

if __name__ == '__main__':
    app.run()

If you run this application and visit the URL /admin, you will now be returned a 404 error. This is probably not what you intended. The reason you see a 404 error when you rearrange function definition ordering is that routing declarations expressed via our microframework’s routing decorators have an ordering, and that ordering matters.

In the first case, where we achieved the expected result, we first added a route with the pattern /admin, then we added a route with the pattern /:action by virtue of adding routing patterns via decorators at module scope. When a request with a PATH_INFO of /admin enters our application, the web framework loops over each of our application’s route patterns in the order in which they were defined in our module. As a result, the view associated with the /admin routing pattern will be invoked: it matches first. All is right with the world.

In the second case, where we did not achieve the expected result, we first added a route with the pattern /:action, then we added a route with the pattern /admin. When a request with a PATH_INFO of /admin enters our application, the web framework loops over each of our application’s route patterns in the order in which they were defined in our module. As a result, the view associated with the /:action routing pattern will be invoked: it matches first. A 404 error is raised. This is not what we wanted; it just happened due to the order in which we defined our view functions.

You may be willing to maintain an ordering of your view functions which reifies your routing policy. Your application may be small enough where this will never cause an issue. If it becomes large enough to matter, however, I don’t envy you. Maintaining that ordering as your application grows larger will be difficult. At some point, you will also need to start controlling import ordering as well as function definition ordering. When your application grows beyond the size of a single file, and when decorators are used to register views, the non-__main__ modules which contain configuration decorators must be imported somehow for their configuration to be executed.

Does that make you a little uncomfortable? It should, because Application Programmers Don’t Control The Module-Scope Codepath (Import-Time Side-Effects Are Evil).

“Stacked Object Proxies” Are Too Clever / Thread Locals Are A Nuisance

In another manifestation of “import fascination”, some microframeworks use the import statement to get a handle to an object which is not logically global:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from flask import request

@app.route('/login', methods=['POST', 'GET'])
def login():
    error = None
    if request.method == 'POST':
        if valid_login(request.form['username'],
                       request.form['password']):
            return log_the_user_in(request.form['username'])
        else:
            error = 'Invalid username/password'
    # this is executed if the request method was GET or the
    # credentials were invalid

The Pylons 1.X [http://pylonsproject.org] web framework uses a similar strategy. It calls these things “Stacked Object Proxies”, so, for purposes of this discussion, I’ll do so as well.

Import statements in Python (import foo, from bar import baz) are most frequently performed to obtain a reference to an object defined globally within an external Python module. However, in “normal” programs, they are never used to obtain a reference to an object that has a lifetime measured by the scope of the body of a function. It would be absurd to try to import, for example, a variable named i representing a loop counter defined in the body of a function. For example, we’d never try to import i from the code below:

1
2
3

def afunc():
    for i in range(10):
        print i

By its nature, the request object created as the result of a WSGI server’s call into a long-lived web framework cannot be global, because the lifetime of a single request will be much shorter than the lifetime of the process running the framework. A request object created by a web framework actually has more similarity to the i loop counter in our example above than it has to any comparable importable object defined in the Python standard library or in “normal” library code.

However, systems which use stacked object proxies promote locally scoped objects such as request out to module scope, for the purpose of being able to offer users a “nice” spelling involving import. They, for what I consider dubious reasons, would rather present to their users the canonical way of getting at a request as from framework import request instead of a saner from myframework.threadlocals import get_request; request = get_request() even though the latter is more explicit.

It would be most explicit if the microframeworks did not use thread local variables at all. Pyramid view functions are passed a request object; many of Pyramid’s APIs require that an explicit request object be passed to them. It is possible to retrieve the current Pyramid request as a threadlocal variable but it is a “in case of emergency, break glass” type of activity. This explicitness makes Pyramid view functions more easily unit testable, as you don’t need to rely on the framework to manufacture suitable “dummy” request (and other similarly-scoped) objects during test setup. It also makes them more likely to work on arbitrary systems, such as async servers that do no monkeypatching.

Explicitly WSGI

Some microframeworks offer a run() method of an application object that executes a default server configuration for easy execution.

Pyramid doesn’t currently try to hide the fact that its router is a WSGI application behind a convenience run() API. It just tells people to import a WSGI server and use it to serve up their Pyramid application as per the documentation of that WSGI server.

The extra lines saved by abstracting away the serving step behind run() seem to have driven dubious second-order decisions related to API in some microframeworks. For example, Bottle contains a ServerAdapter subclass for each type of WSGI server it supports via its app.run() mechanism. This means that there exists code in bottle.py that depends on the following modules: wsgiref, flup, paste, cherrypy, fapws, tornado, google.appengine, twisted.web, diesel, gevent, gunicorn, eventlet, and rocket. You choose the kind of server you want to run by passing its name into the run method. In theory, this sounds great: I can try Bottle out on gunicorn just by passing in a name! However, to fully test Bottle, all of these third-party systems must be installed and functional; the Bottle developers must monitor changes to each of these packages and make sure their code still interfaces properly with them. This expands the packages required for testing greatly; this is a lot of requirements. It is likely difficult to fully automate these tests due to requirements conflicts and build issues.

As a result, for single-file apps, we currently don’t bother to offer a run() shortcut; we tell folks to import their WSGI server of choice and run it “by hand”. For the people who want a server abstraction layer, we suggest that they use PasteDeploy. In PasteDeploy-based systems, the onus for making sure that the server can interface with a WSGI application is placed on the server developer, not the web framework developer, making it more likely to be timely and correct.

Wrapping Up

Here’s a diagrammed version of the simplest pyramid application, where comments take into account what we’ve discussed in the Microframeworks Have Smaller Hello World Programs section.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from webob import Response                 # explicit response objects, no TL
from paste.httpserver import serve         # explicitly WSGI

def hello_world(request):  # accepts a request; no request thread local reqd
    # explicit response object means no response threadlocal
    return Response('Hello world!')

if __name__ == '__main__':
    from pyramid.config import Configurator
    config = Configurator()       # no global application object.
    config.add_view(hello_world)  # explicit non-decorator registration
    app = config.make_wsgi_app()  # explicitly WSGI
    serve(app, host='0.0.0.0')    # explicitly WSGI

Pyramid Has Zope Things In It, So It’s Too Complex

On occasion, someone will feel compelled to post a mailing list message that reads something like this:

had a quick look at pyramid ... too complex to me and not really
understand for which benefits.. I feel should consider whether it's time
for me to step back to django .. I always hated zope (useless ?)
complexity and I love simple way of thinking

(Paraphrased from a real email, actually.)

Let’s take this criticism point-by point.

Too Complex

If you can understand this hello world program, you can use Pyramid:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from paste.httpserver import serve
from pyramid.config import Configurator
from pyramid.response import Response

def hello_world(request):
    return Response('Hello world!')

if __name__ == '__main__':
    config = Configurator()
    config.add_view(hello_world)
    app = config.make_wsgi_app()
    serve(app)

Pyramid has ~ 650 pages of documentation (printed), covering topics from the very basic to the most advanced. Nothing is left undocumented, quite literally. It also has an awesome, very helpful community. Visit the #repoze and/or #pylons IRC channels on freenode.net and see.

Hate Zope

I’m sorry you feel that way. The Zope brand has certainly taken its share of lumps over the years, and has a reputation for being insular and mysterious. But the word “Zope” is literally quite meaningless without qualification. What part of Zope do you hate? “Zope” is a brand, not a technology.

If it’s Zope2-the-web-framework, Pyramid is not that. The primary designers and developers of Pyramid, if anyone, should know. We wrote Pyramid’s predecessor (repoze.bfg), in part, because we knew that Zope 2 had usability issues and limitations. repoze.bfg (and now Pyramid) was written to address these issues.

If it’s Zope3-the-web-framework, Pyramid is definitely not that. Making use of lots of Zope 3 technologies is territory already staked out by the Grok project. Save for the obvious fact that they’re both web frameworks, Pyramid is very, very different than Grok. Grok exposes lots of Zope technologies to end users. On the other hand, if you need to understand a Zope-only concept while using Pyramid, then we’ve failed on some very basic axis.

If it’s just the word Zope: this can only be guilt by association. Because a piece of software internally uses some package named zope.foo, it doesn’t turn the piece of software that uses it into “Zope”. There is a lot of great software written that has the word Zope in its name. Zope is not some sort of monolithic thing, and a lot of its software is usable externally. And while it’s not really the job of this document to defend it, Zope has been around for over 10 years and has an incredibly large, active community. If you don’t believe this, http://taichino.appspot.com/pypi_ranking/authors is an eye-opening reality check.

Love Simplicity

Years of effort have gone into honing this package and its documentation to make it as simple as humanly possible for developers to use. Everything is a tradeoff, of course, and people have their own ideas about what “simple” is. You may have a style difference if you believe Pyramid is complex. Its developers obviously disagree.

Other Challenges

Other challenges are encouraged to be sent to the Pylons-devel [http://groups.google.com/group/pylons-devel] maillist. We’ll try to address them by considering a design change, or at very least via exposition here.

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

The Pyramid Web Application Development Framework v1.0 »

Python Module Index

p

| p |
- | pyramid |
|     pyramid.authentication |
|     pyramid.authorization |
|     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 |

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.

Navigation

index

modules |

The Pyramid Web Application Development Framework v1.0 »

Index

_ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | Z

_

__call__() (IRoutePregenerator method)

(ISessionFactory method)

(IViewMapper method)

(IViewMapperFactory method)

__contains__() (IBeforeRender method)

(ISession method)

__delitem__() (ISession method)

__getitem__() (IBeforeRender method)

(ISession method)

__init__.py

__iter__() (ISession method)

__len__() (ISession method)

__setitem__() (IBeforeRender method)

(ISession method)

A

absolute_asset_spec() (Configurator method)

accept (Request attribute)

accept_charset (Request attribute)

accept_encoding (Request attribute)

accept_language (Request attribute)

accept_ranges (Response attribute)

access control entry

access control list

ACE, [1]

(special)

ACL, [1]

ACL inheritance

ACLAllowed (class in pyramid.security)

ACLAuthorizationPolicy (class in pyramid.authorization)

ACLDenied (class in pyramid.security)

action() (Configurator method)

activating

translation

add_directive() (Configurator method)

add_finished_callback() (Request method), [1]

add_renderer() (Configurator method)

add_response_callback() (Request method), [1]

add_route

add_route() (Configurator method)

add_settings() (Configurator method)

add_static_view

add_static_view() (Configurator method)

add_subscriber() (Configurator method)

add_translation_dirs() (Configurator method)

add_view

add_view() (Configurator method)

advanced

configuration

age (Response attribute)

Agendaless Consulting, [1], [2]

Akkerman, Wichert

ALL_PERMISSIONS (in module pyramid.security)

Allow (in module pyramid.security)

allow (Response attribute)

Allowed (class in pyramid.security)

app (IApplicationCreated attribute)

app_iter (Response attribute)

app_iter_range() (Response method)

append_slash_notfound_view() (in module pyramid.view)

AppendSlashNotFoundViewFactory (class in pyramid.view)

application configuration

application registry, [1]

application_url (Request attribute)

ApplicationCreated (class in pyramid.events)

asbool() (in module pyramid.settings)

assert_() (DummyTemplateRenderer method)

asset

asset specification

assets

overriding, [1]

Authenticated (in module pyramid.security)

authenticated_userid() (in module pyramid.security)

authentication

authentication policy

(creating)

authorization

(Request attribute)

authorization policy, [1]

(creating)

AuthTktAuthenticationPolicy (class in pyramid.authentication)

AuthTktCookieHelper (class in pyramid.authentication)

automatic reloading of templates

B

Babel, [1], [2]

message extractors

Bangert, Ben

Beaker

before render event

BeforeRender (class in pyramid.events)

begin() (Configurator method)

bfg2pyramid

Bicking, Ian, [1]

blank() (pyramid.request.Request class method)

body (Request attribute)

(Response attribute)

body_file (Request attribute)

(Response attribute)

book audience

book content overview

Borch, Malthe

Brandl, Georg

built-in renderers

C

cache_control (Request attribute)

(Response attribute)

call_application() (Request method)

chameleon

renderer

Chameleon

translation strings

Chameleon text templates

Chameleon ZPT macros

Chameleon ZPT templates

changed() (ISession method)

charset (Request attribute)

(Response attribute)

cleanUp() (in module pyramid.testing)

clear() (ISession method)

clone() (DummyResource method)

code scanning

commit() (Configurator method)

compiling

message catalog

conditional_response_app() (Response method)

configuration

advanced

configuration declaration

configuration decoration, [1]

configuration decorator

ConfigurationError (class in pyramid.exceptions)

configurator

Configurator

(class in pyramid.config)

Configurator testing API

container resources

content_disposition (Response attribute)

content_encoding (Response attribute)

content_language (Response attribute)

content_length (Request attribute)

(Response attribute)

content_location (Response attribute)

content_md5 (Response attribute)

content_range (Response attribute)

content_type (Request attribute)

(Response attribute)

content_type_params (Response attribute)

context, [1]

(Request attribute)

ContextFound (class in pyramid.events)

converting a BFG app

cookies (Request attribute)

copy() (Request method)

(Response method)

copy_body() (Request method)

copy_get() (Request method)

CPython

created (ISession attribute)

creating a project

cross-site request forgery attacks, prevention

current_route_url() (in module pyramid.url)

D

date (Request attribute)

(Response attribute)

date and currency formatting (i18n)

de la Guardia, Carlos

debug settings

debug_all

debug_authorization

debug_notfound

debugging authorization failures

debugging not found errors

declarative configuration

decorator

Default Locale Name

default permission

default view

Default view

default_locale_name, [1]

default_locale_negotiator() (in module pyramid.i18n)

delete_cookie() (Response method)

Denied (class in pyramid.security)

Deny (in module pyramid.security)

DENY_ALL (in module pyramid.security)

Deployment settings

derive_view() (Configurator method)

development install

distribution

distutils

Django, [1], [2]

domain

translation

domain model

dotted Python name

DummyRequest (class in pyramid.testing)

DummyResource (class in pyramid.testing)

DummyTemplateRenderer (class in pyramid.testing)

Duncan, Casey

E

effective_principals() (in module pyramid.security)

encode_content() (Response method)

end() (Configurator method)

entry point

environ (Response attribute)

environment variables, [1]

etag (Response attribute)

event, [1]

Everitt, Paul

Everyone (in module pyramid.security)

exception (Request attribute)

Exception view

exception views

expires (Response attribute)

extending an existing application

extensible application

extracting

messages

F

factory (IRoute attribute)

find_interface() (in module pyramid.traversal)

find_resource() (in module pyramid.traversal)

find_root() (in module pyramid.traversal)

finished callback, [1]

flash messages

flash()

(ISession method)

Forbidden (class in pyramid.exceptions)

Forbidden view

forbidden view, [1]

forget() (in module pyramid.security)

forms, views, and unicode

framework

frameworks vs. libraries

from_file() (pyramid.request.Request class method)

(pyramid.response.Response class method)

Fulton, Jim

functional testing

functional tests

G

generate() (IRoute method)

generating

resource url

generating route URLs

generating static asset urls

Genshi

GET (Request attribute)

get() (BeforeRender method)

(IBeforeRender method)

(ISession method)

get_app() (in module pyramid.paster)

get_csrf_token() (ISession method)

get_current_registry, [1], [2]

get_current_registry() (in module pyramid.threadlocal)

get_current_request

get_current_request() (in module pyramid.threadlocal)

get_locale_name

get_locale_name() (in module pyramid.i18n)

get_localizer

get_localizer() (in module pyramid.i18n)

get_renderer() (in module pyramid.renderers)

get_response() (Request method)

get_root() (in module pyramid.scripting)

get_settings() (Configurator method)

(in module pyramid.settings)

get_template() (in module pyramid.chameleon_text)

(in module pyramid.chameleon_zpt)

getGlobalSiteManager

getSiteManager, [1]

gettext

Gettext

getUtility, [1]

Google App Engine

Grok

H

Hardwick, Nat

has_permission() (in module pyramid.security)

Hathaway, Shane

headerlist (Response attribute)

headers (Request attribute)

(Response attribute)

helloworld (imperative)

Holth, Daniel

hook_zca (configurator method)

hook_zca() (Configurator method)

host (Request attribute)

host_url (Request attribute)

http redirect (from a view)

HTTPAccepted (class in pyramid.httpexceptions)

HTTPBadGateway (class in pyramid.httpexceptions)

HTTPBadRequest (class in pyramid.httpexceptions)

HTTPClientError (class in pyramid.httpexceptions)

HTTPConflict (class in pyramid.httpexceptions)

HTTPCreated (class in pyramid.httpexceptions)

HTTPError (class in pyramid.httpexceptions)

HTTPException (class in pyramid.httpexceptions)

HTTPExpectationFailed (class in pyramid.httpexceptions)

HTTPForbidden (class in pyramid.httpexceptions)

HTTPFound (class in pyramid.httpexceptions)

HTTPGatewayTimeout (class in pyramid.httpexceptions)

HTTPGone (class in pyramid.httpexceptions)

HTTPInternalServerError (class in pyramid.httpexceptions)

HTTPLengthRequired (class in pyramid.httpexceptions)

HTTPMethodNotAllowed (class in pyramid.httpexceptions)

HTTPMovedPermanently (class in pyramid.httpexceptions)

HTTPMultipleChoices (class in pyramid.httpexceptions)

HTTPNoContent (class in pyramid.httpexceptions)

HTTPNonAuthoritativeInformation (class in pyramid.httpexceptions)

HTTPNotAcceptable (class in pyramid.httpexceptions)

HTTPNotFound (class in pyramid.httpexceptions)

HTTPNotImplemented (class in pyramid.httpexceptions)

HTTPNotModified (class in pyramid.httpexceptions)

HTTPOk (class in pyramid.httpexceptions)

HTTPPartialContent (class in pyramid.httpexceptions)

HTTPPaymentRequired (class in pyramid.httpexceptions)

HTTPPreconditionFailed (class in pyramid.httpexceptions)

HTTPProxyAuthenticationRequired (class in pyramid.httpexceptions)

HTTPRedirection (class in pyramid.httpexceptions)

HTTPRequestEntityTooLarge (class in pyramid.httpexceptions)

HTTPRequestRangeNotSatisfiable (class in pyramid.httpexceptions)

HTTPRequestTimeout (class in pyramid.httpexceptions)

HTTPRequestURITooLong (class in pyramid.httpexceptions)

HTTPResetContent (class in pyramid.httpexceptions)

HTTPSeeOther (class in pyramid.httpexceptions)

HTTPServerError (class in pyramid.httpexceptions)

HTTPServiceUnavailable (class in pyramid.httpexceptions)

HTTPTemporaryRedirect (class in pyramid.httpexceptions)

HTTPUnauthorized (class in pyramid.httpexceptions)

HTTPUnsupportedMediaType (class in pyramid.httpexceptions)

HTTPUseProxy (class in pyramid.httpexceptions)

HTTPVersionNotSupported (class in pyramid.httpexceptions)

I

i18n

IApplicationCreated (interface in pyramid.interfaces)

IBeforeRender (interface in pyramid.interfaces)

IContextFound (interface in pyramid.interfaces)

IExceptionResponse (interface in pyramid.interfaces)

if_match (Request attribute)

if_modified_since (Request attribute)

if_none_match (Request attribute)

if_range (Request attribute)

if_unmodified_since (Request attribute)

imperative configuration, [1], [2], [3]

implementation() (ITemplateRenderer method)

include() (Configurator method)

INewRequest

(interface in pyramid.interfaces)

INewResponse

(interface in pyramid.interfaces)

ini file

ini file settings

initializing

message catalog

inside() (in module pyramid.location)

install preparation

installing on Google App Engine

installing on UNIX

installing on Windows

integration testing

integration tests

interactive shell

interface

internationalization

Internationalization

internationalization (of templates)

invalidate() (ISession method)

IPython

IRendererInfo (interface in pyramid.interfaces)

IRoute (interface in pyramid.interfaces)

IRoutePregenerator (interface in pyramid.interfaces)

is_response() (in module pyramid.view)

is_xhr (Request attribute)

ISession (interface in pyramid.interfaces)

ISessionFactory (interface in pyramid.interfaces)

ITemplateRenderer (interface in pyramid.interfaces)

items() (DummyResource method)

(ISession method)

iteritems() (ISession method)

iterkeys() (ISession method)

itervalues() (ISession method)

IViewMapper (interface in pyramid.interfaces)

IViewMapperFactory (interface in pyramid.interfaces)

J

Jinja2, [1]

JSON

renderer

Jython

K

keys() (DummyResource method)

(ISession method)

Koym, Todd

L

l10n

Laflamme, Blaise

last_modified (Response attribute)

leaf resources

lineage

lineage() (in module pyramid.location)

locale

negotiator

locale name

Locale Name

Locale Negotiator

locale_name (Localizer attribute)

localization

Localization

localization deployment settings

localizer

Localizer

(class in pyramid.i18n)

location

(Response attribute)

location-aware

resource

security

M

make_body_seekable() (Request method)

make_wsgi_app

make_wsgi_app() (Configurator method)

Mako, [1]

mako

renderer

match() (IRoute method)

matchdict, [1]

(Request attribute)

matched_route

(Request attribute)

matching the root URL

max_forwards (Request attribute)

maybe_dotted() (Configurator method)

md5_etag() (Response method)

merge_cookies() (Response method)

Message Catalog

message catalog

compiling

initializing

updating

Message Identifier

message identifier

messages

extracting

METAL

method (Request attribute)

middleware

mod_wsgi, [1]

model_url() (Request method)

module

Moroz, Tom

msgid

translation

multidict

(WebOb)

MVC

N

name (IRendererInfo attribute)

(IRoute attribute)

negotiate_locale_name

negotiate_locale_name() (in module pyramid.i18n)

negotiator

locale

new (ISession attribute)

new_csrf_token() (ISession method)

NewRequest

(class in pyramid.events)

NewResponse

(class in pyramid.events)

not found error (debugging)

not found view

Not Found view

NotFound (class in pyramid.exceptions)

O

object tree, [1]

Oram, Simon

Orr, Mike

override_asset

override_asset() (Configurator method)

overriding

assets, [1]

routes

views

P

package, [1]

(IRendererInfo attribute)

params (Request attribute)

Paste

PasteDeploy, [1]

PasteDeploy settings

paster proutes

paster pshell

paster serve

paster templates

path (Request attribute)

path_info (Request attribute)

path_info_peek() (Request method)

path_info_pop() (Request method)

path_qs (Request attribute)

path_url (Request attribute)

pattern (IRoute attribute)

peek_flash()

(ISession method)

permission

permission names

permissions

Peters, Tim

pipeline

pkg_resources

pluralize() (Localizer method)

pluralizing (i18n)

pop() (ISession method)

pop_flash()

(ISession method)

popitem() (ISession method)

POST (Request attribute)

postvars (Request attribute)

pragma (Request attribute)

(Response attribute)

predicate

predicates (IRoute attribute)

pregenerator

(IRoute attribute)

preventing cross-site request forgery attacks

principal, [1]

principal names

principals_allowed_by_permission() (in module pyramid.security)

printing

routes

project, [1]

project structure

protecting views

Pylons, [1], [2], [3]

PyPI

pyramid and other frameworks

Pyramid Cookbook

pyramid genesis

pyramid.authentication (module)

pyramid.authorization (module)

pyramid.chameleon_text (module)

pyramid.chameleon_zpt (module)

pyramid.config (module)

pyramid.events (module)

pyramid.exceptions (module)

pyramid.httpexceptions (module)

pyramid.i18n (module)

pyramid.interfaces (module)

pyramid.location (module)

pyramid.paster (module)

pyramid.registry (module)

pyramid.renderers (module)

pyramid.request (module)

pyramid.response (module)

pyramid.scripting (module)

pyramid.security (module)

pyramid.session (module)

pyramid.settings (module)

pyramid.testing

(module)

pyramid.threadlocal (module)

pyramid.traversal (module)

pyramid.url (module)

pyramid.view (module)

pyramid.wsgi (module)

pyramid_alchemy paster template

pyramid_beaker

pyramid_handlers

pyramid_jinja2

pyramid_routesalchemy paster template

pyramid_sqla

pyramid_starter paster template

pyramid_zcml

pyramid_zodb paster template

Python

Q

query_string (Request attribute)

queryvars (Request attribute)

quote_path_segment() (in module pyramid.traversal)

R

range (Request attribute)

redirecting to slash-appended routes

referer (Request attribute)

referrer (Request attribute)

Registry (class in pyramid.registry)

registry (Configurator attribute)

(IRendererInfo attribute)

(Request attribute)

relative_url() (Request method)

reload, [1]

reload settings

reload_all

reload_assets, [1]

reload_templates

remember() (in module pyramid.security)

remote_addr (Request attribute)

remote_user (Request attribute)

RemoteUserAuthenticationPolicy (class in pyramid.authentication)

remove_conditional_headers() (Request method)

render() (in module pyramid.renderers)

render_template() (in module pyramid.chameleon_text)

(in module pyramid.chameleon_zpt)

render_template_to_response() (in module pyramid.chameleon_text)

(in module pyramid.chameleon_zpt)

render_to_response() (in module pyramid.renderers)

render_view() (in module pyramid.view)

render_view_to_iterable() (in module pyramid.view)

render_view_to_response() (in module pyramid.view)

renderer, [1]

JSON

chameleon

mako

string

renderer (adding)

(template)

renderer factory

renderer globals, [1]

renderer response headers

renderers (built-in)

Repoze

repoze namespace package

repoze.bfg genesis

repoze.catalog

repoze.lemonade

repoze.who

repoze.workflow

repoze.zope2

RepozeWho1AuthenticationPolicy (class in pyramid.authentication)

request, [1]

(and unicode)

Request (class in pyramid.request)

request (IContextFound attribute)

(INewRequest attribute)

(INewResponse attribute)

(Response attribute)

request attributes

(special)

request factory, [1]

request methods

request object

request processing

request type

request URLs

request.registry

RequestClass (Response attribute)

resource

location-aware

resource API functions

resource interfaces, [1]

Resource Location

resource tree, [1], [2]

resource url

generating

resource_path() (in module pyramid.traversal)

resource_path_tuple() (in module pyramid.traversal)

resource_url

resource_url() (in module pyramid.url)

(Request method), [1]

resources.py

response, [1]

Response (class in pyramid.response)

response (creating)

(INewResponse attribute)

response callback, [1]

response exceptions

response headers

(from a renderer)

response object

ResponseClass (Request attribute)

reStructuredText

retry_after (Response attribute)

root

(Request attribute)

root factory, [1]

root url (matching)

Rossi, Chris

route

route configuration

view callable

route factory

route ordering

route path pattern syntax

route predicate

route subpath

route URLs

route_path() (in module pyramid.url)

(Request method), [1]

route_url() (in module pyramid.url)

(Request method), [1]

router, [1]

Routes

routes

overriding

printing

routes mapper

running an application

running tests

S

sample template

Sawyers, Andrew

scan

scan() (Configurator method)

scheme (Request attribute)

script_name (Request attribute)

Seaver, Tres

security

URL dispatch

location-aware

view

server (Response attribute)

server_name (Request attribute)

server_port (Request attribute)

session, [1]

(Request attribute), [1]

session factory, [1]

set_cookie() (Response method)

set_default_permission() (Configurator method)

set_forbidden_view() (Configurator method)

set_locale_negotiator() (Configurator method)

set_notfound_view() (Configurator method)

set_renderer_globals_factory() (Configurator method)

set_request_factory() (Configurator method)

set_session_factory() (Configurator method)

setdefault() (ISession method)

settings

(IRendererInfo attribute)

(Registry attribute)

setUp() (in module pyramid.testing)

setup.py

setup.py develop

setup_registry() (Configurator method)

setuptools

Shipman, John

signed_deserialize() (in module pyramid.session)

signed_serialize() (in module pyramid.session)

special ACE

special permission names

SQLAlchemy

startup

startup process

static (class in pyramid.view)

static asset urls

static assets view

static asssets

static_url() (in module pyramid.url)

(Request method), [1]

status (Response attribute)

status_code (Response attribute)

status_int (Response attribute)

status_map (in module pyramid.httpexceptions)

str_cookies (Request attribute)

str_GET (Request attribute)

str_params (Request attribute)

str_POST (Request attribute)

str_postvars (Request attribute)

str_queryvars (Request attribute)

string

renderer

subpath, [1]

(Request attribute)

(route)

subscriber, [1]

subscriber() (in module pyramid.events)

T

tearDown() (in module pyramid.testing)

template

template automatic reload

template internationalization

template renderer side effects

template renderers

template system bindings

templates used as renderers

templates used directly

test setup

test tear down

testing_add_renderer() (Configurator method)

testing_add_subscriber() (Configurator method)

testing_resources() (Configurator method)

testing_securitypolicy() (Configurator method)

tests (running)

tests.py

thread local

thread locals

tmpl_context (Request attribute), [1]

translate() (Localizer method)

translating (i18n)

translation

activating

domain

msgid

translation directories

translation directory

Translation Directory

Translation Domain

translation string

Translation String

translation string factory

translation strings

Chameleon

TranslationString (class in pyramid.i18n)

TranslationStringFactory (class in pyramid.i18n)

Translator

traversal

traversal algorithm

traversal details

traversal examples

traversal overview

traversal tree, [1]

traversal_path() (in module pyramid.traversal)

traverse() (in module pyramid.traversal)

traversed (Request attribute)

traverser

type (IRendererInfo attribute)

U

ubody (Response attribute)

unauthenticated_userid() (in module pyramid.security)

UnencryptedCookieSessionFactoryConfig() (in module pyramid.session)

unhook_zca() (Configurator method)

unicode (and the request)

unicode, views, and forms

unicode_body (Response attribute)

unit testing

unittest

unset_cookie() (Response method)

upath_info (Request attribute)

update() (BeforeRender method)

(IBeforeRender method)

(ISession method)

updating

message catalog

url (Request attribute)

URL dispatch, [1]

security

url generation (traversal)

url generator

urlargs (Request attribute)

URLDecodeError (class in pyramid.exceptions)

urlencode() (in module pyramid.url)

urlvars (Request attribute)

uscript_name (Request attribute)

user_agent (Request attribute)

V

values() (DummyResource method)

(ISession method)

van Rossum, Guido

vary (Response attribute)

Venusian

view

security

view callable

view calling convention, [1], [2]

view class

view configuration

view exceptions

view function

View handler

view http redirect

View Lookup

view lookup, [1]

view mapper, [1]

view name, [1]

view predicate

view renderer

view response

view security

view_config

(class in pyramid.view)

view_config decorator

view_execution_permitted() (in module pyramid.security)

view_name (Request attribute)

views

overriding

views, forms, and unicode

virtual hosting

virtual root, [1]

virtual_root (Request attribute)

virtual_root() (in module pyramid.traversal)

virtual_root_path (Request attribute)

virtualenv, [1], [2]

W

WebError

WebOb, [1]

WebTest

with_package() (Configurator method)

WSGI

WSGI application

wsgiapp() (in module pyramid.wsgi)

wsgiapp2() (in module pyramid.wsgi)

www_authenticate (Response attribute)

Z

ZCA

ZCA global API

ZCA global registry

ZCML

ZCML declaration

ZCML directive

ZEO

ZODB

Zope, [1], [2]

Zope 2

Zope 3

Zope Component Architecture, [1]

zope.component

ZPT

ZPT macros

ZPT templates (Chameleon)

© Copyright 2011, Agendaless Consulting. Last updated on Jan 31, 2011. Created using Sphinx 1.0.7.