prep for 1.3a4

Chris McDonough

2010-07-04 4dc529e4bbc36b7e5e2bd3ea199a7929e407a267

 CHANGES.txt

@@ -1,10 +1,173 @@
Next release
============
1.3a4 (2010-07-03)
==================

Features
--------

- Added "exception views".  When you use an exception (anything than
- 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
-------------

- 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 Route Predicates`` was added to the URL
  Dispatch narrative chapter.

- The Static Resources chapter has been updated to mention using
  ``static_url`` to generate URLs to external webservers.

Internal
--------

- Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new
  abstraction revolving around the (still-internal)
  ``repoze.bfg.static.StaticURLInfo`` helper class.

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

@@ -18,11 +181,11 @@

  For the above example, when the ``repoze.bfg.exceptions.NotFound``
  exception is raised by any view or any root factory, the
  ``notfound_view`` view callable wil be invoked and its response
  ``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:
  exception view registration::

      from repoze.bfg.view import bfg_view
      from repoze.bfg.exceptions import NotFound
@@ -47,7 +210,51 @@
  contexts will also work.

  The feature can be used with any view registration mechanism
  (``@bfg_view`` decorator, ZCML, or imperative ``add_view`` styles).
  (``@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
------------
@@ -58,6 +265,18 @@
   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
--------
@@ -71,8 +290,49 @@
  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.