prep for 1.3a4

Chris McDonough

2010-07-04 4dc529e4bbc36b7e5e2bd3ea199a7929e407a267

 CHANGES.txt

@@ -1,957 +1,338 @@
Next release
============
1.3a4 (2010-07-03)
==================

Features
--------

- Undocumented hook: make ``get_app`` and ``get_root`` of the
  ``repoze.bfg.paster.BFGShellCommand`` hookable in cases where
  endware may interfere with the default versions.

- In earlier versions, a custom route predicate associated with a url
  dispatch route (each of the predicate functions fed to the
  ``custom_predicates`` argument of
  ``repoze.bfg.configuration.Configurator.add_route``) has always
  required a 2-positional argument signature, e.g. ``(context,
  request)``.  Before this release, the ``context`` argument was
  always ``None``.

  As of this release, the first argument passed to a predicate is now
  a dictionary conventionally named ``info`` consisting of ``route``,
  and ``match``.  ``match`` is a dictionary: it represents the
  arguments matched in the URL by the route.  ``route`` is an object
  representing the route which was matched.

  This is useful when predicates need access to the route match.  For
  example::

    def any_of(segment_name, *args):
        def predicate(info, request):
            if info['match'][segment_name] in args:
                return True
        return predicate

    num_one_two_or_three = any_of('num, 'one', 'two', 'three')

    add_route('num', '/:num', custom_predicates=(num_one_two_or_three,))

  The ``route`` object is an object that has two useful attributes:
  ``name`` and ``path``.  The ``name`` attribute is the route name.
  The ``path`` attribute is the route pattern.  An example of using
  the route in a set of route predicates::

    def twenty_ten(info, request):
        if info['route'].name in ('ymd', 'ym', 'y'):
            return info['match']['year'] == '2010'

    add_route('y', '/:year', custom_predicates=(twenty_ten,))
    add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,))
    add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,))

- The ``repoze.bfg.url.route_url`` API has changed.  If a keyword
  ``_app_url`` is present in the arguments passed to ``route_url``,
  this value will be used as the protocol/hostname/port/leading path
  prefix of the generated URL.  For example, using an ``_app_url`` of
  ``http://example.com:8080/foo`` would cause the URL
  ``http://example.com:8080/foo/fleeb/flub`` to be returned from this
  function if the expansion of the route pattern associated with the
  ``route_name`` expanded to ``/fleeb/flub``.

- It is now possible to use a URL as the ``name`` argument fed to
  ``repoze.bfg.configuration.Configurator.add_static_view``.  When the
  name argument is a URL, the ``repoze.bfg.url.static_url`` API will
  generate join this URL (as a prefix) to a path including the static
  file name.  This makes it more possible to put static media on a
  separate webserver for production, while keeping static media
  package-internal and served by the development webserver during
  development.

Documentation
-------------

- Update GAE tutorial to use Chameleon instead of Jinja2 (now that
  it's possible).
- The authorization chapter of the ZODB Wiki Tutorial
  (docs/tutorials/bfgwiki) was changed to demonstrate authorization
  via a group rather than via a direct username (thanks to Alex
  Marandon).

Bug Fixes
---------
- The authorization chapter of the SQLAlchemy Wiki Tutorial
  (docs/tutorials/bfgwiki2) was changed to demonstrate authorization
  via a group rather than via a direct username.

- Ensure that ``secure`` flag for AuthTktAuthenticationPolicy
  constructor does what it's documented to do (merge Daniel Holth's
  fancy-cookies-2 branch).
- Redirect requests for tutorial sources to
  http://docs.repoze.org/bfgwiki-1.3 and
  http://docs.repoze.org/bfgwiki2-1.3/ respectively.

Features
--------
- A section named ``Custom Route Predicates`` was added to the URL
  Dispatch narrative chapter.

- 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).
- The Static Resources chapter has been updated to mention using
  ``static_url`` to generate URLs to external webservers.

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.
- Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new
  abstraction revolving around the (still-internal)
  ``repoze.bfg.static.StaticURLInfo`` helper class.

1.2b2 (2010-01-21)
1.3a3 (2010-05-01)
==================

Bug Fixes
---------
Paster Templates
----------------

- 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.
- The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer
  register a ``handle_teardown`` event listener which calls
  ``DBSession.remove``.  This was found by Chris Withers to be
  unnecessary.

Documentation
-------------

- Change renderings of ZCML directive documentation.
- The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation
  was changed to remove the ``handle_teardown`` event listener which
  calls ``DBSession.remove``.

- Add a narrative documentation chapter: "Using the Zope Component
  Architecture in repoze.bfg".
- Any mention of the ``handle_teardown`` event listener as used by the
  paster templates was removed from the URL Dispatch narrative chapter.

Dependencies
------------
- A section entitled Detecting Available Languages was added to the
  i18n narrative docs chapter.

- 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)
1.3a2 (2010-04-28)
==================

Features
--------

- Add a ``**kw`` arg to the ``Configurator.add_settings`` API.
- A locale negotiator no longer needs to be registered explicitly. The
  default locale negotiator at
  ``repoze.bfg.i18n.default_locale_negotiator`` is now used
  unconditionally as... um, the default locale negotiator.

- Add ``hook_zca`` and ``unhook_zca`` methods to the ``Configurator``
  API.
- The default locale negotiator has become more complex.

- The ``repoze.bfg.testing.setUp`` method now returns a
  ``Configurator`` instance which can be used to do further
  configuration during unit tests.
  * First, the negotiator looks for the ``_LOCALE_`` attribute of
    the request object (possibly set by a view or an event listener).
  
  * Then it looks for the ``request.params['_LOCALE_']`` value.

Bug Fixes
---------

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

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

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

- Added a description of imperative configuration in various places
  which only described ZCML configuration.

- A syntactical refreshing of various tutorials.

- Added the ``repoze.bfg.authentication``,
  ``repoze.bfg.authorization``, and ``repoze.bfg.interfaces`` modules
  to API documentation.

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.

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

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.
  * Then it looks for the ``request.cookies['_LOCALE_']`` value.

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.
- The default locale negotiator now looks for the parameter named
  ``_LOCALE_`` rather than a parameter named ``locale`` in
  ``request.params``.

1.2a2 (2009-11-29)
==================
Behavior Changes
----------------

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.
- A locale negotiator may now return ``None``, signifying that the
  default locale should be used.

Documentation
-------------

- Fixed "Startup" narrative documentation chapter; it was explaining
  "the old way" an application constructor worked.
- Documentation concerning locale negotiation in the
  Internationalizationa and Localization chapter was updated.

1.2a1 (2009-11-28)
- Expanded portion of i18n narrative chapter docs which discuss
  working with gettext files.

1.3a1 (2010-04-26)
==================

Features
--------

- An imperative configuration mode.
- Added "exception views".  When you use an exception (anything that
  inherits from the Python ``Exception`` builtin) as view context
  argument, e.g.::

  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.
      from repoze.bfg.view import bfg_view
      from repoze.bfg.exceptions import NotFound
      from webob.exc import HTTPNotFound

  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.
      @bfg_view(context=NotFound)
      def notfound_view(request):
          return HTTPNotFound()

  The simplest possible ``repoze.bfg`` application is now::
  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 will be invoked and its response
  returned.

     from webob import Response
     from wsgiref import simple_server
     from repoze.bfg.configuration import Configurator
  Other normal view predicates can also be used in combination with an
  exception view registration::

     def hello_world(request):
         return Response('Hello world!')
      from repoze.bfg.view import bfg_view
      from repoze.bfg.exceptions import NotFound
      from webob.exc import HTTPNotFound

     if __name__ == '__main__':
         config = Configurator()
         config.add_view(hello_world)
         app = config.make_wsgi_app()
         simple_server.make_server('', 8080, app).serve_forever()
      @bfg_view(context=NotFound, route_name='home')
      def notfound_view(request):
          return HTTPNotFound()

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

- The ``repoze.bfg.testing.setUp`` function now accepts three extra
  optional keyword arguments: ``registry``, ``request`` and
  ``hook_zca``.
  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.

  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 feature can be used with any view registration mechanism
  (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view``
  styles).

  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``.
  This feature was kindly contributed by Andrey Popp.

  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.
- Use "Venusian" (`http://docs.repoze.org/venusian
  <http://docs.repoze.org/venusian>`_) to perform ``bfg_view``
  decorator scanning rather than relying on a BFG-internal decorator
  scanner.  (Truth be told, Venusian is really just a generalization
  of the BFG-internal decorator scanner).

- 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.
- Internationalization and localization features as documented in the
  narrative documentation chapter entitled ``Internationalization and
  Localization``.

- 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.
- A new deployment setting named ``default_locale_name`` was added.
  If this string is present as a Paster ``.ini`` file option, it will
  be considered the default locale name.  The default locale name is
  used during locale-related operations such as language translation.

Documentation
-------------
- It is now possible to turn on Chameleon template "debugging mode"
  for all Chameleon BFG templates by setting a BFG-related Paster
  ``.ini`` file setting named ``debug_templates``. The exceptions
  raised by Chameleon templates when a rendering fails are sometimes
  less than helpful.  ``debug_templates`` allows you to configure your
  application development environment so that exceptions generated by
  Chameleon during template compilation and execution will contain
  more helpful debugging information.  This mode is on by default in
  all new projects.

- 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".
- Add a new method of the Configurator named ``derive_view`` which can
  be used to generate a BFG view callable from a user-supplied
  function, instance, or class. This useful for external framework and
  plugin authors wishing to wrap callables supplied by their users
  which follow the same calling conventions and response conventions
  as objects that can be supplied directly to BFG as a view callable.
  See the ``derive_view`` method in the
  ``repoze.bfg.configuration.Configurator`` docs.

- ``repoze.bfg.configuration`` API documentation has been added.
ZCML
----

- 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.
- Add a ``translationdir`` ZCML directive to support localization.

- 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.
- Add a ``localenegotiator`` ZCML directive to support localization.

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

Dependencies
------------

- A dependency on the ``martian`` package has been removed (its
  functionality is replaced internally).
- A new install-time dependency on the ``venusian`` distribution was
  added.

- A dependency on the ``repoze.zcml`` package has been removed (its
  functionality is replaced internally).
- A new install-time dependency on the ``translationstring``
  distribution was added.

- Chameleon 1.2.3 or better is now required (internationalization and
  per-template debug settings).

Internal
--------

- View registrations and lookups are now done with three "requires"
  arguments instead of two to accomodate orthogonality of exception
  views.

- The ``repoze.bfg.interfaces.IForbiddenView`` and
  ``repoze.bfg.interfaces.INotFoundView`` interfaces were removed;
  they weren't APIs and they became vestigial with the addition of
  exception views.

- Remove ``repoze.bfg.compat.pkgutil_26.py`` and import alias
  ``repoze.bfg.compat.walk_packages``.  These were only required by
  internal scanning machinery; Venusian replaced the internal scanning
  machinery, so these are no longer required.

Documentation
-------------

- Exception view documentation was added to the ``Hooks`` narrative
  chapter.

- A new narrative chapter entitled ``Internationalization and
  Localization`` was added.

- The "Environment Variables and ``ini`` File Settings" chapter was
  changed: documentation about the ``default_locale_name`` setting was
  added.

- A new API chapter for the ``repoze.bfg.i18n`` module was added.

- Documentation for the new ``translationdir`` and
  ``localenegotiator`` ZCML directives were added.

- A section was added to the Templates chapter entitled "Nicer
  Exceptions in Templates" describing the result of setting
  ``debug_templates = true``.

Paster Templates
----------------

- All paster templates now create a ``setup.cfg`` which includes
  commands related to nose testing and Babel message catalog
  extraction/compilation.

- A ``default_locale_name = en`` setting was added to each existing paster
  template.

- A ``debug_templates = true`` setting was added to each existing
  paster template.

Licensing
---------

- The Edgewall (BSD) license was added to the LICENSES.txt file, as
  some code in the ``repoze.bfg.i18n`` derives from Babel source.