The repoze.bfg Web Application Framework

repoze.bfg is a small, fast, down-to-earth Python web application framework. It is developed as part of the Repoze project by Agendaless Consulting and other contributors. It is licensed under a BSD-like license.

Front Matter

• Copyright, Trademarks, and Attributions
• Typographical Conventions

“What’s New” Documents

• What’s New In repoze.bfg 1.3
  • Major Feature Additions
  • Minor Feature Additions
  • Backwards Incompatibilities
  • Deprecations and Behavior Differences
  • Dependency Changes
  • Documentation Enhancements
  • Licensing Changes
• What’s New In repoze.bfg 1.2
  • Major Feature Additions
  • Minor Feature Additions
  • Backwards Incompatibilites
  • Deprecations and Behavior Differences
  • Dependency Changes
  • Documentation Enhancements
  • Licensing Changes
• What’s New In repoze.bfg 1.1
  • Major Feature Additions
  • Minor Miscellaneous Feature Additions
  • Backwards Incompatibilities
  • Deprecations and Behavior Differences
  • Dependency Changes

Narrative documentation

Narrative documentation in chapter form explaining how to use repoze.bfg.

• repoze.bfg Introduction
  • What Is Repoze?
  • repoze.bfg and Other Web Frameworks
• Installing repoze.bfg
  • Before You Install
  • Installing repoze.bfg on a UNIX System
  • Installing repoze.bfg on a Windows System
  • Installing repoze.bfg on Google App Engine
  • Installing repoze.bfg on Jython
  • What Gets Installed
• Application Configuration
  • Imperative Configuration
  • Declarative Configuration
  • Which Mode Should I Use?
• Creating Your First repoze.bfg Application
  • Hello World, Goodbye World (Imperative)
  • Hello World, Goodbye World (Declarative)
  • References
• Creating a repoze.bfg Project
  • Paster Templates Included with repoze.bfg
  • 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
• Startup
  • The Startup Process
• Context Finding and View Lookup
  • Should I Use Traversal or URL Dispatch for Context Finding?
• Traversal
  • A Traversal Analogy
  • A High-Level Overview of Traversal
  • The Object Graph
  • The Traversal Algorithm
  • References
• 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 repoze.bfg Security With URL Dispatch
  • References
• Combining Traversal and URL Dispatch
  • A Review of Non-Hybrid Applications
  • Hybrid Applications
  • Corner Cases
• Views
  • View Callables
  • View Configuration: Mapping a Context to a View
  • View Lookup and Invocation
• Static Resources
  • Serving Static Resources Using a ZCML Directive
  • Advanced: Serving Static Resources Using a View Callable
• Request and Response Objects
  • Request
  • Response
  • Multidict
• Templates
  • Templates Used 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
  • Automatically Reloading Templates
  • Nicer Exceptions in Templates
  • Chameleon Template Internationalization
  • Available Add-On Template System Bindings
• Models
  • Defining a Model Constructor
  • Model Instances Which Implement Interfaces
  • Defining a Graph of Model Instances for Traversal
  • Location-Aware Model Instances
  • repoze.bfg API Functions That Act Against Models
• Security
  • Enabling an Authorization Policy
  • Protecting Views with Permissions
  • Assigning ACLs to your Model 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
  • Built-In Authentication Policy ZCML Directives
  • Built-In Authorization Policy ZCML Directives
  • Creating Your Own Authentication Policy
  • Creating Your Own Authorization Policy
• 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
  • 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
  • An Example
• Environment Variables and .ini File Settings
  • Reloading Templates
  • Reloading Resources
  • Debugging Authorization
  • Debugging Not Found Errors
  • Debugging All
  • Reloading All
  • Default Locale Name
  • Examples
  • Understanding the Distinction Between reload_templates and reload_resources
• Unit and Integration Testing
  • Test Set Up and Tear Down
  • Using the Configurator and repoze.bfg.testing APIs in Unit Tests
  • Creating Integration Tests
• Using Hooks
  • Changing the Not Found View
  • Changing the Forbidden View
  • Changing the Traverser
  • Changing How repoze.bfg.url.model_url Generates a URL
  • Changing the Request Factory
  • Adding Renderer Globals
  • Using Response Callbacks
  • Using Finished Callbacks
  • Registering Configuration Decorators
