path: root/CHANGES.txt

Next release
============

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


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

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

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

- Redirect requests for tutorial sources to
  http://docs.repoze.org/bfgwiki-1.3 and
  http://docs.repoze.org/bfgwiki2-1.3/ respectively.

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

1.3a3 (2010-05-01)
==================

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

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

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

- Any mention of the ``handle_teardown`` event listener as used by the
  paster templates was removed from the URL Dispatch narrative chapter.

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

1.3a2 (2010-04-28)
==================

Features
--------

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

- The default locale negotiator has become more complex.

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

  * Then it looks for the ``request.cookies['_LOCALE_']`` value.

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

- The default locale negotiator now looks for the parameter named
  ``_LOCALE_`` rather than a parameter named ``locale`` in
  ``request.params``.

Behavior Changes
----------------

- A locale negotiator may now return ``None``, signifying that the
  default locale should be used.

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

- Documentation concerning locale negotiation in the
  Internationalizationa and Localization chapter was updated.

- Expanded portion of i18n narrative chapter docs which discuss
  working with gettext files.

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

Features
--------

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

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

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

  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.

  The feature can be used with any view registration mechanism
  (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view``
  styles).

  This feature was kindly contributed by Andrey Popp.

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

- Internationalization and localization features as documented in the
  narrative documentation chapter entitled ``Internationalization and
  Localization``.

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

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

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

ZCML
----

- Add a ``translationdir`` ZCML directive to support localization.

- Add a ``localenegotiator`` ZCML directive to support localization.

Deprecations
------------

-  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 new install-time dependency on the ``venusian`` distribution was
  added.

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