What's New In :mod:`repoze.bfg` 1.2 =================================== This article explains the new features in :mod:`repoze.bfg` version 1.2 as compared to the previous 1.1 release. It also documents backwards incompatibilities between the two versions and deprecations added to 1.2, as well as software dependency changes and notable documentation additions. Major Feature Additions ----------------------- The major feature additions of 1.2 are: - An :term:`imperative configuration` mode. This feature makes :mod:`repoze.bfg` competetive with "microframeworks" such as `Bottle `_ and `Tornado `_, because it means that :mod:`repoze.bfg` applications can begin life as a single file. Later, the application may evolve into a package, and may start making use of other configuration features, such as :term:`ZCML`. :mod:`repoze.bfg` has a good deal of functionality that microframeworks lack, so this is meant as a a "best of both worlds" feature. As a result of :term:`imperative configuration`, the simplest possible :mod:`repoze.bfg` application is now: .. code-block:: python :linenos: from webob import Response from wsgiref import simple_server from repoze.bfg.configuration import Configurator def hello_world(request): return Response('Hello world!') if __name__ == '__main__': config = Configurator() config.add_view(hello_world) app = config.make_wsgi_app() simple_server.make_server('', 8080, app).serve_forever() For an introduction to imperative-mode configuration, see :ref:`configuration_narr`. Miscellaneous Minor Feature Additions -------------------------------------- - The ``repoze.bfg.testing.setUp`` function now accepts three extra optional keyword arguments: ``registry``, ``request`` and ``hook_zca``. If the ``registry`` argument is not ``None``, the argument will be treated as the registry that is set as the "current registry" (it will be returned by ``repoze.bfg.threadlocal.get_current_registry``) for the duration of the test. If the ``registry`` argument is ``None`` (the default), a new registry is created and used for the duration of the test. The value of the ``request`` argument is used as the "current request" (it will be returned by ``repoze.bfg.threadlocal.get_current_request``) for the duration of the test; it defaults to ``None``. If ``hook_zca`` is ``True`` (the default), the ``zope.component.getSiteManager`` function will be hooked with a function that returns the value of ``registry`` (or the default-created registry if ``registry`` is ``None``) instead of the registry returned by ``zope.component.getGlobalSiteManager``, causing the Zope Component Architecture API (``getSiteManager``, ``getAdapter``, ``getUtility``, and so on) to use the registry we're using for testing instead of the global ZCA registry. - The ``repoze.bfg.testing.tearDown`` function now accepts an ``unhook_zca`` argument. If this argument is ``True`` (the default), ``zope.component.getSiteManager.reset()`` will be called, causing the "base" registry to once again start returnining the result of ``zope.component.getSiteManager``. Documentation ------------- - The documentation now uses the "request-only" view calling convention in most examples (as opposed to the ``context, request`` convention). This is a documentation-only change; the ``context, request`` convention is also supported and documented, and will be "forever". - ``repoze.bfg.configuration`` API documentation has been added. - A narrative documentation chapter entitled "Creating Your First ``repoze.bfg`` Application" has been added. This chapter details usage of the new ``repoze.bfg.configuration.Configurator`` class, and demonstrates a simplified "imperative-mode" configuration; doing ``repoze.bfg`` application configuration imperatively was previously much more difficult. - A narrative documentation chapter entitled "Configuration, Decorations and Code Scanning" explaining ZCML- vs. imperative- vs. decorator-based configuration equivalence. - The "ZCML Hooks" chapter has been renamed to "Hooks"; it documents how to override hooks now via imperative configuration and ZCML. - The explanation about how to supply an alternate "response factory" has been removed from the "Hooks" chapter. This feature may be removed in a later release (it still works now, it's just not documented). - Add a section entitled "Test Set Up and Tear Down" to the unittesting chapter. Bug Fixes ---------- - The ACL authorization policy debugging output when ``debug_authorization`` console debugging output was turned on wasn't as clear as it could have been when a view execution was denied due to an authorization failure resulting from the set of principals passed never having matched any ACE in any ACL in the lineage. Now in this case, we report ```` as the ACE value and either the root ACL or ```` if no ACL was found. - When two views were registered with the same ``accept`` argument, but were otherwise registered with the same arguments, if a request entered the application which had an ``Accept`` header that accepted *either* of the media types defined by the set of views registered with predicates that otherwise matched, a more or less "random" one view would "win". Now, we try harder to use the view callable associated with the view configuration that has the most specific ``accept`` argument. Thanks to Alberto Valverde for an initial patch. Backwards Incompatibilites -------------------------- - View registration no longer registers a ``repoze.bfg.interfaces.IViewPermission`` adapter (it is no longer checked by the framework; since 1.1, views have been responsible for providing their own security). - The ``repoze.bfg.router.make_app`` callable no longer accepts the ``authentication_policy`` nor the ``authorization_policy`` arguments. This feature was deprecated in version 1.0 and has been removed. - Obscure: the machinery which configured views with a ``request_type`` *and* a ``route_name`` would ignore the request interface implied by ``route_name`` registering a view only for the interface implied by ``request_type``. In the unlikely event that you were trying to use these two features together, the symptom would have been that views that named a ``request_type`` but which were also associated with routes were not found when the route matched. Now if a view is configured with both a ``request_type`` and a ``route_name``, an error is raised. - The ``route`` ZCML directive now no longer accepts the ``request_type`` or ``view_request_type`` attributes. These attributes didn't actually work in any useful way (see entry above this one). - Because the ``repoze.bfg`` package now includes implementations of the ``adapter``, ``subscriber`` and ``utility`` ZCML directives, it is now an error to have ```` in the ZCML of a ``repoze.bfg`` application. A ZCML conflict error will be raised if your ZCML does so. This shouldn't be an issue for "normal" installations; it has always been the responsibility of the ``repoze.bfg.includes`` ZCML to include this file in the past; it now just doesn't. - The ``repoze.bfg.testing.zcml_configure`` API was removed. Use the ``Configurator.load_zcml`` API instead. Deprecations ------------ - The ``repoze.bfg.router.make_app`` function is now nominally deprecated. Its import and usage does not throw a warning, nor will it probably ever disappear. However, using a ``repoze.bfg.configuration.Configurator`` class is now the preferred way to generate a WSGI application. Note that ``make_app`` calls ``zope.component.getSiteManager.sethook( repoze.bfg.threadlocal.get_current_registry)`` on the caller's behalf, hooking ZCA global API lookups, for backwards compatibility purposes. If you disuse ``make_app``, your calling code will need to perform this call itself, at least if your application uses the ZCA global API (``getSiteManager``, ``getAdapter``, etc). Dependencies ------------ - A dependency on the ``martian`` package has been removed (its functionality is replaced internally). - A dependency on the ``repoze.zcml`` package has been removed (its functionality is replaced internally).