• Extending An Existing repoze.bfg Application
  • Rules for Building An Extensible Application
  • Extending an Existing Application
  • Dealing With ZCML Inclusions
• Resources
  • Understanding Resources
  • Overriding Resources
• Request Processing
• Thread Locals
  • Why and How repoze.bfg Uses Thread Local Variables
  • Why You Shouldn’t Abuse Thread Locals
• Using the Zope Component Architecture in repoze.bfg
  • Using the ZCA Global API in a repoze.bfg Application
  • Using Broken ZCML Directives

Tutorials

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

• ZODB + Traversal Wiki Tutorial
  • Background
  • Installation
  • Basic Layout
  • Defining Models
  • Defining Views
  • Using View Decorators Rather than ZCML view directives
  • Adding Authorization
  • Distributing Your Application
• SQLAlchemy + URL Dispatch Wiki Tutorial
  • Background
  • Installation
  • Basic Layout
  • Defining Models
  • Defining Views
  • Adding Authorization
  • Distributing Your Application
• Converting an Existing Zope/CMF Application to repoze.bfg
  • Content Types
  • Catalog
  • Skins
  • Actions
  • Workflow
  • Missing Comparisons
• Running repoze.bfg on Google’s App Engine
  • Zipping Files Via Pip
• Running a repoze.bfg Application under mod_wsgi
• Using ZODB with ZEO
  • Installing Dependencies
  • Configuration
  • Running
• Using ZODB-Based Sessions
  • Installing Dependencies
  • Configuration
• Using repoze.catalog Within repoze.bfg

Reference Material

Reference material includes API documentation and documentation of every repoze.bfg ZCML directive.

• API Documentation
  • repoze.bfg.authorization
  • repoze.bfg.authentication
  • repoze.bfg.chameleon_text
  • repoze.bfg.chameleon_zpt
  • repoze.bfg.configuration
  • repoze.bfg.events
  • repoze.bfg.exceptions
  • repoze.bfg.i18n
  • repoze.bfg.interfaces
  • repoze.bfg.location
  • repoze.bfg.paster
  • repoze.bfg.renderers
  • repoze.bfg.request
  • repoze.bfg.router
  • repoze.bfg.scripting
  • repoze.bfg.security
  • repoze.bfg.settings
  • repoze.bfg.testing
  • repoze.bfg.threadlocal
  • repoze.bfg.traversal
  • repoze.bfg.url
  • repoze.bfg.view
  • repoze.bfg.wsgi
• ZCML Directives
  • aclauthorizationpolicy
  • adapter
  • authtktauthenticationpolicy
  • configure
  • default_permission
  • forbidden
  • include
  • localenegotiator
  • notfound
  • remoteuserauthenticationpolicy
  • renderer
  • repozewho1authenticationpolicy
  • resource
  • route
  • scan
  • static
  • subscriber
  • translationdir
  • utility
  • view

Detailed Change History

• repoze.bfg Change History

Design Documentation

• Defending BFG’s Design

Sample Applications

repoze.cluegun is a simple pastebin application based on Rocky Burt’s ClueBin. It demonstrates form processing, security, and the use of ZODB within a repoze.bfg application. It also has very simple repoze.who integration. Check this application out of Subversion via:

svn co http://svn.repoze.org/repoze.cluegun/trunk repoze.cluegun

repoze.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. This application runs the repoze.org website. Check this application out of Subversion via:

svn co http://svn.repoze.org/repoze.virginia/trunk repoze.virginia

repoze.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 and repoze.who. Check this application out of Subversion via:

svn co http://svn.repoze.org/repoze.shootout/trunk repoze.shootout

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

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

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

Support and Development

The BFG web site is the main online source of repoze.bfg support and development information.

To report bugs, use the bug tracker.

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

Browse and check out tagged and trunk versions of repoze.bfg via the Repoze Subversion repository. To check out the trunk via Subversion, use this command:

svn co http://svn.repoze.org/repoze.bfg/trunk repoze.bfg

To find out how to become a contributor to repoze.bfg, please see the contributor’s page.

Index and Glossary

• Glossary
• Index
• Search Page