- Move 1.0.1 and previous changelog to HISTORY.txt.

1 files changed, 2 insertions, 2983 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index f7a979ea1..1dc78a37e 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -11,6 +11,8 @@ Bug Fixes
 Documentation
 -------------
 
+- Move 1.0.1 and previous changelog to HISTORY.txt.
+
 - Add examples to ``repoze.bfg.url.model_url`` docstring.
 
 Templates
@@ -1096,2986 +1098,3 @@ Backwards Incompatibilities
   registry by the view machinery during deferred ZCML processing, view
   security will not work as expected.
 
-1.0.1 (2009-07-22)
-==================
-
-- Added support for ``has_resource``, ``resource_isdir``, and
-  ``resource_listdir`` to the resource "OverrideProvider"; this fixes
-  a bug with a symptom that a file could not be overridden in a
-  resource directory unless a file with the same name existed in the
-  original directory being overridden.
-
-- Fixed documentation bug showing invalid test for values from the
-  ``matchdict``:  they are stored as attributes of the ``Article``, rather
-  than subitems.
-
-- Fixed documentation bug showing wrong environment key for the ``matchdict``
-  produced by the matching route.
-
-- Added a workaround for a bug in Python 2.6, 2.6.1, and 2.6.2 having
-  to do with a recursion error in the mimetypes module when trying to
-  serve static files from Paste's FileApp:
-  http://bugs.python.org/issue5853.  Symptom: File
-  "/usr/lib/python2.6/mimetypes.py", line 244, in guess_type return
-  guess_type(url, strict) RuntimeError: maximum recursion depth
-  exceeded.  Thanks to Armin Ronacher for identifying the symptom and
-  pointing out a fix.
-
-- Minor edits to tutorials for accuracy based on feedback.
-
-- Declared Paste and PasteDeploy dependencies.
-
-1.0 (2009-07-05)
-================
-
-- Retested and added some content to GAE tutorial.
-
-- Edited "Extending" narrative docs chapter.
-
-- Added "Deleting the Database" section to the "Defining Models"
-  chapter of the traversal wiki tutorial.
-
-- Spell checking of narratives and tutorials.
-
-1.0b2 (2009-07-03)
-==================
-
-- ``remoteuserauthenticationpolicy`` ZCML directive didn't work
-  without an ``environ_key`` directive (didn't match docs).
-
-- Fix ``configure_zcml`` filespec check on Windows.  Previously if an
-  absolute filesystem path including a drive letter was passed as
-  ``filename`` (or as ``configure_zcml`` in the options dict) to
-  ``repoze.bfg.router.make_app``, it would be treated as a
-  package:resource_name specification.
-
-- Fix inaccuracies and import errors in bfgwiki (traversal+ZODB) and
-  bfgwiki2 (urldispatch+SA) tutorials.
-
-- Use bfgsite index for all tutorial setup.cfg files.
-
-- Full documentation grammar/style/spelling audit.
-
-1.0b1 (2009-07-02)
-==================
-
-Features
---------
-
-- Allow a Paste config file (``configure_zcml``) value or an
-  environment variable (``BFG_CONFIGURE_ZCML``) to name a ZCML file
-  (optionally package-relative) that will be used to bootstrap the
-  application.  Previously, the integrator could not influence which
-  ZCML file was used to do the boostrapping (only the original
-  application developer could do so).
-
-Documentation
--------------
-
-- Added a "Resources" chapter to the narrative documentation which
-  explains how to override resources within one package from another
-  package.
-
-- Added an "Extending" chapter to the narrative documentation which
-  explains how to extend or modify an existing BFG application using
-  another Python package and ZCML.
-
-1.0a9 (2009-07-01)
-==================
-
-Features
---------
-
-- Make it possible to pass strings in the form
-  "package_name:relative/path" to APIs like ``render_template``,
-  ``render_template_to_response``, and ``get_template``.  Sometimes
-  the package in which a caller lives is a direct namespace package,
-  so the module which is returned is semi-useless for navigating from.
-  In this way, the caller can control the horizontal and vertical of
-  where things get looked up from.
-
-1.0a8 (2009-07-01)
-==================
-
-Deprecations
-------------
-
-- Deprecate the ``authentication_policy`` and ``authorization_policy``
-  arguments to ``repoze.bfg.router.make_app``.  Instead, developers
-  should use the various authentication policy ZCML directives
-  (``repozewho1authenticationpolicy``,
-  ``remoteuserauthenticationpolicy`` and
-  ``authtktauthenticationpolicy``) and the `aclauthorizationpolicy``
-  authorization policy directive as described in the changes to the
-  "Security" narrative documenation chapter and the wiki tutorials.
-
-Features
---------
-
-- Add three new ZCML directives which configure authentication
-  policies:
-
-  - ``repozewho1authenticationpolicy``
-
-  - ``remoteuserauthenticationpolicy``
-
-  - ``authtktauthenticationpolicy``
-
-- Add a new ZCML directive which configures an ACL authorization
-  policy named ``aclauthorizationpolicy``.
-
-Bug Fixes
----------
-
-- Bug fix: when a ``repoze.bfg.resource.PackageOverrides`` class was
-  instantiated, and the package it was overriding already had a
-  ``__loader__`` attribute, it would fail at startup time, even if the
-  ``__loader__`` attribute was another PackageOverrides instance.  We
-  now replace any ``__loader__`` that is also a PackageOverrides
-  instance.  Symptom: ``ConfigurationExecutionError: <type
-  'exceptions.TypeError'>: Package <module 'karl.views' from
-  '/Users/chrism/projects/osi/bfgenv/src/karl/karl/views/__init__.pyc'>
-  already has a __loader__ (probably a module in a zipped egg)``.
-
-1.0a7 (2009-06-30)
-==================
-
-Features
---------
-
-- Add a ``reload_resources`` configuration file setting (aka the
-  ``BFG_RELOAD_RESOURCES`` environment variable).  When this is set to
-  true, the server never needs to be restarted when moving files
-  between directory resource overrides (esp. for templates currently).
-
-- Add a ``reload_all`` configuration file setting (aka the
-  ``BFG_RELOAD_ALL`` environment variable) that implies both
-  ``reload_resources`` and ``reload_templates``.
-
-- The ``static`` helper view class now uses a ``PackageURLParser`` in
-  order to allow for the overriding of static resources (CSS / logo
-  files, etc) using the ``resource`` ZCML directive.  The
-  ``PackageURLParser`` class was added to a (new) ``static`` module in
-  BFG; it is a subclass of the ``StaticURLParser`` class in
-  ``paste.urlparser``.
-
-- The ``repoze.bfg.templating.renderer_from_cache`` function now
-  checks for the ``reload_resources`` setting; if it's true, it does
-  not register a template renderer (it won't use the registry as a
-  template renderer cache).
-
-Documentation
--------------
-
-- Add ``pkg_resources`` to the glossary.
-
-- Update the "Environment" docs to note the existence of
-  ``reload_resources`` and ``reload_all``.
-
-- Updated the ``bfg_alchemy`` paster template to include two views:
-  the view on the root shows a list of links to records;  the view on
-  a record shows the details for that object.
-
-Internal
---------
-
-- Use a colon instead of a tab as the separator between package name
-  and relpath to form the "spec" when register a ITemplateRenderer.
-
-- Register a ``repoze.bfg.resource.OverrideProvider`` as a
-  pkg_resources provider only for modules which are known to have
-  overrides, instead of globally, when a <resource> directive is used
-  (performance).
-
-1.0a6 (2009-06-29)
-==================
-
-Bug Fixes
----------
-
-- Use ``caller_package`` function instead of ``caller_module``
-  function within ``templating`` to avoid needing to name the caller
-  module in resource overrides (actually match docs).
-
-- Make it possible to override templates stored directly in a module
-  with templates in a subdirectory of the same module, stored directly
-  within another module, or stored in a subdirectory of another module
-  (actually match docs).
-
-1.0a5 (2009-06-28)
-==================
-
-Features
---------
-
-- A new ZCML directive exists named "resource".  This ZCML directive
-  allows you to override Chameleon templates within a package (both
-  directories full of templates and individual template files) with
-  other templates in the same package or within another package.  This
-  allows you to "fake out" a view's use of a template, causing it to
-  retrieve a different template than the one actually named by a
-  relative path to a call like
-  ``render_template_to_response('templates/mytemplate.pt')``.  For
-  example, you can override a template file by doing::
-
-    <resource
-      to_override="some.package:templates/mytemplate.pt"
-      override_with="another.package:othertemplates/anothertemplate.pt"
-     />
-
-  The string passed to "to_override" and "override_with" is named a
-  "specification".  The colon separator in a specification separates
-  the package name from a package-relative directory name.  The colon
-  and the following relative path are optional.  If they are not
-  specified, the override attempts to resolve every lookup into a
-  package from the directory of another package.  For example::
-
-    <resource
-      to_override="some.package"
-      override_with="another.package"
-     />
-
-
-  Individual subdirectories within a package can also be overridden::
-
-    <resource
-      to_override="some.package:templates/"
-      override_with="another.package:othertemplates/"
-     />
-
-  If you wish to override a directory with another directory, you must
-  make sure to attach the slash to the end of both the ``to_override``
-  specification and the ``override_with`` specification.  If you fail
-  to attach a slash to the end of a specification that points a
-  directory, you will get unexpected results.  You cannot override a
-  directory specification with a file specification, and vice versa (a
-  startup error will occur if you try).
-
-  You cannot override a resource with itself (a startup error will
-  occur if you try).
-
-  Only individual *package* resources may be overridden.  Overrides
-  will not traverse through subpackages within an overridden package.
-  This means that if you want to override resources for both
-  ``some.package:templates``, and ``some.package.views:templates``,
-  you will need to register two overrides.
-
-  The package name in a specification may start with a dot, meaning
-  that the package is relative to the package in which the ZCML file
-  resides.  For example::
-
-    <resource
-      to_override=".subpackage:templates/"
-      override_with="another.package:templates/"
-     />
-
-  Overrides for the same ``to_overrides`` specification can be named
-  multiple times within ZCML.  Each ``override_with`` path will be
-  consulted in the order defined within ZCML, forming an override
-  search path.
-
-  Resource overrides can actually override resources other than
-  templates.  Any software which uses the ``pkg_resources``
-  ``get_resource_filename``, ``get_resource_stream`` or
-  ``get_resource_string`` APIs will obtain an overridden file when an
-  override is used.  However, the only built-in facility which uses
-  the ``pkg_resources`` API within BFG is the templating stuff, so we
-  only call out template overrides here.
-
-- Use the ``pkg_resources`` API to locate template filenames instead
-  of dead-reckoning using the ``os.path`` module.
-
-- The ``repoze.bfg.templating`` module now uses ``pkg_resources`` to
-  locate and register template files instead of using an absolute
-  path name.
-
-1.0a4 (2009-06-25)
-==================
-
-Features
---------
-
-- Cause ``:segment`` matches in route paths to put a Unicode-decoded
-  and URL-dequoted value in the matchdict for the value matched.
-  Previously a non-decoded non-URL-dequoted string was placed in the
-  matchdict as the value.
-
-- Cause ``*remainder`` matches in route paths to put a *tuple* in the
-  matchdict dictionary in order to be able to present Unicode-decoded
-  and URL-dequoted values for the traversal path.  Previously a
-  non-decoded non-URL-dequoted string was placed in the matchdict as
-  the value.
-
-- Add optional ``max_age`` keyword value to the ``remember`` method of
-  ``repoze.bfg.authentication.AuthTktAuthenticationPolicy``; if this
-  value is passed to ``remember``, the generated cookie will have a
-  corresponding Max-Age value.
-
-Documentation
--------------
-
-- Add information to the URL Dispatch narrative documentation about
-  path pattern matching syntax.
-
-Bug Fixes
----------
-
-- Make ``route_url`` URL-quote segment replacements during generation.
-  Remainder segments are not quoted.
-
-1.0a3 (2009-06-24)
-==================
-
-Implementation Changes
-----------------------
-
-- ``repoze.bfg`` no longer relies on the Routes package to interpret
-  URL paths.  All known existing ``path`` patterns will continue to
-  work with the reimplemented logic, which lives in
-  ``repoze.bfg.urldispatch``.  ``<route>`` ZCML directives which use
-  certain attributes (uncommon ones) may not work (see "Backwards
-  Incompatibilities" below).
-
-Bug Fixes
----------
-
-- ``model_url`` when passed a request that was generated as a result
-  of a route match would fail in a call to ``route.generate``.
-
-- BFG-on-GAE didn't work due to a corner case bug in the fallback
-  Python implementation of ``threading.local`` (symptom:
-  "Initialization arguments are not supported").  Thanks to Michael
-  Bernstein for the bug report.
-
-Documentation
--------------
-
-- Added a "corner case" explanation to the "Hybrid Apps" chapter
-  explaining what to do when "the wrong" view is matched.
-
-- Use ``repoze.bfg.url.route_url`` API in tutorials rather than Routes
-  ``url_for`` API.
-
-Features
---------
-
-- Added the ``repoze.bfg.url.route_url`` API.  This API allows you to
-  generate URLs based on ``<route>`` declarations.  See the URL
-  Dispatch narrative chapter and the "repoze.bfg.url" module API
-  documentation for more information.
-
-Backwards Incompatibilities
----------------------------
-
-- As a result of disusing Routes, using the Routes ``url_for`` API
-  inside a BFG application (as was suggested by previous iterations of
-  tutorials) will no longer work.  Use the
-  ``repoze.bfg.url.route_url`` method instead.
-
-- The following attributes on the ``<route>`` ZCML directive no longer
-  work: ``encoding``, ``static``, ``filter``, ``condition_method``,
-  ``condition_subdomain``, ``condition_function``, ``explicit``, or
-  ``subdomains``.  These were all Routes features.
-
-- The ``<route>`` ZCML directive no longer supports the
-  ``<requirement>`` subdirective.  This was a Routes feature.
-
-1.0a2 (2009-06-23)
-==================
-
-Bug Fixes
----------
-
-- The ``bfg_routesalchemy`` paster template app tests failed due to a
-  mismatch between test and view signatures.
-
-Features
---------
-
-- Add a ``view_for`` attribute to the ``route`` ZCML directive.  This
-  attribute should refer to an interface or a class (ala the ``for``
-  attribute of the ``view`` ZCML directive).
-
-Documentation
--------------
-
-- Conditional documentation in installation section ("how to install a
-  Python interpreter").
-
-Backwards Incompatibilities
----------------------------
-
-- The ``callback`` argument of the ``repoze.bfg.authentication``
-  authentication policies named ``RepozeWho1AuthenticationPolicy``,
-  ``RemoteUserAuthenticationPolicy``, and
-  ``AuthTktAuthenticationPolicy`` now must accept two positional
-  arguments: the orginal argument accepted by each (userid or
-  identity) plus a second argument, which will be the current request.
-  Apologies, this is required to service finding groups when there is
-  no "global" database connection.
-
-1.0a1 (2009-06-22)
-==================
-
-Features
---------
-
-- A new ZCML directive was added named ``notfound``.  This ZCML
-  directive can be used to name a view that should be invoked when the
-  request can't otherwise be resolved to a view callable.  For example::
-
-    <notfound 
-        view="helloworld.views.notfound_view"/>
-
-- A new ZCML directive was added named ``forbidden``.  This ZCML
-  directive can be used to name a view that should be invoked when a
-  view callable for a request is found, but cannot be invoked due to
-  an authorization failure.  For example::
-
-   <forbidden
-       view="helloworld.views.forbidden_view"/>
-
-- Allow views to be *optionally* defined as callables that accept only
-  a request object, instead of both a context and a request (which
-  still works, and always will).  The following types work as views in
-  this style:
-
-  - functions that accept a single argument ``request``, e.g.::
-
-      def aview(request):
-          pass
-
-  - new and old-style classes that have an ``__init__`` method that
-    accepts ``self, request``, e.g.::
-
-      def View(object):
-          __init__(self, request):
-             pass
-
-  - Arbitrary callables that have a ``__call__`` method that accepts
-    ``self, request``, e.g.::
-
-      def AView(object):
-          def __call__(self, request):
-             pass
-      view = AView()
-
-  This likely should have been the calling convention all along, as
-  the request has ``context`` as an attribute already, and with views
-  called as a result of URL dispatch, having the context in the
-  arguments is not very useful.  C'est la vie.
-
-- Cache the absolute path in the caller's package globals within
-  ``repoze.bfg.path`` to get rid of repeated (expensive) calls to
-  os.path.abspath.
-
-- Add ``reissue_time`` and ``timeout`` parameters to
-  ``repoze.bfg.authentication.AuthTktAuthenticationPolicy``
-  constructor.  If these are passed, cookies will be reset every so
-  often (cadged from the same change to repoze.who lately).
-
-- The matchdict related to the matching of a Routes route is available
-  on the request as the ``matchdict`` attribute:
-  ``request.matchdict``.  If no route matched, this attribute will be
-  None.
-
-- Make 404 responses slightly cheaper by showing
-  ``environ["PATH_INFO"]`` on the notfound result page rather than the
-  fullly computed URL.
-
-- Move LRU cache implementation into a separate package
-  (``repoze.lru``).
-
-- The concepts of traversal and URL dispatch have been unified.  It is
-  now possible to use the same sort of factory as both a traversal
-  "root factory" and what used to be referred to as a urldispatch
-  "context factory".
-
-- When the root factory argument (as a first argument) passed to
-  ``repoze.bfg.router.make_app`` is ``None``, a *default* root factory
-  is used.  This is in support of using routes as "root finders"; it
-  supplants the idea that there is a default
-  ``IRoutesContextFactory``.
-
-- The `view`` ZCML statement and the ``repoze.bfg.view.bfg_view``
-  decorator now accept an extra argument: ``route_name``.  If a
-  ``route_name`` is specified, it must match the name of a previously
-  defined ``route`` statement.  When it is specified, the view will
-  only be called when that route matches during a request.
-
-- It is now possible to perfom traversal *after* a route has matched.
-  Use the pattern ``*traverse`` in a ``<route>`` ``path`` attribute
-  within ZCML, and the path remainder which it matches will be used as
-  a traversal path.
-
-- When any route defined matches, the WSGI environment will now
-  contain a key ``bfg.routes.route`` (the Route object which matched),
-  and a key ``bfg.routes.matchdict`` (the result of calling route.match).
-
-Deprecations
-------------
-
-- Utility registrations against
-  ``repoze.bfg.interfaces.INotFoundView`` and
-  ``repoze.bfg.interfaces.IForbiddenView`` are now deprecated.  Use
-  the ``notfound`` and ``forbidden`` ZCML directives instead (see the
-  "Hooks" chapter for more information).  Such registrations will
-  continue to work, but the notfound and forbidden directives do
-  "extra work" to ensure that the callable named by the directive can
-  be called by the router even if it's a class or
-  request-argument-only view.
-
-Removals
---------
-
-- The ``IRoutesContext``, ``IRoutesContextFactory``, and
-  ``IContextNotFound`` interfaces were removed from
-  ``repoze.bfg.interfaces``.  These were never APIs.
-
-- The ``repoze.bfg.urldispatch.RoutesContextNotFound``,
-  ``repoze.bfg.urldispatch.RoutesModelTraverser`` and
-  ``repoze.bfg.urldispatch.RoutesContextURL`` classes were removed.
-  These were also never APIs.
-
-Backwards Incompatibilities
----------------------------
-
-- Moved the ``repoze.bfg.push`` module, which implemented the ``pushpage``
-  decorator, into a separate distribution, ``repoze.bfg.pushpage``.
-  Applications which used this decorator should continue to work after
-  adding that distribution to their installation requirements.
-
-- Changing the default request factory via an IRequestFactory utility
-  registration (as used to be documented in the "Hooks" chapter's
-  "Changing the request factory" section) is no longer supported.  The
-  dance to manufacture a request is complicated as a result of
-  unifying traversal and url dispatch, making it highly unlikely for
-  anyone to be able to override it properly.  For those who just want
-  to decorate or modify a request, use a NewRequestEvent subscriber
-  (see the Events chapter in the documentation).
-
-- The ``repoze.bfg.IRequestFactory`` interface was removed.  See the
-  bullet above for why.
-
-- Routes "context factories" (spelled as the factory argument to a
-  route statement in ZCML) must now expect the WSGI environ as a
-  single argument rather than a set of keyword arguments.  They can
-  obtain the match dictionary by asking for
-  environ['bfg.routes.matchdict'].  This is the same set of keywords
-  that used to be passed to urldispatch "context factories" in BFG 0.9
-  and below.
-
-- Using the ``@zope.component.adapter`` decorator on a bfg view
-  function no longer works.  Use the ``@repoze.bfg.view.bfg_view``
-  decorator instead to mark a function (or a class) as a view.
-
-- The name under which the matching route object is found in the
-  environ was changed from ``bfg.route`` to ``bfg.routes.route``.
-
-- Finding the root is now done *before* manufacturing a request object
-  (and sending a new request event) within the router (it used to be
-  performed afterwards).
-
-- Adding ``*path_info`` to a route no longer changes the PATH_INFO for
-  a request that matches using URL dispatch.  This feature was only
-  there to service the ``repoze.bfg.wsgi.wsgiapp2`` decorator and it
-  did it wrong; use ``*subpath`` instead now.
-
-- The values of ``subpath``, ``traversed``, and ``virtual_root_path``
-  attached to the request object are always now tuples instead of
-  lists (performance).
-
-Bug Fixes
----------
-
-- The ``bfg_alchemy`` Paster template named "repoze.tm" in its
-  pipeline rather than "repoze.tm2", causing the startup to fail.
-
-- Move BBB logic for registering an
-  IAuthenticationPolicy/IForbiddenView/INotFoundView based on older
-  concepts from the router module's ``make_app`` function into the
-  ``repoze.bfg.zcml.zcml_configure`` callable, to service
-  compatibility with scripts that use "zope.configuration.xmlconfig"
-  (replace with ``repoze.bfg.zml.zcml_configure`` as necessary to get
-  BBB logic)
-
-Documentation
--------------
-
-- Add interface docs related to how to create authentication policies
-  and authorization policies to the "Security" narrative chapter.
-
-- Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter
-  to the narrative documentation.  This explains the usage of
-  ``*traverse`` and ``*subpath`` in routes URL patters.
-
-- A "router" chapter explaining the request/response lifecycle at a
-  high level was added.
-
-- Replaced all mentions and explanations of a routes "context factory"
-  with equivalent explanations of a "root factory" (context factories
-  have been disused).
-
-- Updated Routes bfgwiki2 tutorial to reflect the fact that context
-  factories are now no longer used.
-
-0.9.1 (2009-06-02)
-==================
-
-Features
---------
-
-- Add API named ``repoze.bfg.settings.get_settings`` which retrieves a
-  derivation of values passed as the ``options`` value of
-  ``repoze.bfg.router.make_app``.  This API should be preferred
-  instead of using getUtility(ISettings).  I added a new
-  ``repoze.bfg.settings`` API document as well.
-
-Bug Fixes
----------
-
-- Restored missing entry point declaration for bfg_alchemy paster
-  template, which was accidentally removed in 0.9.
-
-Documentation
--------------
-
-- Fix a reference to ``wsgiapp`` in the ``wsgiapp2`` API documentation
-  within the ``repoze.bfg.wsgi`` module.
-
-API Removals
-------------
-
-- The ``repoze.bfg.location.locate`` API was removed: it didn't do
-  enough to be very helpful and had a misleading name.
-
-0.9 (2009-06-01)
-================
-
-Bug Fixes
----------
-
-- It was not possible to register a custom ``IRoutesContextFactory``
-  for use as a default context factory as documented in the "Hooks"
-  chapter.
-
-Features
---------
-
-- The ``request_type`` argument of ZCML ``view`` declarations and
-  ``bfg_view`` decorators can now be one of the strings ``GET``,
-  ``POST``, ``PUT``, ``DELETE``, or ``HEAD`` instead of a reference to
-  the respective interface type imported from
-  ``repoze.bfg.interfaces``.
-
-- The ``route`` ZCML directive now accepts ``request_type`` as an
-  alias for its ``condition_method`` argument for symmetry with the
-  ``view`` directive.
-
-- The ``bfg_routesalchemy`` paster template now provides a unit test
-  and actually uses the database during a view rendering.
-
-Removals
---------
-
-- Remove ``repoze.bfg.threadlocal.setManager``.  It was only used in
-  unit tests.
-
-- Remove ``repoze.bfg.wsgi.HTTPException``,
-  ``repoze.bfg.wsgi.NotFound``, and ``repoze.bfg.wsgi.Unauthorized``.
-  These classes were disused with the introduction of the
-  ``IUnauthorizedView`` and ``INotFoundView`` machinery.
-
-Documentation
--------------
-
-- Add description to narrative templating chapter about how to use
-  Chameleon text templates.
-
-- Changed Views narrative chapter to use method strings rather than
-  interface types, and moved advanced interface type usage to Events
-  narrative chapter.
-
-- Added a Routes+SQLAlchemy wiki tutorial.
-
-0.9a8 (2009-05-31)
-==================
-
-Features
---------
-
-- It is now possible to register a custom
-  ``repoze.bfg.interfaces.INotFoundView`` for a given application.
-  This feature replaces the
-  ``repoze.bfg.interfaces.INotFoundAppFactory`` feature previously
-  described in the Hooks chapter.  The INotFoundView will be called
-  when the framework detects that a view lookup done as a result of a
-  request fails; it should accept a context object and a request
-  object; it should return an IResponse object (a webob response,
-  basically).  See the Hooks narrative chapter of the BFG docs for
-  more info.
-
-- The error presented when a view invoked by the router returns a
-  non-response object now includes the view's name for troubleshooting
-  purposes.
-
-Bug Fixes
----------
-
-- A "new response" event is emitted for forbidden and notfound views.
-
-Deprecations
-------------
-
-- The ``repoze.bfg.interfaces.INotFoundAppFactory`` interface has been
-  deprecated in favor of using the new
-  ``repoze.bfg.interfaces.INotFoundView`` mechanism.
-
-Renames
--------
-
-- Renamed ``repoze.bfg.interfaces.IForbiddenResponseFactory`` to
-  ``repoze.bfg.interfaces.IForbiddenView``.
-
-0.9a7 (2009-05-30)
-==================
-
-Features
---------
-
-- Remove "context" argument from ``effective_principals`` and
-  ``authenticated_userid`` function APIs in ``repoze.bfg.security``,
-  effectively a doing reversion to 0.8 and before behavior.  Both
-  functions now again accept only the ``request`` parameter.
-
-0.9a6 (2009-05-29)
-==================
-
-Documentation
--------------
-
-- Changed "BFG Wiki" tutorial to use AuthTktAuthenticationPolicy
-  rather than repoze.who.
-
-Features
---------
-
-- Add an AuthTktAuthenticationPolicy.  This policy retrieves
-  credentials from an auth_tkt cookie managed by the application
-  itself (instead of relying on an upstream data source for
-  authentication data).  See the Security API chapter of the
-  documentation for more info.
-
-- Allow RemoteUserAuthenticationPolicy and
-  RepozeWho1AuthenticationPolicy to accept various constructor
-  arguments.  See the Security API chapter of the documentation for
-  more info.
-
-0.9a5 (2009-05-28)
-==================
-
-Features
---------
-
-- Add a ``get_app`` API functions to the ``paster`` module.  This
-  obtains a WSGI application from a config file given a config file
-  name and a section name.  See the ``repoze.bfg.paster`` API docs for
-  more information.
-
-- Add a new module named ``scripting``.  It contains a ``get_root``
-  API function, which, provided a Router instance, returns a traversal
-  root object and a "closer".  See the ``repoze.bfg.scripting`` API
-  docs for more info.
-
-0.9a4 (2009-05-27)
-==================
-
-Bug Fixes
----------
-
-- Try checking for an "old style" security policy *after* we parse
-  ZCML (thinko).
-
-0.9a3 (2009-05-27)
-==================
-
-Features
---------
-
-- Allow IAuthenticationPolicy and IAuthorizationPolicy to be
-  overridden via ZCML registrations (do ZCML parsing after
-  registering these in router.py).
-
-Documentation
--------------
-
-- Added "BFG Wiki" tutorial to documentation; it describes
-  step-by-step how to create a traversal-based ZODB application with
-  authentication.
-
-Deprecations
-------------
-
-- Added deprecations for imports of ``ACLSecurityPolicy``,
-  ``InheritingACLSecurityPolicy``, ``RemoteUserACLSecurityPolicy``,
-  ``RemoteUserInheritingACLSecurityPolicy``, ``WhoACLSecurityPolicy``,
-  and ``WhoInheritingACLSecurityPolicy`` from the
-  ``repoze.bfg.security`` module; for the meantime (for backwards
-  compatibility purposes) these live in the ``repoze.bfg.secpols``
-  module.  Note however, that the entire concept of a "security
-  policy" is deprecated in BFG in favor of separate authentication and
-  authorization policies, so any use of a security policy will
-  generate additional deprecation warnings even if you do start using
-  ``repoze.bfg.secpols``.  ``repoze.bfg.secpols`` will disappear in a
-  future release of ``repoze.bfg``.
-
-Deprecated Import Alias Removals
---------------------------------
-
-- Remove ``repoze.bfg.template`` module.  All imports from this
-  package have been deprecated since 0.3.8.  Instead, import
-  ``get_template``, ``render_template``, and
-  ``render_template_to_response`` from the
-  ``repoze.bfg.chameleon_zpt`` module. 
-
-- Remove backwards compatibility import alias for
-  ``repoze.bfg.traversal.split_path`` (deprecated since 0.6.5).  This
-  must now be imported as ``repoze.bfg.traversal.traversal_path``).
-
-- Remove backwards compatibility import alias for
-  ``repoze.bfg.urldispatch.RoutesContext`` (deprecated since 0.6.5).
-  This must now be imported as
-  ``repoze.bfg.urldispatch.DefaultRoutesContext``.
-
-- Removed backwards compatibility import aliases for
-  ``repoze.bfg.router.get_options`` and ``repoze.bfg.router.Settings``
-  (deprecated since 0.6.2).  These both must now be imported from
-  ``repoze.bfg.settings``.
-
-- Removed backwards compatibility import alias for
-  ``repoze.bfg.interfaces.IRootPolicy`` (deprecated since 0.6.2).  It
-  must be imported as ``repoze.bfg.interfaces.IRootFactory`` now.
-
-- Removed backwards compatibility import alias for
-  ``repoze.bfg.interfaces.ITemplate`` (deprecated since 0.4.4).  It
-  must be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` now.
-
-- Removed backwards compatibility import alias for
-  ``repoze.bfg.interfaces.ITemplateFactory`` (deprecated since 0.4.4).
-  It must be imported as
-  ``repoze.bfg.interfaces.ITemplateRendererFactory`` now.
-
-- Removed backwards compatibility import alias for
-  ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` (deprecated since
-  0.4.4).  This must be imported as ``repoze.bfg.ZPTTemplateRenderer``
-  now.
-
-0.9a2 (2009-05-27)
-==================
-
-Features
---------
-
-- A paster command has been added named "bfgshell".  This command can
-  be used to get an interactive prompt with your BFG root object in
-  the global namespace.  E.g.::
-
-    bin/paster bfgshell /path/to/myapp.ini myapp
-
-  See the ``Project`` chapter in the BFG documentation for more
-  information.
-
-Deprecations
-------------
-
-- The name ``repoze.bfg.registry.registry_manager`` was never an API,
-  but scripts in the wild were using it to set up an environment for
-  use under a debug shell.  A backwards compatibility shim has been
-  added for this purpose, but the feature is deprecated.
-
-0.9a1 (2009-5-27)
-=================
-
-Features
---------
-
-- New API functions named ``forget`` and ``remember`` are available in
-  the ``security`` module.  The ``forget`` function returns headers
-  which will cause the currently authenticated user to be logged out
-  when set in a response.  The ``remember`` function (when passed the
-  proper arguments) will return headers which will cause a principal
-  to be "logged in" when set in a response.  See the Security API
-  chapter of the docs for more info.
-
-- New keyword arguments to the ``repoze.bfg.router.make_app`` call
-  have been added: ``authentication_policy`` and
-  ``authorization_policy``.  These should, respectively, be an
-  implementation of an authentication policy (an object implementing
-  the ``repoze.bfg.interfaces.IAuthenticationPolicy`` interface) and
-  an implementation of an authorization policy (an object implementing
-  ``repoze.bfg.interfaces.IAuthorizationPolicy)``.  Concrete
-  implementations of authentication policies exist in
-  ``repoze.bfg.authentication``.  Concrete implementations of
-  authorization policies exist in ``repoze.bfg.authorization``.
-
-  Both ``authentication_policy`` and ``authorization_policy`` default
-  to ``None``.
-
-  If ``authentication_policy`` is ``None``, but
-  ``authorization_policy`` is *not* ``None``, then
-  ``authorization_policy`` is ignored (the ability to do authorization
-  depends on authentication).
-
-  If the ``authentication_policy`` argument is *not* ``None``, and the
-  ``authorization_policy`` argument *is* ``None``, the authorization
-  policy defaults to an authorization implementation that uses ACLs
-  (``repoze.bfg.authorization.ACLAuthorizationPolicy``).
-
-  We no longer encourage configuration of "security policies" using
-  ZCML, as previously we did for ``ISecurityPolicy``.  This is because
-  it's not uncommon to need to configure settings for concrete
-  authorization or authentication policies using paste .ini
-  parameters; the app entry point for your application is the natural
-  place to do this.
-
-- Two new abstractions have been added in the way of adapters used by
-  the system: an ``IAuthorizationPolicy`` and an
-  ``IAuthenticationPolicy``.  A combination of these (as registered by
-  the ``securitypolicy`` ZCML directive) take the place of the
-  ``ISecurityPolicy`` abstraction in previous releases of repoze.who.
-  The API functions in ``repoze.who.security`` (such as
-  ``authentication_userid``, ``effective_principals``,
-  ``has_permission``, and so on) have been changed to try to make use
-  of these new adapters.  If you're using an older ``ISecurityPolicy``
-  adapter, the system will still work, but it will print deprecation
-  warnings when such a policy is used.
-
-- The way the (internal) IViewPermission utilities registered via ZCML
-  are invoked has changed.  They are purely adapters now, returning a
-  boolean result, rather than returning a callable. You shouldn't have
-  been using these anyway. ;-)
-
-- New concrete implementations of IAuthenticationPolicy have been
-  added to the ``repoze.bfg.authentication`` module:
-  ``RepozeWho1AuthenticationPolicy`` which uses ``repoze.who``
-  identity to retrieve authentication data from and
-  ``RemoteUserAuthenticationPolicy``, which uses the ``REMOTE_USER``
-  value in the WSGI environment to retrieve authentication data.
-
-- A new concrete implementation of IAuthorizationPolicy has been added
-  to the ``repoze.bfg.authorization`` module:
-  ``ACLAuthorizationPolicy`` which uses ACL inheritance to do
-  authorization.
-
-- It is now possible to register a custom
-  ``repoze.bfg.interfaces.IForbiddenResponseFactory`` for a given
-  application.  This feature replaces the
-  ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` feature previously
-  described in the Hooks chapter.  The IForbiddenResponseFactory will
-  be called when the framework detects an authorization failure; it
-  should accept a context object and a request object; it should
-  return an IResponse object (a webob response, basically).  Read the
-  below point for more info and see the Hooks narrative chapter of the
-  BFG docs for more info.
-
-Backwards Incompatibilities
----------------------------
-
-- Custom NotFound and Forbidden (nee' Unauthorized) WSGI applications
-  (registered as a utility for INotFoundAppFactory and
-  IUnauthorizedAppFactory) could rely on an environment key named
-  ``message`` describing the circumstance of the response.  This key
-  has been renamed to ``repoze.bfg.message`` (as per the WSGI spec,
-  which requires environment extensions to contain dots).
-
-Deprecations
-------------
-
-- The ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` interface has
-  been deprecated in favor of using the new
-  ``repoze.bfg.interfaces.IForbiddenResponseFactory`` mechanism.
-
-- The ``view_execution_permitted`` API should now be imported from the
-  ``repoze.bfg.security`` module instead of the ``repoze.bfg.view``
-  module.
-
-- The ``authenticated_userid`` and ``effective_principals`` APIs in
-  ``repoze.bfg.security`` used to only take a single argument
-  (request).  They now accept two arguments (``context`` and
-  ``request``).  Calling them with a single argument is still
-  supported but issues a deprecation warning.  (NOTE: this change was
-  reverted in 0.9a7; meaning the 0.9 versions of these functions
-  again accept ``request`` only, just like 0.8 and before).
-
-- Use of "old-style" security policies (those base on ISecurityPolicy)
-  is now deprecated.  See the "Security" chapter of the docs for info
-  about activating an authorization policy and an authentication poicy.
-
-0.8.1 (2009-05-21)
-==================
-
-Features
---------
-
-- Class objects may now be used as view callables (both via ZCML and
-  via use of the ``bfg_view`` decorator in Python 2.6 as a class
-  decorator).  The calling semantics when using a class as a view
-  callable is similar to that of using a class as a Zope "browser
-  view": the class' ``__init__`` must accept two positional parameters
-  (conventionally named ``context``, and ``request``).  The resulting
-  instance must be callable (it must have a ``__call__`` method).
-  When called, the instance should return a response.  For example::
-
-    from webob import Response
-
-    class MyView(object):
-        def __init__(self, context, request):
-            self.context = context
-            self.request = request
-
-        def __call__(self):
-            return Response('hello from %s!' % self.context)
-
-   See the "Views" chapter in the documentation and the
-   ``repoze.bfg.view`` API documentation for more information.
-
-- Removed the pickling of ZCML actions (the code that wrote
-  ``configure.zcml.cache`` next to ``configure.zcml`` files in
-  projects).  The code which managed writing and reading of the cache
-  file was a source of subtle bugs when users switched between
-  imperative (e.g. ``@bfg_view``) registrations and declarative
-  registrations (e.g. the ``view`` directive in ZCML) on the same
-  project. On a moderately-sized project (535 ZCML actions and 15 ZCML
-  files), executing actions read from the pickle was saving us only
-  about 200ms (2.5 sec vs 2.7 sec average). On very small projects (1
-  ZCML file and 4 actions), startup time was comparable, and sometimes
-  even slower when reading from the pickle, and both ways were so fast
-  that it really just didn't matter anyway.
-
-0.8 (2009-05-18)
-================
-
-Features
---------
-
-- Added a ``traverse`` function to the ``repoze.bfg.traversal``
-  module.  This function may be used to retrieve certain values
-  computed during path resolution.  See the Traversal API chapter of
-  the documentation for more information about this function.
-
-Deprecations
-------------
-
-- Internal: ``ITraverser`` callables should now return a dictionary
-  rather than a tuple.  Up until 0.7.0, all ITraversers were assumed
-  to return a 3-tuple.  In 0.7.1, ITraversers were assumed to return a
-  6-tuple.  As (by evidence) it's likely we'll need to add further
-  information to the return value of an ITraverser callable, 0.8
-  assumes that an ITraverser return a dictionary with certain elements
-  in it.  See the ``repoze.bfg.interfaces.ITraverser`` interface for
-  the list of keys that should be present in the dictionary.
-  ``ITraversers`` which return tuples will still work, although a
-  deprecation warning will be issued.
-
-Backwards Incompatibilities
----------------------------
-
-- If your code used the ITraverser interface directly (not via an API
-  function such as ``find_model``) via an adapter lookup, you'll need
-  to change your code to expect a dictionary rather than a 3- or
-  6-tuple if your code ever gets return values from the default
-  ModelGraphTraverser or RoutesModelTraverser adapters.
-
-0.8a7 (2009-05-16)
-==================
-
-Backwards Incompatibilities
----------------------------
-
-- The ``RoutesMapper`` class in ``repoze.bfg.urldispatch`` has been
-  removed, as well as its documentation.  It had been deprecated since
-  0.6.3.  Code in ``repoze.bfg.urldispatch.RoutesModelTraverser``
-  which catered to it has also been removed.
-
-- The semantics of the ``route`` ZCML directive have been simplified.
-  Previously, it was assumed that to use a route, you wanted to map a
-  route to an externally registered view.  The new ``route`` directive
-  instead has a ``view`` attribute which is required, specifying the
-  dotted path to a view callable.  When a route directive is
-  processed, a view is *registered* using the name attribute of the
-  route directive as its name and the callable as its value.  The
-  ``view_name`` and ``provides`` attributes of the ``route`` directive
-  are therefore no longer used.  Effectively, if you were previously
-  using the ``route`` directive, it means you must change a pair of
-  ZCML directives that look like this::
-
-    <route
-       name="home"
-       path=""
-       view_name="login"
-       factory=".models.root.Root"
-     />
-
-    <view
-       for=".models.root.Root"
-       name="login"
-       view=".views.login_view"
-     />
-    
-  To a ZCML directive that looks like this::
-
-    <route
-       name="home"
-       path=""
-       view=".views.login_view"
-       factory=".models.root.Root"
-     />
-
-  In other words, to make old code work, remove the ``view``
-  directives that were only there to serve the purpose of backing
-  ``route`` directives, and move their ``view=`` attribute into the
-  ``route`` directive itself.
-
-  This change also necessitated that the ``name`` attribute of the
-  ``route`` directive is now required.  If you were previously using
-  ``route`` directives without a ``name`` attribute, you'll need to
-  add one (the name is arbitrary, but must be unique among all
-  ``route`` and ``view`` statements).
-
-  The ``provides`` attribute of the ``route`` directive has also been
-  removed.  This directive specified a sequence of interface types
-  that the generated context would be decorated with.  Since route
-  views are always generated now for a single interface
-  (``repoze.bfg.IRoutesContext``) as opposed to being looked up
-  arbitrarily, there is no need to decorate any context to ensure a
-  view is found.
-
-Documentation
--------------
-
-- Added API docs for the ``repoze.bfg.testing`` methods
-  ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and
-  ``cleanUp``.
-
-- Added glossary entry for "root factory".
-
-- Noted existence of ``repoze.bfg.pagetemplate`` template bindings in
-  "Available Add On Template System Bindings" in Templates chapter in
-  narrative docs.
-
-- Update "Templates" narrative chapter in docs (expand to show a
-  sample template and correct macro example).
-
-Features
---------
-
-- Courtesty Carlos de la Guardia, added an ``alchemy`` Paster
-  template.  This paster template sets up a BFG project that uses
-  SQAlchemy (with SQLite) and uses traversal to resolve URLs.  (no
-  Routes areused).  This template can be used via ``paster create -t
-  bfg_alchemy``.
-
-- The Routes ``Route`` object used to resolve the match is now put
-  into the environment as ``bfg.route`` when URL dispatch is used.
-
-- You can now change the default Routes "context factory" globally.
-  See the "ZCML Hooks" chapter of the documentation (in the "Changing
-  the Default Routes Context Factory" section).
-
-0.8a6 (2009-05-11)
-==================
-
-Features
---------
-
-- Added a ``routesalchemy`` Paster template.  This paster template
-  sets up a BFG project that uses SQAlchemy (with SQLite) and uses
-  Routes exclusively to resolve URLs (no traversal root factory is
-  used).  This template can be used via ``paster create -t
-  bfg_routesalchemy``.
-
-Documentation
--------------
-
-- Added documentation to the URL Dispatch chapter about how to catch
-  the root URL using a ZCML ``route`` directive.
-
-- Added documentation to the URL Dispatch chapter about how to perform
-  a cleanup function at the end of a request (e.g. close the SQL
-  connection).
-
-Bug Fixes
----------
-
-- In version 0.6.3, passing a ``get_root`` callback (a "root factory")
-  to ``repoze.bfg.router.make_app`` became optional if any ``route``
-  declaration was made in ZCML.  The intent was to make it possible to
-  disuse traversal entirely, instead relying entirely on URL dispatch
-  (Routes) to resolve all contexts.  However a compound set of bugs
-  prevented usage of a Routes-based root view (a view which responds
-  to "/").  One bug existed in `repoze.bfg.urldispatch``, another
-  existed in Routes itself.
-
-  To resolve this issue, the urldispatch module was fixed, and a fork
-  of the Routes trunk was put into the "dev" index named
-  ``Routes-1.11dev-chrism-home``.  The source for the fork exists at
-  `http://bitbucket.org/chrism/routes-home/
-  <http://bitbucket.org/chrism/routes-home/>`_; its contents have been
-  merged into the Routes trunk (what will be Routes 1.11).
-
-0.8a5 (2009-05-08)
-==================
-
-Features
---------
-
-- Two new security policies were added:
-  RemoteUserInheritingACLSecurityPolicy and
-  WhoInheritingACLSecurityPolicy.  These are security policies which
-  take into account *all* ACLs defined in the lineage of a context
-  rather than stopping at the first ACL found in a lineage.  See the
-  "Security" chapter of the API documentation for more information.
-
-- The API and narrative documentation dealing with security was
-  changed to introduce the new "inheriting" security policy variants.
-
-- Added glossary entry for "lineage".
-
-Deprecations
-------------
-
-- The security policy previously named
-  ``RepozeWhoIdentityACLSecurityPolicy`` now has the slightly saner
-  name of ``WhoACLSecurityPolicy``.  A deprecation warning is emitted
-  when this policy is imported under the "old" name; usually this is
-  due to its use in ZCML within your application.  If you're getting
-  this deprecation warning, change your ZCML to use the new name,
-  e.g. change::
-
-   <utility
-     provides="repoze.bfg.interfaces.ISecurityPolicy"
-     factory="repoze.bfg.security.RepozeWhoIdentityACLSecurityPolicy"
-     />
-
-  To::
-
-   <utility
-     provides="repoze.bfg.interfaces.ISecurityPolicy"
-     factory="repoze.bfg.security.WhoACLSecurityPolicy"
-     />
-
-0.8a4 (2009-05-04)
-==================
-
-Features
---------
-
-- ``zope.testing`` is no longer a direct dependency, although our
-  dependencies (such as ``zope.interface``, ``repoze.zcml``, etc)
-  still depend on it.
-
-- Tested on Google App Engine.  Added a tutorial to the documentation
-  explaining how to deploy a BFG app to GAE.
-
-Backwards Incompatibilities
----------------------------
-
-- Applications which rely on ``zope.testing.cleanup.cleanUp`` in unit
-  tests can still use that function indefinitely.  However, for
-  maximum forward compatibility, they should import ``cleanUp`` from
-  ``repoze.bfg.testing`` instead of from ``zope.testing.cleanup``.
-  The BFG paster templates and docs have been changed to use this
-  function instead of the ``zope.testing.cleanup`` version.
-
-0.8a3 (2009-05-03)
-===================
-
-Features
---------
-
-- Don't require a successful import of ``zope.testing`` at BFG
-  application runtime.  This allows us to get rid of ``zope.testing``
-  on platforms like GAE which have file limits.
-
-0.8a2 (2009-05-02)
-==================
-
-Features
---------
-
-- We no longer include the ``configure.zcml`` of the ``chameleon.zpt``
-  package within the ``configure.zcml`` of the "repoze.bfg.includes"
-  package.  This has been a no-op for some time now.
-
-- The ``repoze.bfg.chameleon_zpt`` package no longer imports from
-  ``chameleon.zpt`` at module scope, deferring the import until later
-  within a method call.  The ``chameleon.zpt`` package can't be
-  imported on platforms like GAE.
-
-0.8a1 (2009-05-02)
-==================
-
-Deprecation Warning and Import Alias Removals
----------------------------------------------
-
-- Since version 0.6.1, a deprecation warning has been emitted when the
-  name ``model_url`` is imported from the ``repoze.bfg.traversal``
-  module.  This import alias (and the deprecation warning) has been
-  removed.  Any import of the ``model_url`` function will now need to
-  be done from ``repoze.bfg.url``; any import of the name
-  ``model_url`` from ``repoze.bfg.traversal`` will now fail.  This was
-  done to remove a dependency on zope.deferredimport.
-
-- Since version 0.6.5, a deprecation warning has been emitted when the
-  name ``RoutesModelTraverser`` is imported from the
-  ``repoze.bfg.traversal`` module.  This import alias (and the
-  deprecation warning) has been removed.  Any import of the
-  ``RoutesModelTraverser`` class will now need to be done from
-  ``repoze.bfg.urldispatch``; any import of the name
-  ``RoutesModelTraverser`` from ``repoze.bfg.traversal`` will now
-  fail.  This was done to remove a dependency on zope.deferredimport.
-
-Features
---------
-
-- This release of ``repoze.bfg`` is "C-free".  This means it has no
-  hard dependencies on any software that must be compiled from C
-  source at installation time.  In particular, ``repoze.bfg`` no
-  longer depends on the ``lxml`` package.
-
-  This change has introduced some backwards incompatibilities,
-  described in the "Backwards Incompatibilities" section below.
-
-- This release was tested on Windows XP.  It appears to work fine and
-  all the tests pass.
-
-Backwards Incompatibilities
----------------------------
-
-Incompatibilities related to making ``repoze.bfg`` "C-free":
-
-- Removed the ``repoze.bfg.chameleon_genshi`` module, and thus support
-  for Genshi-style chameleon templates.  Genshi-style Chameleon
-  templates depend upon ``lxml``, which is implemented in C (as
-  opposed to pure Python) and the ``repoze.bfg`` core is "C-free" as
-  of this release. You may get Genshi-style Chameleon support back by
-  installing the ``repoze.bfg.chameleon_genshi`` package availalable
-  from http://svn.repoze.org/repoze.bfg.chameleon_genshi (also
-  available in the index at http://dist.repoze.org/bfg/0.8/simple).
-  All existing code that depended on the ``chameleon_genshi`` module
-  prior to this release of ``repoze.bfg`` should work without change
-  after this addon is installed.
-
-- Removed the ``repoze.bfg.xslt`` module and thus support for XSL
-  templates.  The ``repoze.bfg.xslt`` module depended upon ``lxml``,
-  which is implemented in C, and the ``repoze.bfg`` core is "C-free"
-  as of this release.  You bay get XSL templating back by installing
-  the ``repoze.bfg.xslt`` package available from
-  http://svn.repoze.org/repoze.bfg.xslt/ (also available in the index
-  at http://dist.repoze.org/bfg/0.8/simple).  All existing code that
-  depended upon the ``xslt`` module prior to this release of
-  ``repoze.bfg`` should work without modification after this addon is
-  installed.
-
-- Removed the ``repoze.bfg.interfaces.INodeTemplateRenderer``
-  interface and the an old b/w compat aliases from that interface to
-  ``repoze.bfg.interfaces.INodeTemplate``.  This interface must now be
-  imported from the ``repoze.bfg.xslt.interfaces`` package after
-  installation of the ``repoze.bfg.xslt`` addon package described
-  above as ``repoze.bfg.interfaces.INodeTemplateRenderer``.  This
-  interface was never part of any public API.
-
-Other backwards incompatibilities:
-
-- The ``render_template`` function in ``repoze.bfg.chameleon_zpt``
-  returns Unicode instead of a string.  Likewise, the individual
-  values returned by the iterable created by the
-  ``render_template_to_iterable`` function are also each Unicode.
-  This is actually a backwards incompatibility inherited from our new
-  use of the combination of ``chameleon.core`` 1.0b32 (the
-  non-lxml-depending version) and ``chameleon.zpt`` 1.0b16+ ; the
-  ``chameleon.zpt`` PageTemplateFile implementation used to return a
-  string, but now returns Unicode.
-
-0.7.1 (2009-05-01)
-==================
-
-Index-Related
--------------
-
-- The canonical package index location for ``repoze.bfg`` has changed.
-  The "old" index (http://dist.repoze.org/lemonade/dev/simple) has
-  been superseded by a new index location
-  (`http://dist.repoze.org/bfg/current/simple
-  <http://dist.repoze.org/bfg/current/simple>`_).  The installation
-  documentation has been updated as well as the ``setup.cfg`` file in
-  this package.  The "lemonade" index still exists, but it is not
-  guaranteed to have the latest BFG software in it, nor will it be
-  maintained in the future.
-
-Features
---------
-
-- The "paster create" templates have been modified to use links to the
-  new "bfg.repoze.org" and "docs.repoze.org" websites.
-
-- Added better documentation for virtual hosting at a URL prefix
-  within the virtual hosting docs chapter.
-
-- The interface for ``repoze.bfg.interfaces.ITraverser`` and the
-  built-in implementations that implement the interface
-  (``repoze.bfg.traversal.ModelGraphTraverser``, and
-  ``repoze.bfg.urldispatch.RoutesModelTraverser``) now expect the
-  ``__call__`` method of an ITraverser to return 3 additional
-  arguments: ``traversed``, ``virtual_root``, and
-  ``virtual_root_path`` (the old contract was that the ``__call__``
-  method of an ITraverser returned; three arguments, the contract new
-  is that it returns six).  ``traversed`` will be a sequence of
-  Unicode names that were traversed (including the virtual root path,
-  if any) or ``None`` if no traversal was performed, ``virtual_root``
-  will be a model object representing the virtual root (or the
-  physical root if traversal was not performed), and
-  ``virtual_root_path`` will be a sequence representing the virtual
-  root path (a sequence of Unicode names) or ``None`` if traversal was
-  not performed.
-
-  Six arguments are now returned from BFG ITraversers.  They are
-  returned in this order: ``context``, ``view_name``, ``subpath``,
-  ``traversed``, ``virtual_root``, and ``virtual_root_path``.
-
-  Places in the BFG code which called an ITraverser continue to accept
-  a 3-argument return value, although BFG will generate and log a
-  warning when one is encountered.
-
-- The request object now has the following attributes: ``traversed``
-  (the sequence of names traversed or ``None`` if traversal was not
-  performed), ``virtual_root`` (the model object representing the
-  virtual root, including the virtual root path if any), and
-  ``virtual_root_path`` (the seuquence of names representing the
-  virtual root path or ``None`` if traversal was not performed).
-
-- A new decorator named ``wsgiapp2`` was added to the
-  ``repoze.bfg.wsgi`` module.  This decorator performs the same
-  function as ``repoze.bfg.wsgi.wsgiapp`` except it fixes up the
-  ``SCRIPT_NAME``, and ``PATH_INFO`` environment values before
-  invoking the WSGI subapplication.
-
-- The ``repoze.bfg.testing.DummyRequest`` object now has default
-  attributes for ``traversed``, ``virtual_root``, and
-  ``virtual_root_path``.
-
-- The RoutesModelTraverser now behaves more like the Routes
-  "RoutesMiddleware" object when an element in the match dict is named
-  ``path_info`` (usually when there's a pattern like
-  ``http://foo/*path_info``).  When this is the case, the
-  ``PATH_INFO`` environment variable is set to the value in the match
-  dict, and the ``SCRIPT_NAME`` is appended to with the prefix of the
-  original ``PATH_INFO`` not including the value of the new variable.
-
-- The notfound debug now shows the traversed path, the virtual root,
-  and the virtual root path too.
-
-- Speed up / clarify 'traversal' module's 'model_path', 'model_path_tuple',
-  and '_model_path_list' functions.
-
-Backwards Incompatibilities
----------------------------
-
-- In previous releases, the ``repoze.bfg.url.model_url``,
-  ``repoze.bfg.traversal.model_path`` and
-  ``repoze.bfg.traversal.model_path_tuple`` functions always ignored
-  the ``__name__`` argument of the root object in a model graph (
-  effectively replacing it with a leading ``/`` in the returned value)
-  when a path or URL was generated.  The code required to perform this
-  operation was not efficient.  As of this release, the root object in
-  a model graph *must* have a ``__name__`` attribute that is either
-  ``None`` or the empty string (``''``) for URLs and paths to be
-  generated properly from these APIs.  If your root model object has a
-  ``__name__`` argument that is not one of these values, you will need
-  to change your code for URLs and paths to be generated properly.  If
-  your model graph has a root node with a string ``__name__`` that is
-  not null, the value of ``__name__`` will be prepended to every path
-  and URL generated.
-
-- The ``repoze.bfg.location.LocationProxy`` class and the
-  ``repoze.bfg.location.ClassAndInstanceDescr`` class have both been
-  removed in order to be able to eventually shed a dependency on
-  ``zope.proxy``.  Neither of these classes was ever an API.
-
-- In all previous releases, the ``repoze.bfg.location.locate``
-  function worked like so: if a model did not explicitly provide the
-  ``repoze.bfg.interfaces.ILocation`` interface, ``locate`` returned a
-  ``LocationProxy`` object representing ``model`` with its
-  ``__parent__`` attribute assigned to ``parent`` and a ``__name__``
-  attribute assigned to ``__name__``.  In this release, the
-  ``repoze.bfg.location.locate`` function simply jams the ``__name__``
-  and ``__parent__`` attributes on to the supplied model
-  unconditionally, no matter if the object implements ILocation or
-  not, and it never returns a proxy.  This was done because the
-  LocationProxy behavior has now moved into an add-on package
-  (``repoze.bfg.traversalwrapper``), in order to eventually be able to
-  shed a dependency on ``zope.proxy``.
-
-- In all previous releases, by default, if traversal was used (as
-  opposed to URL-dispatch), and the root object supplied
-  the``repoze.bfg.interfaces.ILocation`` interface, but the children
-  returned via its ``__getitem__`` returned an object that did not
-  implement the same interface, ``repoze.bfg`` provided some
-  implicit help during traversal.  This traversal feature wrapped
-  subobjects from the root (and thereafter) that did not implement
-  ``ILocation`` in proxies which automatically provided them with a
-  ``__name__`` and ``__parent__`` attribute based on the name being
-  traversed and the previous object traversed.  This feature has now
-  been removed from the base ``repoze.bfg`` package for purposes of
-  eventually shedding a dependency on ``zope.proxy``.
-
-  In order to re-enable the wrapper behavior for older applications
-  which cannot be changed, register the "traversalwrapper"
-  ``ModelGraphTraverser`` as the traversal policy, rather than the
-  default ``ModelGraphTraverser``. To use this feature, you will need
-  to install the ``repoze.bfg.traversalwrapper`` package (an add-on
-  package, available at
-  http://svn.repoze.org/repoze.bfg.traversalwrapper) Then change your
-  application's ``configure.zcml`` to include the following stanza:
-
-    <adapter
-        factory="repoze.bfg.traversalwrapper.ModelGraphTraverser"
-        provides="repoze.bfg.interfaces.ITraverserFactory"
-        for="*"
-        />
-
-   When this ITraverserFactory is used instead of the default, no
-   object in the graph (even the root object) must supply a
-   ``__name__`` or ``__parent__`` attribute.  Even if subobjects
-   returned from the root *do* implement the ILocation interface,
-   these will still be wrapped in proxies that override the object's
-   "real" ``__parent__`` and ``__name__`` attributes.
-
-   See also changes to the "Models" chapter of the documentation (in
-   the "Location-Aware Model Instances") section.
-
-0.7.0 (2009-04-11)
-==================
-
-Bug Fixes
----------
-
-- Fix a bug in ``repoze.bfg.wsgi.HTTPException``: the content length
-  was returned as an int rather than as a string.
- 
-- Add explicit dependencies on ``zope.deferredimport``,
-  ``zope.deprecation``, and ``zope.proxy`` for forward compatibility
-  reasons (``zope.component`` will stop relying on
-  ``zope.deferredimport`` soon and although we use it directly, it's
-  only a transitive dependency, and ''zope.deprecation`` and
-  ``zope.proxy`` are used directly even though they're only transitive
-  dependencies as well).
-
-- Using ``model_url`` or ``model_path`` against a broken model graph
-  (one with models that had a non-root model with a ``__name__`` of
-  ``None``) caused an inscrutable error to be thrown: ( if not
-  ``_must_quote[cachekey].search(s): TypeError: expected string or
-  buffer``).  Now URLs and paths generated against graphs that have
-  None names in intermediate nodes will replace the None with the
-  empty string, and, as a result, the error won't be raised.  Of
-  course the URL or path will still be bogus.
-
-Features
---------
-
-- Make it possible to have ``testing.DummyTemplateRenderer`` return
-  some nondefault string representation.
-
-- Added a new ``anchor`` keyword argument to ``model_url``.  If 
-  ``anchor`` is present, its string representation will be used 
-  as a named anchor in the generated URL (e.g. if ``anchor`` is 
-  passed as ``foo`` and the model URL is 
-  ``http://example.com/model/url``, the generated URL will be 
-  ``http://example.com/model/url#foo``).
-
-Backwards Incompatibilities
----------------------------
-
-- The default request charset encoding is now ``utf-8``.  As a result,
-  the request machinery will attempt to decode values from the utf-8
-  encoding to Unicode automatically when they are obtained via
-  ``request.params``, ``request.GET``, and ``request.POST``.  The
-  previous behavior of BFG was to return a bytestring when a value was
-  accessed in this manner.  This change will break form handling code
-  in apps that rely on values from those APIs being considered
-  bytestrings.  If you are manually decoding values from form
-  submissions in your application, you'll either need to change the
-  code that does that to expect Unicode values from
-  ``request.params``, ``request.GET`` and ``request.POST``, or you'll
-  need to explicitly reenable the previous behavior.  To reenable the
-  previous behavior, add the following to your application's
-  ``configure.zcml``::
-
-    <subscriber for="repoze.bfg.interfaces.INewRequest"
-                handler="repoze.bfg.request.make_request_ascii"/>
-
-  See also the documentation in the "Views" chapter of the BFG docs
-  entitled "Using Views to Handle Form Submissions (Unicode and
-  Character Set Issues)".
-
-Documentation
--------------
-
-- Add a section to the narrative Views chapter entitled "Using Views
-  to Handle Form Submissions (Unicode and Character Set Issues)"
-  explaining implicit decoding of form data values.
-
-0.6.9 (2009-02-16)
-==================
-
-Bug Fixes
----------
-
-- lru cache was unstable under concurrency (big surprise!) when it
-  tried to redelete a key in the cache that had already been deleted.
-  Symptom: line 64 in put:del data[oldkey]:KeyError: '/some/path'.
-  Now we just ignore the key error if we can't delete the key (it has
-  already been deleted).
-
-- Empty location names in model paths when generating a URL using
-  ``repoze.bfg.model_url`` based on a model obtained via traversal are
-  no longer ignored in the generated URL.  This means that if a
-  non-root model object has a ``__name__`` of ``''``, the URL will
-  reflect it (e.g. ``model_url`` will generate ``http://foo/bar//baz``
-  if an object with the ``__name__`` of ``''`` is a child of bar and
-  the parent of baz).  URLs generated with empty path segments are,
-  however, still irresolveable by the model graph traverser on request
-  ingress (the traverser strips empty path segment names).
-
-Features
---------
-
-- Microspeedups of ``repoze.bfg.traversal.model_path``,
-  ``repoze.bfg.traversal.model_path_tuple``,
-  ``repoze.bfg.traversal.quote_path_segment``, and
-  ``repoze.bfg.url.urlencode``.
-
-- add zip_safe = false to setup.cfg.
-
-Documentation
--------------
-
-- Add a note to the ``repoze.bfg.traversal.quote_path_segment`` API
-  docs about caching of computed values.
-
-Implementation Changes
-----------------------
-
-- Simplification of
-  ``repoze.bfg.traversal.TraversalContextURL.__call__`` (it now uses
-  ``repoze.bfg.traversal.model_path`` instead of rolling its own
-  path-generation).
-
-0.6.8 (2009-02-05)
-==================
-
-Backwards Incompatibilities
----------------------------
-
-- The ``repoze.bfg.traversal.model_path`` API now returns a *quoted*
-  string rather than a string represented by series of unquoted
-  elements joined via ``/`` characters.  Previously it returned a
-  string or unicode object representing the model path, with each
-  segment name in the path joined together via ``/`` characters,
-  e.g. ``/foo /bar``.  Now it returns a string, where each segment is
-  a UTF-8 encoded and URL-quoted element e.g. ``/foo%20/bar``.  This
-  change was (as discussed briefly on the repoze-dev maillist)
-  necessary to accomodate model objects which themselves have
-  ``__name__`` attributes that contain the ``/`` character.
-
-  For people that have no models that have high-order Unicode
-  ``__name__`` attributes or ``__name__`` attributes with values that
-  require URL-quoting with in their model graphs, this won't cause any
-  issue.  However, if you have code that currently expects
-  ``model_path`` to return an unquoted string, or you have an existing
-  application with data generated via the old method, and you're too
-  lazy to change anything, you may wish replace the BFG-imported
-  ``model_path`` in your code with this function (this is the code of
-  the "old" ``model_path`` implementation)::
-
-        from repoze.bfg.location import lineage
-
-        def i_am_too_lazy_to_move_to_the_new_model_path(model, *elements):
-            rpath = []
-            for location in lineage(model):
-                if location.__name__:
-                    rpath.append(location.__name__)
-            path = '/' + '/'.join(reversed(rpath))
-            if elements:
-                suffix = '/'.join(elements)
-                path = '/'.join([path, suffix])
-            return path
-
-- The ``repoze.bfg.traversal.find_model`` API no longer implicitly
-  converts unicode representations of a full path passed to it as a
-  Unicode object into a UTF-8 string.  Callers should either use
-  prequoted path strings returned by
-  ``repoze.bfg.traversal.model_path``, or tuple values returned by the
-  result of ``repoze.bfg.traversal.model_path_tuple`` or they should
-  use the guidelines about passing a string ``path`` argument
-  described in the ``find_model`` API documentation.
-
-Bugfixes
---------
-
-- Each argument contained in ``elements`` passed to
-  ``repoze.bfg.traversal.model_path`` will now have any ``/``
-  characters contained within quoted to ``%2F`` in the returned
-  string.  Previously, ``/`` characters in elements were left unquoted
-  (a bug).
-
-Features
---------
-
-- A ``repoze.bfg.traversal.model_path_tuple`` API was added.  This API
-  is an alternative to ``model_path`` (which returns a string);
-  ``model_path_tuple`` returns a model path as a tuple (much like
-  Zope's ``getPhysicalPath``).
-
-- A ``repoze.bfg.traversal.quote_path_segment`` API was added.  This
-  API will quote an individual path segment (string or unicode
-  object).  See the ``repoze.bfg.traversal`` API documentation for
-  more information.
-
-- The ``repoze.bfg.traversal.find_model`` API now accepts "path
-  tuples" (see the above note regarding ``model_path_tuple``) as well
-  as string path representations (from
-  ``repoze.bfg.traversal.model_path``) as a ``path`` argument.
-
-- Add ` `renderer`` argument (defaulting to None) to
-  ``repoze.bfg.testing.registerDummyRenderer``.  This makes it
-  possible, for instance, to register a custom renderer that raises an
-  exception in a unit test.
-
-Implementation Changes
-----------------------
-
-- Moved _url_quote function back to ``repoze.bfg.traversal`` from
-  ``repoze.bfg.url``.  This is not an API.
-
-0.6.7 (2009-01-27)
-==================
-
-Features
---------
-
-- The ``repoze.bfg.url.model_url`` API now works against contexts
-  derived from Routes URL dispatch (``Routes.util.url_for`` is called
-  under the hood).
-
-- "Virtual root" support for traversal-based applications has been
-  added.  Virtual root support is useful when you'd like to host some
-  model in a ``repoze.bfg`` model graph as an application under a
-  URL pathname that does not include the model path itself.  For more
-  information, see the (new) "Virtual Hosting" chapter in the
-  documentation.
-
-- A ``repoze.bfg.traversal.virtual_root`` API has been added.  When
-  called, it returns the virtual root object (or the physical root
-  object if no virtual root has been specified).
-
-Implementation Changes
-----------------------
-
-- ``repoze.bfg.traversal.RoutesModelTraverser`` has been moved to
-  ``repoze.bfg.urldispatch``.
-
-- ``model_url`` URL generation is now performed via an adapter lookup
-  based on the context and the request.
-
-- ZCML which registers two adapters for the ``IContextURL`` interface
-  has been added to the configure.zcml in ``repoze.bfg.includes``.
-
-0.6.6 (2009-01-26)
-==================
-
-Implementation Changes
-----------------------
-
-- There is an indirection in ``repoze.bfg.url.model_url`` now that
-  consults a utility to generate the base model url (without extra
-  elements or a query string).  Eventually this will service virtual
-  hosting; for now it's undocumented and should not be hooked.
-
-0.6.5 (2009-01-26)
-==================
-
-Features
---------
-
-- You can now override the NotFound and Unauthorized responses that
-  ``repoze.bfg`` generates when a view cannot be found or cannot be
-  invoked due to lack of permission.  See the "ZCML Hooks" chapter in
-  the docs for more information.
-
-- Added Routes ZCML directive attribute explanations in documentation.
-
-- Added a ``traversal_path`` API to the traversal module; see the
-  "traversal" API chapter in the docs.  This was a function previously
-  known as ``split_path`` that was not an API but people were using it
-  anyway.  Unlike ``split_path``, it now returns a tuple instead of a
-  list (as its values are cached).
-
-Behavior Changes
-----------------
-
-- The ``repoze.bfg.view.render_view_to_response`` API will no longer
-  raise a ValueError if an object returned by a view function it calls
-  does not possess certain attributes (``headerlist``, ``app_iter``,
-  ``status``).  This API used to attempt to perform a check using the
-  ``is_response`` function in ``repoze.bfg.view``, and raised a
-  ``ValueError`` if the ``is_response`` check failed.  The
-  responsibility is now the caller's to ensure that the return value
-  from a view function is a "real" response.
-
-- WSGI environ dicts passed to ``repoze.bfg`` 's Router must now
-  contain a REQUEST_METHOD key/value; if they do not, a KeyError will
-  be raised (speed).  
-
-- It is no longer permissible to pass a "nested" list of principals to
-  ``repoze.bfg.ACLAuthorizer.permits`` (e.g. ``['fred', ['larry',
-  'bob']]``).  The principals list must be fully expanded.  This
-  feature was never documented, and was never an API, so it's not a
-  backwards incompatibility.
-
-- It is no longer permissible for a security ACE to contain a "nested"
-  list of permissions (e.g. ``(Allow, Everyone, ['read', ['view',
-  ['write', 'manage']]])`)`.  The list must instead be fully expanded
-  (e.g. ``(Allow, Everyone, ['read', 'view', 'write', 'manage])``).  This
-  feature was never documented, and was never an API, so it's not a
-  backwards incompatibility.
-
-- The ``repoze.bfg.urldispatch.RoutesRootFactory`` now injects the
-  ``wsgiorg.routing_args`` environment variable into the environ when
-  a route matches.  This is a tuple of ((), routing_args) where
-  routing_args is the value that comes back from the routes mapper
-  match (the "match dict").
-
-- The ``repoze.bfg.traversal.RoutesModelTraverser`` class now wants to
-  obtain the ``view_name`` and ``subpath`` from the
-  ``wsgiorgs.routing_args`` environment variable.  It falls back to
-  obtaining these from the context for backwards compatibility.
-
-Implementation Changes
-----------------------
-
-- Get rid of ``repoze.bfg.security.ACLAuthorizer``: the
-  ``ACLSecurityPolicy`` now does what it did inline.
-
-- Get rid of ``repoze.bfg.interfaces.NoAuthorizationInformation``
-  exception: it was used only by ``ACLAuthorizer``.
-
-- Use a homegrown NotFound error instead of ``webob.exc.HTTPNotFound``
-  (the latter is slow).
-
-- Use a homegrown Unauthorized error instead of
-  ``webob.exc.Unauthorized`` (the latter is slow).
-
-- the ``repoze.bfg.lru.lru_cached`` decorator now uses functools.wraps
-  in order to make documentation of LRU-cached functions possible.
-
-- Various speed micro-tweaks.
-
-Bug Fixes
----------
-
-- ``repoze.bfg.testing.DummyModel`` did not have a ``get`` method;
-  it now does.
-
-0.6.4 (2009-01-23)
-==================
-
-Backwards Incompatibilities
----------------------------
-
-- The ``unicode_path_segments`` configuration variable and the
-  ``BFG_UNICODE_PATH_SEGMENTS`` configuration variable have been
-  removed.  Path segments are now always passed to model
-  ``__getitem__`` methods as unicode.  "True" has been the default for
-  this setting since 0.5.4, but changing this configuration setting to
-  false allowed you to go back to passing raw path element strings to
-  model ``__getitem__`` methods.  Removal of this knob services a
-  speed goal (we get about +80 req/s by removing the check), and it's
-  clearer just to always expect unicode path segments in model
-  ``__getitem__`` methods.
-
-Implementation Changes
-----------------------
-
-- ``repoze.bfg.traversal.split_path`` now also handles decoding
-  path segments to unicode (for speed, because its results are
-  cached).
-
-- ``repoze.bfg.traversal.step`` was made a method of the
-   ModelGraphTraverser.
-
-- Use "precooked" Request subclasses
-  (e.g. ``repoze.bfg.request.GETRequest``) that correspond to HTTP
-  request methods within ``router.py`` when constructing a request
-  object rather than using ``alsoProvides`` to attach the proper
-  interface to an unsubclassed ``webob.Request``.  This pattern is
-  purely an optimization (e.g. preventing calls to ``alsoProvides``
-  means the difference between 590 r/s and 690 r/s on a MacBook 2GHz).
-
-- Tease out an extra 4% performance boost by changing the Router;
-  instead of using imported ZCA APIs, use the same APIs directly
-  against the registry that is an attribute of the Router.
-
-- The registry used by BFG is now a subclass of
-  ``zope.component.registry.Components`` (defined as
-  ``repoze.bfg.registry.Registry``); it has a ``notify`` method, a
-  ``registerSubscriptionAdapter`` and a ``registerHandler`` method.
-  If no subscribers are registered via ``registerHandler`` or
-  ``registerSubscriptionAdapter``, ``notify`` is a noop for speed.
-
-- The Allowed and Denied classes in ``repoze.bfg.security`` now are
-  lazier about constructing the representation of a reason message for
-  speed; ``repoze.bfg.view_execution_permitted`` takes advantage of
-  this.
-
-- The ``is_response`` check was sped up by about half at the expense
-  of making its code slightly uglier.
-
-New Modules
------------
-
-- ``repoze.bfg.lru`` implements an LRU cache class and a decorator for
-  internal use.
-
-0.6.3 (2009-01-19)
-==================
-
-Bug Fixes
----------
-
-- Readd ``root_policy`` attribute on Router object (as a property
-  which returns the IRootFactory utility).  It was inadvertently
-  removed in 0.6.2.  Code in the wild depended upon its presence
-  (esp. scripts and "debug" helpers).
-
-Features
---------
-
-- URL-dispatch has been overhauled: it is no longer necessary to
-  manually create a RoutesMapper in your application's entry point
-  callable in order to use URL-dispatch (aka `Routes
-  <http://routes.groovie.org>`_).  A new ``route`` directive has been
-  added to the available list of ZCML directives.  Each ``route``
-  directive inserted into your application's ``configure.zcml``
-  establishes a Routes mapper connection.  If any ``route``
-  declarations are made via ZCML within a particular application, the
-  ``get_root`` callable passed in to ``repoze.bfg.router.make_app``
-  will automatically be wrapped in the equivalent of a RoutesMapper.
-  Additionally, the new ``route`` directive allows the specification
-  of a ``context_interfaces`` attribute for a route, this will be used
-  to tag the manufactured routes context with specific interfaces when
-  a route specifying a ``context_interfaces`` attribute is matched.
-
-- A new interface ``repoze.bfg.interfaces.IContextNotFound`` was
-  added.  This interface is attached to a "dummy" context generated
-  when Routes cannot find a match and there is no "fallback" get_root
-  callable that uses traversal.
-
-- The ``bfg_starter`` and ``bfg_zodb`` "paster create" templates now
-  contain images and CSS which are displayed when the default page is
-  displayed after initial project generation.
-
-- Allow the ``repoze.bfg.view.static`` helper to be passed a relative
-  ``root_path`` name; it will be considered relative to the file in
-  which it was called.
-
-- The functionality of ``repoze.bfg.convention`` has been merged into
-  the core.  Applications which make use of ``repoze.bfg.convention``
-  will continue to work indefinitely, but it is recommended that apps
-  stop depending upon it.  To do so, substitute imports of
-  ``repoze.bfg.convention.bfg_view`` with imports of
-  ``repoze.bfg.view.bfg_view``, and change the stanza in ZCML from
-  ``<convention package=".">`` to ``<scan package=".">``.  As a result
-  of the merge, bfg has grown a new dependency: ``martian``.
-
-- View functions which use the pushpage decorator are now pickleable
-  (meaning their use won't prevent a ``configure.zcml.cache`` file
-  from being written to disk).
-
-- Instead of invariably using ``webob.Request`` as the "request
-  factory" (e.g. in the ``Router`` class) and ``webob.Response`` and
-  the "response factory" (e.g. in ``render_template_to_response``),
-  allow both to be overridden via a ZCML utility hook.  See the "Using
-  ZCML Hooks" chapter of the documentation for more information.
-
-Deprecations
-------------
-
-- The class ``repoze.bfg.urldispatch.RoutesContext`` has been renamed
-  to ``repoze.bfg.urldispatch.DefaultRoutesContext``.  The class
-  should be imported by the new name as necessary (although in reality
-  it probably shouldn't be imported from anywhere except internally
-  within BFG, as it's not part of the API).
-
-Implementation Changes
-----------------------
-
-- The ``repoze.bfg.wsgi.wsgiapp`` decorator now uses
-  ``webob.Request.get_response`` to do its work rather than relying on
-  homegrown WSGI code.
-
-- The ``repoze.bfg.view.static`` helper now uses
-  ``webob.Request.get_response`` to do its work rather than relying on
-  homegrown WSGI code.
-
-- The ``repoze.bfg.urldispatch.RoutesModelTraverser`` class has been
-  moved to ``repoze.bfg.traversal.RoutesModelTraverser``.
-
-- The ``repoze.bfg.registry.makeRegistry`` function was renamed to
-  ``repoze.bfg.registry.populateRegistry`` and now accepts a
-  ``registry`` argument (which should be an instance of
-  ``zope.component.registry.Components``).
-
-Documentation Additions
------------------------
-
-- Updated narrative urldispatch chapter with changes required by
-  ``<route..>`` ZCML directive.
-
-- Add a section on "Using BFG Security With URL Dispatch" into the
-  urldispatch chapter of the documentation.
-
-- Better documentation of security policy implementations that ship
-  with repoze.bfg.
-
-- Added a "Using ZPT Macros in repoze.bfg" section to the narrative
-  templating chapter.
-
-0.6.2 (2009-01-13)
-==================
-
-Features
---------
-
-- Tests can be run with coverage output if you've got ``nose``
-  installed in the interpreter which you use to run tests.  Using an
-  interpreter with ``nose`` installed, do ``python setup.py
-  nosetests`` within a checkout of the ``repoze.bfg`` package to see
-  test coverage output.
-
-- Added a ``post`` argument to the ``repoze.bfg.testing:DummyRequest``
-  constructor.
-  
-- Added ``__len__`` and ``__nonzero__`` to ``repoze.bfg.testing:DummyModel``.
-
-- The ``repoze.bfg.registry.get_options`` callable (now renamed to
-  ``repoze.bfg.setings.get_options``) used to return only
-  framework-specific keys and values in the dictionary it returned.
-  It now returns all the keys and values in the dictionary it is
-  passed *plus* any framework-specific settings culled from the
-  environment.  As a side effect, all PasteDeploy application-specific
-  config file settings are made available as attributes of the
-  ``ISettings`` utility from within BFG.
-
-- Renamed the existing BFG paster template to ``bfg_starter``.  Added
-  another template (``bfg_zodb``) showing default ZODB setup using
-  ``repoze.zodbconn``.
-
-- Add a method named ``assert_`` to the DummyTemplateRenderer.  This
-  method accepts keyword arguments.  Each key/value pair in the
-  keyword arguments causes an assertion to be made that the renderer
-  received this key with a value equal to the asserted value.
-
-- Projects generated by the paster templates now use the
-  ``DummyTemplateRenderer.assert_`` method in their view tests.
-
-- Make the (internal) thread local registry manager maintain a stack
-  of registries in order to make it possible to call one BFG
-  application from inside another.
-
-- An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is
-  attached to each request object on ingress.  The HTTP-verb-related
-  interfaces are defined in ``repoze.bfg.interfaces`` and are
-  ``IGETRequest``, ``IPOSTRequest``, ``IPUTRequest``,
-  ``IDELETERequest`` and ``IHEADRequest``.  These interfaces can be
-  specified as the ``request_type`` attribute of a bfg view
-  declaration.  A view naming a specific HTTP-verb-matching interface
-  will be found only if the view is defined with a request_type that
-  matches the HTTP verb in the incoming request.  The more general
-  ``IRequest`` interface can be used as the request_type to catch all
-  requests (and this is indeed the default).  All requests implement
-  ``IRequest``. The HTTP-verb-matching idea was pioneered by
-  `repoze.bfg.restrequest
-  <http://pypi.python.org/pypi/repoze.bfg.restrequest/1.0.1>`_ . That
-  package is no longer required, but still functions fine.
-
-Bug Fixes
----------
-
-- Fix a bug where the Paste configuration's ``unicode_path_segments``
-  (and os.environ's ``BFG_UNICODE_PATH_SEGMENTS``) may have been
-  defaulting to false in some circumstances.  It now always defaults
-  to true, matching the documentation and intent.
-
-- The ``repoze.bfg.traversal.find_model`` API did not work properly
-  when passed a ``path`` argument which was unicode and contained
-  high-order bytes when the ``unicode_path_segments`` or
-  ``BFG_UNICODE_PATH_SEGMENTS`` configuration variables were "true".
-
-- A new module was added: ``repoze.bfg.settings``.  This contains
-  deployment-settings-related code.
-
-Implementation Changes
-----------------------
-
-- The ``make_app`` callable within ``repoze.bfg.router`` now registers
-  the ``root_policy`` argument as a utility (unnamed, using the new
-  ``repoze.bfg.interfaces.IRootFactory`` as a provides interface)
-  rather than passing it as the first argument to the
-  ``repoze.bfg.router.Router`` class.  As a result, the
-  ``repoze.bfg.router.Router`` router class only accepts a single
-  argument: ``registry``.  The ``repoze.bfg.router.Router`` class
-  retrieves the root policy via a utility lookup now.  The
-  ``repoze.bfg.router.make_app`` API also now performs some important
-  application registrations that were previously handled inside
-  ``repoze.bfg.registry.makeRegistry``.
-
-New Modules
------------
-
-- A ``repoze.bfg.settings`` module was added.  It contains code
-  related to deployment settings.  Most of the code it contains was
-  moved to it from the ``repoze.bfg.registry`` module.
-
-Behavior Changes
-----------------
-
-- The ``repoze.bfg.settings.Settings`` class (an instance of which is
-  registered as a utility providing
-  ``repoze.bfg.interfaces.ISettings`` when any application is started)
-  now automatically calls ``repoze.bfg.settings.get_options`` on the
-  options passed to its constructor.  This means that usage of
-  ``get_options`` within an application's ``make_app`` function is no
-  longer required (the "raw" ``options`` dict or None may be passed).
-
-- Remove old cold which attempts to recover from trying to unpickle a
-  ``z3c.pt`` template; Chameleon has been the templating engine for a
-  good long time now.  Running repoze.bfg against a sandbox that has
-  pickled ``z3c.pt`` templates it will now just fail with an
-  unpickling error, but can be fixed by deleting the template cache
-  files.
-
-Deprecations
-------------
-
-- Moved the ``repoze.bfg.registry.Settings`` class.  This has been
-  moved to ``repoze.bfg.settings.Settings``. A deprecation warning is
-  issued when it is imported from the older location.
-
-- Moved the ``repoze.bfg.registry.get_options`` function This has been
-  moved to ``repoze.bfg.settings.get_options``.  A deprecation warning
-  is issued when it is imported from the older location.
-
-- The ``repoze.bfg.interfaces.IRootPolicy`` interface was renamed
-  within the interfaces package.  It has been renamed to
-  ``IRootFactory``.  A deprecation warning is issued when it is
-  imported from the older location.
-
-0.6.1 (2009-01-06)
-==================
-
-New Modules
------------
-
-- A new module ``repoze.bfg.url`` has been added.  It contains the
-  ``model_url`` API (moved from ``repoze.bfg.traversal``) and an
-  implementation of ``urlencode`` (like Python's
-  ``urllib.urlencode``) which can handle Unicode keys and values in
-  parameters to the ``query`` argument.
-
-Deprecations
-------------
-
-- The ``model_url`` function has been moved from
-  ``repoze.bfg.traversal`` into ``repoze.bfg.url``.  It can still
-  be imported from ``repoze.bfg.traversal`` but an import from
-  ``repoze.bfg.traversal`` will emit a DeprecationWarning.
-
-Features
---------
-
-- A ``static`` helper class was added to the ``repoze.bfg.views``
-  module.  Instances of this class are willing to act as BFG views
-  which return static resources using files on disk.  See the
-  ``repoze.bfg.view`` docs for more info.
-
-- The ``repoze.bfg.url.model_url`` API (nee'
-  ``repoze.bfg.traversal.model_url``) now accepts and honors a
-  keyword argument named ``query``.  The value of this argument
-  will be used to compose a query string, which will be attached to
-  the generated URL before it is returned.  See the API docs (in
-  the docs directory or `on the web
-  <http://static.repoze.org/bfgdocs>`_) for more information.
-
-0.6 (2008-12-26)
-================
-
-Backwards Incompatibilities
----------------------------
-
-- Rather than prepare the "stock" implementations of the ZCML directives
-  from the ``zope.configuration`` package for use under ``repoze.bfg``,
-  ``repoze.bfg`` now makes available the implementations of directives
-  from the ``repoze.zcml`` package (see http://static.repoze.org/zcmldocs).
-  As a result, the ``repoze.bfg`` package now depends on the
-  ``repoze.zcml`` package, and no longer depends directly on the
-  ``zope.component``, ``zope.configuration``, ``zope.interface``, or
-  ``zope.proxy`` packages.
-
-  The primary reason for this change is to enable us to eventually reduce
-  the number of inappropriate ``repoze.bfg`` Zope package dependencies,
-  as well as to shed features of dependent package directives that don't
-  make sense for ``repoze.bfg``.
-
-  Note that currently the set of requirements necessary to use bfg has not
-  changed.  This is due to inappropriate Zope package requirements in
-  ``chameleon.zpt``, which will hopefully be remedied soon. NOTE: in
-  lemonade index a 1.0b8-repozezcml0 package exists which does away with
-  these requirements.
-
-- BFG applications written prior to this release which expect the "stock"
-  ``zope.component`` ZCML directive implementations (e.g. ``adapter``,
-  ``subscriber``, or ``utility``) to function now must either 1) include
-  the ``meta.zcml`` file from ``zope.component`` manually (e.g. ``<include
-  package="zope.component" file="meta.zcml">``) and include the
-  ``zope.security`` package as an ``install_requires`` dependency or 2)
-  change the ZCML in their applications to use the declarations from
-  `repoze.zcml <http://static.repoze.org/zcmldocs/>`_ instead of the stock
-  declarations.  ``repoze.zcml`` only makes available the ``adapter``,
-  ``subscriber`` and ``utility`` directives.
-
-  In short, if you've got an existing BFG application, after this
-  update, if your application won't start due to an import error for
-  "zope.security", the fastest way to get it working again is to add
-  ``zope.security`` to the "install_requires" of your BFG
-  application's ``setup.py``, then add the following ZCML anywhere
-  in your application's ``configure.zcml``::
-
-   <include package="zope.component" file="meta.zcml">
-
-  Then re-``setup.py develop`` or reinstall your application.
-
-- The ``http://namespaces.repoze.org/bfg`` XML namespace is now the default
-  XML namespace in ZCML for paster-generated applications.  The docs have
-  been updated to reflect this.
-
-- The copies of BFG's ``meta.zcml`` and ``configure.zcml`` were removed
-  from the root of the ``repoze.bfg`` package.  In 0.3.6, a new package
-  named ``repoze.bfg.includes`` was added, which contains the "correct"
-  copies of these ZCML files; the ones that were removed were for backwards
-  compatibility purposes.
-
-- The BFG ``view`` ZCML directive no longer calls
-  ``zope.component.interface.provideInterface`` for the ``for`` interface.
-  We don't support ``provideInterface`` in BFG because it mutates the
-  global registry.
-
-Other
------
-
-- The minimum requirement for ``chameleon.core`` is now 1.0b13.  The
-  minimum requirement for ``chameleon.zpt`` is now 1.0b8.  The minimum
-  requirement for ``chameleon.genshi`` is now 1.0b2.
-
-- Updated paster template "ez_setup.py" to one that requires setuptools
-  0.6c9.
-
-- Turn ``view_execution_permitted`` from the ``repoze.bfg.view`` module
-  into a documented API.
-
-- Doc cleanups.
-
-- Documented how to create a view capable of serving static resources.
-
-0.5.6 (2008-12-18)
-==================
-
-- Speed up ``traversal.model_url`` execution by using a custom url quoting
-  function instead of Python's ``urllib.quote``, by caching URL path
-  segment quoting and encoding results, by disusing Python's
-  ``urlparse.urljoin`` in favor of a simple string concatenation, and by
-  using ``ob.__class__ is unicode`` rather than ``isinstance(ob, unicode)``
-  in one strategic place.
-
-0.5.5 (2008-12-17)
-==================
-
-Backwards Incompatibilities
----------------------------
-
-- In the past, during traversal, the ModelGraphTraverser (the default
-  traverser) always passed each URL path segment to any ``__getitem__``
-  method of a model object as a byte string (a ``str`` object).  Now, by
-  default the ModelGraphTraverser attempts to decode the path segment to
-  Unicode (a ``unicode`` object) using the UTF-8 encoding before passing it
-  to the ``__getitem__`` method of a model object.  This makes it possible
-  for model objects to be dumber in ``__getitem__`` when trying to resolve
-  a subobject, as model objects themselves no longer need to try to divine
-  whether or not to try to decode the path segment passed by the
-  traverser.
-
-  Note that since 0.5.4, URLs generated by repoze.bfg's ``model_url`` API
-  will contain UTF-8 encoded path segments as necessary, so any URL
-  generated by BFG itself will be decodeable by the traverser.  If another
-  application generates URLs to a BFG application, to be resolved
-  successully, it should generate the URL with UTF-8 encoded path segments
-  to be successfully resolved.  The decoder is not at all magical: if a
-  non-UTF-8-decodeable path segment (e.g. one encoded using UTF-16 or some
-  other insanity) is passed in the URL, BFG will raise a ``TypeError`` with
-  a message indicating it could not decode the path segment.
-
-  To turn on the older behavior, where path segments were not decoded to
-  Unicode before being passed to model object ``__getitem__`` by the
-  traverser, and were passed as a raw byte string, set the
-  ``unicode_path_segments`` configuration setting to a false value in your
-  BFG application's section of the paste .ini file, for example::
-
-    unicode_path_segments = False
-
-  Or start the application using the ``BFG_UNICODE_PATH_SEGMENT`` envvar
-  set to a false value::
-
-    BFG_UNICODE_PATH_SEGMENTS=0
-
-0.5.4 (2008-12-13)
-==================
-
-Backwards Incompatibilities
----------------------------
-
-- URL-quote "extra" element names passed in as ``**elements`` to the
-  ``traversal.model_url`` API.  If any of these names is a Unicode string,
-  encode it to UTF-8 before URL-quoting.  This is a slight backwards
-  incompatibility that will impact you if you were already UTF-8 encoding
-  or URL-quoting the values you passed in as ``elements`` to this API.
-
-Bugfixes
---------
-
-- UTF-8 encode each segment in the model path used to generate a URL before
-  url-quoting it within the ``traversal.model_url`` API.  This is a bugfix,
-  as Unicode cannot always be successfully URL-quoted.
-
-Features
---------
-
-- Make it possible to run unit tests using a buildout-generated Python
-  "interpreter".  
-
-- Add ``request.root`` to ``router.Router`` in order to have easy access to
-  the application root.
-
-0.5.3 (2008-12-07)
-==================
-
-- Remove the ``ITestingTemplateRenderer`` interface.  When
-  ``testing.registerDummyRenderer`` is used, it instead registers a dummy
-  implementation using ``ITemplateRenderer`` interface, which is checked
-  for when the built-in templating facilities do rendering.  This change
-  also allows developers to make explcit named utility registrations in
-  the ZCML registry against ``ITemplateRenderer``; these will be found
-  before any on-disk template is looked up.
-
-0.5.2 (2008-12-05)
-==================
-
-- The component registration handler for views (functions or class
-  instances) now observes component adaptation annotations (see
-  ``zope.component.adaptedBy``) and uses them before the fallback values
-  for ``for_`` and ``request_type``. This change does not affect existing
-  code insomuch as the code does not rely on these defaults when an
-  annotation is set on the view (unlikely).  This means that for a
-  new-style class you can do ``zope.component.adapts(ISomeContext,
-  ISomeRequest)`` at class scope or at module scope as a decorator to a
-  bfg view function you can do ``@zope.component.adapter(ISomeContext,
-  ISomeRequest)``.  This differs from r.bfg.convention inasmuch as you
-  still need to put something in ZCML for the registrations to get done;
-  it's only the defaults that will change if these declarations exist.
-
-- Strip all slashes from end and beginning of path in clean_path within
-  traversal machinery.
-
-0.5.1 (2008-11-25)
-==================
-
-- Add ``keys``, ``items``, and ``values`` methods to
-  ``testing.DummyModel``.
-
-- Add __delitem__ method to ``testing.DummyModel``.
-
-0.5.0 (2008-11-18)
-==================
-
-- Fix ModelGraphTraverser; don't try to change the ``__name__`` or
-  ``__parent__`` of an object that claims it implements ILocation during
-  traversal even if the ``__name__`` or ``__parent__`` of the object
-  traversed does not match the name used in the traversal step or the or
-  the traversal parent .  Rationale: it was insane to do so. This bug was
-  only found due to a misconfiguration in an application that mistakenly
-  had intermediate persistent non-ILocation objects; traversal was causing
-  a persistent write on every request under this setup.
-
-- ``repoze.bfg.location.locate`` now unconditionally sets ``__name__`` and
-  ``__parent__`` on objects which provide ILocation (it previously only set
-  them conditionally if they didn't match attributes already present on the
-  object via equality).
-
-0.4.9 (2008-11-17)
-==================
-
-- Add chameleon text template API (chameleon ${name} renderings where the
-  template does not need to be wrapped in any containing XML).
-
-- Change docs to explain install in terms of a virtualenv
-  (unconditionally).
-
-- Make pushpage decorator compatible with repoze.bfg.convention's
-  ``bfg_view`` decorator when they're stacked.
-
-- Add content_length attribute to testing.DummyRequest.
-
-- Change paster template ``tests.py`` to include a true unit test.  Retain
-  old test as an integration test.  Update documentation.
-
-- Document view registrations against classes and ``repoze.bfg.convention``
-  in context.
-
-- Change the default paster template to register its single view against a
-  class rather than an interface.
-
-- Document adding a request type interface to the request via a subscriber
-  function in the events narrative documentation.
-
-0.4.8 (2008-11-12)
-==================
-
-Backwards Incompatibilities
----------------------------
-
-- ``repoze.bfg.traversal.model_url`` now always appends a slash to all
-  generated URLs unless further elements are passed in as the third and
-  following arguments.  Rationale: views often use ``model_url`` without
-  the third-and-following arguments in order to generate a URL for a model
-  in order to point at the default view of a model.  The URL that points to
-  the default view of the *root* model is technically ``http://mysite/`` as
-  opposed to ``http://mysite`` (browsers happen to ask for '/' implicitly
-  in the GET request).  Because URLs are never automatically generated for
-  anything *except* models by ``model_url``, and because the root model is
-  not really special, we continue this pattern.  The impact of this change
-  is minimal (at most you will have too many slashes in your URL, which BFG
-  deals with gracefully anyway).
-
-0.4.7 (2008-11-11)
-==================
-
-Features
---------
-
-- Allow ``testing.registerEventListener`` to be used with Zope 3 style
-  "object events" (subscribers accept more than a single event argument).
-  We extend the list with the arguments, rather than append.
-
-0.4.6 (2008-11-10)
-==================
-
-Bug Fixes
----------
-
-- The ``model_path`` and ``model_url`` traversal APIs returned the wrong
-  value for the root object (e.g. ``model_path`` returned ``''`` for the
-  root object, while it should have been returning ``'/'``).
-
-0.4.5 (2008-11-09)
-==================
-
-Features
---------
-
-- Added a ``clone`` method and a ``__contains__`` method to the DummyModel
-  testing object.
-
-- Allow DummyModel objects to receive extra keyword arguments, which will
-  be attached as attributes.
-
-- The DummyTemplateRenderer now returns ``self`` as its implementation.
-
-0.4.4 (2008-11-08)
-==================
-
-Features
---------
-
-- Added a ``repoze.bfg.testing`` module to attempt to make it slightly
-  easier to write unittest-based automated tests of BFG applications.
-  Information about this module is in the documentation.
-
-- The default template renderer now supports testing better by looking for
-  ``ITestingTemplateRenderer`` using a relative pathname.  This is exposed
-  indirectly through the API named ``registerTemplateRenderer`` in
-  ``repoze.bfg.testing``.
-
-Deprecations
-------------
-
-- The names ``repoze.bfg.interfaces.ITemplate`` ,
-  ``repoze.bfg.interfaces.ITemplateFactory`` and
-  ``repoze.bfg.interfaces.INodeTemplate`` have been deprecated.  These
-  should now be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` and
-  ``repoze.bfg.interfaces.ITemplateRendererFactory``, and
-  ``INodeTemplateRenderer`` respectively.
-
-- The name ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` is deprecated.
-  Use ``repoze.bfg.chameleon_zpt.ZPTTemplateRenderer``.
-
-- The name ``repoze.bfg.chameleon_genshi.GenshiTemplateFactory`` is
-  deprecated.  Use ``repoze.bfg.chameleon_genshi.GenshiTemplateRenderer``.
-
-- The name ``repoze.bfg.xslt.XSLTemplateFactory`` is deprecated.  Use
-  ``repoze.bfg.xslt.XSLTemplateRenderer``.
-
-0.4.3 (2008-11-02)
-==================
-
-Bug Fixes
----------
-
-- Not passing the result of "get_options" as the second argument of
-  make_app could cause attribute errors when attempting to look up settings
-  against the ISettings object (internal).  Fixed by giving the Settings
-  objects defaults for ``debug_authorization`` and ``debug_notfound``.
-
-- Return an instance of ``Allowed`` (rather than ``True``) from
-  ``has_permission`` when no security policy is in use.
-
-- Fix bug where default deny in authorization check would throw a TypeError
-  (use ``ACLDenied`` instead of ``Denied``).
-
-0.4.2 (2008-11-02)
-==================
-
-Features
---------
-
-- Expose a single ILogger named "repoze.bfg.debug" as a utility; this
-  logger is registered unconditionally and is used by the authorization
-  debug machinery.  Applications may also make use of it as necessary
-  rather than inventing their own logger, for convenience.
-
-- The ``BFG_DEBUG_AUTHORIZATION`` envvar and the ``debug_authorization``
-  config file value now only imply debugging of view-invoked security
-  checks.  Previously, information was printed for every call to
-  ``has_permission`` as well, which made output confusing.  To debug
-  ``has_permission`` checks and other manual permission checks, use the
-  debugger and print statements in your own code.
-
-- Authorization debugging info is now only present in the HTTP response
-  body oif ``debug_authorization`` is true.
-
-- The format of authorization debug messages was improved.
-
-- A new ``BFG_DEBUG_NOTFOUND`` envvar was added and a symmetric
-  ``debug_notfound`` config file value was added.  When either is true, and
-  a NotFound response is returned by the BFG router (because a view could
-  not be found), debugging information is printed to stderr.  When this
-  value is set true, the body of HTTPNotFound responses will also contain
-  the same debugging information.
-
-- ``Allowed`` and ``Denied`` responses from the security machinery are now
-  specialized into two types: ACL types, and non-ACL types.  The
-  ACL-related responses are instances of ``repoze.bfg.security.ACLAllowed``
-  and ``repoze.bfg.security.ACLDenied``.  The non-ACL-related responses are
-  ``repoze.bfg.security.Allowed`` and ``repoze.bfg.security.Denied``.  The
-  allowed-type responses continue to evaluate equal to things that
-  themselves evaluate equal to the ``True`` boolean, while the denied-type
-  responses continue to evaluate equal to things that themselves evaluate
-  equal to the ``False`` boolean.  The only difference between the two
-  types is the information attached to them for debugging purposes.
-
-- Added a new ``BFG_DEBUG_ALL`` envvar and a symmetric ``debug_all`` config
-  file value.  When either is true, all other debug-related flags are set
-  true unconditionally (e.g. ``debug_notfound`` and
-  ``debug_authorization``).
-
-Documentation
--------------
-
-- Added info about debug flag changes.
-
-- Added a section to the security chapter named "Debugging Imperative
-  Authorization Failures" (for e.g. ``has_permssion``).
-
-Bug Fixes
----------
-
-- Change default paster template generator to use ``Paste#http`` server
-  rather than ``PasteScript#cherrpy`` server.  The cherrypy server has a
-  security risk in it when ``REMOTE_USER`` is trusted by the downstream
-  application.
-
-0.4.1 (2008-10-28)
-==================
-
-Bug Fixes
----------
-
-- If the ``render_view_to_response`` function was called, if the view was
-  found and called, but it returned something that did not implement
-  IResponse, the error would pass by unflagged.  This was noticed when I
-  created a view function that essentially returned None, but received a
-  NotFound error rather than a ValueError when the view was rendered.  This
-  was fixed.
-
-0.4.0 (2008-10-03)
-==================
-
-Docs 
-----
-
-- An "Environment and Configuration" chapter was added to the narrative 
-  portion of the documentation.
-
-Features
---------
-
-- Ensure bfg doesn't generate warnings when running under Python
-  2.6.
-
-- The environment variable ``BFG_RELOAD_TEMPLATES`` is now available
-  (serves the same purpose as ``reload_templates`` in the config file).
-
-- A new configuration file option ``debug_authorization`` was added.
-  This turns on printing of security authorization debug statements
-  to ``sys.stderr``.  The ``BFG_DEBUG_AUTHORIZATION`` environment
-  variable was also added; this performs the same duty.
-
-Bug Fixes
----------
-
-- The environment variable ``BFG_SECURITY_DEBUG`` did not always work.
-  It has been renamed to ``BFG_DEBUG_AUTHORIZATION`` and fixed.
-
-Deprecations
-------------
-
-- A deprecation warning is now issued when old API names from the
-  ``repoze.bfg.templates`` module are imported.
-
-Backwards incompatibilities
----------------------------
-
-- The ``BFG_SECURITY_DEBUG`` environment variable was renamed to
-  ``BFG_DEBUG_AUTHORIZATION``.
-
-0.3.9 (2008-08-27)
-==================
-
-Features
---------
-
-- A ``repoze.bfg.location`` API module was added.
-
-Backwards incompatibilities
----------------------------
-
-- Applications must now use the ``repoze.bfg.interfaces.ILocation``
-  interface rather than ``zope.location.interfaces.ILocation`` to
-  represent that a model object is "location-aware".  We've removed
-  a dependency on ``zope.location`` for cleanliness purposes: as
-  new versions of zope libraries are released which have improved
-  dependency information, getting rid of our dependence on
-  ``zope.location`` will prevent a newly installed repoze.bfg
-  application from requiring the ``zope.security``, egg, which not
-  truly used at all in a "stock" repoze.bfg setup.  These
-  dependencies are still required by the stack at this time; this
-  is purely a futureproofing move.
-
-  The security and model documentation for previous versions of
-  ``repoze.bfg`` recommended using the
-  ``zope.location.interfaces.ILocation`` interface to represent
-  that a model object is "location-aware".  This documentation has
-  been changed to reflect that this interface should now be
-  imported from ``repoze.bfg.interfaces.ILocation`` instead.
-
-0.3.8 (2008-08-26)
-==================
-
-Docs
-----
-
-- Documented URL dispatch better in narrative form.
-
-Bug fixes
----------
-
-- Routes URL dispatch did not have access to the WSGI environment,
-  so conditions such as method=GET did not work.
-
-Features
---------
-
-- Add ``principals_allowed_by_permission`` API to security module.
-
-- Replace ``z3c.pt`` support with support for ``chameleon.zpt``.
-  Chameleon is the new name for the package that used to be named
-  ``z3c.pt``.  NOTE: If you update a ``repoze.bfg`` SVN checkout
-  that you're using for development, you will need to run "setup.py
-  install" or "setup.py develop" again in order to obtain the
-  proper Chameleon packages.  ``z3c.pt`` is no longer supported by
-  ``repoze.bfg``.  All API functions that used to render ``z3c.pt``
-  templates will work fine with the new packages, and your
-  templates should render almost identically.
-
-- Add a ``repoze.bfg.chameleon_zpt`` module.  This module provides
-  Chameleon ZPT support.
-
-- Add a ``repoze.bfg.xslt`` module.  This module provides XSLT
-  support.
-
-- Add a ``repoze.bfg.chameleon_genshi`` module.  This provides
-  direct Genshi support, which did not exist previously.
-
-Deprecations
-------------
-
-- Importing API functions directly from ``repoze.bfg.template`` is
-  now deprecated.  The ``get_template``, ``render_template``,
-  ``render_template_to_response`` functions should now be imported
-  from ``repoze.chameleon_zpt``.  The ``render_transform``, and
-  ``render_transform_to_response`` functions should now be imported
-  from ``repoze.bfg.xslt``.  The ``repoze.bfg.template`` module
-  will remain around "forever" to support backwards compatibility.
-
-0.3.7 (2008-09-09)
-==================
-
-Features
---------
-
-- Add compatibility with z3c.pt 1.0a7+ (z3c.pt became a namespace package).
-
-Bug fixes
----------
-
-- ``repoze.bfg.traversal.find_model`` function did not function properly.
-
-0.3.6 (2008-09-04)
-==================
-
-Features
---------
-
-- Add startup process docs.
-
-- Allow configuration cache to be bypassed by actions which include special
-  "uncacheable" discriminators (for actions that have variable results).
-
-Bug Fixes
----------
-
-- Move core repoze.bfg ZCML into a ``repoze.bfg.includes`` package so we
-  can use repoze.bfg better as a namespace package.  Adjust the code
-  generator to use it.  We've left around the ``configure.zcml`` in the
-  repoze.bfg package directly so as not to break older apps.
-
-- When a zcml application registry cache was unpickled, and it contained a
-  reference to an object that no longer existed (such as a view), bfg would
-  not start properly.
-
-0.3.5 (2008-09-01)
-==================
-
-Features
---------
-
-- Event notification is issued after application is created and configured
-  (``IWSGIApplicationCreatedEvent``).
-
-- New API module: ``repoze.bfg.view``.  This module contains the functions
-  named ``render_view_to_response``, ``render_view_to_iterable``,
-  ``render_view`` and ``is_response``, which are documented in the API
-  docs.  These features aid programmatic (non-server-driven) view
-  execution.
-
-0.3.4 (2008-08-28)
-==================
-
-Backwards incompatibilities
----------------------------
-
-- Make ``repoze.bfg`` a namespace package so we can allow folks to create
-  subpackages (e.g. ``repoze.bfg.otherthing``) within separate eggs.  This
-  is a backwards incompatible change which makes it impossible to import
-  "make_app" and "get_options" from the ``repoze.bfg`` module directly.
-  This change will break all existing apps generated by the paster code
-  generator.  Instead, you need to import these functions as
-  ``repoze.bfg.router:make_app`` and ``repoze.bfg.registry:get_options``,
-  respectively.  Sorry folks, it has to be done now or never, and
-  definitely better now.
-
-Features
---------
-
-- Add ``model_path`` API function to traversal module.
-
-Bugfixes
-
-- Normalize path returned by repoze.bfg.caller_path.
-
-0.3.3 (2008-08-23)
-==================
-
-- Fix generated test.py module to use project name rather than package
-  name.
-
-0.3.2 (2008-08-23)
-==================
-
-- Remove ``sampleapp`` sample application from bfg package itself.
-
-- Remove dependency on FormEncode (only needed by sampleapp).
-
-- Fix paster template generation so that case-sensitivity is preserved for
-  project vs. package name.
-
-- Depend on ``z3c.pt`` version 1.0a1 (which requires the ``[lxml]`` extra
-  currently).
-
-- Read and write a pickled ZCML actions list, stored as
-  ``configure.zcml.cache`` next to the applications's "normal"
-  configuration file.  A given bfg app will usually start faster if it's
-  able to read the pickle data.  It fails gracefully to reading the real
-  ZCML file if it cannot read the pickle.
-
-0.3.1 (2008-08-20)
-==================
-
-- Generated application differences: ``make_app`` entry point renamed to
-  ``app`` in order to have a different name than the bfg function of the
-  same name, to prevent confusion.
-
-- Add "options" processing to bfg's ``make_app`` to support runtime
-  options.  A new API function named ``get_options`` was added to the
-  registry module.  This function is typically used in an application's
-  ``app`` entry point.  The Paste config file section for the app can now
-  supply the ``reload_templates`` option, which, if true, will prevent the
-  need to restart the appserver in order for ``z3c.pt`` or XSLT template
-  changes to be detected.
-
-- Use only the module name in generated project's "test_suite" (run all
-  tests found in the package).
-
-- Default port for generated apps changed from 5432 to 6543 (Postgres
-  default port is 6543).
-
-0.3.0 (2008-08-16)
-==================
-
-- Add ``get_template`` API to template module.
-
-0.2.9 (2008-08-11)
-==================
-
-- 0.2.8 was "brown bag" release.  It didn't work at all.  Symptom:
-  ComponentLookupError when trying to render a page.
-
-0.2.8 (2008-08-11)
-==================
-
-- Add ``find_model`` and ``find_root`` traversal APIs.  In the process,
-  make ITraverser a uni-adapter (on context) rather than a multiadapter (on
-  context and request).
-
-0.2.7 (2008-08-05)
-==================
-
-- Add a ``request_type`` attribute to the available attributes of a
-  ``bfg:view`` configure.zcml element.  This attribute will have a value
-  which is a dotted Python path, pointing at an interface.  If the request
-  object implements this interface when the view lookup is performed, the
-  appropriate view will be called.  This is meant to allow for simple
-  "skinning" of sites based on request type.  An event subscriber should
-  attach the interface to the request on ingress to support skins.
-
-- Remove "template only" views.  These were just confusing and were never
-  documented.
-
-- Small url dispatch overhaul: the ``connect`` method of the
-  ``urldispatch.RoutesMapper`` object now accepts a keyword parameter named
-  ``context_factory``.  If this parameter is supplied, it must be a
-  callable which returns an instance.  This instance is used as the context
-  for the request when a route is matched.
-
-- The registration of a RoutesModelTraverser no longer needs to be
-  performed by the application; it's in the bfg ZCML now.
-
-0.2.6 (2008-07-31)
-==================
-
-- Add event sends for INewRequest and INewResponse.  See the events.rst
-  chapter in the documentation's ``api`` directory.
-
-0.2.5 (2008-07-28)
-==================
-
-- Add ``model_url`` API.
-
-0.2.4 (2008-07-27)
-==================
-
-- Added url-based dispatch.
-
-0.2.3 (2008-07-20)
-==================
-
-- Add API functions for authenticated_userid and effective_principals.
-
-0.2.2 (2008-07-20)
-==================
-
-- Add authenticated_userid and effective_principals API to security
-  policy.
-
-0.2.1 (2008-07-20)
-==================
-
-- Add find_interface API.
-
-0.2 (2008-07-19)
-================
-
-- Add wsgiapp decorator.
-
-- The concept of "view factories" was removed in favor of always calling a
-  view, which is a callable that returns a response directly (as opposed to
-  returning a view).  As a result, the ``factory`` attribute in the
-  bfg:view ZCML statement has been renamed to ``view``.  Various interface
-  names were changed also.
-
-- ``render_template`` and ``render_transform`` no longer return a Response
-  object.  Instead, these return strings.  The old behavior can be obtained
-  by using ``render_template_to_response`` and
-  ``render_transform_to_response``.
-
-- Added 'repoze.bfg.push:pushpage' decorator, which creates BFG views from
-  callables which take (context, request) and return a mapping of top-level
-  names.
-
-- Added ACL-based security.
-
-- Support for XSLT templates via a render_transform method
-
-0.1 (2008-07-08)
-================
-
-- Initial release.
-