Add "exception views" work contributed primarily by Andrey Popp by merging the "phash" branch.

1 files changed, 46 insertions, 989 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index cb9453b43..4f125d33d 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,1016 +1,73 @@
 Next release
 ============
 
-Bug Fixes
----------
-
-- Defer conditional import of IPython to avoid breakage under mod_wsgi.
-  http://bugs.repoze.org/issue138
-
-- The ``__name__`` value assigned to the returned object in the
-  ``bfg_alchemy`` application template's ``MyApp`` model was an
-  integer.  This was incorrect.  It is now a string.
-
-Internal
---------
-
-- Replace the statement ``path = path.rstrip('/').lstrip('/')`` with
-  the simpler ``path = path.strip('/')`` in the
-  ``repoze.bfg.traversal.traversal_path`` function.
-
-1.2 (2010-02-10)
-================
-
-- No changes from 1.2b6.
-
-1.2b6 (2010-02-06)
-==================
-
-Backwards Incompatibilities
----------------------------
-
-- Remove magical feature of ``repoze.bfg.url.model_url`` which
-  prepended a fully-expanded urldispatch route URL before a the
-  model's path if it was noticed that the request had matched a route.
-  This feature was ill-conceived, and didn't work in all scenarios.
-
-Bug Fixes
----------
-
-- More correct conversion of provided ``renderer`` values to resource
-  specification values (internal).
-
-1.2b5 (2010-02-04)
-==================
-
-Bug Fixes
----------
-
-- 1.2b4 introduced a bug whereby views added via a route configuration
-  that named a view callable and also a ``view_attr`` became broken.
-  Symptom: ``MyViewClass is not callable`` or the ``__call__`` of a
-  class was being called instead of the method named via
-  ``view_attr``.
-
-- Fix a bug whereby a ``renderer`` argument to the ``@bfg_view``
-  decorator that provided a package-relative template filename might
-  not have been resolved properly.  Symptom: inappropriate ``Missing
-  template resource`` errors.
-
-1.2b4 (2010-02-03)
-==================
-
-Documentation
--------------
-
-- Update GAE tutorial to use Chameleon instead of Jinja2 (now that
-  it's possible).
-
-Bug Fixes
----------
-
-- Ensure that ``secure`` flag for AuthTktAuthenticationPolicy
-  constructor does what it's documented to do (merge Daniel Holth's
-  fancy-cookies-2 branch).
-
-Features
---------
-
-- Add ``path`` and ``http_only`` options to
-  AuthTktAuthenticationPolicy constructor (merge Daniel Holth's
-  fancy-cookies-2 branch).
-
-Backwards Incompatibilities
----------------------------
-
-- Remove ``view_header``, ``view_accept``, ``view_xhr``,
-  ``view_path_info``, ``view_request_method``, ``view_request_param``,
-  and ``view_containment`` predicate arguments from the
-  ``Configurator.add_route`` argument list.  These arguments were
-  speculative.  If you need the features exposed by these arguments,
-  add a view associated with a route using the ``route_name`` argument
-  to the ``add_view`` method instead.
-
-- Remove ``view_header``, ``view_accept``, ``view_xhr``,
-  ``view_path_info``, ``view_request_method``, ``view_request_param``,
-  and ``view_containment`` predicate arguments from the ``route`` ZCML
-  directive attribute set.  These attributes were speculative.  If you
-  need the features exposed by these attributes, add a view associated
-  with a route using the ``route_name`` attribute of the ``view`` ZCML
-  directive instead.
-
-Dependencies
-------------
-
-- Remove dependency on ``sourcecodegen`` (not depended upon by
-  Chameleon 1.1.1+).
-
-1.2b3 (2010-01-24)
-==================
-
-Bug Fixes
----------
-
-- When "hybrid mode" (both traversal and urldispatch) is in use,
-  default to finding route-related views even if a non-route-related
-  view registration has been made with a more specific context.  The
-  default used to be to find views with a more specific context first.
-  Use the new ``use_global_views`` argument to the route definition to
-  get back the older behavior.
-
-Features
---------
-
-- Add ``use_global_views`` argument to ``add_route`` method of
-  Configurator.  When this argument is true, views registered for *no*
-  route will be found if no more specific view related to the route is
-  found.
-
-- Add ``use_global_views`` attribute to ZCML ``<route>`` directive
-  (see above).
-
-Internal
---------
-
-- When registering a view, register the view adapter with the
-  "requires" interfaces as ``(request_type, context_type)`` rather
-  than ``(context_type, request_type)``.  This provides for saner
-  lookup, because the registration will always be made with a specific
-  request interface, but registration may not be made with a specific
-  context interface.  In general, when creating multiadapters, you
-  want to order the requires interfaces so that the the elements which
-  are more likely to be registered using specific interfaces are
-  ordered before those which are less likely.
-
-1.2b2 (2010-01-21)
-==================
-
-Bug Fixes
----------
-
-- When the ``Configurator`` is passed an instance of
-  ``zope.component.registry.Components`` as a ``registry`` constructor
-  argument, fix the instance up to have the attributes we expect of an
-  instance of ``repoze.bfg.registry.Registry`` when ``setup_registry``
-  is called.  This makes it possible to use the global Zope component
-  registry as a BFG application registry.
-
-- When WebOb 0.9.7.1 was used, a deprecation warning was issued for
-  the class attribute named ``charset`` within
-  ``repoze.bfg.request.Request``.  BFG now *requires* WebOb >= 0.9.7,
-  and code was added so that this deprecation warning has disappeared.
-
-- Fix a view lookup ordering bug whereby a view with a larger number
-  of predicates registered first (literally first, not "earlier") for
-  a triad would lose during view lookup to one registered with fewer.
-
-- Make sure views with exactly N custom predicates are always called
-  before views with exactly N non-custom predicates given all else is
-  equal in the view configuration.
-
-Documentation
--------------
-
-- Change renderings of ZCML directive documentation.
-
-- Add a narrative documentation chapter: "Using the Zope Component
-  Architecture in repoze.bfg".
-
-Dependencies
-------------
-
-- Require WebOb >= 0.9.7
-
-1.2b1 (2010-01-18)
-==================
-
-Bug Fixes
----------
-
-- In ``bfg_routesalchemy``, ``bfg_alchemy`` paster templates and the
-  ``bfgwiki2`` tutorial, clean up the SQLAlchemy connection by
-  registering a ``repoze.tm.after_end`` callback instead of relying on
-  a ``__del__`` method of a ``Cleanup`` class added to the WSGI
-  environment.  The ``__del__`` strategy was fragile and caused
-  problems in the wild.  Thanks to Daniel Holth for testing.
-
-Features
---------
-
-- Read logging configuration from PasteDeploy config file ``loggers``
-  section (and related) when ``paster bfgshell`` is invoked.
-
-Documentation
--------------
-
-- Major rework in preparation for book publication.
-
-1.2a11 (2010-01-05)
-===================
-
-Bug Fixes
----------
-
-- Make ``paster bfgshell`` and ``paster create -t bfg_xxx`` work on
-  Jython (fix minor incompatibility with treatment of ``__doc__`` at
-  the class level).
-
-- Updated dependency on ``WebOb`` to require a version which supports
-  features now used in tests.
-
-Features
---------
-
-- Jython compatibility (at least when repoze.bfg.jinja2 is used as the
-  templating engine; Chameleon does not work under Jython).
-
-- Show the derived abspath of template resource specifications in the
-  traceback when a renderer template cannot be found.
-
-- Show the original traceback when a Chameleon template cannot be
-  rendered due to a platform incompatibility.
-
-1.2a10 (2010-01-04)
-===================
-
-Features
---------
-
-- The ``Configurator.add_view`` method now accepts an argument named
-  ``context``.  This is an alias for the older argument named
-  ``for_``; it is preferred over ``for_``, but ``for_`` will continue
-  to be supported "forever".
-
-- The ``view`` ZCML directive now accepts an attribute named
-  ``context``.  This is an alias for the older attribute named
-  ``for``; it is preferred over ``for``, but ``for`` will continue to
-  be supported "forever".
-
-- The ``Configurator.add_route`` method now accepts an argument named
-  ``view_context``.  This is an alias for the older argument named
-  ``view_for``; it is preferred over ``view_for``, but ``view_for``
-  will continue to be supported "forever".
-
-- The ``route`` ZCML directive now accepts an attribute named
-  ``view_context``.  This is an alias for the older attribute named
-  ``view_for``; it is preferred over ``view_for``, but ``view_for``
-  will continue to be supported "forever".
-
-Documentation and Paster Templates
-----------------------------------
-
-- LaTeX rendering tweaks.
-
-- All uses of the ``Configurator.add_view`` method that used its
-  ``for_`` argument now use the ``context`` argument instead.
-
-- All uses of the ``Configurator.add_route`` method that used its
-  ``view_for`` argument now use the ``view_context`` argument instead.
-
-- All uses of the ``view`` ZCML directive that used its ``for``
-  attribute now use the ``context`` attribute instead.
-
-- All uses of the ``route`` ZCML directive that used its ``view_for``
-  attribute now use the ``view_context`` attribute instead.
-
-- Add a (minimal) tutorial dealing with use of ``repoze.catalog`` in a
-  ``repoze.bfg`` application.
-
-Documentation Licensing
------------------------
-
-- Loosen the documentation licensing to allow derivative works: it is
-  now offered under the `Creative Commons
-  Attribution-Noncommercial-Share Alike 3.0 United States License
-  <http://creativecommons.org/licenses/by-nc-sa/3.0/us/>`_.  This is
-  only a documentation licensing change; the ``repoze.bfg`` software
-  continues to be offered under the Repoze Public License at
-  http://repoze.org/license.html (BSD-like).
-
-1.2a9 (2009-12-27)
-==================
-
-Documentation Licensing
------------------------
-
-- The *documentation* (the result of ``make <html|latex|htmlhelp>``
-  within the ``docs`` directory) in this release is now offered under
-  the Creative Commons Attribution-Noncommercial-No Derivative Works
-  3.0 United States License as described by
-  http://creativecommons.org/licenses/by-nc-nd/3.0/us/ .  This is only
-  a licensing change for the documentation; the ``repoze.bfg``
-  software continues to be offered under the Repoze Public License
-  at http://repoze.org/license.html (BSD-like).
-
-Documentation
--------------
-
-- Added manual index entries to generated index.
-
-- Document the previously existing (but non-API)
-  ``repoze.bfg.configuration.Configurator.setup_registry`` method as
-  an official API of a ``Configurator``.
-
-- Fix syntax errors in various documentation code blocks.
-
-- Created new top-level documentation section: "ZCML Directives".
-  This section contains detailed ZCML directive information, some of
-  which was removed from various narrative chapters.
-
-- The LaTeX rendering of the documentation has been improved.
-
-- Added a "Fore-Matter" section with author, copyright, and licensing
-  information.
-
-1.2a8 (2009-12-24)
-==================
-
 Features
 --------
 
