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. Backwards Incompatibilites -------------------------- N/A 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. 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). 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. 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.