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