-- Add a ``**kw`` arg to the ``Configurator.add_settings`` API.
+- Added "exception views".  When you use an exception (anything than
+  inherits from the Python ``Exception`` builtin) as view context
+  argument, e.g.::
 
-- Add ``hook_zca`` and ``unhook_zca`` methods to the ``Configurator``
-  API.
+      from repoze.bfg.view import bfg_view
+      from repoze.bfg.exceptions import NotFound
+      from webob.exc import HTTPNotFound
 
-- The ``repoze.bfg.testing.setUp`` method now returns a
-  ``Configurator`` instance which can be used to do further
-  configuration during unit tests.
+      @bfg_view(context=NotFound)
+      def notfound_view(request):
+          return HTTPNotFound()
 
-Bug Fixes
----------
+  For the above example, when the ``repoze.bfg.exceptions.NotFound``
+  exception is raised by any view or any root factory, the
+  ``notfound_view`` view callable wil be invoked and its response
+  returned.
 
-- The ``json`` renderer failed to set the response content type to
-  ``application/json``.  It now does, by setting
-  ``request.response_content_type`` unless this attribute is already
-  set.
+  Other normal view predicates can also be used in combination with an
+  exception view registration:
 
-- The ``string`` renderer failed to set the response content type to
-  ``text/plain``.  It now does, by setting
-  ``request.response_content_type`` unless this attribute is already
-  set.
-
-Documentation
--------------
+      from repoze.bfg.view import bfg_view
+      from repoze.bfg.exceptions import NotFound
+      from webob.exc import HTTPNotFound
 
-- General documentation improvements by using better Sphinx roles such
-  as "class", "func", "meth", and so on.  This means that there are
-  many more hyperlinks pointing to API documentation for API
-  definitions in all narrative, tutorial, and API documentation
-  elements.
+      @bfg_view(context=NotFound, route_name='home')
+      def notfound_view(request):
+          return HTTPNotFound()
 
-- Added a description of imperative configuration in various places
-  which only described ZCML configuration.
+  The above exception view names the ``route_name`` of ``home``,
+  meaning that it will only be called when the route matched has a
+  name of ``home``.  You can therefore have more than one exception
+  view for any given exception in the system: the "most specific" one
+  will be called when the set of request circumstances which match the
+  view registration.  The only predicate that cannot be not be used
+  successfully is ``name``.  The name used to look up an exception
+  view is always the empty string.
 
-- A syntactical refreshing of various tutorials.
+  Existing (pre-1.3) normal views registered against objects
+  inheriting from ``Exception`` will continue to work.  Exception
+  views used for user-defined exceptions and system exceptions used as
+  contexts will also work.
 
-- Added the ``repoze.bfg.authentication``,
-  ``repoze.bfg.authorization``, and ``repoze.bfg.interfaces`` modules
-  to API documentation.
+  The feature can be used with any view registration mechanism
+  (``@bfg_view`` decorator, ZCML, or imperative ``add_view`` styles).
 
 Deprecations
 ------------
 
-- The ``repoze.bfg.testing.registerRoutesMapper`` API (added in an
-  early 1.2 alpha) was deprecated.  Its import now generates a
-  deprecation warning.
-
-1.2a7 (2009-12-20)
-==================
-
-Features
---------
-
-- Add four new testing-related APIs to the
-  ``repoze.bfg.configuration.Configurator`` class:
-  ``testing_securitypolicy``, ``testing_models``,
-  ``testing_add_subscriber``, and ``testing_add_template``.  These
-  were added in order to provide more direct access to the
-  functionality of the ``repoze.bfg.testing`` APIs named
-  ``registerDummySecurityPolicy``, ``registerModels``,
-  ``registerEventListener``, and ``registerTemplateRenderer`` when a
-  configurator is used.  The ``testing`` APIs named are nominally
-  deprecated (although they will likely remain around "forever", as
-  they are in heavy use in the wild).
-
-- Add a new API to the ``repoze.bfg.configuration.Configurator``
-  class: ``add_settings``.  This API can be used to add "settings"
-  (information returned within via the
-  ``repoze.bfg.settings.get_settings`` API) after the configurator has
-  been initially set up.  This is most useful for testing purposes.
-
-- Add a ``custom_predicates`` argument to the ``Configurator``
-  ``add_view`` method, the ``bfg_view`` decorator and the attribute
-  list of the ZCML ``view`` directive.  If ``custom_predicates`` is
-  specified, it must be a sequence of predicate callables (a predicate
-  callable accepts two arguments: ``context`` and ``request`` and
-  returns ``True`` or ``False``).  The associated view callable will
-  only be invoked if all custom predicates return ``True``.  Use one
-  or more custom predicates when no existing predefined predicate is
-  useful.  Predefined and custom predicates can be mixed freely.
-
-- Add a ``custom_predicates`` argument to the ``Configurator``
-  ``add_route`` and the attribute list of the ZCML ``route``
-  directive.  If ``custom_predicates`` is specified, it must be a
-  sequence of predicate callables (a predicate callable accepts two
-  arguments: ``context`` and ``request`` and returns ``True`` or
-  ``False``).  The associated route will match will only be invoked if
-  all custom predicates return ``True``, else route matching
-  continues.  Note that the value ``context`` will always be ``None``
-  when passed to a custom route predicate.  Use one or more custom
-  predicates when no existing predefined predicate is useful.
-  Predefined and custom predicates can be mixed freely.
+-  The exception views feature replaces the need for the
+   ``set_notfound_view`` and ``set_forbidden_view`` methods of the
+   ``Configurator`` as well as the ``notfound`` and ``forbidden`` ZCML
+   directives.  Those methods and directives will continue to work for
+   the foreseeable future, but they are deprecated in the
+   documentation.
 
 Internal
 --------
 
-- Remove the ``repoze.bfg.testing.registerTraverser`` function.  This
-  function was never an API.
-
-Documenation
-------------
-
-- Doc-deprecated most helper functions in the ``repoze.bfg.testing``
-  module.  These helper functions likely won't be removed any time
-  soon, nor will they generate a warning any time soon, due to their
-  heavy use in the wild, but equivalent behavior exists in methods of
-  a Configurator.
-
-1.2a6 (2009-12-18)
-==================
-
-Features
---------
-
-- The ``Configurator`` object now has two new methods: ``begin`` and
-  ``end``.  The ``begin`` method is meant to be called before any
-  "configuration" begins (e.g. before ``add_view``, et. al are
-  called).  The ``end`` method is meant to be called after all
-  "configuration" is complete.
-
-  Previously, before there was imperative configuration at all (1.1
-  and prior), configuration begin and end was invariably implied by
-  the process of loading a ZCML file.  When a ZCML load happened, the
-  threadlocal data structure containing the request and registry was
-  modified before the load, and torn down after the load, making sure
-  that all framework code that needed ``get_current_registry`` for the
-  duration of the ZCML load was satisfied.
-
-  Some API methods called during imperative configuration, (such as
-  ``Configurator.add_view`` when a renderer is involved) end up for
-  historical reasons calling ``get_current_registry``.  However, in
-  1.2a5 and below, the Configurator supplied no functionality that
-  allowed people to make sure that ``get_current_registry`` returned
-  the registry implied by the configurator being used.  ``begin`` now
-  serves this purpose.  Inversely, ``end`` pops the thread local
-  stack, undoing the actions of ``begin``.
-
-  We make this boundary explicit to reduce the potential for confusion
-  when the configurator is used in different circumstances (e.g. in
-  unit tests and app code vs. just in initial app setup).
-
-  Existing code written for 1.2a1-1.2a5 which does not call ``begin``
-  or ``end`` continues to work in the same manner it did before.  It
-  is however suggested that this code be changed to call ``begin`` and
-  ``end`` to reduce the potential for confusion in the future.
-
-- All ``paster`` templates which generate an application skeleton now
-  make use of the new ``begin`` and ``end`` methods of the
-  Configurator they use in their respective copies of ``run.py`` and
-  ``tests.py``.
+- View registrations and lookups are now done with three "requires"
+  arguments instead of two to accomodate orthogonality of exception
+  views.
 
 Documentation
 -------------
 
-- All documentation that makes use of a ``Configurator`` object to do
-  application setup and test setup now makes use of the new ``begin``
-  and ``end`` methods of the configurator.
-
-Bug Fixes
----------
-
-- When a ``repoze.bfg.exceptions.NotFound`` or
-  ``repoze.bfg.exceptions.Forbidden`` *class* (as opposed to instance)
-  was raised as an exception within a root factory (or route root
-  factory), the exception would not be caught properly by the
-  ``repoze.bfg.`` Router and it would propagate to up the call stack,
-  as opposed to rendering the not found view or the forbidden view as
-  would have been expected.
-
-- When Chameleon page or text templates used as renderers were added
-  imperatively (via ``Configurator.add_view`` or some derivative),
-  they too-eagerly attempted to look up the ``reload_templates``
-  setting via ``get_settings``, meaning they were always registered in
-  non-auto-reload-mode (the default).  Each now waits until its
-  respective ``template`` attribute is accessed to look up the value.
-
-- When a route with the same name as a previously registered route was
-  added, the old route was not removed from the mapper's routelist.
-  Symptom: the old registered route would be used (and possibly
-  matched) during route lookup when it should not have had a chance to
-  ever be used.
-
-1.2a5 (2009-12-10)
-==================
-
-Features
---------
-
-- When the ``repoze.bfg.exceptions.NotFound`` or
-  ``repoze.bfg.exceptions.Forbidden`` error is raised from within a
-  custom root factory or the ``factory`` of a route, the appropriate
-  response is now sent to the requesting user agent (the result of the
-  notfound view or the forbidden view, respectively).  When these
-  errors are raised from within a root factory, the ``context`` passed
-  to the notfound or forbidden view will be ``None``.  Also, the
-  request will not be decorated with ``view_name``, ``subpath``,
-  ``context``, etc. as would normally be the case if traversal had
-  been allowed to take place.
-
-Internals
----------
-
-- The exception class representing the error raised by various methods
-  of a ``Configurator`` is now importable as
-  ``repoze.bfg.exceptions.ConfigurationError``.
-
-Documentation
--------------
-
-- General documentation freshening which takes imperative
-  configuration into account in more places and uses glossary
-  references more liberally.
-
-- Remove explanation of changing the request type in a new request
-  event subscriber, as other predicates are now usually an easier way
-  to get this done.
-
-- Added "Thread Locals" narrative chapter to documentation, and added
-  a API chapter documenting the ``repoze.bfg.threadlocals`` module.
-
-- Added a "Special Exceptions" section to the "Views" narrative
-  documentation chapter explaining the effect of raising
-  ``repoze.bfg.exceptions.NotFound`` and
-  ``repoze.bfg.exceptions.Forbidden`` from within view code.
-
-Dependencies
-------------
-
-- A new dependency on the ``twill`` package was added to the
-  ``setup.py`` ``tests_require`` argument (Twill will only be
-  downloaded when ``repoze.bfg`` ``setup.py test`` or ``setup.py
-  nosetests`` is invoked).
-
-1.2a4 (2009-12-07)
-==================
-
-Features
---------
-
-- ``repoze.bfg.testing.DummyModel`` now accepts a new constructor
-  keyword argument: ``__provides__``.  If this constructor argument is
-  provided, it should be an interface or a tuple of interfaces.  The
-  resulting model will then provide these interfaces (they will be
-  attached to the constructed model via
-  ``zope.interface.alsoProvides``).
-
-Bug Fixes
----------
-
-- Operation on GAE was broken, presumably because the
-  ``repoze.bfg.configuration`` module began to attempt to import the
-  ``repoze.bfg.chameleon_zpt`` and ``repoze.bfg.chameleon_text``
-  modules, and these cannot be used on non-CPython platforms.  It now
-  tolerates startup time import failures for these modules, and only
-  raise an import error when a template from one of these packages is
-  actually used.
-
-1.2a3 (2009-12-02)
-==================
-
-Bug Fixes
----------
-
-- The ``repoze.bfg.url.route_url`` function inappropriately passed
-  along ``_query`` and/or ``_anchor`` arguments to the
-  ``mapper.generate`` function, resulting in blowups.
-
-- When two views were registered with differering ``for`` interfaces
-  or classes, and the ``for`` of first view registered was a
-  superclass of the second, the ``repoze.bfg`` view machinery would
-  incorrectly associate the two views with the same "multiview".
-  Multiviews are meant to be collections of views that have *exactly*
-  the same for/request/viewname values, without taking inheritance
-  into account.  Symptom: wrong view callable found even when you had
-  correctly specified a ``for_`` interface/class during view
-  configuration for one or both view configurations.
-
-Backwards Incompatibilities
----------------------------
-
-- The ``repoze.bfg.templating`` module has been removed; it had been
-  deprecated in 1.1 and never actually had any APIs in it.
-
-1.2a2 (2009-11-29)
-==================
-
-Bug Fixes
----------
-
-- The the long description of this package (as shown on PyPI) was not
-  valid reStructuredText, and so was not renderable.
-
-- Trying to use an HTTP method name string such as ``GET`` as a
-  ``request_type`` predicate argument caused a startup time failure
-  when it was encountered in imperative configuration or in a
-  decorator (symptom: ``Type Error: Required specification must be a
-  specification``).  This now works again, although ``request_method``
-  is now the preferred predicate argument for associating a view
-  configuration with an HTTP request method.
-
-Documentation
--------------
-
-- Fixed "Startup" narrative documentation chapter; it was explaining
-  "the old way" an application constructor worked.
-
-1.2a1 (2009-11-28)
-==================
-
-Features
---------
-
-- An imperative configuration mode.
-
-  A ``repoze.bfg`` application can now begin its life as a single
-  Python file.  Later, the application might evolve into a set of
-  Python files in a package.  Even later, it might start making use of
-  other configuration features, such as ``ZCML``.  But neither the use
-  of a package nor the use of non-imperative configuration is required
-  to create a simple ``repoze.bfg`` application any longer.
-
-  Imperative configuration makes ``repoze.bfg`` competetive with
-  "microframeworks" such as `Bottle <http://bottle.paws.de/>`_ and
-  `Tornado <http://www.tornadoweb.org/>`_.  ``repoze.bfg`` has a good
-  deal of functionality that most microframeworks lack, so this is
-  hopefully a "best of both worlds" feature.
-
-  The simplest possible ``repoze.bfg`` application is now::
-
-     from webob import Response
-     from wsgiref import simple_server
-     from repoze.bfg.configuration import Configurator
-
-     def hello_world(request):
-         return Response('Hello world!')
-
-     if __name__ == '__main__':
-         config = Configurator()
-         config.add_view(hello_world)
-         app = config.make_wsgi_app()
-         simple_server.make_server('', 8080, app).serve_forever()
-
-- A new class now exists: ``repoze.bfg.configuration.Configurator``.
-  This class forms the basis for sharing machinery between
-  "imperatively" configured applications and traditional
-  declaratively-configured applications.
-
-- The ``repoze.bfg.testing.setUp`` function now accepts three extra
-  optional keyword arguments: ``registry``, ``request`` and
-  ``hook_zca``.
-
-  If the ``registry`` argument is not ``None``, the argument will be
-  treated as the registry that is set as the "current registry" (it
-  will be returned by ``repoze.bfg.threadlocal.get_current_registry``)
-  for the duration of the test.  If the ``registry`` argument is
-  ``None`` (the default), a new registry is created and used for the
-  duration of the test.
-
-  The value of the ``request`` argument is used as the "current
-  request" (it will be returned by
-  ``repoze.bfg.threadlocal.get_current_request``) for the duration of
-  the test; it defaults to ``None``.
-
-  If ``hook_zca`` is ``True`` (the default), the
-  ``zope.component.getSiteManager`` function will be hooked with a
-  function that returns the value of ``registry`` (or the
-  default-created registry if ``registry`` is ``None``) instead of the
-  registry returned by ``zope.component.getGlobalSiteManager``,
-  causing the Zope Component Architecture API (``getSiteManager``,
-  ``getAdapter``, ``getUtility``, and so on) to use the testing
-  registry instead of the global ZCA registry.
-
-- The ``repoze.bfg.testing.tearDown`` function now accepts an
-  ``unhook_zca`` argument.  If this argument is ``True`` (the
-  default), ``zope.component.getSiteManager.reset()`` will be called.
-  This will cause the result of the ``zope.component.getSiteManager``
-  function to be the global ZCA registry (the result of
-  ``zope.component.getGlobalSiteManager``) once again.
-
-- The ``run.py`` module in various ``repoze.bfg`` ``paster`` templates
-  now use a ``repoze.bfg.configuration.Configurator`` class instead of
-  the (now-legacy) ``repoze.bfg.router.make_app`` function to produce
-  a WSGI application.
-
-Documentation
--------------
-
-- The documentation now uses the "request-only" view calling
-  convention in most examples (as opposed to the ``context, request``
-  convention).  This is a documentation-only change; the ``context,
-  request`` convention is also supported and documented, and will be
-  "forever".
-
-- ``repoze.bfg.configuration`` API documentation has been added.
-
-- A narrative documentation chapter entitled "Creating Your First
-  ``repoze.bfg`` Application" has been added.  This chapter details
-  usage of the new ``repoze.bfg.configuration.Configurator`` class,
-  and demonstrates a simplified "imperative-mode" configuration; doing
-  ``repoze.bfg`` application configuration imperatively was previously
-  much more difficult.
-
-- A narrative documentation chapter entitled "Configuration,
-  Decorations and Code Scanning" explaining ZCML- vs. imperative-
-  vs. decorator-based configuration equivalence.
-
-- The "ZCML Hooks" chapter has been renamed to "Hooks"; it documents
-  how to override hooks now via imperative configuration and ZCML.
-
-- The explanation about how to supply an alternate "response factory"
-  has been removed from the "Hooks" chapter.  This feature may be
-  removed in a later release (it still works now, it's just not
-  documented).
-
-- Add a section entitled "Test Set Up and Tear Down" to the
-  unittesting chapter.
-
-Bug Fixes
-----------
-
-- The ACL authorization policy debugging output when
-  ``debug_authorization`` console debugging output was turned on
-  wasn't as clear as it could have been when a view execution was
-  denied due to an authorization failure resulting from the set of
-  principals passed never having matched any ACE in any ACL in the
-  lineage.  Now in this case, we report ``<default deny>`` as the ACE
-  value and either the root ACL or ``<No ACL found on any object in
-  model lineage>`` if no ACL was found.
-
-- When two views were registered with the same ``accept`` argument,
-  but were otherwise registered with the same arguments, if a request
-  entered the application which had an ``Accept`` header that accepted
-  *either* of the media types defined by the set of views registered
-  with predicates that otherwise matched, a more or less "random" one
-  view would "win".  Now, we try harder to use the view callable
-  associated with the view configuration that has the most specific
-  ``accept`` argument.  Thanks to Alberto Valverde for an initial
-  patch.
-
-Internals
----------
-
-- The routes mapper is no longer a root factory wrapper.  It is now
-  consulted directly by the router.
-
-- The ``repoze.bfg.registry.make_registry`` callable has been removed.
-
-- The ``repoze.bfg.view.map_view`` callable has been removed.
-
-- The ``repoze.bfg.view.owrap_view`` callable has been removed.
-
-- The ``repoze.bfg.view.predicate_wrap`` callable has been removed.
-
-- The ``repoze.bfg.view.secure_view`` callable has been removed.
-
-- The ``repoze.bfg.view.authdebug_view`` callable has been removed.
-
-- The ``repoze.bfg.view.renderer_from_name`` callable has been
-  removed.  Use ``repoze.bfg.configuration.Configurator.renderer_from_name``
-  instead (still not an API, however).
-
-- The ``repoze.bfg.view.derive_view`` callable has been removed.  Use
-  ``repoze.bfg.configuration.Configurator.derive_view`` instead (still
-  not an API, however).
-
-- The ``repoze.bfg.settings.get_options`` callable has been removed.
-  Its job has been subsumed by the ``repoze.bfg.settings.Settings``
-  class constructor.
-
-- The ``repoze.bfg.view.requestonly`` function has been moved to
-  ``repoze.bfg.configuration.requestonly``.
-
-- The ``repoze.bfg.view.rendered_response`` function has been moved to
-  ``repoze.bfg.configuration.rendered_response``.
-
-- The ``repoze.bfg.view.decorate_view`` function has been moved to
-  ``repoze.bfg.configuration.decorate_view``.
-
-- The ``repoze.bfg.view.MultiView`` class has been moved to
-  ``repoze.bfg.configuration.MultiView``.
-
-- The ``repoze.bfg.zcml.Uncacheable`` class has been removed.
-
-- The ``repoze.bfg.resource.resource_spec`` function has been removed.
-
-- All ZCML directives which deal with attributes which are paths now
-  use the ``path`` method of the ZCML context to resolve a relative
-  name to an absolute one (imperative configuration requirement).
-
-- The ``repoze.bfg.scripting.get_root`` API now uses a 'real' WebOb
-  request rather than a FakeRequest when it sets up the request as a
-  threadlocal.
-
-- The ``repoze.bfg.traversal.traverse`` API now uses a 'real' WebOb
-  request rather than a FakeRequest when it calls the traverser.
-
-- The ``repoze.bfg.request.FakeRequest`` class has been removed.
-
-- Most uses of the ZCA threadlocal API (the ``getSiteManager``,
-  ``getUtility``, ``getAdapter``, ``getMultiAdapter`` threadlocal API)
-  have been removed from the core.  Instead, when a threadlocal is
-  necessary, the core uses the
-  ``repoze.bfg.threadlocal.get_current_registry`` API to obtain the
-  registry.
-
-- The internal ILogger utility named ``repoze.bfg.debug`` is now just
-  an IDebugLogger unnamed utility.  A named utility with the old name
-  is registered for b/w compat.
-
-- The ``repoze.bfg.interfaces.ITemplateRendererFactory`` interface was
-  removed; it has become unused.
-
-- Instead of depending on the ``martian`` package to do code scanning,
-  we now just use our own scanning routines.
-
-- We now no longer have a dependency on ``repoze.zcml`` package;
-  instead, the ``repoze.bfg`` package includes implementations of the
-  ``adapter``, ``subscriber`` and ``utility`` directives.
-
-- Relating to the following functions:
-
-  ``repoze.bfg.view.render_view``
-
-  ``repoze.bfg.view.render_view_to_iterable``
-
-  ``repoze.bfg.view.render_view_to_response``
-
-  ``repoze.bfg.view.append_slash_notfound_view``
-
-  ``repoze.bfg.view.default_notfound_view``
-
-  ``repoze.bfg.view.default_forbidden_view``
-
-  ``repoze.bfg.configuration.rendered_response``
-
-  ``repoze.bfg.security.has_permission``
-
-  ``repoze.bfg.security.authenticated_userid``
-
-  ``repoze.bfg.security.effective_principals``
-
-  ``repoze.bfg.security.view_execution_permitted``
-
-  ``repoze.bfg.security.remember``
-
-  ``repoze.bfg.security.forget``
-
-  ``repoze.bfg.url.route_url``
-
-  ``repoze.bfg.url.model_url``
-
-  ``repoze.bfg.url.static_url``
-
-  ``repoze.bfg.traversal.virtual_root``
-
-  Each of these functions now expects to be called with a request
-  object that has a ``registry`` attribute which represents the
-  current ``repoze.bfg`` registry.  They fall back to obtaining the
-  registry from the threadlocal API.
-
-Backwards Incompatibilites
---------------------------
-
-- Unit tests which use ``zope.testing.cleanup.cleanUp`` for the
-  purpose of isolating tests from one another may now begin to fail
-  due to lack of isolation between tests.
-
-  Here's why: In repoze.bfg 1.1 and prior, the registry returned by
-  ``repoze.bfg.threadlocal.get_current_registry`` when no other
-  registry had been pushed on to the threadlocal stack was the
-  ``zope.component.globalregistry.base`` global registry (aka the
-  result of ``zope.component.getGlobalSiteManager()``).  In repoze.bfg
-  1.2+, however, the registry returned in this situation is the new
-  module-scope ``repoze.bfg.registry.global_registry`` object.  The
-  ``zope.testing.cleanup.cleanUp`` function clears the
-  ``zope.component.globalregistry.base`` global registry
-  unconditionally.  However, it does not know about the
-  ``repoze.bfg.registry.global_registry`` object, so it does not clear
-  it.
-
-  If you use the ``zope.testing.cleanup.cleanUp`` function in the
-  ``setUp`` of test cases in your unit test suite instead of using the
-  (more correct as of 1.1) ``repoze.bfg.testing.setUp``, you will need
-  to replace all calls to ``zope.testing.cleanup.cleanUp`` with a call
-  to ``repoze.bfg.testing.setUp``.
-
-  If replacing all calls to ``zope.testing.cleanup.cleanUp`` with a
-  call to ``repoze.bfg.testing.setUp`` is infeasible, you can put this
-  bit of code somewhere that is executed exactly **once** (*not* for
-  each test in a test suite; in the `` __init__.py`` of your package
-  or your package's ``tests`` subpackage would be a reasonable
-  place)::
-
-    import zope.testing.cleanup
-    from repoze.bfg.testing import setUp
-    zope.testing.cleanup.addCleanUp(setUp)
-
-- When there is no "current registry" in the
-  ``repoze.bfg.threadlocal.manager`` threadlocal data structure (this
-  is the case when there is no "current request" or we're not in the
-  midst of a ``r.b.testing.setUp``-bounded unit test), the ``.get``
-  method of the manager returns a data structure containing a *global*
-  registry.  In previous releases, this function returned the global
-  Zope "base" registry: the result of
-  ``zope.component.getGlobalSiteManager``, which is an instance of the
-  ``zope.component.registry.Component`` class.  In this release,
-  however, the global registry returns a globally importable instance
-  of the ``repoze.bfg.registry.Registry`` class.  This registry
-  instance can always be imported as
-  ``repoze.bfg.registry.global_registry``.
-
-  Effectively, this means that when you call
-  ``repoze.bfg.threadlocal.get_current_registry`` when no request or
-  ``setUp`` bounded unit test is in effect, you will always get back
-  the global registry that lives in
-  ``repoze.bfg.registry.global_registry``.  It also means that
-  ``repoze.bfg`` APIs that *call* ``get_current_registry`` will use
-  this registry.
-
-  This change was made because ``repoze.bfg`` now expects the registry
-  it uses to have a slightly different API than a bare instance of
-  ``zope.component.registry.Components``.
-
-- View registration no longer registers a
-  ``repoze.bfg.interfaces.IViewPermission`` adapter (it is no longer
-  checked by the framework; since 1.1, views have been responsible for
-  providing their own security).
-
-- The ``repoze.bfg.router.make_app`` callable no longer accepts the
-  ``authentication_policy`` nor the ``authorization_policy``
-  arguments.  This feature was deprecated in version 1.0 and has been
-  removed.
-
-- Obscure: the machinery which configured views with a
-  ``request_type`` *and* a ``route_name`` would ignore the request
-  interface implied by ``route_name`` registering a view only for the
-  interface implied by ``request_type``.  In the unlikely event that
-  you were trying to use these two features together, the symptom
-  would have been that views that named a ``request_type`` but which
-  were also associated with routes were not found when the route
-  matched.  Now if a view is configured with both a ``request_type``
-  and a ``route_name``, an error is raised.
-
-- The ``route`` ZCML directive now no longer accepts the
-  ``request_type`` or ``view_request_type`` attributes.  These
-  attributes didn't actually work in any useful way (see entry above
-  this one).
-
-- Because the ``repoze.bfg`` package now includes implementations of
-  the ``adapter``, ``subscriber`` and ``utility`` ZCML directives, it
-  is now an error to have ``<include package="repoze.zcml"
-  file="meta.zcml"/>`` in the ZCML of a ``repoze.bfg`` application.  A
-  ZCML conflict error will be raised if your ZCML does so.  This
-  shouldn't be an issue for "normal" installations; it has always been
-  the responsibility of the ``repoze.bfg.includes`` ZCML to include
-  this file in the past; it now just doesn't.
-
-- The ``repoze.bfg.testing.zcml_configure`` API was removed.  Use
-  the ``Configurator.load_zcml`` API instead.
-
-Deprecations
-------------
-
-- The ``repoze.bfg.router.make_app`` function is now nominally
-  deprecated.  Its import and usage does not throw a warning, nor will
-  it probably ever disappear.  However, using a
-  ``repoze.bfg.configuration.Configurator`` class is now the preferred
-  way to generate a WSGI application.
-
-  Note that ``make_app`` calls
-  ``zope.component.getSiteManager.sethook(
-  repoze.bfg.threadlocal.get_current_registry)`` on the caller's
-  behalf, hooking ZCA global API lookups, for backwards compatibility
-  purposes.  If you disuse ``make_app``, your calling code will need
-  to perform this call itself, at least if your application uses the
-  ZCA global API (``getSiteManager``, ``getAdapter``, etc).
-
-Dependencies
-------------
-
-- A dependency on the ``martian`` package has been removed (its
-  functionality is replaced internally).
-
-- A dependency on the ``repoze.zcml`` package has been removed (its
-  functionality is replaced internally).
-
+- Exception view documentation was added to the ``Hooks`` narrative
+  chapter.