From edd91578808d808646ca583dbd091220b5b7cb28 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 Oct 2010 19:20:22 -0400 Subject: convert remainder of docs to use pyramid instead of repoze.bfg --- docs/whatsnew-1.3.rst | 771 -------------------------------------------------- 1 file changed, 771 deletions(-) delete mode 100644 docs/whatsnew-1.3.rst (limited to 'docs/whatsnew-1.3.rst') diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst deleted file mode 100644 index 8447f8e38..000000000 --- a/docs/whatsnew-1.3.rst +++ /dev/null @@ -1,771 +0,0 @@ -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. - -- 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). - -- The :class:`repoze.bfg.configuration.Configurator` constructor now - accepts a dotted name *string* to a package as a ``package`` - argument. The ``package`` argument was previously required to be a - package *object* (not a dotted name string). - -- The :meth:`repoze.bfg.configuration.Configurator.with_package` - method was added. This method returns a new Configurator using the - same application registry as the configurator object it is called - upon. The new configurator is created afresh with its ``package`` - constructor argument set to the value passed to ``with_package``. - -- The :meth:`repoze.bfg.configuration.Configurator.maybe_dotted` - method resolves a Python dotted name string supplied as its - ``dotted`` argument to a global Python object. If the value cannot - be resolved, a :exc:`repoze.bfg.configuration.ConfigurationError` is - raised. If the value supplied as ``dotted`` is not a string, the - value is returned unconditionally without any resolution attempted. - -- The new - :meth:`repoze.bfg.configuration.Configurator.absolute_resource_spec` - method resolves a potentially relative :term:`resource - specification` string into an absolute version. - -- A new :meth:`repoze.bfg.request.Request.add_response_callback` API - has been added. It can be used to influence response values before - a concrete response object has been created. See the - :ref:`using_response_callbacks` for more information. - -- The :class:`repoze.bfg.interfaces.INewResponse` interface now - includes a ``request`` attribute; as a result, a handler for - INewResponse now has access to the request which caused the - response. - -- Each of the follow methods of the - :class:`repoze.bfg.configuration.Configurator` now allow the - below-named arguments to be passed as "dotted name strings" - (e.g. "foo.bar.baz") rather than as actual implementation objects - that must be imported: - - setup_registry - root_factory, authentication_policy, authorization_policy, - debug_logger, locale_negotiator, request_factory, - renderer_globals_factory - - add_subscriber - subscriber, iface - - derive_view - view - - add_view - view, ``for_``, context, request_type, containment - - add_route() - view, view_for, factory, ``for_``, view_context - - scan - package - - add_renderer - factory - - set_forbidden_view - view - - set_notfound_view - view - - set_request_factory - factory - - set_renderer_globals_factory() - factory - - set_locale_negotiator - negotiator - - testing_add_subscriber - event_iface - -- The argument to - :meth:`repoze.bfg.configuration.Configurator.add_route` which was - previously called ``path`` is now called ``pattern`` for better - explicability. For backwards compatibility purposes, passing a - keyword argument named ``path`` to ``add_route`` will still work - indefinitely. - -- The ``path`` attribute to the ZCML ``route`` directive (see - :ref:`route_directive`) is now named ``pattern`` for better - explicability. The older ``path`` attribute will continue to work - indefinitely. - -- The ``routesalchemy`` paster template has been updated to use - ``pattern`` in its route declarations rather than ``path``. - -- In support of making it easier to configure applications which are - "secure by default", a default permission feature was added. If - supplied, the default permission is used as the permission string to - all view registrations which don't otherwise name a permission. - These APIs are in support of that: - - - A new constructor argument was added to - :class:`repoze.bfg.configuration.Configurator`: - ``default_permission``. - - - A new method was added: - :meth:`repoze.bfg.configuration.Configurator.set_default_permission`. - - - A new ZCML directive was added: :ref:`default_permission_directive`. - -- Add a new request API: - :meth:`repoze.bfg.request.Request.add_finished_callback`. Finished - callbacks are called by the router unconditionally near the very end - of request processing. See the :ref:`using_finished_callbacks` for - more information. - -- A ``matched_route`` attribute is now added to the :term:`request` - object when a route has matched. Its value is the :term:`route` - object that matched (see :class:`repoze.bfg.interfaces.IRoute` for - the API of a route object). - -- The ``exception`` attribute of the :term:`request` is now set - slightly earlier and in a slightly different set of scenarios by the - router, for benefit of "finished callbacks" and "response - callbacks". In previous versions, the ``exception`` attribute of - the request was not set at all if an exception view was not found. - In this version, the ``request.exception`` attribute is set - immediately when an exception is caught by the router, even if an - exception view could not be found. - -- The :meth:`repoze.bfg.configuration.Configurator.add_route` method - now accepts a ``pregenerator`` argument. The pregenerator for the - resulting route is called by :func:`repoze.bfg.url.route_url` in - order to adjust the set of arguments passed to it by the user for - special purposes, such as Pylons 'subdomain' support. It will - influence the URL returned by ``route_url``. See - :class:`repoze.bfg.interfaces.IRoutePregenerator` for more - information. - -- Compatibility with WebOb 1.0 (now requires WebOb >= 1.0). - -- The :meth:`repoze.bfg.traversal.traversal_path` API now eagerly - attempts to encode a Unicode ``path`` into ASCII before attempting - to split it and decode its segments. This is for convenience, - effectively to allow a (stored-as-Unicode-in-a-database, or - retrieved-as-Unicode-from-a-request-parameter) Unicode path to be - passed to :meth:`repoze.bfg.traversal.find_model`, which eventually - internally uses the ``traversal_path`` function under the hood. In - version 1.2 and prior, if the ``path`` was Unicode, that Unicode was - split on slashes and each resulting segment value was Unicode. An - inappropriate call to the ``decode()`` method of a resulting Unicode - path segment could cause a ``UnicodeDecodeError`` to occur even if - the Unicode representation of the path contained no 'high order' - characters (it effectively did a "double decode"). By converting - the Unicode path argument to ASCII before we attempt to decode and - split, genuine errors will occur in a more obvious place while also - allowing us to handle (for convenience) the case that it's a Unicode - representation formed entirely from ASCII-compatible characters. - -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. - -- The router no longer sets the value ``wsgiorg.routing_args`` into - the environ when a route matches. The value used to be something - like ``((), matchdict)``. This functionality was only ever - obliquely referred to in change logs; it was never documented as an - API. - -- The ``exception`` attribute of the request now defaults to ``None``. - In prior versions, the ``request.exception`` attribute did not exist - if an exception was not raised by user code during request - processing; it only began existence once an exception view was - found. - -- Due to changes introduced WebOb 1.0, the - ``repoze.bfg.request.make_request_ascii`` event subscriber no longer - worked, so it has been removed. This subscriber was meant to be used - in a deployment so that code written before BFG 0.7.0 could run - unchanged. At this point, such code will need to be rewritten to - expect Unicode from ``request.GET``, ``request.POST`` and - ``request.params`` or it will need to be changed to use - ``request.str_POST``, ``request.str_GET`` and/or - ``request.str_params`` instead of the non-``str`` versions of same, - as the non-``str`` versions of the same APIs always now perform - decoding to Unicode. - -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. - -- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event - interface was renamed to - :class:`repoze.bfg.interfaces.IApplicationCreated`. Likewise, the - ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed - to :class:`repoze.bfg.events.ApplicationCreated`. The older aliases - will continue to work indefinitely. - -- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was - renamed to :class:`repoze.bfg.interfaces.IContextFound`. Likewise, - the ``repoze.bfg.events.AfterTraversal`` class was renamed to - :class:`repoze.bfg.events.ContextFound`. The older aliases will - continue to work indefinitely. - -- References to the WSGI environment values ``bfg.routes.matchdict`` - and ``bfg.routes.route`` were removed from documentation. These - will stick around internally for several more releases, but it is - ``request.matchdict`` and ``request.matched_route`` are now the - "official" way to obtain the matchdict and the route object which - resulted in the match. - -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). - -- :mod:`repoze.bfg` ``tests_require`` now includes - ``repoze.sphinx.autointerface`` as a dependency. - -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. - -- Add an API chapter for the :mod:`repoze.bfg.request` module, which - includes documentation for the :class:`repoze.bfg.request.Request` - class (the "request object"). - -- Modify the :ref:`webob_chapter` narrative chapter to reference the - new :mod:`repoze.bfg.request` API chapter. Some content was moved - from this chapter into the API documentation itself. - -- Various changes to denote that Python dotted names are now allowed - as input to Configurator methods. - -- All narrative, API, and tutorial docs which referred to a route - pattern as a ``path`` have now been updated to refer to them as a - ``pattern``. - -- The :mod:`repoze.bfg.interfaces` API documentation page is now - rendered via ``repoze.sphinx.autointerface``. - -- The :ref:`urldispatch_chapter` chapter now refers to the - :mod:`repoze.bfg.interfaces` chapter to explain the API of an - :class:`repoze.bfg.interfaces.IRoute` object. - -- Added documentation for the :ref:`default_permission_directive` ZCML - directive. - -- Added documentation for the ``default_permission`` parameter of the - :class:`repoze.bfg.configuration.Configurator` constructor and the - :meth:`repoze.bfg.configuration.Configurator.set_default_permission`` - method. - -- Added a new section to the :ref:`security_chapter` named - :ref:`setting_a_default_permission`. - -- Document ``renderer_globals_factory`` and ``request_factory`` - arguments to the :class:`repoze.bfg.configuration.Configurator` - constructor. - -- Added two sections to the "Hooks" chapter of the documentation: - :ref:`using_response_callbacks` and :ref:`using_finished_callbacks`. - -- Added documentation of the ``request.exception`` attribute to the - :class:`repoze.bfg.request.Request` API documentation. - -- The :ref:`router_chapter` narrative chapter has been updated to note - finished and response callback steps. - -- New interface in interfaces API documentation: - :class:`repoze.bfg.interfaces.IRoutePregenerator`. - -- Added a "The Matched Route" section to the - :ref:`urldispatch_chapter` narrative docs chapter, detailing the - ``matched_route`` attribute. - -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. -- cgit v1.2.3