From ff1213e8f2aed987108ba57aed517c033491b1aa Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 14 Apr 2010 02:49:19 +0000 Subject: Add "exception views" work contributed primarily by Andrey Popp by merging the "phash" branch. --- CHANGES.txt | 1035 +++-------------------------------------------------------- 1 file changed, 46 insertions(+), 989 deletions(-) (limited to 'CHANGES.txt') diff --git a/CHANGES.txt b/CHANGES.txt index cb9453b43..4f125d33d 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,1016 +1,73 @@ Next release ============ -Bug Fixes ---------- - -- Defer conditional import of IPython to avoid breakage under mod_wsgi. - http://bugs.repoze.org/issue138 - -- The ``__name__`` value assigned to the returned object in the - ``bfg_alchemy`` application template's ``MyApp`` model was an - integer. This was incorrect. It is now a string. - -Internal --------- - -- Replace the statement ``path = path.rstrip('/').lstrip('/')`` with - the simpler ``path = path.strip('/')`` in the - ``repoze.bfg.traversal.traversal_path`` function. - -1.2 (2010-02-10) -================ - -- No changes from 1.2b6. - -1.2b6 (2010-02-06) -================== - -Backwards Incompatibilities ---------------------------- - -- Remove magical feature of ``repoze.bfg.url.model_url`` which - prepended a fully-expanded urldispatch route URL before a the - model's path if it was noticed that the request had matched a route. - This feature was ill-conceived, and didn't work in all scenarios. - -Bug Fixes ---------- - -- More correct conversion of provided ``renderer`` values to resource - specification values (internal). - -1.2b5 (2010-02-04) -================== - -Bug Fixes ---------- - -- 1.2b4 introduced a bug whereby views added via a route configuration - that named a view callable and also a ``view_attr`` became broken. - Symptom: ``MyViewClass is not callable`` or the ``__call__`` of a - class was being called instead of the method named via - ``view_attr``. - -- Fix a bug whereby a ``renderer`` argument to the ``@bfg_view`` - decorator that provided a package-relative template filename might - not have been resolved properly. Symptom: inappropriate ``Missing - template resource`` errors. - -1.2b4 (2010-02-03) -================== - -Documentation -------------- - -- Update GAE tutorial to use Chameleon instead of Jinja2 (now that - it's possible). - -Bug Fixes ---------- - -- Ensure that ``secure`` flag for AuthTktAuthenticationPolicy - constructor does what it's documented to do (merge Daniel Holth's - fancy-cookies-2 branch). - -Features --------- - -- Add ``path`` and ``http_only`` options to - AuthTktAuthenticationPolicy constructor (merge Daniel Holth's - fancy-cookies-2 branch). - -Backwards Incompatibilities ---------------------------- - -- Remove ``view_header``, ``view_accept``, ``view_xhr``, - ``view_path_info``, ``view_request_method``, ``view_request_param``, - and ``view_containment`` predicate arguments from the - ``Configurator.add_route`` argument list. These arguments were - speculative. If you need the features exposed by these arguments, - add a view associated with a route using the ``route_name`` argument - to the ``add_view`` method instead. - -- Remove ``view_header``, ``view_accept``, ``view_xhr``, - ``view_path_info``, ``view_request_method``, ``view_request_param``, - and ``view_containment`` predicate arguments from the ``route`` ZCML - directive attribute set. These attributes were speculative. If you - need the features exposed by these attributes, add a view associated - with a route using the ``route_name`` attribute of the ``view`` ZCML - directive instead. - -Dependencies ------------- - -- Remove dependency on ``sourcecodegen`` (not depended upon by - Chameleon 1.1.1+). - -1.2b3 (2010-01-24) -================== - -Bug Fixes ---------- - -- When "hybrid mode" (both traversal and urldispatch) is in use, - default to finding route-related views even if a non-route-related - view registration has been made with a more specific context. The - default used to be to find views with a more specific context first. - Use the new ``use_global_views`` argument to the route definition to - get back the older behavior. - -Features --------- - -- Add ``use_global_views`` argument to ``add_route`` method of - Configurator. When this argument is true, views registered for *no* - route will be found if no more specific view related to the route is - found. - -- Add ``use_global_views`` attribute to ZCML ```` directive - (see above). - -Internal --------- - -- When registering a view, register the view adapter with the - "requires" interfaces as ``(request_type, context_type)`` rather - than ``(context_type, request_type)``. This provides for saner - lookup, because the registration will always be made with a specific - request interface, but registration may not be made with a specific - context interface. In general, when creating multiadapters, you - want to order the requires interfaces so that the the elements which - are more likely to be registered using specific interfaces are - ordered before those which are less likely. - -1.2b2 (2010-01-21) -================== - -Bug Fixes ---------- - -- When the ``Configurator`` is passed an instance of - ``zope.component.registry.Components`` as a ``registry`` constructor - argument, fix the instance up to have the attributes we expect of an - instance of ``repoze.bfg.registry.Registry`` when ``setup_registry`` - is called. This makes it possible to use the global Zope component - registry as a BFG application registry. - -- When WebOb 0.9.7.1 was used, a deprecation warning was issued for - the class attribute named ``charset`` within - ``repoze.bfg.request.Request``. BFG now *requires* WebOb >= 0.9.7, - and code was added so that this deprecation warning has disappeared. - -- Fix a view lookup ordering bug whereby a view with a larger number - of predicates registered first (literally first, not "earlier") for - a triad would lose during view lookup to one registered with fewer. - -- Make sure views with exactly N custom predicates are always called - before views with exactly N non-custom predicates given all else is - equal in the view configuration. - -Documentation -------------- - -- Change renderings of ZCML directive documentation. - -- Add a narrative documentation chapter: "Using the Zope Component - Architecture in repoze.bfg". - -Dependencies ------------- - -- Require WebOb >= 0.9.7 - -1.2b1 (2010-01-18) -================== - -Bug Fixes ---------- - -- In ``bfg_routesalchemy``, ``bfg_alchemy`` paster templates and the - ``bfgwiki2`` tutorial, clean up the SQLAlchemy connection by - registering a ``repoze.tm.after_end`` callback instead of relying on - a ``__del__`` method of a ``Cleanup`` class added to the WSGI - environment. The ``__del__`` strategy was fragile and caused - problems in the wild. Thanks to Daniel Holth for testing. - -Features --------- - -- Read logging configuration from PasteDeploy config file ``loggers`` - section (and related) when ``paster bfgshell`` is invoked. - -Documentation -------------- - -- Major rework in preparation for book publication. - -1.2a11 (2010-01-05) -=================== - -Bug Fixes ---------- - -- Make ``paster bfgshell`` and ``paster create -t bfg_xxx`` work on - Jython (fix minor incompatibility with treatment of ``__doc__`` at - the class level). - -- Updated dependency on ``WebOb`` to require a version which supports - features now used in tests. - -Features --------- - -- Jython compatibility (at least when repoze.bfg.jinja2 is used as the - templating engine; Chameleon does not work under Jython). - -- Show the derived abspath of template resource specifications in the - traceback when a renderer template cannot be found. - -- Show the original traceback when a Chameleon template cannot be - rendered due to a platform incompatibility. - -1.2a10 (2010-01-04) -=================== - -Features --------- - -- The ``Configurator.add_view`` method now accepts an argument named - ``context``. This is an alias for the older argument named - ``for_``; it is preferred over ``for_``, but ``for_`` will continue - to be supported "forever". - -- The ``view`` ZCML directive now accepts an attribute named - ``context``. This is an alias for the older attribute named - ``for``; it is preferred over ``for``, but ``for`` will continue to - be supported "forever". - -- The ``Configurator.add_route`` method now accepts an argument named - ``view_context``. This is an alias for the older argument named - ``view_for``; it is preferred over ``view_for``, but ``view_for`` - will continue to be supported "forever". - -- The ``route`` ZCML directive now accepts an attribute named - ``view_context``. This is an alias for the older attribute named - ``view_for``; it is preferred over ``view_for``, but ``view_for`` - will continue to be supported "forever". - -Documentation and Paster Templates ----------------------------------- - -- LaTeX rendering tweaks. - -- All uses of the ``Configurator.add_view`` method that used its - ``for_`` argument now use the ``context`` argument instead. - -- All uses of the ``Configurator.add_route`` method that used its - ``view_for`` argument now use the ``view_context`` argument instead. - -- All uses of the ``view`` ZCML directive that used its ``for`` - attribute now use the ``context`` attribute instead. - -- All uses of the ``route`` ZCML directive that used its ``view_for`` - attribute now use the ``view_context`` attribute instead. - -- Add a (minimal) tutorial dealing with use of ``repoze.catalog`` in a - ``repoze.bfg`` application. - -Documentation Licensing ------------------------ - -- Loosen the documentation licensing to allow derivative works: it is - now offered under the `Creative Commons - Attribution-Noncommercial-Share Alike 3.0 United States License - `_. This is - only a documentation licensing change; the ``repoze.bfg`` software - continues to be offered under the Repoze Public License at - http://repoze.org/license.html (BSD-like). - -1.2a9 (2009-12-27) -================== - -Documentation Licensing ------------------------ - -- The *documentation* (the result of ``make `` - within the ``docs`` directory) in this release is now offered under - the Creative Commons Attribution-Noncommercial-No Derivative Works - 3.0 United States License as described by - http://creativecommons.org/licenses/by-nc-nd/3.0/us/ . This is only - a licensing change for the documentation; the ``repoze.bfg`` - software continues to be offered under the Repoze Public License - at http://repoze.org/license.html (BSD-like). - -Documentation -------------- - -- Added manual index entries to generated index. - -- Document the previously existing (but non-API) - ``repoze.bfg.configuration.Configurator.setup_registry`` method as - an official API of a ``Configurator``. - -- Fix syntax errors in various documentation code blocks. - -- Created new top-level documentation section: "ZCML Directives". - This section contains detailed ZCML directive information, some of - which was removed from various narrative chapters. - -- The LaTeX rendering of the documentation has been improved. - -- Added a "Fore-Matter" section with author, copyright, and licensing - information. - -1.2a8 (2009-12-24) -================== - Features -------- -- Add a ``**kw`` arg to the ``Configurator.add_settings`` API. +- Added "exception views". When you use an exception (anything than + inherits from the Python ``Exception`` builtin) as view context + argument, e.g.:: -- Add ``hook_zca`` and ``unhook_zca`` methods to the ``Configurator`` - API. + from repoze.bfg.view import bfg_view + from repoze.bfg.exceptions import NotFound + from webob.exc import HTTPNotFound -- The ``repoze.bfg.testing.setUp`` method now returns a - ``Configurator`` instance which can be used to do further - configuration during unit tests. + @bfg_view(context=NotFound) + def notfound_view(request): + return HTTPNotFound() -Bug Fixes ---------- + 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 + returned. -- The ``json`` renderer failed to set the response content type to - ``application/json``. It now does, by setting - ``request.response_content_type`` unless this attribute is already - set. + Other normal view predicates can also be used in combination with an + exception view registration: -- The ``string`` renderer failed to set the response content type to - ``text/plain``. It now does, by setting - ``request.response_content_type`` unless this attribute is already - set. - -Documentation -------------- + from repoze.bfg.view import bfg_view + from repoze.bfg.exceptions import NotFound + from webob.exc import HTTPNotFound -- General documentation improvements by using better Sphinx roles such - as "class", "func", "meth", and so on. This means that there are - many more hyperlinks pointing to API documentation for API - definitions in all narrative, tutorial, and API documentation - elements. + @bfg_view(context=NotFound, route_name='home') + def notfound_view(request): + return HTTPNotFound() -- Added a description of imperative configuration in various places - which only described ZCML configuration. + 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. -- A syntactical refreshing of various tutorials. + 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. -- Added the ``repoze.bfg.authentication``, - ``repoze.bfg.authorization``, and ``repoze.bfg.interfaces`` modules - to API documentation. + The feature can be used with any view registration mechanism + (``@bfg_view`` decorator, ZCML, or imperative ``add_view`` styles). Deprecations ------------ -- The ``repoze.bfg.testing.registerRoutesMapper`` API (added in an - early 1.2 alpha) was deprecated. Its import now generates a - deprecation warning. - -1.2a7 (2009-12-20) -================== - -Features --------- - -- Add four new testing-related APIs to the - ``repoze.bfg.configuration.Configurator`` class: - ``testing_securitypolicy``, ``testing_models``, - ``testing_add_subscriber``, and ``testing_add_template``. These - were added in order to provide more direct access to the - functionality of the ``repoze.bfg.testing`` APIs named - ``registerDummySecurityPolicy``, ``registerModels``, - ``registerEventListener``, and ``registerTemplateRenderer`` when a - configurator is used. The ``testing`` APIs named are nominally - deprecated (although they will likely remain around "forever", as - they are in heavy use in the wild). - -- Add a new API to the ``repoze.bfg.configuration.Configurator`` - class: ``add_settings``. This API can be used to add "settings" - (information returned within via the - ``repoze.bfg.settings.get_settings`` API) after the configurator has - been initially set up. This is most useful for testing purposes. - -- Add a ``custom_predicates`` argument to the ``Configurator`` - ``add_view`` method, the ``bfg_view`` decorator and the attribute - list of the ZCML ``view`` directive. If ``custom_predicates`` is - specified, it must be a sequence of predicate callables (a predicate - callable accepts two arguments: ``context`` and ``request`` and - returns ``True`` or ``False``). The associated view callable will - only be invoked if all custom predicates return ``True``. Use one - or more custom predicates when no existing predefined predicate is - useful. Predefined and custom predicates can be mixed freely. - -- Add a ``custom_predicates`` argument to the ``Configurator`` - ``add_route`` and the attribute list of the ZCML ``route`` - directive. If ``custom_predicates`` is specified, it must be a - sequence of predicate callables (a predicate callable accepts two - arguments: ``context`` and ``request`` and returns ``True`` or - ``False``). The associated route will match will only be invoked if - all custom predicates return ``True``, else route matching - continues. Note that the value ``context`` will always be ``None`` - when passed to a custom route predicate. Use one or more custom - predicates when no existing predefined predicate is useful. - Predefined and custom predicates can be mixed freely. +- 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. Internal -------- -- Remove the ``repoze.bfg.testing.registerTraverser`` function. This - function was never an API. - -Documenation ------------- - -- Doc-deprecated most helper functions in the ``repoze.bfg.testing`` - module. These helper functions likely won't be removed any time - soon, nor will they generate a warning any time soon, due to their - heavy use in the wild, but equivalent behavior exists in methods of - a Configurator. - -1.2a6 (2009-12-18) -================== - -Features --------- - -- The ``Configurator`` object now has two new methods: ``begin`` and - ``end``. The ``begin`` method is meant to be called before any - "configuration" begins (e.g. before ``add_view``, et. al are - called). The ``end`` method is meant to be called after all - "configuration" is complete. - - Previously, before there was imperative configuration at all (1.1 - and prior), configuration begin and end was invariably implied by - the process of loading a ZCML file. When a ZCML load happened, the - threadlocal data structure containing the request and registry was - modified before the load, and torn down after the load, making sure - that all framework code that needed ``get_current_registry`` for the - duration of the ZCML load was satisfied. - - Some API methods called during imperative configuration, (such as - ``Configurator.add_view`` when a renderer is involved) end up for - historical reasons calling ``get_current_registry``. However, in - 1.2a5 and below, the Configurator supplied no functionality that - allowed people to make sure that ``get_current_registry`` returned - the registry implied by the configurator being used. ``begin`` now - serves this purpose. Inversely, ``end`` pops the thread local - stack, undoing the actions of ``begin``. - - We make this boundary explicit to reduce the potential for confusion - when the configurator is used in different circumstances (e.g. in - unit tests and app code vs. just in initial app setup). - - Existing code written for 1.2a1-1.2a5 which does not call ``begin`` - or ``end`` continues to work in the same manner it did before. It - is however suggested that this code be changed to call ``begin`` and - ``end`` to reduce the potential for confusion in the future. - -- All ``paster`` templates which generate an application skeleton now - make use of the new ``begin`` and ``end`` methods of the - Configurator they use in their respective copies of ``run.py`` and - ``tests.py``. +- View registrations and lookups are now done with three "requires" + arguments instead of two to accomodate orthogonality of exception + views. Documentation ------------- -- All documentation that makes use of a ``Configurator`` object to do - application setup and test setup now makes use of the new ``begin`` - and ``end`` methods of the configurator. - -Bug Fixes ---------- - -- When a ``repoze.bfg.exceptions.NotFound`` or - ``repoze.bfg.exceptions.Forbidden`` *class* (as opposed to instance) - was raised as an exception within a root factory (or route root - factory), the exception would not be caught properly by the - ``repoze.bfg.`` Router and it would propagate to up the call stack, - as opposed to rendering the not found view or the forbidden view as - would have been expected. - -- When Chameleon page or text templates used as renderers were added - imperatively (via ``Configurator.add_view`` or some derivative), - they too-eagerly attempted to look up the ``reload_templates`` - setting via ``get_settings``, meaning they were always registered in - non-auto-reload-mode (the default). Each now waits until its - respective ``template`` attribute is accessed to look up the value. - -- When a route with the same name as a previously registered route was - added, the old route was not removed from the mapper's routelist. - Symptom: the old registered route would be used (and possibly - matched) during route lookup when it should not have had a chance to - ever be used. - -1.2a5 (2009-12-10) -================== - -Features --------- - -- When the ``repoze.bfg.exceptions.NotFound`` or - ``repoze.bfg.exceptions.Forbidden`` error is raised from within a - custom root factory or the ``factory`` of a route, the appropriate - response is now sent to the requesting user agent (the result of the - notfound view or the forbidden view, respectively). When these - errors are raised from within a root factory, the ``context`` passed - to the notfound or forbidden view will be ``None``. Also, the - request will not be decorated with ``view_name``, ``subpath``, - ``context``, etc. as would normally be the case if traversal had - been allowed to take place. - -Internals ---------- - -- The exception class representing the error raised by various methods - of a ``Configurator`` is now importable as - ``repoze.bfg.exceptions.ConfigurationError``. - -Documentation -------------- - -- General documentation freshening which takes imperative - configuration into account in more places and uses glossary - references more liberally. - -- Remove explanation of changing the request type in a new request - event subscriber, as other predicates are now usually an easier way - to get this done. - -- Added "Thread Locals" narrative chapter to documentation, and added - a API chapter documenting the ``repoze.bfg.threadlocals`` module. - -- Added a "Special Exceptions" section to the "Views" narrative - documentation chapter explaining the effect of raising - ``repoze.bfg.exceptions.NotFound`` and - ``repoze.bfg.exceptions.Forbidden`` from within view code. - -Dependencies ------------- - -- A new dependency on the ``twill`` package was added to the - ``setup.py`` ``tests_require`` argument (Twill will only be - downloaded when ``repoze.bfg`` ``setup.py test`` or ``setup.py - nosetests`` is invoked). - -1.2a4 (2009-12-07) -================== - -Features --------- - -- ``repoze.bfg.testing.DummyModel`` now accepts a new constructor - keyword argument: ``__provides__``. If this constructor argument is - provided, it should be an interface or a tuple of interfaces. The - resulting model will then provide these interfaces (they will be - attached to the constructed model via - ``zope.interface.alsoProvides``). - -Bug Fixes ---------- - -- Operation on GAE was broken, presumably because the - ``repoze.bfg.configuration`` module began to attempt to import the - ``repoze.bfg.chameleon_zpt`` and ``repoze.bfg.chameleon_text`` - modules, and these cannot be used on non-CPython platforms. It now - tolerates startup time import failures for these modules, and only - raise an import error when a template from one of these packages is - actually used. - -1.2a3 (2009-12-02) -================== - -Bug Fixes ---------- - -- The ``repoze.bfg.url.route_url`` function inappropriately passed - along ``_query`` and/or ``_anchor`` arguments to the - ``mapper.generate`` function, resulting in blowups. - -- When two views were registered with differering ``for`` interfaces - or classes, and the ``for`` of first view registered was a - superclass of the second, the ``repoze.bfg`` view machinery would - incorrectly associate the two views with the same "multiview". - Multiviews are meant to be collections of views that have *exactly* - the same for/request/viewname values, without taking inheritance - into account. Symptom: wrong view callable found even when you had - correctly specified a ``for_`` interface/class during view - configuration for one or both view configurations. - -Backwards Incompatibilities ---------------------------- - -- The ``repoze.bfg.templating`` module has been removed; it had been - deprecated in 1.1 and never actually had any APIs in it. - -1.2a2 (2009-11-29) -================== - -Bug Fixes ---------- - -- The the long description of this package (as shown on PyPI) was not - valid reStructuredText, and so was not renderable. - -- Trying to use an HTTP method name string such as ``GET`` as a - ``request_type`` predicate argument caused a startup time failure - when it was encountered in imperative configuration or in a - decorator (symptom: ``Type Error: Required specification must be a - specification``). This now works again, although ``request_method`` - is now the preferred predicate argument for associating a view - configuration with an HTTP request method. - -Documentation -------------- - -- Fixed "Startup" narrative documentation chapter; it was explaining - "the old way" an application constructor worked. - -1.2a1 (2009-11-28) -================== - -Features --------- - -- An imperative configuration mode. - - A ``repoze.bfg`` application can now begin its life as a single - Python file. Later, the application might evolve into a set of - Python files in a package. Even later, it might start making use of - other configuration features, such as ``ZCML``. But neither the use - of a package nor the use of non-imperative configuration is required - to create a simple ``repoze.bfg`` application any longer. - - Imperative configuration makes ``repoze.bfg`` competetive with - "microframeworks" such as `Bottle `_ and - `Tornado `_. ``repoze.bfg`` has a good - deal of functionality that most microframeworks lack, so this is - hopefully a "best of both worlds" feature. - - The simplest possible ``repoze.bfg`` application is now:: - - 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() - -- A new class now exists: ``repoze.bfg.configuration.Configurator``. - This class forms the basis for sharing machinery between - "imperatively" configured applications and traditional - declaratively-configured applications. - -- 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 testing - registry 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. - This will cause the result of the ``zope.component.getSiteManager`` - function to be the global ZCA registry (the result of - ``zope.component.getGlobalSiteManager``) once again. - -- The ``run.py`` module in various ``repoze.bfg`` ``paster`` templates - now use a ``repoze.bfg.configuration.Configurator`` class instead of - the (now-legacy) ``repoze.bfg.router.make_app`` function to produce - a WSGI application. - -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. - -Internals ---------- - -- The routes mapper is no longer a root factory wrapper. It is now - consulted directly by the router. - -- The ``repoze.bfg.registry.make_registry`` callable has been removed. - -- The ``repoze.bfg.view.map_view`` callable has been removed. - -- The ``repoze.bfg.view.owrap_view`` callable has been removed. - -- The ``repoze.bfg.view.predicate_wrap`` callable has been removed. - -- The ``repoze.bfg.view.secure_view`` callable has been removed. - -- The ``repoze.bfg.view.authdebug_view`` callable has been removed. - -- The ``repoze.bfg.view.renderer_from_name`` callable has been - removed. Use ``repoze.bfg.configuration.Configurator.renderer_from_name`` - instead (still not an API, however). - -- The ``repoze.bfg.view.derive_view`` callable has been removed. Use - ``repoze.bfg.configuration.Configurator.derive_view`` instead (still - not an API, however). - -- The ``repoze.bfg.settings.get_options`` callable has been removed. - Its job has been subsumed by the ``repoze.bfg.settings.Settings`` - class constructor. - -- The ``repoze.bfg.view.requestonly`` function has been moved to - ``repoze.bfg.configuration.requestonly``. - -- The ``repoze.bfg.view.rendered_response`` function has been moved to - ``repoze.bfg.configuration.rendered_response``. - -- The ``repoze.bfg.view.decorate_view`` function has been moved to - ``repoze.bfg.configuration.decorate_view``. - -- The ``repoze.bfg.view.MultiView`` class has been moved to - ``repoze.bfg.configuration.MultiView``. - -- The ``repoze.bfg.zcml.Uncacheable`` class has been removed. - -- The ``repoze.bfg.resource.resource_spec`` function has been removed. - -- All ZCML directives which deal with attributes which are paths now - use the ``path`` method of the ZCML context to resolve a relative - name to an absolute one (imperative configuration requirement). - -- The ``repoze.bfg.scripting.get_root`` API now uses a 'real' WebOb - request rather than a FakeRequest when it sets up the request as a - threadlocal. - -- The ``repoze.bfg.traversal.traverse`` API now uses a 'real' WebOb - request rather than a FakeRequest when it calls the traverser. - -- The ``repoze.bfg.request.FakeRequest`` class has been removed. - -- Most uses of the ZCA threadlocal API (the ``getSiteManager``, - ``getUtility``, ``getAdapter``, ``getMultiAdapter`` threadlocal API) - have been removed from the core. Instead, when a threadlocal is - necessary, the core uses the - ``repoze.bfg.threadlocal.get_current_registry`` API to obtain the - registry. - -- The internal ILogger utility named ``repoze.bfg.debug`` is now just - an IDebugLogger unnamed utility. A named utility with the old name - is registered for b/w compat. - -- The ``repoze.bfg.interfaces.ITemplateRendererFactory`` interface was - removed; it has become unused. - -- Instead of depending on the ``martian`` package to do code scanning, - we now just use our own scanning routines. - -- We now no longer have a dependency on ``repoze.zcml`` package; - instead, the ``repoze.bfg`` package includes implementations of the - ``adapter``, ``subscriber`` and ``utility`` directives. - -- Relating to the following functions: - - ``repoze.bfg.view.render_view`` - - ``repoze.bfg.view.render_view_to_iterable`` - - ``repoze.bfg.view.render_view_to_response`` - - ``repoze.bfg.view.append_slash_notfound_view`` - - ``repoze.bfg.view.default_notfound_view`` - - ``repoze.bfg.view.default_forbidden_view`` - - ``repoze.bfg.configuration.rendered_response`` - - ``repoze.bfg.security.has_permission`` - - ``repoze.bfg.security.authenticated_userid`` - - ``repoze.bfg.security.effective_principals`` - - ``repoze.bfg.security.view_execution_permitted`` - - ``repoze.bfg.security.remember`` - - ``repoze.bfg.security.forget`` - - ``repoze.bfg.url.route_url`` - - ``repoze.bfg.url.model_url`` - - ``repoze.bfg.url.static_url`` - - ``repoze.bfg.traversal.virtual_root`` - - Each of these functions now expects to be called with a request - object that has a ``registry`` attribute which represents the - current ``repoze.bfg`` registry. They fall back to obtaining the - registry from the threadlocal API. - -Backwards Incompatibilites --------------------------- - -- Unit tests which use ``zope.testing.cleanup.cleanUp`` for the - purpose of isolating tests from one another may now begin to fail - due to lack of isolation between tests. - - Here's why: In repoze.bfg 1.1 and prior, the registry returned by - ``repoze.bfg.threadlocal.get_current_registry`` when no other - registry had been pushed on to the threadlocal stack was the - ``zope.component.globalregistry.base`` global registry (aka the - result of ``zope.component.getGlobalSiteManager()``). In repoze.bfg - 1.2+, however, the registry returned in this situation is the new - module-scope ``repoze.bfg.registry.global_registry`` object. The - ``zope.testing.cleanup.cleanUp`` function clears the - ``zope.component.globalregistry.base`` global registry - unconditionally. However, it does not know about the - ``repoze.bfg.registry.global_registry`` object, so it does not clear - it. - - If you use the ``zope.testing.cleanup.cleanUp`` function in the - ``setUp`` of test cases in your unit test suite instead of using the - (more correct as of 1.1) ``repoze.bfg.testing.setUp``, you will need - to replace all calls to ``zope.testing.cleanup.cleanUp`` with a call - to ``repoze.bfg.testing.setUp``. - - If replacing all calls to ``zope.testing.cleanup.cleanUp`` with a - call to ``repoze.bfg.testing.setUp`` is infeasible, you can put this - bit of code somewhere that is executed exactly **once** (*not* for - each test in a test suite; in the `` __init__.py`` of your package - or your package's ``tests`` subpackage would be a reasonable - place):: - - import zope.testing.cleanup - from repoze.bfg.testing import setUp - zope.testing.cleanup.addCleanUp(setUp) - -- When there is no "current registry" in the - ``repoze.bfg.threadlocal.manager`` threadlocal data structure (this - is the case when there is no "current request" or we're not in the - midst of a ``r.b.testing.setUp``-bounded unit test), the ``.get`` - method of the manager returns a data structure containing a *global* - registry. In previous releases, this function returned the global - Zope "base" registry: the result of - ``zope.component.getGlobalSiteManager``, which is an instance of the - ``zope.component.registry.Component`` class. In this release, - however, the global registry returns a globally importable instance - of the ``repoze.bfg.registry.Registry`` class. This registry - instance can always be imported as - ``repoze.bfg.registry.global_registry``. - - Effectively, this means that when you call - ``repoze.bfg.threadlocal.get_current_registry`` when no request or - ``setUp`` bounded unit test is in effect, you will always get back - the global registry that lives in - ``repoze.bfg.registry.global_registry``. It also means that - ``repoze.bfg`` APIs that *call* ``get_current_registry`` will use - this registry. - - This change was made because ``repoze.bfg`` now expects the registry - it uses to have a slightly different API than a bare instance of - ``zope.component.registry.Components``. - -- 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). - +- Exception view documentation was added to the ``Hooks`` narrative + chapter. -- cgit v1.2.3