path: root/docs/whatsnew-1.3.rst

What's New In :mod:`repoze.bfg` 1.3
===================================

This article explains the new features in :mod:`repoze.bfg` version
1.3 as compared to the previous 1.2 release.  It also documents
backwards incompatibilities between the two versions and deprecations
added to 1.3, as well as software dependency changes and notable
documentation additions.

Major Feature Additions
-----------------------

The major feature additions in 1.3 are:

- *Internationalization* (i18n) and *localization* (l10n) services

- *Exception views*

Internationalization and Localization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:mod:`repoze.bfg` 1.3 offers internationalization (i18n) and
localization (l10n) subsystems that can be used to translate the text
of buttons, the text of error messages and other software- and
template-defined values into the native language of a user of your
application.

:mod:`repoze.bfg` i18n / l10n framework includes:

- Support for :term:`translation string` specifications.

- Tools allowing you to specify and work with :term:`gettext`
  :term:`message catalog` files to allow for text translation.

- :term:`Locale name` negotiation features.

- Translation and pluralization services.

For detailed documentation about :mod:`repoze.bfg`
internationalization and localization features, see
:ref:`i18n_chapter`.

Exception Views
~~~~~~~~~~~~~~~~

In :mod:`repoze.bfg` 1.3+, when you use an exception (anything that
inherits from the Python :exc:`Exception` builtin) as view context
argument, e.g.:

.. code-block:: python
   :linenos:

      from repoze.bfg.view import bfg_view
      from repoze.bfg.exceptions import NotFound
      from webob.exc import HTTPNotFound

      @bfg_view(context=NotFound)
      def notfound_view(request):
          return HTTPNotFound()

