Latex rendering.

Chris McDonough

2009-12-27 878328bdfc3b5ac832f1728e4a0461e3129cf8d4

Latex rendering.

Documentation licensing.

 CHANGES.txt

@@ -1,6 +1,18 @@
Next release
============

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
-------------

@@ -14,6 +26,11 @@
  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)
==================


 LICENSE.txt

@@ -1,4 +1,4 @@
The majority of the code in bfg is supplied under this license:
The majority of the code in repoze.bfg is supplied under this license:

  A copyright notice accompanies this license document that identifies
  the copyright holders.
@@ -43,57 +43,63 @@
within individiual files indicate that these portions are licensed
under the ZPL):

Zope Public License (ZPL) Version 2.1
-------------------------------------
  Zope Public License (ZPL) Version 2.1
  -------------------------------------

A copyright notice accompanies this license document that
identifies the copyright holders.
  A copyright notice accompanies this license document that
  identifies the copyright holders.

This license has been certified as open source. It has also
been designated as GPL compatible by the Free Software
Foundation (FSF).
  This license has been certified as open source. It has also
  been designated as GPL compatible by the Free Software
  Foundation (FSF).

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:
  Redistribution and use in source and binary forms, with or
  without modification, are permitted provided that the
  following conditions are met:

1. Redistributions in source code must retain the
   accompanying copyright notice, this list of conditions,
   and the following disclaimer.
  1. Redistributions in source code must retain the
     accompanying copyright notice, this list of conditions,
     and the following disclaimer.

2. Redistributions in binary form must reproduce the accompanying
   copyright notice, this list of conditions, and the
   following disclaimer in the documentation and/or other
   materials provided with the distribution.
  2. Redistributions in binary form must reproduce the accompanying
     copyright notice, this list of conditions, and the
     following disclaimer in the documentation and/or other
     materials provided with the distribution.

3. Names of the copyright holders must not be used to
   endorse or promote products derived from this software
   without prior written permission from the copyright
   holders.
  3. Names of the copyright holders must not be used to
     endorse or promote products derived from this software
     without prior written permission from the copyright
     holders.

4. The right to distribute this software or to use it for
   any purpose does not give you the right to use
   Servicemarks (sm) or Trademarks (tm) of the copyright
   holders. Use of them is covered by separate agreement
   with the copyright holders.
  4. The right to distribute this software or to use it for
     any purpose does not give you the right to use
     Servicemarks (sm) or Trademarks (tm) of the copyright
     holders. Use of them is covered by separate agreement
     with the copyright holders.

5. If any files are modified, you must cause the modified
   files to carry prominent notices stating that you changed
   the files and the date of any change.
  5. If any files are modified, you must cause the modified
     files to carry prominent notices stating that you changed
     the files and the date of any change.

Disclaimer
  Disclaimer

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
  AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
  NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
  NO EVENT SHALL THE COPYRIGHT HOLDERS BE
  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  DAMAGE.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
    AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
    NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
    AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
    NO EVENT SHALL THE COPYRIGHT HOLDERS BE
    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
    OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
    DAMAGE.

The documentation portion of repoze.bfg (the rendered contents of the
"docs" directory of a software distribution or checkout) is supplied
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/

 docs/conf.py

@@ -44,7 +44,7 @@
master_doc = 'index'

# General substitutions.
project = 'repoze.bfg'
project = 'The repoze.bfg Web Application Framework'
copyright = '2008-2010, Agendaless Consulting'

# The default replacements for |version| and |release|, also used in various
@@ -96,7 +96,7 @@

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
#html_title = 'The repoze.bfg Web Application Framework v%release%'

# A shorter title for the navigation bar.  Default is the same as html_title.
#html_short_title = None
@@ -151,8 +151,7 @@
#html_file_suffix = ''

# Output file base name for HTML help builder.
htmlhelp_basename = 'repozebfgdoc'

htmlhelp_basename = 'repozebfg'

