Introduction to Pegboard

Pegboard is a toolkit for grouping related WSGI components together and dispatching WSGI events into the group of components. These components conform to the WSGI interface and can be either Pegboard-aware components or any WSGI compliant application.

Pegboard-aware components can be statically or dynamically arranged in a hierarchy, can communicate with each other through a shared context, and can handle special setup and teardown events that can be used to prepare and cleanup themselves before and after they are called.

Pegboard-aware components can have children components which in turn can have their own children. Parents propagate events into their children, which in turn propagate them to the grand-children, until the tree is completely traversed.

Component can share data and communicate with each other through a shared data context called a "pegboard". Each component is "attached" to the pegboard using a Peg object. The Peg is responsible for containing the component's shared context and propagating the WSGI events recursively through its component and its component's children.

The component library contains a simple WSGI application called PegboardApplication that can be used as a starting point for developing WSGI apps that use pegboard.

| Pegboard Application                                            |
|  +-----------------------------------------------------------+  |
|  | Pegboard                                                  |  |
|  |          +-------------------+   +---------------------+  |  |
|  |          | Peg +-----------+ |   | Peg +-------------+ |  |  |
|  |          |     | WSGI      | |   |     | Child       | |  |  |
|  |          |     | Component |---------->| Component   | |  |  |
|  |          |     +-----------+ |   |     +-------------+ |  |  |
|  |          +-------------------+   +---------------------+  |  |
|  |                                                           |  |
|  +-----------------------------------------------------------+  |

Dispatching requests into a components happens in a fixed sequence of phases: preparation, processing, composition and cleanup. WSGI callables may define custom behavior by implementing additional hooks:

__before__(environ, start_response)

__call__(environ, start_response)

__compose__(environ, start_response)



The Pegs and other pegboard machinery are decoupled from the WSGI callables and won't get in your way. The overall 'pegboard' directory of components sits in the environ under environ['pegboard.board`], and each WSGI callable will find its managing Peg instance at ``environ['pegboard.peg'].


Example Compositions

The pegboard toolkit is usable as-is, and also designed to be a completely extensible base for more sophisticated applications and frameworks. The :mod:`pegboard.contrib` package contains example component and composition schemes built on top of the toolkit kernel.