For the above example, when the :exc:`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.

Other normal view predicates can also be used in combination with an
exception view registration:

.. code-block:: python
   :linenos:

      from repoze.bfg.view import bfg_view
      from repoze.bfg.exceptions import NotFound
      from webob.exc import HTTPNotFound

      @bfg_view(context=NotFound, route_name='home')
      def notfound_view(request):
          return HTTPNotFound()

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

Existing (pre-1.3) normal views registered against objects inheriting
from :class:`Exception` will continue to work.  Exception views used
for user-defined exceptions and system exceptions used as contexts
will also work.

The feature can be used with any view registration mechanism
(``@bfg_view`` decorator, ZCML, or imperative
:meth:`repoze.bfg.configuration.Configurator.add_view` styles).

This feature was kindly contributed by Andrey Popp.

Minor Feature Additions
-----------------------

- Use :term:`Venusian` to perform ``@bfg_view`` decorator scanning
  rather than relying on a BFG-internal decorator scanner.  This means
  that user-defined decorators can be defined and found during
  :mod:`repoze.bfg` scanning.  See
  :ref:`registering_configuration_decorators` for more information.

- 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
  newly generated projects.  See also :ref:`debug_templates_section`.

- A new API method named
  :meth:`repoze.bfg.configuration.Configurator.derive_view` was
  added. This API 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.

- Prior to 1.3, a *route predicate* had no access to route pattern
  matching information and had no way to know which route was matched.
  As of 1.3a4, each of the predicate callables fed to the
  ``custom_predicates`` argument of
  :meth:`repoze.bfg.configuration.Configurator.add_route` or the
  ``custom_predicates`` ZCML attribute can be a callable accepting two
  arguments.  The first argument passed to a custom predicate is a
  dictionary conventionally named ``info``.  The second argument is
  the current :term:`request` object.  The ``info`` dictionary has a
  number of contained values: ``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.  See also
  :ref:`custom_route_predicates`.  In prior versions, the ``info``
  argument was always ``None``.

- The :func:`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
  :meth:`repoze.bfg.configuration.Configurator.add_static_view`.  When
  the name argument is a URL, the :func:`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.

- New argument to
  :class:`repoze.bfg.configuration.Configurator.add_route` and the
  ZCML ``route`` directive: ``traverse``.  If you would like to cause
  the :term:`context` to be something other than the :term:`root`
  object when this route matches, you can spell a traversal pattern as
  the ``traverse`` argument.  This traversal pattern will be used as
  the traversal path: traversal will begin at the root object implied
  by this route (either the global root, or the object returned by the
  ``factory`` associated with this route).  See
  :class:`repoze.bfg.configuration.Configurator.add_route` for more
  information (the ``traverse`` argument).

- A new method exists:
  :meth:`repoze.bfg.configuration.Configurator.set_request_factory`.
  If used, this method will set the factory used by the
  :mod:`repoze.bfg` router to create all request objects.

- The :class:`repoze.bfg.configuration.Configurator` constructor takes
  an additional argument: ``request_factory``.  If used, this argument
  will set the factory used by the :mod:`repoze.bfg` router to create
  all request objects.

- A new method exists
  :meth:`repoze.bfg.configuration.Configurator.set_renderer_globals_factory`.
  If used, this method will set the factory used by the
  :mod:`repoze.bfg` router to create renderer globals.

- A new method exists:
  :meth:`repoze.bfg.configuration.Configurator.get_settings`.  If
  used, this method will return the current settings object (performs
  the same job as the :func:`repoze.bfg.settings.get_settings` API).

- The :class:`repoze.bfg.configuration.Configurator` constructor takes
  an additional argument: ``renderer_globals_factory``.  If used, this
  argument will set the factory used by the :mod:`repoze.bfg` router
  to create renderer globals.

- Add :func:`repoze.bfg.renderers.render`,
  :func:`repoze.bfg.renderers.render_to_response` and
  :func:`repoze.bfg.renderers.get_renderer` functions.  These are
  imperative APIs which will use the same rendering machinery used by
  view configurations with a ``renderer=`` attribute/argument to
  produce a rendering or renderer.  Because these APIs provide a
  central API for all rendering, they now form the preferred way to
  perform imperative template rendering.  Using functions named
  ``render_*`` from modules such as :mod:`repoze.bfg.chameleon_zpt`
  and :mod:`repoze.bfg.chameleon_text` is now discouraged (although
  not deprecated).  The code the backing older
  templating-system-specific APIs now calls into the newer
  :mod:`repoze.bfg.renderer` code.

- The
  :meth:`repoze.bfg.configuration.Configurator.testing_add_template`
  method has been renamed to
  :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer`.
  A backwards compatibility alias is present using the old name.

- When decoding a URL segment to Unicode fails, the exception raised
  is now :exc:`repoze.bfg.exceptions.URLDecodeError` instead of
  :exc:`UnicodeDecodeError`.  This makes it possible to register an
  exception view invoked specifically when :mod:`repoze.bfg` cannot
  decode a URL.

- A :func:`repoze.bfg.events.subscriber` decorator was added.  This
  decorator can be used to decorates module-scope functions, which are
  then treated as event listeners after a scan() is performed.  See
  the :ref:`events_chapter` documentation chapter and the
  :mod:`repoze.bfg.events` module documentation for more information.

- The :func:`repoze.bfg.configuration.Configurator.add_route` API now
  returns the route object that was added.

- New API class:
  :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory`.

  There can only be one :term:`Not Found view` in any
  :mod:`repoze.bfg` application.  Even if you use
  :func:`repoze.bfg.view.append_slash_notfound_view` as the Not Found
  view, :mod:`repoze.bfg` still must generate a ``404 Not Found``
  response when it cannot redirect to a slash-appended URL; this not
  found response will be visible to site users.

  If you don't care what this 404 response looks like, and only you
  need redirections to slash-appended route URLs, you may use the
  :func:`repoze.bfg.view.append_slash_notfound_view` object as the Not
  Found view.  However, if you wish to use a *custom* notfound view
  callable when a URL cannot be redirected to a slash-appended URL,
  you may wish to use an instance of the
  :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory` class as the
  Not Found view, supplying a :term:`view callable` to be used as the
  custom notfound view as the first argument to its constructor.  For
  instance:

  .. code-block:: python

       from repoze.bfg.exceptions import NotFound
       from repoze.bfg.view import AppendSlashNotFoundViewFactory

       def notfound_view(context, request):
           return HTTPNotFound('It aint there, stop trying!')

       custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
       config.add_view(custom_append_slash, context=NotFound)

  The ``notfound_view`` supplied must adhere to the two-argument view
  callable calling convention of ``(context, request)`` (``context``
  will be the exception object).

- The :class:`repoze.bfg.configuration.Configurator` constructor now
  accepts a dotted name *string* to a package as a ``package``
  argument. The ``package`` argument was previously required to be a
  package *object* (not a dotted name string).

- The :meth:`repoze.bfg.configuration.Configurator.with_package`
  method was added.  This method returns a new Configurator using the
  same application registry as the configurator object it is called
  upon. The new configurator is created afresh with its ``package``
  constructor argument set to the value passed to ``with_package``.

- The :meth:`repoze.bfg.configuration.Configurator.maybe_dotted`
  method resolves a Python dotted name string supplied as its
  ``dotted`` argument to a global Python object.  If the value cannot
  be resolved, a :exc:`repoze.bfg.configuration.ConfigurationError` is
  raised.  If the value supplied as ``dotted`` is not a string, the
  value is returned unconditionally without any resolution attempted.

- The new
  :meth:`repoze.bfg.configuration.Configurator.absolute_resource_spec`
  method resolves a potentially relative :term:`resource
  specification` string into an absolute version.

- A new :meth:`repoze.bfg.request.Request.add_response_callback` API
  has been added.  It can be used to influence response values before
  a concrete response object has been created.  See the
  :ref:`using_response_callbacks` for more information.

- The :class:`repoze.bfg.interfaces.INewResponse` interface now
  includes a ``request`` attribute; as a result, a handler for
  INewResponse now has access to the request which caused the
  response.

- Each of the follow methods of the
  :class:`repoze.bfg.configuration.Configurator` now allow the
  below-named arguments to be passed as "dotted name strings"
  (e.g. "foo.bar.baz") rather than as actual implementation objects
  that must be imported:

  setup_registry
     root_factory, authentication_policy, authorization_policy,
     debug_logger, locale_negotiator, request_factory,
     renderer_globals_factory

  add_subscriber
     subscriber, iface

  derive_view
     view

  add_view
     view, ``for_``, context, request_type, containment

  add_route()
     view, view_for, factory, ``for_``, view_context

  scan
     package

  add_renderer
     factory

  set_forbidden_view
     view

  set_notfound_view
     view

  set_request_factory
     factory

  set_renderer_globals_factory()
     factory

  set_locale_negotiator
     negotiator

  testing_add_subscriber
     event_iface

- The argument to
  :meth:`repoze.bfg.configuration.Configurator.add_route` which was
  previously called ``path`` is now called ``pattern`` for better
  explicability.  For backwards compatibility purposes, passing a
  keyword argument named ``path`` to ``add_route`` will still work
  indefinitely.

- The ``path`` attribute to the ZCML ``route`` directive (see
  :ref:`route_directive`) is now named ``pattern`` for better
  explicability.  The older ``path`` attribute will continue to work
  indefinitely.

- The ``routesalchemy`` paster template has been updated to use
  ``pattern`` in its route declarations rather than ``path``.

- In support of making it easier to configure applications which are
  "secure by default", a default permission feature was added.  If
  supplied, the default permission is used as the permission string to
  all view registrations which don't otherwise name a permission.
  These APIs are in support of that:

  - A new constructor argument was added to
    :class:`repoze.bfg.configuration.Configurator`:
    ``default_permission``.

  - A new method was added:
    :meth:`repoze.bfg.configuration.Configurator.set_default_permission`.

  - A new ZCML directive was added: :ref:`default_permission_directive`.

- Add a new request API:
  :meth:`repoze.bfg.request.Request.add_finished_callback`.  Finished
  callbacks are called by the router unconditionally near the very end
  of request processing.  See the :ref:`using_finished_callbacks` for
  more information.

- A ``matched_route`` attribute is now added to the :term:`request`
  object when a route has matched.  Its value is the :term:`route`
  object that matched (see :class:`repoze.bfg.interfaces.IRoute` for
  the API of a route object).

- The ``exception`` attribute of the :term:`request` is now set
  slightly earlier and in a slightly different set of scenarios by the
  router, for benefit of "finished callbacks" and "response
  callbacks".  In previous versions, the ``exception`` attribute of
  the request was not set at all if an exception view was not found.
  In this version, the ``request.exception`` attribute is set
  immediately when an exception is caught by the router, even if an
  exception view could not be found.

- The :meth:`repoze.bfg.configuration.Configurator.add_route` method
  now accepts a ``pregenerator`` argument.  The pregenerator for the
  resulting route is called by :func:`repoze.bfg.url.route_url` in
  order to adjust the set of arguments passed to it by the user for
  special purposes, such as Pylons 'subdomain' support.  It will
  influence the URL returned by ``route_url``.  See
  :class:`repoze.bfg.interfaces.IRoutePregenerator` for more
  information.

- Compatibility with WebOb 1.0 (now requires WebOb >= 1.0).

- The :meth:`repoze.bfg.traversal.traversal_path` API now eagerly
  attempts to encode a Unicode ``path`` into ASCII before attempting
  to split it and decode its segments.  This is for convenience,
  effectively to allow a (stored-as-Unicode-in-a-database, or
  retrieved-as-Unicode-from-a-request-parameter) Unicode path to be
  passed to :meth:`repoze.bfg.traversal.find_model`, which eventually
  internally uses the ``traversal_path`` function under the hood.  In
  version 1.2 and prior, if the ``path`` was Unicode, that Unicode was
  split on slashes and each resulting segment value was Unicode.  An
  inappropriate call to the ``decode()`` method of a resulting Unicode
  path segment could cause a ``UnicodeDecodeError`` to occur even if
  the Unicode representation of the path contained no 'high order'
  characters (it effectively did a "double decode").  By converting
  the Unicode path argument to ASCII before we attempt to decode and
  split, genuine errors will occur in a more obvious place while also
  allowing us to handle (for convenience) the case that it's a Unicode
  representation formed entirely from ASCII-compatible characters.

Backwards Incompatibilities
---------------------------

- In previous releases, when a URL could not be decoded from UTF-8
  during traversal, a :exc:`TypeError` was raised.  Now the error
  which is raised is :exc:`repoze.bfg.exceptions.URLDecodeError`.

- A new internal exception class (*not* an API) named
  ``repoze.bfg.exceptions.PredicateMismatch`` now exists.  This
  exception is currently raised when no constituent view of a
  multiview can be called (due to no predicate match).  Previously, in
  this situation, a :exc:`repoze.bfg.exceptions.NotFound` exception
  was raised.  We provide backwards compatibility for code that
  expected a ``NotFound`` to be raised when no predicates match by
  causing ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from
  ``NotFound``.  This will cause any exception view registered for
  ``NotFound`` to be called when a predicate mismatch occurs, as was
  the previous behavior.

  There is however, one perverse case that will expose a backwards
  incompatibility.  If 1) you had a view that was registered as a
  member of a multiview 2) this view explicitly raised a ``NotFound``
  exception *in order to* proceed to the next predicate check in the
  multiview, that code will now behave differently: rather than
  skipping to the next view match, a NotFound will be raised to the
  top-level exception handling machinery instead.  For code to be
  depending upon the behavior of a view raising ``NotFound`` to
  proceed to the next predicate match, would be tragic, but not
  impossible, given that ``NotFound`` is a public interface.
  ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and
  cannot be depended upon by application code, so you should not
  change your view code to raise ``PredicateMismatch``.  Instead, move
  the logic which raised the ``NotFound`` exception in the view out
  into a custom view predicate.

- If, when you run your application's unit test suite under BFG 1.3, a
  ``KeyError`` naming a template or a ``ValueError`` indicating that a
  'renderer factory' is not registered may is raised
  (e.g. ``ValueError: No factory for renderer named '.pt' when looking
  up karl.views:templates/snippets.pt``), you may need to perform some
  extra setup in your test code.

  The best solution is to use the
  :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer`
  (or, alternately the deprecated
  :func:`repoze.bfg.testing.registerTemplateRenderer` or
  `repoze.bfg.testing.registerDummyRenderer`) API within the code
  comprising each individual unit test suite to register a "dummy"
  renderer for each of the templates and renderers used by code under
  test.  For example:

  .. code-block:: python

    config = Configurator()
    config.testing_add_renderer('karl.views:templates/snippets.pt')

  This will register a basic dummy renderer for this particular
  missing template.  The
  :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer`
  API actually *returns* the renderer, but if you don't care about how
  the render is used, you don't care about having a reference to it
  either.

  A more rough way to solve the issue exists.  It causes the "real"
  template implementations to be used while the system is under test,
  which is suboptimal, because tests will run slower, and unit tests
  won't actually *be* unit tests, but it is easier.  Always ensure you
  call the
  :meth:`repoze.bfg.configuration.Configurator.setup_registry`
  method.  For example:

  .. code-block:: python

    reg = MyRegistry()
    config = Configurator(registry=reg)
    config.setup_registry()

  Calling :meth:`repoze.bfg.configuration.Configurator.setup_registry`
  only has an effect if you're *passing in* a ``registry`` argument to
  the Configurator constructor.  ``setup_registry`` is called by the
  course of normal operations anyway if you do not pass in a
  ``registry``.

  If your test suite isn't using a Configurator yet, and is still
  using the older :mod:`repoze.bfg.testing` APIs name
  :func:`repoze.bfg.testng.setUp` or
  :func:`repoze.bfg.testng.cleanUp`, these will register the renderers
  on your behalf.

  A variant on the symptom for this theme exists: you may already be
  dutifully registering a dummy template or renderer for a template
  used by the code you're testing using
  :meth:`repoze.bfg.configuration.Configurator.testing_register_renderer`
  or :func:`repoze.bfg.testing.registerTemplateRenderer`, but (perhaps
  unbeknownst to you) the code under test expects to be able to use a
  "real" template renderer implementation to retrieve or render
  *another* template that you forgot was being rendered as a side
  effect of calling the code you're testing.  This happened to work
  because it found the *real* template while the system was under test
  previously, and now it cannot.  The solution is the same.

  It may also help reduce confusion to use a :term:`resource
  specification` to specify the template path in the test suite and
  code rather than a relative path in either.  A resource
  specification is unambiguous, while a relative path needs to be
  relative to "here", where "here" isn't always well-defined ("here"
  in a test suite may or may not be the same as "here" in the code
  under test).

- A bug existed in the regular expression to do URL matching.  As an
  example, the URL matching machinery would cause the pattern
  ``/{foo}`` to match the root URL ``/`` resulting in a match
  dictionary of ``{'foo':u''}`` or the pattern ``/{fud}/edit might
  match the URL ``//edit`` resulting in a match dictionary of
  ``{'fud':u''}``.  It was always the intent that ``:segment`` markers
  in the pattern would need to match *at least one* character, and
  never match the empty string.  This, however, means that in certain
  circumstances, a routing match which your application inadvertently
  depended upon may no longer happen.

- The router no longer sets the value ``wsgiorg.routing_args`` into
  the environ when a route matches. The value used to be something
  like ``((), matchdict)``.  This functionality was only ever
  obliquely referred to in change logs; it was never documented as an
  API.

- The ``exception`` attribute of the request now defaults to ``None``.
  In prior versions, the ``request.exception`` attribute did not exist
  if an exception was not raised by user code during request
  processing; it only began existence once an exception view was
  found.

- Due to changes introduced WebOb 1.0, the
  ``repoze.bfg.request.make_request_ascii`` event subscriber no longer
  worked, so it has been removed.  This subscriber was meant to be used
  in a deployment so that code written before BFG 0.7.0 could run
  unchanged.  At this point, such code will need to be rewritten to
  expect Unicode from ``request.GET``, ``request.POST`` and
  ``request.params`` or it will need to be changed to use
  ``request.str_POST``, ``request.str_GET`` and/or
  ``request.str_params`` instead of the non-``str`` versions of same,
  as the non-``str`` versions of the same APIs always now perform
  decoding to Unicode.

Deprecations and Behavior Differences
-------------------------------------

- The exception views feature replaces the need for the
  ``set_notfound_view`` and ``set_forbidden_view`` methods of the
  :class:`repoze.bfg.configuration.Configurator` as well as the
  :ref:`notfound_directive` and :ref:`forbidden_directive` ZCML
  directives.  Those methods and directives will continue to work for
  the foreseeable future, but they are deprecated in the
  documentation.

- The ``repoze.bfg.renderers.rendered_response`` function was never an
  official API, but may have been imported by extensions in the wild.
  It is officially deprecated in this release.  Use
  :func:`repoze.bfg.renderers.render_to_response` instead.

- The following APIs are *documentation* deprecated (meaning they are
  officially deprecated in documentation but do not raise a
  deprecation error upon their usage, and may continue to work for an
  indefinite period of time):

  In the :mod:`repoze.bfg.chameleon_zpt` module: ``get_renderer``,
  ``get_template``, ``render_template``,
  ``render_template_to_response``.  The suggested alternatives are
  documented within the docstrings of those methods (which are still
  present in the documentation).

  In the :mod:`repoze.bfg.chameleon_text` module: ``get_renderer``,
  ``get_template``, ``render_template``,
  ``render_template_to_response``.  The suggested alternatives are
  documented within the docstrings of those methods (which are still
  present in the documentation).

  In general, to perform template-related functions, one should now
  use the various methods in the :mod:`repoze.bfg.renderers` module.

- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event
  interface was renamed to
  :class:`repoze.bfg.interfaces.IApplicationCreated`.  Likewise, the
  ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed
  to :class:`repoze.bfg.events.ApplicationCreated`.  The older aliases
  will continue to work indefinitely.

- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was
  renamed to :class:`repoze.bfg.interfaces.IContextFound`.  Likewise,
  the ``repoze.bfg.events.AfterTraversal`` class was renamed to
  :class:`repoze.bfg.events.ContextFound`.  The older aliases will
  continue to work indefinitely.

- References to the WSGI environment values ``bfg.routes.matchdict``
  and ``bfg.routes.route`` were removed from documentation.  These
  will stick around internally for several more releases, but it is
  ``request.matchdict`` and ``request.matched_route`` are now the
  "official" way to obtain the matchdict and the route object which
  resulted in the match.

Dependency Changes
------------------

- A new install-time dependency on the ``venusian`` distribution was
  added.

- A new install-time dependency on the ``translationstring``
  distribution was added (internationalization).

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

- :mod:`repoze.bfg` ``tests_require`` now includes
  ``repoze.sphinx.autointerface`` as a dependency.

Documentation Enhancements
--------------------------

- Exception view documentation was added to the :ref:`hooks_chapter`
  narrative chapter.

- A new narrative chapter entitled :ref:`i18n_chapter` was added.

- The :ref:`environment_chapter` chapter was changed: documentation
  about the ``default_locale_name`` setting was added.

- A new API chapter for the :ref:`i18n_module` module was added.

- Documentation for the new :ref:`translationdir_directive` and
  :ref:`localenegotiator_directive` ZCML directives were added.

- A section :ref:`custom_route_predicates` was added to the URL
  Dispatch narrative chapter.

- The :ref:`static_resources_section` and
  :ref:`generating_static_resource_urls` sections of the Static
  Resources chapter have been updated to mention using
  :func:`repoze.bfg.url.static_url` to generate URLs to external
  webservers.

- Documentation for registering a new configuration decorator was
  added in :ref:`registering_configuration_decorators`.

- The authorization chapter of the :ref:`bfg_wiki_tutorial` was
  changed to demonstrate authorization via a group rather than via a
  direct username.

- The authorization chapter of the :ref:`bfg_sql_wiki_tutorial` was
  changed to demonstrate authorization via a group rather than via a
  direct username.

- The :ref:`hooks_chapter` chapter now contains a section about
  changing the request factory.

- The :ref:`hooks_chapter` chapter now contains sections about
  changing the request factory and adding a renderer globals factory.

- The :ref:`hybrid_chapter` chapter now contains a description of the
  ``traverse`` route argument.

- The API documentation includes a new module:
  :mod:`repoze.bfg.renderers`.

- The :ref:`templates` chapter was updated; all narrative that used
  templating-specific APIs within examples to perform rendering (such
  as the :func:`repoze.bfg.chameleon_zpt.render_template_to_response`
  method) was changed to use :mod:`repoze.bfg.renderers` ``render_*``
  functions.

- Added description of the :class:`repoze.bfg.events.subscriber`
  decorator to the :ref:`events_chapter` narrative documentation
  chapter.

- Added :class:`repoze.bfg.events.subscriber` API documentation to
  :mod:`repoze.bfg.events` API docs.

- Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By
  Default; BFG Does Not" to the :ref:`design_defense` chapter.

- Expanded the :ref:`cleaning_up_after_a_request` section of the URL
  Dispatch narrative chapter.

- Expanded the :ref:`redirecting_to_slash_appended_routes` section of
  the URL Dispatch narrative chapter.

- Add an API chapter for the :mod:`repoze.bfg.request` module, which
  includes documentation for the :class:`repoze.bfg.request.Request`
  class (the "request object").

- Modify the :ref:`webob_chapter` narrative chapter to reference the
  new :mod:`repoze.bfg.request` API chapter.  Some content was moved
  from this chapter into the API documentation itself.

- Various changes to denote that Python dotted names are now allowed
  as input to Configurator methods.

- All narrative, API, and tutorial docs which referred to a route
  pattern as a ``path`` have now been updated to refer to them as a
  ``pattern``.

- The :mod:`repoze.bfg.interfaces` API documentation page is now
  rendered via ``repoze.sphinx.autointerface``.

- The :ref:`urldispatch_chapter` chapter now refers to the
  :mod:`repoze.bfg.interfaces` chapter to explain the API of an
  :class:`repoze.bfg.interfaces.IRoute` object.

- Added documentation for the :ref:`default_permission_directive` ZCML
  directive.

- Added documentation for the ``default_permission`` parameter of the
  :class:`repoze.bfg.configuration.Configurator` constructor and the
  :meth:`repoze.bfg.configuration.Configurator.set_default_permission``
  method.

- Added a new section to the :ref:`security_chapter` named
  :ref:`setting_a_default_permission`.

- Document ``renderer_globals_factory`` and ``request_factory``
  arguments to the :class:`repoze.bfg.configuration.Configurator`
  constructor.

- Added two sections to the "Hooks" chapter of the documentation:
  :ref:`using_response_callbacks` and :ref:`using_finished_callbacks`.

- Added documentation of the ``request.exception`` attribute to the
  :class:`repoze.bfg.request.Request` API documentation.

- The :ref:`router_chapter` narrative chapter has been updated to note
  finished and response callback steps.

- New interface in interfaces API documentation:
  :class:`repoze.bfg.interfaces.IRoutePregenerator`.

- Added a "The Matched Route" section to the
  :ref:`urldispatch_chapter` narrative docs chapter, detailing the
  ``matched_route`` attribute.

Licensing Changes
-----------------

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