# Options for LaTeX output
# ------------------------
@@ -166,7 +165,7 @@
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
latex_documents = [
  ('latexindex', 'repoze.bfg.tex', 'The repoze.bfg Web Framework',
  ('latexindex', 'repozebfg.tex', 'The repoze.bfg Web Application Framework',
   'Chris McDonough', 'manual'),
    ]


 docs/conventions.rst

New file
@@ -0,0 +1,63 @@
Typographical Conventions
=========================

The following typographical conventions are used within this guide.

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 class names using the following style:

  :class:`Python.class.name`

We present Python method names using the following style:

  :meth:`Python.method_name`.

We present Python module names using the following style:

  :mod:`Python.module.name`.

We present Python attributes and global variables using the following
style:

  :data:`Python.attribute`.

References ot glossary terms and other document sections are presented
using the following style:

  :term:`Repoze`.

Python code blocks are presented in the following style:

  .. code-block:: python
     :linenos:

     def foo(abc):
         pass

Blocks of XML markup are presented in the following style:

  .. code-block:: xml
     :linenos:

     <root>
       <!-- ... more XML .. -->
     </root>


 docs/copyright.rst

New file
@@ -0,0 +1,49 @@
Copyright and Trademarks
========================

*The repoze.bfg Web Application Framework*

by Chris McDonough

Copyright ©2008-2010, Agendaless Consulting.

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-No Derivative Works 3.0 United States
License as described by
http://creativecommons.org/licenses/by-nc-nd/3.0/us/ .  You must give
the original author credit.  You may not use this work for commercial
purposes.  You may not alter, transform, or build upon this work. 

.. note::

   While the :mod:`repoze.bfg` *documentation* is offered under the
   Creative Commons Attribution-Nonconmmercial-No Derivate Works 3.0
   United States License, the :mod:`repoze.bfg` *software* is offered
   under the less restrictive (BSD-like) license described at
   http://repoze.org/license.html .

**Trademarks**

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.

**Warning and Disclaimer**

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.

**Contacting The Publisher**

Please send documentation licensing inquiries and other business
communications to ``webmaster@agendaless.com``.  Please send software
and other technical queries to the ``repoze-dev`` mailing list
described at http://lists.repoze.org/listinfo/repoze-dev .


 docs/glossary.rst

@@ -1,526 +1,608 @@
.. _glossary:

============================
Glossary
============================
========

.. glossary::
   :sorted:

  Request
    A ``WebOb`` request object.  See :ref:`webob_chapter` for
    information about request objects.
  Response
    An object that has three attributes: ``app_iter`` (representing an
    iterable body), ``headerlist`` (representing the http headers sent
    to the user agent), and ``status`` (representing the http status
    string sent to the user agent).  This is the interface defined for
    ``WebOb`` response objects.  See :ref:`webob_chapter` for
    information about response objects.
  Repoze
    "Repoze" is essentially a "brand" of software developed by
    `Agendaless Consulting <http://agendaless.com>`_ and a set of
    contributors.  The term has no special intrinsic meaning.  The
    project's `website <http://repoze.org>`_ has more information.
    The software developed "under the brand" is available in a
    `Subversion repository <http://svn.repoze.org>`_.
  Setuptools
    `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
    builds on Python's ``distutils`` to provide easier building,
    distribution, and installation of libraries and applications.
  pkg_resources
    A module which ships with :term:`setuptools` that provides an API
    for addressing "resource files" within Python packages.  Resource
    files are static files, template files, etc; basically anything
    non-Python-source that lives in a Python package can be considered
    a resource file.  See also `PkgResources
    <http://peak.telecommunity.com/DevCenter/PkgResources>`_
  Resource
    Any file contained within a Python :term:`package` which is *not*
    a Python source code file.
  Resource Specification
    A colon-delimited identifier for a :term:`resource`.  The colon
    separates a Python :term:`package` name from a package subpath.
    For example, the resource specification
    ``my.package:static/baz.css`` identifies the file named
    ``baz.css`` in the ``static`` subdirectory of the ``my.package``
    Python :term:`package`.
  Package
    A directory on disk which contains an ``__init__.py`` file, making
    it recognizable to Python as a location which can be ``import`` -ed.
  Project
    (Setuptools/distutils terminology). A directory on disk which
    contains a ``setup.py`` file and one or more Python packages.  The
    ``setup.py`` file contains code that allows the package(s) to be
    installed, distributed, and tested.
  Distribution
    (Setuptools/distutils terminology).  A file representing an
    installable library or application.  Distributions are usually
    files that have the suffix of ``.egg``, ``.tar.gz``, or ``.zip``.
    Distributions are the target of Setuptools commands such as
    ``easy_install``.
  Entry Point
    A :term:`setuptools` indirection, defined within a setuptools
    :term:`distribution` setup.py.  It is usually a name which refers
    to a function somewhere in a package which is held by the
    distribution.
  Dotted Python name
    A reference to a Python object by name using a string, in the form
    ``path.to.modulename:attributename``.  Often used in Paste and
    setuptools configurations.  A variant is used in dotted names
    within :term:`ZCML` attributes that name objects (such as the ZCML
    "view" directive's "view" attribute): the colon (``:``) is not
    used; in its place is a dot.
  View
    Common vernacular for a :term:`view callable`.
  View Callable
    A "view callable" is a callable Python object which is associated
    with a :term:`view configuration`; it returns a :term:`response`
    object .  A view callable accepts a single argument: ``request``,
    which will be an instance of a :term:`request` object.  An
    alternate calling convention allows a view to be defined as a
    callable which accepts a pair of arguments: ``context`` and
    ``request``: this calling convention is useful for traversal-based
    applications in which a :term:`context` is always very important.  A
    view callable is the primary mechanism by which a developer writes
    user interface code within :mod:`repoze.bfg`.  See
    :ref:`views_chapter` for more information about :mod:`repoze.bfg`
    view callables.
  View Configuration
    View configuration is the act of associating a :term:`view
    callable` with configuration information.  This configuration
    information helps map a given :term:`request` to a particular view
    callable and it can influence the response of a view callable.
    :mod:`repoze.bfg` views can be configured via :term:`imperative
    configuration`, :term:`ZCML` or by a special ``@bfg_view``
    decorator coupled with a :term:`scan`.  See :ref:`views_chapter`
    for more information about view configuration.
  View name
    The "URL name" of a view, e.g ``index.html``.  If a view is
    configured without a name, its name is considered to be the empty
    string (which implies the :term:`default view`).
  Default view
    The default view of a model is the view invoked when the
    :term:`view name` is the empty string (``''``).  This is the case
    when :term:`traversal` exhausts the path elements in the PATH_INFO
    of a request before it returns a :term:`context`.
  Virtualenv
    An isolated Python environment.  Allows you to control which
    packages are used on a particular project by cloning your main
    Python.  `virtualenv <http://pypi.python.org/pypi/virtualenv>`_
    was created by Ian Bicking.
  Model
    An object representing data in the system.  If :mod:`traversal` is
    used, a model is a node in the object graph traversed by the
    system.  When traversal is used, a model instance becomes the
    :term:`context` of a :term:`view`.  If :mod:`url dispatch` is
    used, a single :term:`context` is generated for each request and
    is used as the context of a view: this object is also technically
    a "model" in :mod:`repoze.bfg` terms, although this terminology
    can be a bit confusing: see :ref:`model_traversal_confusion`.
  Traversal
    The act of descending "down" a graph of model objects from a root
    model in order to find a :term:`context`.  The :mod:`repoze.bfg`
    :term:`router` performs traversal of model objects when a
    :term:`root factory` is specified.  See the
    :ref:`traversal_chapter` chapter for more information.  Traversal
    can be performed *instead* of :term:`URL dispatch` or can be
    combined *with* URL dispatch.  See :ref:`hybrid_chapter` for more
    information about combining traversal and URL dispatch (advanced).
  Router
    The :term:`WSGI` application created when you start a
    :mod:`repoze.bfg` application.  The router intercepts requests,
    invokes traversal and/or URL dispatch, calls view functions, and
    returns responses to the WSGI server on behalf of your
    :mod:`repoze.bfg` application.
  URL dispatch
    An alternative to graph traversal as a mechanism for locating a
    :term:`context` for a :term:`view`.  When you use a :term:`route`
    in your :mod:`repoze.bfg` application via a :term:`route
    configuration`, you are using URL dispatch. See the
    :ref:`urldispatch_chapter` for more information.
  Context
    An object in the system that is found during :term:`traversal` or
    :term:`URL dispatch` based on URL data; if it's found via
    traversal, it's usually a :term:`model` object that is part of an
    object graph; if it's found via :term:`URL dispatch`, it's a
    object manufactured on behalf of the route's "factory".  A context
    becomes the subject of a :term:`view`, and typically has security
    information attached to it.  See the :ref:`traversal_chapter`
    chapter and the :ref:`urldispatch_chapter` chapter for more
    information about how a URL is resolved to a context.
  Application registry
    A registry of configuration information consulted by
    :mod:`repoze.bfg` while servicing an appliation.  An application
    registry maps model types to views, as well as housing other
    application-specific component registrations.  Every
    :mod:`repoze.bfg` application has one (and only one) application
    registry.
  Template
    A file with replaceable parts that is capable of representing some
    text, XML, or HTML when rendered.
  Location
    The path to an object in an object graph.  See :ref:`location_aware`
    for more information about how to make a model object *location-aware*.
  Principal
    A user id or group id.
  Permission
    A string or unicode object that represents an action being taken
    against a context.  A permission is associated with a view name
    and a model type by the developer.  Models are decorated with
    security declarations (e.g. an :term:`ACL`), which reference these
    tokens also.  Permissions are used by the active to security
    policy to match the view permission against the model's statements
    about which permissions are granted to which principal in a
    context in order to to answer the question "is this user allowed
    to do this".  Examples of permissions: ``read``, or
    ``view_blog_entries``.
  ACE
    An *access control entry*.  An access control entry is one element
    in an :term:`ACL`.  An access control entry is a three-tuple that
    describes three things: an *action* (one of either ``Allow`` or
    ``Deny``), a :term:`principal` (a string describing a user or
    group), and a :term:`permission`.  For example the ACE, ``(Allow,
    'bob', 'read')`` is a member of an ACL that indicates that the
    principal ``bob`` is allowed the permission ``read`` against the
    context the ACL is attached to.
  ACL
    An *access control list*.  An ACL is a sequence of :term:`ACE`
    tuples.  An ACL is attached to a model instance.  An example of an
    ACL is ``[ (Allow, 'bob', 'read'), (Deny, 'fred', 'write')]``.  If
    an ACL is attached to a model instance, and that model instance is
    findable via the context, it will be consulted any active security
    policy to determine wither a particular request can be fulfilled
    given the :term:`authentication` information in the request.
  Authentication
    The act of determining that the credentials a user presents during
    a particular request are "good".  :mod:`repoze.bfg` uses the
    :term:`authentication` data supplied by the upstream component as
    one input during :term:`authorization`.  Authentication in
    :mod:`repoze.bfg` is performed via an :term:`authentication
    policy`.
  Authorization
    The act of determining whether a user can perform a specific
    action.  In bfg terms, this means determining whether, for a given
    context, any :term:`principal` (or principals) associated with the
    request have the requisite :term:`permission` to allow the request
    to continue.  Authorization in :mod:`repoze.bfg` is performed via
    its :term:`authorization policy`.
  Principal
    A *principal* is a string or unicode object representing a user or
    a user's membership in a group.  It is provided by an
    :term:`authentication policy`.  For example, if a user had the
    user id "bob", and Bob was part of two groups named "group foo"
    and "group bar", the request might have information attached to it
    that would indictate that Bob was represented by three principals:
    "bob", "group foo" and "group bar".
  Authorization Policy
    An authorization policy in :mod:`repoze.bfg` terms is a bit of
    code which has an API which determines whether or not the
    principals associated with the request can perform an action
    associated with a permission, based on the information found on the
    :term:`context`.
  Authentication Policy
    An authentication policy in :mod:`repoze.bfg` terms is a bit of
    code which has an API which determines the current
    :term:`principal` (or principals) associated with a request.
  WSGI
    `Web Server Gateway Interface <http://wsgi.org/>`_.  This is a
    Python standard for connecting web applications to web servers,
    similar to the concept of Java Servlets.  ``repoze.bfg`` requires
    that your application be served as a WSGI application.
  Middleware
    *Middleware* is a :term:`WSGI` concept.  It is a WSGI component
    that acts both as a server and an application.  Interesting uses
    for middleware exist, such as caching, content-transport
    encoding, and other functions.  See `WSGI.org <http://wsgi.org>`_
    or `PyPI <http://python.org/pypi>`_ to find middleware for your
    application.
  Pipeline
    The :term:`Paste` term for a single configuration of a WSGI
    server, a WSGI application, with a set of middleware in-between.
  mod_wsgi
    An `Apache module <http://code.google.com/p/modwsgi/>`_ for hosting
    Python WSGI applications.
  Zope
    `The Z Object Publishing Framework <http://zope.org>`_, a
    full-featured Python web framework.
  Grok
    `A web framework based on Zope 3 <http://grok.zope.org>`_.
  Django
    `A full-featured Python web framework <http://djangoproject.com>`_.
  Pylons
    `A lightweight Python web framework <http://pylonshq.com>`_.
  ZODB
     `Zope Object Database <http://wiki.zope.org/ZODB/FrontPage>`_, a
     persistent Python object store.
  ZEO
     `Zope Enterprise Objects
     <http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/ZEO.stx>`_
     allows multiple simultaneous processes to access a single
     :term:`ZODB` database.
  WebOb
    `WebOb <http://pythonpaste.org/webob/>`_ is a WSGI request/response
    library created by Ian Bicking.
  Paste
    `Paste <http://pythonpaste.org>`_ is a WSGI development and
    deployment system developed by Ian Bicking.
  PasteDeploy
    `PasteDeploy <http://pythonpaste.org>`_ is a library used by
    :mod:`repoze.bfg` which makes it possible to configure
    :term:`WSGI` components together declaratively within an ``.ini``
    file.  It was developed by Ian Bicking as part of :term:`Paste`.
  Chameleon
    `chameleon <http://chameleon.repoze.org>`_ is an attribute
    language template compiler which supports both the :term:`ZPT` and
    :term:`Genshi` templating specifications.  It is written and
    maintained by Malthe Borch.  It has several extensions, such as
    the ability to use bracketed (Genshi-style) ``${name}`` syntax,
    even within ZPT.  It is also much faster than the reference
    implementations of both ZPT and Genshi.  :mod:`repoze.bfg` offers
    Chameleon templating out of the box in ZPT and text flavors.
  ZPT
    The `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_
    templating language.
  METAL
    `Macro Expansion for TAL <http://wiki.zope.org/ZPT/METAL>`_, a
    part of :term:`ZPT` which makes it possible to share common look
    and feel between templates.  
  Genshi
    An `XML templating language <http://pypi.python.org/pypi/Genshi/>`_
    by Christopher Lenz.
  Jinja2
    A `text templating language <http://jinja.pocoo.org/2/>`_ by Armin 
    Ronacher.
  Routes
    A `system by Ben Bangert <http://routes.groovie.org/>`_ which
    parses URLs and compares them against a number of user defined
    mappings. The URL pattern matching syntax in :mod:`repoze.bfg` is
    inspired by the Routes syntax (which was inspired by Ruby On
    Rails pattern syntax).
  Route
    A single pattern matched by the :term:`url dispatch` subsystem,
    which generally resolves to a :term:`root factory` (and then
    ultimately a :term:`view`).  See also :term:`url dispatch`.
  Route Configuration
    Route configuration is the act of using :term:`imperative
    configuration` or a :term:`ZCML` ``<route>`` statement to
    associate request parameters with a particular :term:`route` using
    pattern matching and :term:`route predicate` statements.  See
    :ref:`urldispatch_chapter` for more information about route
    configuration.
  ZCML
    `Zope Configuration Markup Language
    <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
    used by Zope and :mod:`repoze.bfg` for configuration tasks.  ZCML
    is capable of performing different types of :term:`configuration
    declaration`, but its primary purpose in :mod:`repoze.bfg` is to
    perform :term:`view configuration` and :term:`route configuration`
    within the ``configure.zcml`` file in a :mod:`repoze.bfg`
    application.  You can use ZCML as an alternative to
    :term:`imperative configuration`.
  ZCML Directive
    A ZCML "tag" such as ``<view>`` or ``<route>``.
  ZCML Declaration
    The concrete use of a :term:`ZCML directive` within a ZCML file.
  Zope Component Architecture
    The `Zope Component Architecture
    <http://www.muthukadan.net/docs/zca.html>`_ (aka ZCA) is a system
    which allows for application pluggability and complex dispatching
    based on objects which implement an :term:`interface`.
    :mod:`repoze.bfg` uses the ZCA "under the hood" to perform view
    dispatching and other application configuration tasks.
  ReStructuredText
    A `plain text format <http://docutils.sourceforge.net/rst.html>`_
    that is the defacto standard for descriptive text shipped in
    :term:`distribution` files, and Python docstrings.  This
    documentation is authored in ReStructuredText format.
  Root
    The object at which :term:`traversal` begins when
    :mod:`repoze.bfg` searches for a :term:`context` (for :term:`URL
    Dispatch`, the root is *always* the context).
  Subpath
    A list of element "left over" after the :term:`router` has
    performed a successful traversal to a view.  The subpath is a
    sequence of strings, e.g. ``['left', 'over', 'names']``.  Within
    BFG applications that use URL dispatch rather than traversal, you
    can use ``*subpath`` in the route pattern to influence the
    subpath.  See :ref:`star_subpath` for more information.
  Interface
    A `Zope interface <http://pypi.python.org/pypi/zope.interface>`_
    object.  In :mod:`repoze.bfg`, an interface may be attached to a
    :term:`model` object or a :term:`request` object in order to
    identify that the object is "of a type".  Interfaces are used
    internally by :mod:`repoze.bfg` to perform view lookups and other
    policy lookups.  The ability to make use of an interface is
    exposed to an application programmers during :term:`view
    configuration` via the ``for`` argument, the ``request_type``
    argument and the ``containment`` argument.  Interfaces are also
    exposed to application developers when they make use of the
    :term:`event` system. Fundamentally, :mod:`repoze.bfg` programmers
    can think of an interface as something that they can attach to an
    object that stamps it with a "type" unrelated to its underlying
    Python type.  Interfaces can also be used to describe the behavior
    of an object (its methods and attributes), but unless they choose
    to, :mod:`repoze.bfg` programmers do not need to understand or use
    this feature of interfaces.
  Event
    An object broadcast to zero or more :term:`subscriber` callables
    during normal :mod:`repoze.bfg` system operations during the
    lifetime of an application.  Application code can subscribe to
    these events by using the subscriber functionality described in
    :ref:`events_chapter`.
  Subscriber
    A callable which receives an :term:`event`.  A callable becomes a
    subscriber via :term:`imperative configuration` or the
    ``<subscriber>`` ZCML directive.  See :ref:`events_chapter` for
    more information.
  Request type
    An attribute of a :term:`request` that allows for specialization
    of view invocation based on arbitrary categorization.  The every
    :term:`request` object that :mod:`repoze.bfg` generates and
    manipulates has one or more :term:`interface` objects attached to
    it.  The default interface attached to a request object is
    ``repoze.bfg.interfaces.IRequest``.
  repoze.lemonade
    Zope2 CMF-like `data structures and helper facilities
    <http://docs.repoze.org/lemonade>`_ for CA-and-ZODB-based
    applications useful within bfg applications.
  repoze.catalog
    An indexing and search facility (fielded and full-text) based on
    `zope.index <http://pypi.python.org/pypi/zope.index>`_.  See `the
    documentation <http://docs.repoze.org/catalog>`_ for more
    information.
  repoze.who
    `Authentication middleware <http://docs.repoze.org/who>`_ for
    :term:`WSGI` applications.  It can be used by :mod:`repoze.bfg` to
    provide authentication information.
  repoze.workflow
    `Barebones workflow for Python apps
    <http://docs.repoze.org/workflow>`_ .  It can be used by
    :mod:`repoze.bfg` to form a workflow system.
  Virtual root
    A model object representing the "virtual" root of a request; this
    is typically the physical root object (the object returned by the
    application root factory) unless :ref:`vhosting_chapter` is in
    use.
  Lineage
    An ordered sequence of objects based on a ":term:`location`
    -aware" context.  The lineage of any given :term:`context` is
    composed of itself, its parent, its parent's parent, and so on.
    The order of the sequence is context-first, then the parent of the
    context, then its parent's parent, and so on.  The parent of an
    object in a lineage is available as its ``__parent__`` attribute.
  Root Factory
    The "root factory" of an :mod:`repoze.bfg` application is called
    on every request sent to the application.  The root factory
    returns the traversal root of an application.  It is
    conventionally named ``get_root``.  An application may supply a
    root factory to :mod:`repoze.bfg` during the construction of a
    :term:`Configurator`.  If a root factory is not supplied, the
    application uses a default root object.  Use of the default root
    object is useful in application which use :term:`URL dispatch` for
    all URL-to-view code mappings.
  SQLAlchemy
    `SQLAlchemy' <http://www.sqlalchemy.org/>`_ is an object
    relational mapper used in tutorials within this documentation.
  JSON
    `JavaScript Object Notation <http://www.json.org/>`_ is a data
    serialization format.
  Renderer
    A registered serializer that can be configured via :term:`view
    configuration` which converts a non-:term:`Response` return values
    from a :term:`view` into a string (and ultimately a response).
    Using a renderer can make writing views that require templating or
    other serialization less tedious.  See
    :ref:`views_which_use_a_renderer` for more information.
  mod_wsgi
    `mod_wsgi <http://code.google.com/p/modwsgi/>`_ is an Apache
    module developed by Graham Dumpleton.  It allows :term:`WSGI`
    applications (such as applications developed using
    :mod:`repoze.bfg`) to be served using the Apache web server.
  View Predicate
    An argument to a :term:`view configuration` which evaluates to
    ``True`` or ``False`` for a given :term:`request`.  All predicates
    attached to a view configuration must evaluate to true for the
    associated view to be considered as a possible callable for a
    given request.
  Route Predicate
    An argument to a :term:`route configuration` which implies a value
    that evaluates to ``True`` or ``False`` for a given
    :term:`request`.  All predicates attached to a :term:`route
    configuration` must evaluate to ``True`` for the associated route
    to "match" the current request.  If a route does not match the
    current request, the next route (in definition order) is
    attempted.
  Predicate
    A test which returns ``True`` or ``False``.  Two different types
    of predicates exist in :mod:`repoze.bfg`: a :term:`view predicate`
    and a :term:`route predicate`.  View predicates are attached to
    :term:`view configuration` and route predicates are attached to
    :term:`route configuration`.
  Decorator
    A wrapper around a Python function or class which accepts the
    function or class as its first argument and which returns an
    arbitrary object.  :mod:`repoze.bfg` provides several decorators,
    used for configuration and return value modification purposes.  See
    also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
  Configuration Declaration
    An individual method call made to an instance of a
    :mod:`repoze.bfg` :term:`Configurator` object which performs an
    arbitrary action, such as registering a :term:`view configuration`
    (via the ``view`` method of the configurator) or :term:`route
    configuration` (via the ``route`` method of the configurator).  A
    set of configuration declarations is also usually implied via the
    use of a :term:`ZCML declaration` within an application, or a set
    of configuration declarations might be performed by a :term:`scan`
    of code in a package.
  Configuration Decoration
    Metadata implying one or more :term:`configuration declaration`
    invocations.  Often set by configuration Python :term:`decorator`
    attributes, such as ``repoze.bfg.view.bfg_view``, aka ``@bfg_view``.
  Scan
    The term used by :mod:`repoze.bfg` to define the process of
    importing and examining all code in a Python package or module for
    :term:`configuration decoration`.
  Configurator
    An object used to do :term:`configuration declaration` within an
    application.  The most common configurator is an instance of the
    ``repoze.bfg.configuration.Configurator`` class.
  Imperative Configuration
    The configuration mode in which you use Python to call methods on
    a :term:`Configurator` in order to add each :term:`configuration
    declaration` required by your application.
  Declarative Configuration
    The configuration mode in which you use :term:`ZCML` to make
    a set of :term:`configuration declaration` statements.
  Not Found View
     The :term:`view callable` invoked by :mod:`repoze.bfg` when the
     developer explicitly raises a
     ``repoze.bfg.exceptions.NotFound`` exception from within
     :term:`view` code or :term:`root factory` code, or when the
     current request doesn't match any :term:`view configuration`.
     :mod:`repoze.bfg` provides a default implementation of a not
     found view; it can be overridden.  See
     :ref:`changing_the_notfound_view`.
  Forbidden View
     The :term:`view callable` invoked by :mod:`repoze.bfg` when the
     developer explicitly raises a
     ``repoze.bfg.exceptions.Forbidden`` exception from within
     :term:`view` code or :term:`root factory` code, or when the the
     :term:`view configuration` and :term:`authorization policy` found
     for a request disallows a particular view invocation.
     :mod:`repoze.bfg` provides a default implementation of a
     forbidden view; it can be overridden.  See
     :ref:`changing_the_forbidden_view`.
  Thread Local
     A thread-local variable is one which is essentially a global
     variable in terms of how it is accessed and treated, however,
     each `thread
     <http://en.wikipedia.org/wiki/Thread_(computer_science)>` used by
     the application may have a different value for this same "global"
     variable.  :mod:`repoze.bfg` uses a small number of thread local
     variables, as described in :ref:`threadlocals_chapter`. See also
     the `threading.local documentation
     <http://docs.python.org/library/threading.html#threading.local>`
     for more information.
   Request
     A ``WebOb`` request object.  See :ref:`webob_chapter` for
     information about request objects.

   Response
     An object that has three attributes: ``app_iter`` (representing an
     iterable body), ``headerlist`` (representing the http headers sent
     to the user agent), and ``status`` (representing the http status
     string sent to the user agent).  This is the interface defined for
     ``WebOb`` response objects.  See :ref:`webob_chapter` for
     information about response objects.

   Repoze
     "Repoze" is essentially a "brand" of software developed by
     `Agendaless Consulting <http://agendaless.com>`_ and a set of
     contributors.  The term has no special intrinsic meaning.  The
     project's `website <http://repoze.org>`_ has more information.
     The software developed "under the brand" is available in a
     `Subversion repository <http://svn.repoze.org>`_.

   Setuptools
     `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
     builds on Python's ``distutils`` to provide easier building,
     distribution, and installation of libraries and applications.

   pkg_resources
     A module which ships with :term:`setuptools` that provides an API
     for addressing "resource files" within Python packages.  Resource
     files are static files, template files, etc; basically anything
     non-Python-source that lives in a Python package can be considered
     a resource file.  See also `PkgResources
     <http://peak.telecommunity.com/DevCenter/PkgResources>`_

   Resource
     Any file contained within a Python :term:`package` which is *not*
     a Python source code file.

   Resource Specification
     A colon-delimited identifier for a :term:`resource`.  The colon
     separates a Python :term:`package` name from a package subpath.
     For example, the resource specification
     ``my.package:static/baz.css`` identifies the file named
     ``baz.css`` in the ``static`` subdirectory of the ``my.package``
     Python :term:`package`.

   Package
     A directory on disk which contains an ``__init__.py`` file, making
     it recognizable to Python as a location which can be ``import`` -ed.

   Project
     (Setuptools/distutils terminology). A directory on disk which
     contains a ``setup.py`` file and one or more Python packages.  The
     ``setup.py`` file contains code that allows the package(s) to be
     installed, distributed, and tested.

   Distribution
     (Setuptools/distutils terminology).  A file representing an
     installable library or application.  Distributions are usually
     files that have the suffix of ``.egg``, ``.tar.gz``, or ``.zip``.
     Distributions are the target of Setuptools commands such as
     ``easy_install``.

   Entry Point
     A :term:`setuptools` indirection, defined within a setuptools
     :term:`distribution` setup.py.  It is usually a name which refers
     to a function somewhere in a package which is held by the
     distribution.

   Dotted Python name
     A reference to a Python object by name using a string, in the form
     ``path.to.modulename:attributename``.  Often used in Paste and
     setuptools configurations.  A variant is used in dotted names
     within :term:`ZCML` attributes that name objects (such as the ZCML
     "view" directive's "view" attribute): the colon (``:``) is not
     used; in its place is a dot.

   View
     Common vernacular for a :term:`view callable`.

   View Callable
     A "view callable" is a callable Python object which is associated
     with a :term:`view configuration`; it returns a :term:`response`
     object .  A view callable accepts a single argument: ``request``,
     which will be an instance of a :term:`request` object.  An
     alternate calling convention allows a view to be defined as a
     callable which accepts a pair of arguments: ``context`` and
     ``request``: this calling convention is useful for traversal-based
     applications in which a :term:`context` is always very important.  A
     view callable is the primary mechanism by which a developer writes
     user interface code within :mod:`repoze.bfg`.  See
     :ref:`views_chapter` for more information about :mod:`repoze.bfg`
     view callables.

   View Configuration
     View configuration is the act of associating a :term:`view
     callable` with configuration information.  This configuration
     information helps map a given :term:`request` to a particular view
     callable and it can influence the response of a view callable.
     :mod:`repoze.bfg` views can be configured via :term:`imperative
     configuration`, :term:`ZCML` or by a special ``@bfg_view``
     decorator coupled with a :term:`scan`.  See :ref:`views_chapter`
     for more information about view configuration.

   View name
     The "URL name" of a view, e.g ``index.html``.  If a view is
     configured without a name, its name is considered to be the empty
     string (which implies the :term:`default view`).

   Default view
     The default view of a model is the view invoked when the
     :term:`view name` is the empty string (``''``).  This is the case
     when :term:`traversal` exhausts the path elements in the PATH_INFO
     of a request before it returns a :term:`context`.

   Virtualenv
     An isolated Python environment.  Allows you to control which
     packages are used on a particular project by cloning your main
     Python.  `virtualenv <http://pypi.python.org/pypi/virtualenv>`_
     was created by Ian Bicking.

   Model
     An object representing data in the system.  If :mod:`traversal` is
     used, a model is a node in the object graph traversed by the
     system.  When traversal is used, a model instance becomes the
     :term:`context` of a :term:`view`.  If :mod:`url dispatch` is
     used, a single :term:`context` is generated for each request and
     is used as the context of a view: this object is also technically
     a "model" in :mod:`repoze.bfg` terms, although this terminology
     can be a bit confusing: see :ref:`model_traversal_confusion`.

   Traversal
     The act of descending "down" a graph of model objects from a root
     model in order to find a :term:`context`.  The :mod:`repoze.bfg`
     :term:`router` performs traversal of model objects when a
     :term:`root factory` is specified.  See the
     :ref:`traversal_chapter` chapter for more information.  Traversal
     can be performed *instead* of :term:`URL dispatch` or can be
     combined *with* URL dispatch.  See :ref:`hybrid_chapter` for more
     information about combining traversal and URL dispatch (advanced).

   Router
     The :term:`WSGI` application created when you start a
     :mod:`repoze.bfg` application.  The router intercepts requests,
     invokes traversal and/or URL dispatch, calls view functions, and
     returns responses to the WSGI server on behalf of your
     :mod:`repoze.bfg` application.

   URL dispatch
     An alternative to graph traversal as a mechanism for locating a
     :term:`context` for a :term:`view`.  When you use a :term:`route`
     in your :mod:`repoze.bfg` application via a :term:`route
     configuration`, you are using URL dispatch. See the
     :ref:`urldispatch_chapter` for more information.

   Context
     An object in the system that is found during :term:`traversal` or
     :term:`URL dispatch` based on URL data; if it's found via
     traversal, it's usually a :term:`model` object that is part of an
     object graph; if it's found via :term:`URL dispatch`, it's a
     object manufactured on behalf of the route's "factory".  A context
     becomes the subject of a :term:`view`, and typically has security
     information attached to it.  See the :ref:`traversal_chapter`
     chapter and the :ref:`urldispatch_chapter` chapter for more
     information about how a URL is resolved to a context.

   Application registry
     A registry of configuration information consulted by
     :mod:`repoze.bfg` while servicing an appliation.  An application
     registry maps model types to views, as well as housing other
     application-specific component registrations.  Every
     :mod:`repoze.bfg` application has one (and only one) application
     registry.

   Template
     A file with replaceable parts that is capable of representing some
     text, XML, or HTML when rendered.

   Location
     The path to an object in an object graph.  See :ref:`location_aware`
     for more information about how to make a model object *location-aware*.

   Permission
     A string or unicode object that represents an action being taken
     against a context.  A permission is associated with a view name
     and a model type by the developer.  Models are decorated with
     security declarations (e.g. an :term:`ACL`), which reference these
     tokens also.  Permissions are used by the active to security
     policy to match the view permission against the model's statements
     about which permissions are granted to which principal in a
     context in order to to answer the question "is this user allowed
     to do this".  Examples of permissions: ``read``, or
     ``view_blog_entries``.

   ACE
     An *access control entry*.  An access control entry is one element
     in an :term:`ACL`.  An access control entry is a three-tuple that
     describes three things: an *action* (one of either ``Allow`` or
     ``Deny``), a :term:`principal` (a string describing a user or
     group), and a :term:`permission`.  For example the ACE, ``(Allow,
     'bob', 'read')`` is a member of an ACL that indicates that the
     principal ``bob`` is allowed the permission ``read`` against the
     context the ACL is attached to.

   ACL
     An *access control list*.  An ACL is a sequence of :term:`ACE`
     tuples.  An ACL is attached to a model instance.  An example of an
     ACL is ``[ (Allow, 'bob', 'read'), (Deny, 'fred', 'write')]``.  If
     an ACL is attached to a model instance, and that model instance is
     findable via the context, it will be consulted any active security
     policy to determine wither a particular request can be fulfilled
     given the :term:`authentication` information in the request.

   Authentication
     The act of determining that the credentials a user presents during
     a particular request are "good".  :mod:`repoze.bfg` uses the
     :term:`authentication` data supplied by the upstream component as
     one input during :term:`authorization`.  Authentication in
     :mod:`repoze.bfg` is performed via an :term:`authentication
     policy`.

   Authorization
     The act of determining whether a user can perform a specific
     action.  In bfg terms, this means determining whether, for a given
     context, any :term:`principal` (or principals) associated with the
     request have the requisite :term:`permission` to allow the request
     to continue.  Authorization in :mod:`repoze.bfg` is performed via
     its :term:`authorization policy`.

   Principal
     A *principal* is a string or unicode object representing a userid
     or a group id.  It is provided by an :term:`authentication
     policy`.  For example, if a user had the user id "bob", and Bob
     was part of two groups named "group foo" and "group bar", the
     request might have information attached to it that would
     indictate that Bob was represented by three principals: "bob",
     "group foo" and "group bar".

   Authorization Policy
     An authorization policy in :mod:`repoze.bfg` terms is a bit of
     code which has an API which determines whether or not the
     principals associated with the request can perform an action
     associated with a permission, based on the information found on the
     :term:`context`.

   Authentication Policy
     An authentication policy in :mod:`repoze.bfg` terms is a bit of
     code which has an API which determines the current
     :term:`principal` (or principals) associated with a request.

   WSGI
     `Web Server Gateway Interface <http://wsgi.org/>`_.  This is a
     Python standard for connecting web applications to web servers,
     similar to the concept of Java Servlets.  ``repoze.bfg`` requires
     that your application be served as a WSGI application.

   Middleware
     *Middleware* is a :term:`WSGI` concept.  It is a WSGI component
     that acts both as a server and an application.  Interesting uses
     for middleware exist, such as caching, content-transport
     encoding, and other functions.  See `WSGI.org <http://wsgi.org>`_
     or `PyPI <http://python.org/pypi>`_ to find middleware for your
     application.

   Pipeline
     The :term:`Paste` term for a single configuration of a WSGI
     server, a WSGI application, with a set of middleware in-between.

   Zope
     `The Z Object Publishing Framework <http://zope.org>`_, a
     full-featured Python web framework.

   Grok
     `A web framework based on Zope 3 <http://grok.zope.org>`_.

   Django
     `A full-featured Python web framework <http://djangoproject.com>`_.

   Pylons
     `A lightweight Python web framework <http://pylonshq.com>`_.

   ZODB
      `Zope Object Database <http://wiki.zope.org/ZODB/FrontPage>`_, a
      persistent Python object store.

   ZEO
      `Zope Enterprise Objects
      <http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/ZEO.stx>`_
      allows multiple simultaneous processes to access a single
      :term:`ZODB` database.

   WebOb
     `WebOb <http://pythonpaste.org/webob/>`_ is a WSGI request/response
     library created by Ian Bicking.

   Paste
     `Paste <http://pythonpaste.org>`_ is a WSGI development and
     deployment system developed by Ian Bicking.

   PasteDeploy
     `PasteDeploy <http://pythonpaste.org>`_ is a library used by
     :mod:`repoze.bfg` which makes it possible to configure
     :term:`WSGI` components together declaratively within an ``.ini``
     file.  It was developed by Ian Bicking as part of :term:`Paste`.

   Chameleon
     `chameleon <http://chameleon.repoze.org>`_ is an attribute
     language template compiler which supports both the :term:`ZPT` and
     :term:`Genshi` templating specifications.  It is written and
     maintained by Malthe Borch.  It has several extensions, such as
     the ability to use bracketed (Genshi-style) ``${name}`` syntax,
     even within ZPT.  It is also much faster than the reference
     implementations of both ZPT and Genshi.  :mod:`repoze.bfg` offers
     Chameleon templating out of the box in ZPT and text flavors.

   ZPT
     The `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_
     templating language.

   METAL
     `Macro Expansion for TAL <http://wiki.zope.org/ZPT/METAL>`_, a
     part of :term:`ZPT` which makes it possible to share common look
     and feel between templates.  

   Genshi
     An `XML templating language <http://pypi.python.org/pypi/Genshi/>`_
     by Christopher Lenz.

   Jinja2
     A `text templating language <http://jinja.pocoo.org/2/>`_ by Armin 
     Ronacher.

   Routes
     A `system by Ben Bangert <http://routes.groovie.org/>`_ which
     parses URLs and compares them against a number of user defined
     mappings. The URL pattern matching syntax in :mod:`repoze.bfg` is
     inspired by the Routes syntax (which was inspired by Ruby On
     Rails pattern syntax).

   Route
     A single pattern matched by the :term:`url dispatch` subsystem,
     which generally resolves to a :term:`root factory` (and then
     ultimately a :term:`view`).  See also :term:`url dispatch`.

   Route Configuration
     Route configuration is the act of using :term:`imperative
     configuration` or a :term:`ZCML` ``<route>`` statement to
     associate request parameters with a particular :term:`route` using
     pattern matching and :term:`route predicate` statements.  See
     :ref:`urldispatch_chapter` for more information about route
     configuration.

   ZCML
     `Zope Configuration Markup Language
     <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
     used by Zope and :mod:`repoze.bfg` for configuration tasks.  ZCML
     is capable of performing different types of :term:`configuration
     declaration`, but its primary purpose in :mod:`repoze.bfg` is to
     perform :term:`view configuration` and :term:`route configuration`
     within the ``configure.zcml`` file in a :mod:`repoze.bfg`
     application.  You can use ZCML as an alternative to
     :term:`imperative configuration`.

   ZCML Directive
     A ZCML "tag" such as ``<view>`` or ``<route>``.

   ZCML Declaration
     The concrete use of a :term:`ZCML directive` within a ZCML file.

   Zope Component Architecture
     The `Zope Component Architecture
     <http://www.muthukadan.net/docs/zca.html>`_ (aka ZCA) is a system
     which allows for application pluggability and complex dispatching
     based on objects which implement an :term:`interface`.
     :mod:`repoze.bfg` uses the ZCA "under the hood" to perform view
     dispatching and other application configuration tasks.

   ReStructuredText
     A `plain text format <http://docutils.sourceforge.net/rst.html>`_
     that is the defacto standard for descriptive text shipped in
     :term:`distribution` files, and Python docstrings.  This
     documentation is authored in ReStructuredText format.

   Root
     The object at which :term:`traversal` begins when
     :mod:`repoze.bfg` searches for a :term:`context` (for :term:`URL
     Dispatch`, the root is *always* the context).

   Subpath
     A list of element "left over" after the :term:`router` has
     performed a successful traversal to a view.  The subpath is a
     sequence of strings, e.g. ``['left', 'over', 'names']``.  Within
     BFG applications that use URL dispatch rather than traversal, you
     can use ``*subpath`` in the route pattern to influence the
     subpath.  See :ref:`star_subpath` for more information.

   Interface
     A `Zope interface <http://pypi.python.org/pypi/zope.interface>`_
     object.  In :mod:`repoze.bfg`, an interface may be attached to a
     :term:`model` object or a :term:`request` object in order to
     identify that the object is "of a type".  Interfaces are used
     internally by :mod:`repoze.bfg` to perform view lookups and other
     policy lookups.  The ability to make use of an interface is
     exposed to an application programmers during :term:`view
     configuration` via the ``for`` argument, the ``request_type``
     argument and the ``containment`` argument.  Interfaces are also
     exposed to application developers when they make use of the
     :term:`event` system. Fundamentally, :mod:`repoze.bfg` programmers
     can think of an interface as something that they can attach to an
     object that stamps it with a "type" unrelated to its underlying
     Python type.  Interfaces can also be used to describe the behavior
     of an object (its methods and attributes), but unless they choose
     to, :mod:`repoze.bfg` programmers do not need to understand or use
     this feature of interfaces.

   Event
     An object broadcast to zero or more :term:`subscriber` callables
     during normal :mod:`repoze.bfg` system operations during the
     lifetime of an application.  Application code can subscribe to
     these events by using the subscriber functionality described in
     :ref:`events_chapter`.

   Subscriber
     A callable which receives an :term:`event`.  A callable becomes a
     subscriber via :term:`imperative configuration` or the
     ``<subscriber>`` ZCML directive.  See :ref:`events_chapter` for
     more information.

   Request type
     An attribute of a :term:`request` that allows for specialization
     of view invocation based on arbitrary categorization.  The every
     :term:`request` object that :mod:`repoze.bfg` generates and
     manipulates has one or more :term:`interface` objects attached to
     it.  The default interface attached to a request object is
     ``repoze.bfg.interfaces.IRequest``.

   repoze.lemonade
     Zope2 CMF-like `data structures and helper facilities
     <http://docs.repoze.org/lemonade>`_ for CA-and-ZODB-based
     applications useful within bfg applications.

   repoze.catalog
     An indexing and search facility (fielded and full-text) based on
     `zope.index <http://pypi.python.org/pypi/zope.index>`_.  See `the
     documentation <http://docs.repoze.org/catalog>`_ for more
     information.

   repoze.who
     `Authentication middleware <http://docs.repoze.org/who>`_ for
     :term:`WSGI` applications.  It can be used by :mod:`repoze.bfg` to
     provide authentication information.

   repoze.workflow
     `Barebones workflow for Python apps
     <http://docs.repoze.org/workflow>`_ .  It can be used by
     :mod:`repoze.bfg` to form a workflow system.

   Virtual root
     A model object representing the "virtual" root of a request; this
     is typically the physical root object (the object returned by the
     application root factory) unless :ref:`vhosting_chapter` is in
     use.

   Lineage
     An ordered sequence of objects based on a ":term:`location`
     -aware" context.  The lineage of any given :term:`context` is
     composed of itself, its parent, its parent's parent, and so on.
     The order of the sequence is context-first, then the parent of the
     context, then its parent's parent, and so on.  The parent of an
     object in a lineage is available as its ``__parent__`` attribute.

   Root Factory
     The "root factory" of an :mod:`repoze.bfg` application is called
     on every request sent to the application.  The root factory
     returns the traversal root of an application.  It is
     conventionally named ``get_root``.  An application may supply a
     root factory to :mod:`repoze.bfg` during the construction of a
     :term:`Configurator`.  If a root factory is not supplied, the
     application uses a default root object.  Use of the default root
     object is useful in application which use :term:`URL dispatch` for
     all URL-to-view code mappings.

   SQLAlchemy
     `SQLAlchemy' <http://www.sqlalchemy.org/>`_ is an object
     relational mapper used in tutorials within this documentation.

   JSON
     `JavaScript Object Notation <http://www.json.org/>`_ is a data
     serialization format.

   Renderer
     A registered serializer that can be configured via :term:`view
     configuration` which converts a non-:term:`Response` return values
     from a :term:`view` into a string (and ultimately a response).
     Using a renderer can make writing views that require templating or
     other serialization less tedious.  See
     :ref:`views_which_use_a_renderer` for more information.

   mod_wsgi
     `mod_wsgi <http://code.google.com/p/modwsgi/>`_ is an Apache
     module developed by Graham Dumpleton.  It allows :term:`WSGI`
     applications (such as applications developed using
     :mod:`repoze.bfg`) to be served using the Apache web server.

   View Predicate
     An argument to a :term:`view configuration` which evaluates to
     ``True`` or ``False`` for a given :term:`request`.  All predicates
     attached to a view configuration must evaluate to true for the
     associated view to be considered as a possible callable for a
     given request.

   Route Predicate
     An argument to a :term:`route configuration` which implies a value
     that evaluates to ``True`` or ``False`` for a given
     :term:`request`.  All predicates attached to a :term:`route
     configuration` must evaluate to ``True`` for the associated route
     to "match" the current request.  If a route does not match the
     current request, the next route (in definition order) is
     attempted.

   Predicate
     A test which returns ``True`` or ``False``.  Two different types
     of predicates exist in :mod:`repoze.bfg`: a :term:`view predicate`
     and a :term:`route predicate`.  View predicates are attached to
     :term:`view configuration` and route predicates are attached to
     :term:`route configuration`.

   Decorator
     A wrapper around a Python function or class which accepts the
     function or class as its first argument and which returns an
     arbitrary object.  :mod:`repoze.bfg` provides several decorators,
     used for configuration and return value modification purposes.  See
     also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.

   Configuration Declaration
     An individual method call made to an instance of a
     :mod:`repoze.bfg` :term:`Configurator` object which performs an
     arbitrary action, such as registering a :term:`view configuration`
     (via the ``view`` method of the configurator) or :term:`route
     configuration` (via the ``route`` method of the configurator).  A
     set of configuration declarations is also usually implied via the
     use of a :term:`ZCML declaration` within an application, or a set
     of configuration declarations might be performed by a :term:`scan`
     of code in a package.

   Configuration Decoration
     Metadata implying one or more :term:`configuration declaration`
     invocations.  Often set by configuration Python :term:`decorator`
     attributes, such as ``repoze.bfg.view.bfg_view``, aka ``@bfg_view``.

   Scan
     The term used by :mod:`repoze.bfg` to define the process of
     importing and examining all code in a Python package or module for
     :term:`configuration decoration`.

   Configurator
     An object used to do :term:`configuration declaration` within an
     application.  The most common configurator is an instance of the
     ``repoze.bfg.configuration.Configurator`` class.

   Imperative Configuration
     The configuration mode in which you use Python to call methods on
     a :term:`Configurator` in order to add each :term:`configuration
     declaration` required by your application.

   Declarative Configuration
     The configuration mode in which you use :term:`ZCML` to make
     a set of :term:`configuration declaration` statements.

   Not Found View
      The :term:`view callable` invoked by :mod:`repoze.bfg` when the
      developer explicitly raises a
      ``repoze.bfg.exceptions.NotFound`` exception from within
      :term:`view` code or :term:`root factory` code, or when the
      current request doesn't match any :term:`view configuration`.
      :mod:`repoze.bfg` provides a default implementation of a not
      found view; it can be overridden.  See
      :ref:`changing_the_notfound_view`.

   Forbidden View
      The :term:`view callable` invoked by :mod:`repoze.bfg` when the
      developer explicitly raises a
      ``repoze.bfg.exceptions.Forbidden`` exception from within
      :term:`view` code or :term:`root factory` code, or when the the
      :term:`view configuration` and :term:`authorization policy` found
      for a request disallows a particular view invocation.
      :mod:`repoze.bfg` provides a default implementation of a
      forbidden view; it can be overridden.  See
      :ref:`changing_the_forbidden_view`.

   Thread Local
      A thread-local variable is one which is essentially a global
      variable in terms of how it is accessed and treated, however,
      each `thread
      <http://en.wikipedia.org/wiki/Thread_(computer_science)>` used by
      the application may have a different value for this same "global"
      variable.  :mod:`repoze.bfg` uses a small number of thread local
      variables, as described in :ref:`threadlocals_chapter`. See also
      the `threading.local documentation
      <http://docs.python.org/library/threading.html#threading.local>`
      for more information.

 docs/index.rst

@@ -1,8 +1,8 @@
.. _index:

===========
repoze.bfg
===========
========================================
The repoze.bfg Web Application Framework
========================================

:mod:`repoze.bfg` is a Python web application framework.  It is
inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`.  It uses
@@ -14,6 +14,15 @@
<http://repoze.org>`_ project by `Agendaless Consulting
<http://agendaless.com>`_ and other contributors.  It is licensed
under a `BSD-like license <http://repoze.org/license.html>`_.

Fore-Matter
===========

.. toctree::
   :maxdepth: 1

   copyright.rst
   conventions.rst

"What's New" Documents
======================
@@ -57,7 +66,6 @@
   narr/resources
   narr/router
   narr/threadlocals
   glossary

API documentation
=================
@@ -94,66 +102,26 @@
Documentation for each :mod:`repoze.bfg` :term:`ZCML directive`.

.. toctree::
   :maxdepth: 2
   :maxdepth: 1

   zcml

Tutorials
=========

ZODB + traversal Wiki tutorial, demonstrating how to build a
:term:`traversal` based application using :term:`ZODB` and
:term:`authentication`.  Good for people with prior Zope experience
(or no experience at all).
Detailed tutorials explaining how to use :mod:`repoze.bfg` to build
and various types of applications and how to deploy :mod:`repoze.bfg`
applications to various platforms.

.. toctree::
   :maxdepth: 2

   tutorials/bfgwiki/index.rst

SQLAlchemy + url dispatch Wiki tutorial, demonstrating how to build a
:term:`url dispatch` based application using :term:`SQLAlchemy` and
:term:`authentication`.  Good for people with prior Pylons experience
(or no experience at all).

.. toctree::
   :maxdepth: 2

   tutorials/bfgwiki2/index.rst

:mod:`repoze.bfg` for Zope CMF Developers

.. toctree::
   :maxdepth: 2

   tutorials/cmf/index.rst

:mod:`repoze.bfg` on Google's App Engine

.. toctree::
   :maxdepth: 2

   tutorials/gae/index.rst

:mod:`repoze.bfg` under :term:`mod_wsgi`

.. toctree::
   :maxdepth: 2

   tutorials/modwsgi/index.rst

Using ZODB's :term:`ZEO` with :mod:`repoze.bfg`

.. toctree::
   :maxdepth: 2

   tutorials/zeo/index.rst

Using ZODB Sessions in :mod:`repoze.bfg`

.. toctree::
   :maxdepth: 2

   tutorials/zodbsessions/index.rst

Detailed Change History
@@ -241,11 +209,9 @@
To find out how to become a contributor to :mod:`repoze.bfg`, please
see the `contributor's page <http://repoze.org/contributing.html>`_.

Indices and tables
Index and Glossary
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
* :ref:`glossary`

* :ref:`genindex`
* :ref:`search`

 docs/latexindex.rst

@@ -1,19 +1,18 @@
.. _index:
.. _latexindex:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
The :mod:`repoze.bfg` Web Framework
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
The :mod:`repoze.bfg` Web Application Framework
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

:mod:`repoze.bfg` is a Python web application framework.  It is
inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`.  It uses
various Zope-related libraries internally to do much of its work.
:mod:`repoze.bfg` uses the WSGI protocol to handle request and
responses.
Fore-matter
@@@@@@@@@@@

:mod:`repoze.bfg` is developed as part of the `Repoze
<http://repoze.org>`_ project by `Agendaless Consulting
<http://agendaless.com>`_ and other contributors.  It is licensed
under a `BSD-like license <http://repoze.org/license.html>`_.
.. toctree::
   :maxdepth: 1

   copyright.rst
   thanks.rst
   conventions.rst

Narrative Documentation
@@@@@@@@@@@@@@@@@@@@@@@
@@ -49,68 +48,14 @@
Tutorials
@@@@@@@@@

ZODB + traversal Wiki Tutorial
==============================

Demonstrates how to build a :term:`traversal` based application using
:term:`ZODB` and :term:`authentication`.  Good for people with prior
Zope experience (or no experience at all).

.. toctree::
   :maxdepth: 2

   tutorials/bfgwiki/index.rst

SQLAlchemy + Url Dispatch Wiki Tutorial
=======================================

Demonstrates how to build a :term:`url dispatch` based application
using :term:`SQLAlchemy` and :term:`authentication`.  Good for people
with prior Pylons experience (or no experience at all).

.. toctree::
   :maxdepth: 2

   tutorials/bfgwiki2/index.rst

:mod:`repoze.bfg` for Zope CMF Developers
=========================================

.. toctree::
   :maxdepth: 2

   tutorials/cmf/index.rst

:mod:`repoze.bfg` on Google's App Engine
========================================

.. toctree::
   :maxdepth: 2

   tutorials/gae/index.rst

:mod:`repoze.bfg` under :term:`mod_wsgi`
========================================

.. toctree::
   :maxdepth: 2

   tutorials/modwsgi/index.rst

Using ZODB's :term:`ZEO` with :mod:`repoze.bfg`
===============================================

.. toctree::
   :maxdepth: 2

   tutorials/zeo/index.rst

Using ZODB Sessions in :mod:`repoze.bfg`
========================================

.. toctree::
   :maxdepth: 2

   tutorials/zodbsessions/index.rst

API documentation
@@ -141,23 +86,20 @@
   api/wsgi

ZCML Directives
@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@

.. toctree::
   :maxdepth: 2
   :maxdepth: 1

   zcml

Glossary
@@@@@@@@
Glossary and Index
@@@@@@@@@@@@@@@@@@

.. toctree::
  :maxdepth: 1

  glossary

Index
@@@@@

* :ref:`genindex`


 docs/narr/configuration.rst

@@ -204,8 +204,8 @@
traversal.

.. note:: A useful analogy of how :mod:`repoze.bfg` :term:`traversal`
  works is available within the section entitled
  :ref:`traversal_behavior`.  You should probably go read it now.
  works is available within the chapter section entitled
  :ref:`traversal_behavior`.

The results of a :term:`traversal` include a :term:`context` and a
:term:`view name`.  The :term:`view name` is the *first* URL path
@@ -234,8 +234,6 @@
The object graph of our hello world application is very simple:
there's exactly one object in our graph; the default :term:`root`
object.

Apologies for the digression; on with the tutorial.

Relating Traversal to the Hello World Application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -328,7 +326,6 @@

.. ignore-next-block
.. code-block:: python
   :linenos:

   config.begin()

@@ -449,7 +446,6 @@

.. ignore-next-block
.. code-block:: python
   :linenos:

   config.end()

@@ -467,7 +463,6 @@

.. ignore-next-block
.. code-block:: python
   :linenos:

   app = config.make_wsgi_app()

@@ -499,7 +494,6 @@

.. ignore-next-block
.. code-block:: python
   :linenos:

   serve(app)

@@ -580,20 +574,20 @@
.. code-block:: xml
   :linenos:

    <configure xmlns="http://namespaces.repoze.org/bfg">
   <configure xmlns="http://namespaces.repoze.org/bfg">

      <include package="repoze.bfg.includes" />
     <include package="repoze.bfg.includes" />

      <view
         view="helloworld.hello_world"
         />
     <view
        view="helloworld.hello_world"
        />

      <view
         name="goodbye"
         view="helloworld.goodbye_world"
         />
     <view
       name="goodbye"
       view="helloworld.goodbye_world"
       />

    </configure>
   </configure>

This pair of files forms an application functionally equivalent to the
application we created earlier.  Let's examine the differences between
@@ -641,7 +635,7 @@
.. code-block:: xml
   :linenos:

    <configure xmlns="http://namespaces.repoze.org/bfg">
   <configure xmlns="http://namespaces.repoze.org/bfg">

      <include package="repoze.bfg.includes" />

@@ -654,7 +648,7 @@
         view="helloworld.goodbye_world"
         />

    </configure>
   </configure>

The ``<configure>`` Tag
~~~~~~~~~~~~~~~~~~~~~~~
@@ -665,7 +659,9 @@
   :linenos:

    <configure xmlns="http://namespaces.repoze.org/bfg">

       <!-- other directives -->

    </configure>

Because :term:`ZCML` is XML, and because XML requires a single root
@@ -683,9 +679,8 @@
``<configure>`` root tag:

.. code-block:: xml
   :linenos:

      <include package="repoze.bfg.includes" />
   <include package="repoze.bfg.includes" />

This singleton (self-closing) tag instructs ZCML to load a ZCML file
from the Python package with the :term:`dotted Python name`
@@ -705,8 +700,8 @@
.. code-block:: xml
   :linenos:

      <include package="repoze.bfg.includes" 
               file="configure.zcml"/>
   <include package="repoze.bfg.includes" 
            file="configure.zcml"/>

The ``<include>`` tag that includes the ZCML statements implied by the
``configure.zcml`` file from the Python package named
@@ -729,14 +724,14 @@
.. code-block:: xml
   :linenos:

      <view
         view="helloworld.hello_world"
         />
   <view
     view="helloworld.hello_world"
     />

      <view
         name="goodbye"
         view="helloworld.goodbye_world"
         />
   <view
     name="goodbye"
     view="helloworld.goodbye_world"
     />

These ``<view>`` declaration tags direct :mod:`repoze.bfg` to create
two :term:`view configuration` registrations.  The first ``<view>``
@@ -780,28 +775,28 @@
  .. code-block:: xml
     :linenos:

        <view
           view="helloworld.hello_world"
           />
     <view
       view="helloworld.hello_world"
       />

        <view
           name="goodbye"
           view="helloworld.goodbye_world"
           />
     <view
       name="goodbye"
       view="helloworld.goodbye_world"
       />

.. topic:: Goodbye Before Hello

  .. code-block:: xml
     :linenos:

        <view
           name="goodbye"
           view="helloworld.goodbye_world"
           />
     <view
       name="goodbye"
       view="helloworld.goodbye_world"
       />

        <view
           view="helloworld.hello_world"
           />
     <view
       view="helloworld.hello_world"
       />

The ``<view>`` tag is an example of a :mod:`repoze.bfg` declaration
tag.  Other such tags include ``<route>``, ``<scan>``, ``<notfound>``,
@@ -826,12 +821,12 @@
      <include package="repoze.bfg.includes" />

      <view
         view="helloworld.hello_world"
         />
        view="helloworld.hello_world"
        />

      <view
         view="helloworld.hello_world"
         />
        view="helloworld.hello_world"
        />

    </configure>


 docs/narr/install.rst

@@ -7,11 +7,11 @@
------------------

You will need `Python <http://python.org>`_ version 2.4 or better to
run :mod:`repoze.bfg`.  It has been tested under Python 2.4.5, Python
2.5.2 and Python 2.6.  Development of :mod:`repoze.bfg` is currently
done primarily under Python 2.4 and Python 2.5.  :mod:`repoze.bfg`
does *not* run under any version of Python before 2.4, and does *not*
run under Python 3.X.
run :mod:`repoze.bfg`.  It has been tested under Python 2.4.6, Python
2.5.4 and Python 2.6.2, and Python 2.7a1.  Development of
:mod:`repoze.bfg` is currently done primarily under Python 2.4 and
Python 2.5.  :mod:`repoze.bfg` does *not* run under any version of
Python before 2.4, and does *not* run under Python 3.X.

.. sidebar:: You Don't Need A Compiler

@@ -21,24 +21,15 @@
   development tools installed on the target machine to install
   :mod:`repoze.bfg`.

BFG is known to run properly on all popular Unix-like systems such as
Linux, MacOS X, and FreeBSD.
:mod:`repoze.bfg` is known to run properly on all popular Unix-like
systems such as Linux, MacOS X, and FreeBSD.  :mod:`repoze.bfg` is
also known to run on Windows systems.  However, none of its developers
use Windows as a primary development platform.  It is also known to
run on Google's App Engine.

:mod:`repoze.bfg` is also known to run on Windows systems.  However,
none of its developers use Windows as a primary development platform.
Therefore, most of the platform-specific documentation (excepting this
chapter) assumes you're using a UNIX system. If you're using a Windows
system, you'll need to transliterate command lines in the
documentation to their Windows equivalents.

:mod:`repoze.bfg` is also known to run on Google's App Engine.

It is not known whether :mod:`repoze.bfg` will or will not run under
Jython or IronPython.

.. note:: If you'd like to help make sure :mod:`repoze.bfg` keeps
   running on your favorite alternate platform, we'd love to hear from
   you.  Please contact us via the `repoze.dev maillist
.. note:: If you'd like to help us make sure :mod:`repoze.bfg` runs on
   your favorite alternate platform, we'd love to hear from you.
   Please contact us via the `repoze.dev maillist
   <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd like to
   contribute.

@@ -61,9 +52,9 @@
manager to install a Python 2.5 interpreter, use the following
command:

.. code-block:: bash
.. code-block:: text

  $ sudo apt-get install python2.5-dev
   $ sudo apt-get install python2.5-dev

Once these steps are performed, the Python interpreter will usually be
invokable via ``python2.5`` from a shell prompt.
@@ -82,9 +73,9 @@
development tools.  Often these can be installed via the package
manager.  For example, this works to do so on an Ubuntu Linux system:

.. code-block:: bash
.. code-block:: text

  $ sudo apt-get install build-essential
   $ sudo apt-get install build-essential

On Mac OS X, installing XCode has much the same effect.

@@ -92,18 +83,19 @@
same system, to install a Python 2.5 interpreter from *source*, use
the following commands:

.. code-block:: bash
.. code-block:: text
   :linenos:

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

Once these steps are performed, the Python interpreter will be
invokable via ``$HOME/opt/Python-2.5.4/bin/python`` from a shell
@@ -135,13 +127,14 @@
setuptools`` within the Python interpreter you'd like to run
:mod:`repoze.bfg` under:

.. code-block:: bash
.. code-block:: text
   :linenos:

  [chrism@vitaminf bfg]$ 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
   [chrism@vitaminf bfg]$ 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 ``import setuptools`` does not raise an ``ImportError``, it means
that setuptools is already installed into your Python interpreter.  If
@@ -161,18 +154,18 @@
<http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it
using the Python interpreter you want to install setuptools into.

.. code-block:: bash
.. code-block:: text

  $ sudo python ez_setup.py
   $ sudo 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:

.. code-block:: bash
.. code-block:: text

  $ sudo python ez_setup.py
   $ sudo python ez_setup.py

Installing the ``virtualenv`` Package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -182,17 +175,17 @@
into your setuptools-enabled Python interpreter, use the
``easy_install`` command.

.. code-block:: bash
.. code-block:: text

  $ easy_install virtualenv
   $ 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:

.. code-block:: bash
.. code-block:: text

  $ sudo easy_install virtualenv
   $ sudo easy_install virtualenv

Creating the Virtual Python Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -201,7 +194,7 @@
can actually create a virtual environment.  To do so, invoke the
following:

.. code-block:: bash
.. code-block:: text
   :linenos:

   $ virtualenv --no-site-packages bfgenv
@@ -231,7 +224,7 @@
:mod:`repoze.bfg` itself using the following commands from within the
virtualenv (``bfgenv``) directory:

.. code-block:: bash
.. code-block:: text
   :linenos:

   $ bin/easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
@@ -250,33 +243,33 @@
   pick the right download for Python 2.5 and install it using the
   same Python installation from the previous step.

#. Install latest `setuptools` into the Python you
#. Install latest :term:`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.5 installation using a
   command prompt:

   .. code-block:: bat
   .. code-block:: text

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

#. Use that Python's `bin/easy_install` to install `virtualenv`:

   .. code-block:: bat
   .. code-block:: text

    c:\> c:\Python25\Scripts\easy_install virtualenv
      c:\> c:\Python25\Scripts\easy_install virtualenv

#. Use that Python's virtualenv to make a workspace:

   .. code-block:: bat
   .. code-block:: text

     c:\> c:\Python25\Scripts\virtualenv --no-site-packages bfgenv
      c:\> c:\Python25\Scripts\virtualenv --no-site-packages bfgenv

#. Switch to the ``bfgenv`` directory:

   .. code-block:: bat
   .. code-block:: text

     c:\> cd bfgenv
      c:\> cd bfgenv

#. (Optional) Consider using ``bin\activate.bat`` to make your shell
   environment wired to use the virtualenv.
@@ -284,9 +277,9 @@
#. Use ``easy_install`` and point to the BFG "1.1" index to get BFG
   and its direct dependencies installed:

   .. code-block:: bat
   .. code-block:: text

     c:\bfgenv> Scripts\easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
      c:\bfgenv> Scripts\easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg

Installing :mod:`repoze.bfg` on Google App Engine
-------------------------------------------------

 docs/narr/introduction.rst

@@ -1,47 +1,95 @@
:mod:`repoze.bfg` Introduction
==============================

:mod:`repoze.bfg` is a Python web framework.  It is inspired by
:term:`Zope`, :term:`Pylons`, and :term:`Django`.  :mod:`repoze.bfg`
uses the :term:`WSGI` protocol to handle requests and responses.
:mod:`repoze.bfg` is an open source Python web application framework.
It is inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`.
It uses the :term:`WSGI` protocol to handle requests and responses.

Similarities to Other Frameworks
--------------------------------
:mod:`repoze.bfg` is written by Agendaless Consulting and a community
of contributors.  It is developed primarily by people who come from
the world of :term:`Zope` but for whom Zope as a web application
development platform has lost some of its attraction.  Its authors
also have experience developing applications using many other web
frameworks.

.. sidebar:: Django's Authors Explain Why It Doesn't Use "MVC" Terminology
The first release of :mod:`repoze.bfg` was made in July of 2008.
Since its first release, it has undergone many improvements, and has
gained features steadily.  Still, it strives to maintain the following
attributes:

  Django appears to be a MVC framework, but you call the Controller
  the "view", and the View the "template". How come you don't use the
  standard names?  Well, the standard names are debatable.
Simplicity
  :mod:`repoze.bfg` attempts to be a *"pay only for what you eat"*
  framework in which you can be productive quickly with partial
  knowledge.  We contrast this with *"pay up front for what anyone
  might eventually want to eat"* frameworks, which tend to expect you
  to understand a great many concepts and technologies fully before
  you can be truly productive.  :mod:`repoze.bfg` doesn't force you to
  use any particular technology to produce an application, and we try
  to keep the core set of concepts you need to understand to a
  minimum.

  In our interpretation of MVC, the "view" describes the data that
  gets presented to the user. It's not necessarily how the data looks,
  but which data is presented. The view describes which data you see,
  not how you see it. It's a subtle distinction.
Minimalism
  :mod:`repoze.bfg` provides only the very basics: *URL to code
  mapping*, *templating*, *security*, and *resources*.  There is not
  much more to the framework than these pieces: you are expected to
  provide the rest.

  So, in our case, a "view" is the Python callback function for a
  particular URL, because that callback function describes which data
  is presented.
Documentation
  Because :mod:`repoze.bfg` is minimal, it's relatively easy to keep
  its documentation up-to-date, which is helpful to bring new
  developers up to speed.  It's our goal that nothing remain
  undocumented about :mod:`repoze.bfg`.

  Furthermore, it's sensible to separate content from presentation -
  which is where templates come in. In Django, a "view" describes
  which data is presented, but a view normally delegates to a
  template, which describes how the data is presented.
Speed
  :mod:`repoze.bfg` is faster than many other popular Python web
  frameworks for common tasks such as templating and simple response
  generation.  The "hardware is cheap" mantra has its limits when
  you're responsible for managing a great many machines: the fewer you
  need, the less pain you'll have.

  Where does the "controller" fit in, then? In Django's case, it's
  probably the framework itself: the machinery that sends a request to
  the appropriate view, according to the Django URL configuration.
Familiarity
  As web developers, we've become accustomed to working in very
  particular ways over the years.  This framework is a canonization of
  practices that "fit our brains".

Trustability
  :mod:`repoze.bfg` is developed conservatively and tested
  exhaustively.  *If it ain't tested, it's broke.* Every release of
  :mod:`repoze.bfg` has 100% unit test converage.

A Sense of Fun
  Developing a :mod:`repoze.bfg` application should not feel foreign
  or "enterprisey".  We like to keep things down-to-earth.

Similarities to Other Web Frameworks
------------------------------------

:mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Pylons` and
:term:`Django`.

.. sidebar:: Django's Authors Explain Why It Doesn't Use "MVC" Terminology

   Django appears to be a MVC framework, but you call the Controller
   the "view", and the View the "template". How come you don't use the
   standard names?  Well, the standard names are debatable.  In our
   interpretation of MVC, the "view" describes the data that gets
   presented to the user. It's not necessarily how the data looks, but
   which data is presented. The view describes which data you see, not
   how you see it. It's a subtle distinction.  So, in our case, a
   "view" is the Python callback function for a particular URL,
   because that callback function describes which data is presented.
   Furthermore, it's sensible to separate content from presentation -
   which is where templates come in. In Django, a "view" describes
   which data is presented, but a view normally delegates to a
   template, which describes how the data is presented.

The :mod:`repoze.bfg` concept of :term:`traversal` is inspired by
:term:`Zope`.  Additionally, :mod:`repoze.bfg` uses a :term:`Zope
Component Architecture` :term:`application registry` internally, as
does Zope 2, Zope 3, and :term:`Grok`.  Like Zope, :mod:`repoze.bfg`
allows you to create applications which do not need to be forked or
otherwise modified to be extended or overridden by a third party
developer.
otherwise modified in order to be extended or overridden by a third
party developer.

The :mod:`repoze.bfg` concept of :term:`URL dispatch` is inspired by
the :term:`Routes` system used by :term:`Pylons`.  Like Pylons,
@@ -55,18 +103,18 @@

The Django docs explain that Django is not an "MVC"
("model/view/controller") framework in their `FAQ
<http://www.djangoproject.com/documentation/faq/>`_.  The sidebar to
the right has the Django authors' take on why "MVC" terminology
doesn't match the web very well.  The concepts of :term:`view` and
:term:`model` are used by :mod:`repoze.bfg` as they would be by
Django.
<http://www.djangoproject.com/documentation/faq/>`_.  The sidebar in
this section describes the Django authors' take on why "MVC"
terminology doesn't match the web very well.  The concepts of
:term:`view` and :term:`model` are used by :mod:`repoze.bfg` as they
would be by Django.

The skeleton code generator of :mod:`repoze.bfg` generates a directory
layout very similar to the directory layout suggested by the `Django
Book <http://www.djangobook.com/>`_ .  

Differences from Other Frameworks
---------------------------------
Differences from Other Web Frameworks
-------------------------------------

Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes more
`control inversion <http://plope.com/control_inversion>`_ upon
@@ -121,152 +169,3 @@
allows you to use a relational database but doesn't encourage or
discourage an application developer about such a decision.

Why?
----

*Familiarity*: As web developers, we've become accustomed to working
in very particular ways over the years.  This framework is a
canonization of practices that "fit our brains".

*Simplicity*: :mod:`repoze.bfg` attempts to be a *"pay only for what
you eat"* framework in which you can be productive quickly with
partial knowledge.  We contrast this with *"pay up front for what
anyone might eventually want to eat"* frameworks, which tend to expect
you to understand a great many concepts and technologies fully before
you can be truly productive.  :mod:`repoze.bfg` doesn't force you to
use any particular technology to produce an application, and we try to
keep the core set of concepts you need to understand to a minimum.

*Minimalism*: :mod:`repoze.bfg` provides only the very basics: *URL to
code mapping*, *templating*, *security*, and *resources*.  There is
not much more to the framework than these pieces: you are expected to
provide the rest.

*Documentation*: Because :mod:`repoze.bfg` is minimal, it's relatively
easy to keep its documentation up-to-date, which is helpful to bring
new developers up to speed.  It's our goal that nothing remain
undocumented about :mod:`repoze.bfg`.

*Speed*: :mod:`repoze.bfg` is faster than many other popular Python
web frameworks for common tasks such as templating and simple response
generation.  The "hardware is cheap" mantra has its limits when you're
responsible for managing a great many machines: the fewer you need,
the less pain you'll have.

It's Tested
-----------

*If it ain't tested, it's broke.* We strive to test :mod:`repoze.bfg`
completely.  Below a run of the ``nosetests`` command configured to
show code coverage information run against the :mod:`repoze.bfg`
trunk shortly after the 1.2a1 release.

.. code-block:: bash
   :linenos:

    [chrism@snowpro trunk]$ python setup.py nosetests --with-coverage
    running nosetests
    running egg_info
    writing requirements to repoze.bfg.egg-info/requires.txt
    writing repoze.bfg.egg-info/PKG-INFO
    writing namespace_packages to repoze.bfg.egg-info/namespace_packages.txt
    writing top-level names to repoze.bfg.egg-info/top_level.txt
    writing dependency_links to repoze.bfg.egg-info/dependency_links.txt
    writing entry points to repoze.bfg.egg-info/entry_points.txt
    writing manifest file 'repoze.bfg.egg-info/SOURCES.txt'
    running build_ext
    ...........................................................................
    ...........................................................................
    ...........................................................................
    ...........................................................................
    ...........................................................................
    ...........................................................................
    ...........................................................................
    ...........................................................................
    ...........................................................................
    ...........................................................................
    .................................................
    Name                                                   Stmts   Exec  Cover   Missing
    ------------------------------------------------------------------------------------
    repoze.bfg                                                 0      0   100%   
    repoze.bfg.authentication                                198    198   100%   
    repoze.bfg.authorization                                  51     51   100%   
    repoze.bfg.chameleon_text                                 46     46   100%   
    repoze.bfg.chameleon_zpt                                  39     39   100%   
    repoze.bfg.compat                                          8      8   100%   
    repoze.bfg.compat.pkgutil_26                               0      0   100%   
    repoze.bfg.configuration                                 605    605   100%   
    repoze.bfg.encode                                         49     49   100%   
    repoze.bfg.events                                         22     22   100%   
    repoze.bfg.exceptions                                      2      2   100%   
    repoze.bfg.includes                                        1      1   100%   
    repoze.bfg.interfaces                                     66     66   100%   
    repoze.bfg.location                                       14     14   100%   
    repoze.bfg.log                                             9      9   100%   
    repoze.bfg.paster                                         58     58   100%   
    repoze.bfg.path                                           38     38   100%   
    repoze.bfg.registry                                       15     15   100%   
    repoze.bfg.renderers                                      47     47   100%   
    repoze.bfg.request                                        57     57   100%   
    repoze.bfg.resource                                      127    127   100%   
    repoze.bfg.router                                        109    109   100%   
    repoze.bfg.scripting                                      12     12   100%   
    repoze.bfg.security                                      123    123   100%   
    repoze.bfg.settings                                       38     38   100%   
    repoze.bfg.static                                         53     53   100%   
    repoze.bfg.testing                                       282    282   100%   
    repoze.bfg.tests                                           1      1   100%   
    repoze.bfg.tests.fixtureapp                                1      1   100%   
    repoze.bfg.tests.fixtureapp.models                         4      4   100%   
    repoze.bfg.tests.fixtureapp.subpackage                     1      1   100%   
    repoze.bfg.tests.fixtureapp.views                          4      4   100%   
    repoze.bfg.tests.grokkedapp                               53     53   100%   
    repoze.bfg.tests.grokkedapp.another                       37     37   100%   
    repoze.bfg.tests.grokkedapp.subpackage                     3      3   100%   
    repoze.bfg.tests.grokkedapp.subpackage.notinit             3      3   100%   
    repoze.bfg.tests.grokkedapp.subpackage.subsubpackage       3      3   100%   
    repoze.bfg.tests.routesapp                                 1      1   100%   
    repoze.bfg.tests.routesapp.views                           4      4   100%   
    repoze.bfg.tests.test_authentication                     487    487   100%   
    repoze.bfg.tests.test_authorization                      132    132   100%   
    repoze.bfg.tests.test_chameleon_text                     165    165   100%   
    repoze.bfg.tests.test_chameleon_zpt                      150    150   100%   
    repoze.bfg.tests.test_compat                               7      7   100%   
    repoze.bfg.tests.test_configuration                     2277   2277   100%   
    repoze.bfg.tests.test_encode                              47     47   100%   
    repoze.bfg.tests.test_events                              80     80   100%   
    repoze.bfg.tests.test_integration                         64     64   100%   
    repoze.bfg.tests.test_location                            34     34   100%   
    repoze.bfg.tests.test_log                                 11     11   100%   
    repoze.bfg.tests.test_paster                             111    111   100%   
    repoze.bfg.tests.test_path                               122    122   100%   
    repoze.bfg.tests.test_registry                            34     34   100%   
    repoze.bfg.tests.test_renderers                          150    150   100%   
    repoze.bfg.tests.test_request                            138    138   100%   
    repoze.bfg.tests.test_resource                           352    352   100%   
    repoze.bfg.tests.test_router                             494    494   100%   
    repoze.bfg.tests.test_scripting                           47     47   100%   
    repoze.bfg.tests.test_security                           315    315   100%   
    repoze.bfg.tests.test_settings                           138    138   100%   
    repoze.bfg.tests.test_static                             126    126   100%   
    repoze.bfg.tests.test_testing                            562    562   100%   
    repoze.bfg.tests.test_threadlocal                         74     74   100%   
    repoze.bfg.tests.test_traversal                          926    926   100%   
    repoze.bfg.tests.test_url                                224    224   100%   
    repoze.bfg.tests.test_urldispatch                        192    192   100%   
    repoze.bfg.tests.test_view                               407    407   100%   
    repoze.bfg.tests.test_wsgi                                99     99   100%   
    repoze.bfg.tests.test_zcml                               781    781   100%   
    repoze.bfg.threadlocal                                    26     26   100%   
    repoze.bfg.traversal                                     187    187   100%   
    repoze.bfg.url                                            76     76   100%   
    repoze.bfg.urldispatch                                   101    101   100%   
    repoze.bfg.view                                          120    120   100%   
    repoze.bfg.wsgi                                           26     26   100%   
    repoze.bfg.zcml                                          299    299   100%   
    ------------------------------------------------------------------------------------
    TOTAL                                                  11765  11765   100%   
    ----------------------------------------------------------------------
    Ran 799 tests in 2.080s

    OK

 docs/narr/router.rst

@@ -1,9 +1,7 @@
.. _router_chapter:

How :mod:`repoze.bfg` Processes A Request
=========================================

.. image:: router.png
Request Processing
==================

Once a :mod:`repoze.bfg` application is up and running, it is ready to
accept requests and return responses.
@@ -93,9 +91,12 @@
   attributes are used to generate a WSGI response.  The response is
   sent back to the upstream WSGI server.

.. image:: router.png

This is a very high-level overview that leaves out various details.
For more detail about subsystems invoked by the BFG router (like
traversal, URL dispatch, views, and events), see
:ref:`url_mapping_chapter`, :ref:`traversal_chapter`,
:ref:`urldispatch_chapter`, :ref:`views_chapter`, and
:ref:`events_chapter`.


 docs/thanks.rst

New file
@@ -0,0 +1,17 @@
Author Thanks
=============

This book is dedicated to my grandmother, Dorothy Phillips.

Thanks to the following people for providing expertise, resources, and
software.  Without the help of these folks, neither this book nor the
software which it details would exist: Paul Everitt, Tres Seaver,
Malthe Borch, Carlos de la Guardia, Simon Oram of Electrosoup, Ian
Bicking of the Open Planning Project, Jim Fulton of Zope Corporation,
Tom Moroz of the Open Society Institute, and Todd Koym of
Environmental Health Sciences.

Special thanks to Guido van Rossum and Tim Peters for Python.

Special thanks also to Tricia for putting up with me.


 docs/zcml.rst

@@ -1,12 +1,12 @@
.. _zcml_directives:

ZCML Directives
===============
----------------

:term:`ZCML` is an XML dialect that may be used by a :mod:`repoze.bfg`
application to perform :term:`declarative configuration`.  Each
:term:`ZCML directive` supplied by :mod:`repoze.bfg` is documented
below.
in this chapter.

.. _configure_directive: