Metadata-Version: 1.1
Name: repoze.bfg
Version: 1.3
Summary: The repoze.bfg web application framework
Home-page: http://bfg.repoze.org
Author: Chris McDonough, Agendaless Consulting
Author-email: repoze-dev@lists.repoze.org
License: BSD-derived (http://www.repoze.org/LICENSE.txt)
Description: repoze.bfg
        ==========
        
        ``repoze.bfg`` is a small, fast, down-to-earth, open source Python web
        development framework. It makes real-world web application development
        and deployment more fun, more predictable, and more productive.
        
        Support and Documentation
        -------------------------
        
        See the `repoze.bfg website <http://bfg.repoze.org>`_ to view
        documentation, report bugs, and obtain support.
        
        License
        -------
        
        ``repoze.bfg`` is offered under the BSD-derived `Repoze Public License
        <http://repoze.org/license.html>`_.
        
        Authors
        -------
        
        ``repoze.bfg`` is made available by `Agendaless Consulting
        <http://agendaless.com>`_ and a team of contributors.
        
        
        
        1.3 (2010-11-01)
        ================
        
        Features
        --------
        
        - Raise more understandable error when a Jython application attempts to use a
          Chameleon template.
        
        1.3b3 (2010-10-29)
        ==================
        
        Bug Fixes
        ---------
        
        - When a default permission was in effect, and a "static view" had
          been registered (via
          ``repoze.bfg.configuration.Configurator.add_static_view``, or via the
          ``static`` ZCML directiveq), the static view, was, by default,
          protected by the default permission, without a way to indicate that
          it was anonymously viewable.  As of this release, a static view is
          registered using the permission sentinel
          ``__no_permission_required__`` as the permission by default, making
          its resources viewable by completely anonymous users.
        
        Features
        --------
        
        - A ``permission`` argument has been added to the
          ``repoze.bfg.configuration.Configurator.add_static_view`` method and
          a ``permission`` attribute is now available on the ``static`` ZCML
          directive.  
        
        Documentation
        -------------
        
        - A "default permission" glossary entry was added to the glossary.
        
        1.3b2 (2010-10-28)
        ==================
        
        Bug Fixes
        ---------
        
        - The ``repoze.bfg.security.view_execution_permitted`` API could
          return the wrong boolean result due to a bug in the configurator,
          leading to inappropriate view execution by persons without
          permission when it was imported and used directly.  Thanks to Shane
          Hathaway for a bug report and a patch.
        
        Backwards Incompatibilities
        ---------------------------
        
        - Previously, the sentinel to register a view as explicitly "no
          permission required" (most useful when a default permission is in
          effect) was to register it explicitly with the value ``None`` as an
          argument to the ``permission`` parameter of the
          ``repoze.bfg.configuration.Configurator.add_view``.  Using ``None``
          as a sentinel meaning "no permission required" in that location,
          however, was incompatible with the expectations of both the ``view``
          ZCML directive and the ``bfg_view`` decorator, which both passed
          ``None`` explicitly to ``add_view``, overriding any default
          permission.  The symptom was that any "default permission"
          configured appeared to not work if either ZCML or the ``bfg_view``
          directive was used to register a view (although using ``add_view``
          directly did work).  The ``None`` value as a sentinel could also not
          be spelled using ZCML.
        
          Now, the sentinel meaning "no permission required" is the string
          ``__no_permission_required__``, which satisfies the expectation of
          the ``view`` ZCML directive and the ``bfg_view`` decorator, and,
          since it's a string, it can be spelled in both Python and within
          ZCML.
        
          Thanks to Wichert Akkerman for the bug report.
        
        1.3b1 (2010-10-25)
        ==================
        
        Features
        --------
        
        - The ``paster`` template named ``bfg_routesalchemy`` has been updated
          to use SQLAlchemy declarative syntax.  Thanks to Ergo^.
        
        Bug Fixes
        ---------
        
        - When a renderer factory could not be found, a misleading error
          message was raised if the renderer name was not a string.
        
        Documentation
        -------------
        
        - The ""bfgwiki2" (SQLAlchemy + url dispatch) tutorial has been
          updated slightly.  In particular, the source packages no longer
          attempt to use a private index, and the recommended Python version
          is now 2.6.  It was also updated to take into account the changes to
          the ``bfg_routesalchemy`` template used to set up an environment.
        
        - The "bfgwiki" (ZODB + traversal) tutorial has been updated slightly.
          In particular, the source packages no longer attempt to use a
          private index, and the recommended Python version is now 2.6.
        
        1.3a15 (2010-09-30)
        ===================
        
        Features
        --------
        
        - The ``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 ``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.
        
        1.3a14 (2010-09-14)
        ===================
        
        Bug Fixes
        ---------
        
        - If an exception view was registered through the legacy
          ``set_notfound_view`` or ``set_forbidden_view`` APIs, the context
          sent to the view was incorrect (could be ``None`` inappropriately).
        
        Features
        --------
        
        - Compatibility with WebOb 1.0.
        
        Requirements
        ------------
        
        - Now requires WebOb >= 1.0.
        
        Backwards Incompatibilities
        ---------------------------
        
        - Due to changes introduced WebOb 1.0, the
          ``repoze.bfg.request.make_request_ascii`` event subscriber no longer
          works, 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.
        
        Errata
        ------
        
        - A prior changelog entry asserted that the ``INewResponse`` event was
          not sent to listeners if the response was not "valid" (if a view or
          renderer returned a response object that did not have a
          status/headers/app_iter).  This is not true in this release, nor was
          it true in 1.3a13.
        
        1.3a13 (2010-09-14)
        ===================
        
        Bug Fixes
        ---------
        
        - The ``traverse`` route predicate could not successfully generate a
          traversal path.
        
        Features
        --------
        
        - 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 the Configurator:
            ``default_permission``.
        
          - A new method was added to the Configurator:
            ``set_default_permission``.
        
          - A new ZCML directive was added: ``default_permission``.
        
        - Add a new request API: ``request.add_finished_callback``.  Finished
          callbacks are called by the router unconditionally near the very end
          of request processing.  See the "Using Finished Callbacks" section
          of the "Hooks" narrative chapter of the documentation for more
          information.
        
        - A ``request.matched_route`` attribute is now added to the request
          when a route has matched.  Its value is the "route" object that
          matched (see the ``IRoute`` interface within
          ``repoze.bfg.interfaces`` API documentation for the API of a route
          object).
        
        - The ``exception`` attribute of the request is now set slightly
          earlier and in a slightly different set of scenarios, 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 ``add_route`` method of a Configurator now accepts a
          ``pregenerator`` argument.  The pregenerator for the resulting route
          is called by ``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 the ``repoze.bfg.interfaces.IRoutePregenerator``
          interface for more information.
        
        Backwards Incompatibilities
        ---------------------------
        
        - 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.
        
        Deprecations
        ------------
        
        - The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event
          interface was renamed to
          ``repoze.bfg.interfaces.IApplicationCreated``.  Likewise, the
          ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed
          to ``repoze.bfg.events.ApplicationCreated``.  The older aliases will
          continue to work indefinitely.
        
        - The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was
          renamed to ``repoze.bfg.interfaces.IContextFound``.  Likewise, the
          ``repoze.bfg.events.AfterTraversal`` class was renamed to
          ``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.
        
        Documentation
        -------------
        
        - Added documentation for the ``default_permission`` ZCML directive.
        
        - Added documentation for the ``default_permission`` constructor value
          and the ``set_default_permission`` method in the Configurator API
          documentation.
        
        - Added a new section to the "security" chapter named "Setting a
          Default Permission".
        
        - Document ``renderer_globals_factory`` and ``request_factory``
          arguments to Configurator constructor.
        
        - Added two sections to the "Hooks" chapter of the documentation:
          "Using Response Callbacks" and "Using Finished Callbacks".
        
        - Added documentation of the ``request.exception`` attribute to the
          ``repoze.bfg.request.Request`` API documentation.
        
        - Added glossary entries for "response callback" and "finished
          callback".
        
        - The "Request Processing" narrative chapter has been updated to note
          finished and response callback steps.
        
        - New interface in interfaces API documentation: ``IRoutePregenerator``.
        
        - Added a "The Matched Route" section to the URL Dispatch narrative
          docs chapter, detailing the ``matched_route`` attribute.
        
        1.3a12 (2010-09-08)
        ===================
        
        Bug Fixes
        ---------
        
        - Fix a bug in ``repoze.bfg.url.static_url`` URL generation: if two
          resource specifications were used to create two separate static
          views, but they shared a common prefix, it was possible that
          ``static_url`` would generate an incorrect URL.
        
        - Fix another bug in ``repoze.bfg.static_url`` URL generation: too
          many slashes in generated URL.
        
        - Prevent a race condition which could result in a ``RuntimeError``
          when rendering a Chameleon template that has not already been
          rendered once.  This would usually occur directly after a restart,
          when more than one person or thread is trying to execute the same
          view at the same time: https://bugs.launchpad.net/karl3/+bug/621364
        
        Features
        --------
        
        - The argument to ``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 is now named
          ``pattern`` for better explicability.  The older ``path`` attribute
          will continue to work indefinitely.
        
        Documentation
        -------------
        
        - 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 ``repoze.bfg.interfaces`` API documentation page is now rendered
          via ``repoze.sphinx.autointerface``.
        
        - The URL Dispatch narrative chapter now refers to the ``interfaces``
          chapter to explain the API of an ``IRoute`` object.
        
        Paster Templates
        ----------------
        
        - The routesalchemy template has been updated to use ``pattern`` in
          its route declarations rather than ``path``.
        
        Dependencies
        ------------
        
        - ``tests_require`` now includes ``repoze.sphinx.autointerface`` as a
          dependency.
        
        Internal
        --------
        
        - Add an API to the ``Configurator`` named ``get_routes_mapper``.
          This returns an object implementing the ``IRoutesMapper`` interface.
        
        - The ``repoze.bfg.urldispatch.RoutesMapper`` object now has a
          ``get_route`` method which returns a single Route object or
          ``None``.
        
        - A new interface ``repoze.bfg.interfaces.IRoute`` was added.  The
          ``repoze.bfg.urldispatch.Route`` object implements this interface.
        
        - The canonical attribute for accessing the routing pattern from a
          route object is now ``pattern`` rather than ``path``.
        
        - Use ``hash()`` rather than ``id()`` when computing the "phash" of a
          custom route/view predicate in order to allow the custom predicate
          some control over which predicates are "equal".
        
        - Use ``response.headerlist.append`` instead of
          ``response.headers.add`` in
          ``repoze.bfg.request.add_global_response_headers`` in case the
          response is not a WebOb response.
        
        - The ``repoze.bfg.urldispatch.Route`` constructor (not an API) now
          accepts a different ordering of arguments.  Previously it was
          ``(pattern, name, factory=None, predicates=())``.  It is now
          ``(name, pattern, factory=None, predicates=())``.  This is in
          support of consistency with ``configurator.add_route``.
        
        - The ``repoze.bfg.urldispatch.RoutesMapper.connect`` method (not an
          API) now accepts a different ordering of arguments.  Previously it
          was ``(pattern, name, factory=None, predicates=())``.  It is now
          ``(name, pattern, factory=None, predicates=())``.  This is in
          support of consistency with ``configurator.add_route``.
        
        1.3a11 (2010-09-05)
        ===================
        
        Bug Fixes
        ---------
        
        - Process the response callbacks and the NewResponse event earlier, to
          enable mutations to the response to take effect.
        
        1.3a10 (2010-09-05)
        ===================
        
        Features
        --------
        
        - A new ``repoze.bfg.request.Request.add_response_callback`` API has
          been added.  This method is documented in the new
          ``repoze.bfg.request`` API chapter.  It can be used to influence
          response values before a concrete response object has been created.
        
        - The ``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 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
        
        Bug Fixes
        ---------
        
        - The route pattern registered internally for a a local "static view"
          (either via the ``static`` ZCML directive or via the
          ``add_static_view`` method of the configurator) was incorrect.  It
          was regsistered for e.g. ``static*traverse``, while it should have
          been registered for ``static/*traverse``.  Symptom: two static views
          could not reliably be added to a system when they both shared the
          same path prefix (e.g. ``/static`` and ``/static2``).
        
        Backwards Incompatibilities
        ---------------------------
        
        - The INewResponse event is now not sent to listeners if the response
          returned by view code (or a renderer) is not a "real" response
          (e.g. if it does not have ``.status``, ``.headerlist`` and
          ``.app_iter`` attribtues).
        
        Documentation
        -------------
        
        - Add an API chapter for the ``repoze.bfg.request`` module, which
          includes documentation for the ``repoze.bfg.request.Request`` class
          (the "request object").
        
        - Modify the "Request and Response" narrative chapter to reference the
          new ``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.
        
        Internal
        --------
        
        - The (internal) feature which made it possible to attach a
          ``global_response_headers`` attribute to the request (which was
          assumed to contain a sequence of header key/value pairs which would
          later be added to the response by the router), has been removed.
          The functionality of
          ``repoze.bfg.request.Request.add_response_callback`` takes its
          place.
        
        - The ``repoze.bfg.events.NewResponse`` class's construct has changed:
          it now must be created with ``(request, response)`` rather than
          simply ``(response)``.
        
        1.3a9 (2010-08-22)
        ==================
        
        Features
        --------
        
        - The Configurator now accepts a dotted name *string* to a package as
          a ``package`` constructor argument. The ``package`` argument was
          previously required to be a package *object* (not a dotted name
          string).
        
        - The ``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``.
          This feature will make it easier for future BFG versions to allow
          dotted names as arguments in places where currently only object
          references are allowed (the work to allow dotted names isntead of
          object references everywhere has not yet been done, however).
        
        - The new ``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 ``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
          ``repoze.bfg.configuration.Configurator.absolute_resource_spec``
          method resolves a potentially relative "resource specification"
          string into an absolute version.  If the value supplied as
          ``relative_spec`` is not a string, the value is returned
          unconditionally without any resolution attempted.
        
        Backwards Incompatibilities
        ---------------------------
        
        - The functions in ``repoze.bfg.renderers`` named ``render`` and
          ``render_to_response`` introduced in 1.3a6 previously took a set of
          ``**values`` arguments for the values to be passed to the renderer.
          This was wrong, as renderers don't need to accept only dictionaries
          (they can accept any type of object).  Now, the value sent to the
          renderer must be supplied as a positional argument named ``value``.
          The ``request`` argument is still a keyword argument, however.
        
        - The functions in ``repoze.bfg.renderers`` named ``render`` and
          ``render_to_response`` now accept an additonal keyword argument
          named ``package``.
        
        - The ``get_renderer`` API in ``repoze.bfg.renderers`` now accepts a
          ``package`` argument.
        
        Documentation
        -------------
        
        - The ZCML ``include`` directive docs were incorrect: they specified
          ``filename`` rather than (the correct) ``file`` as an allowable
          attribute.
        
        Internal
        --------
        
        - The ``repoze.bfg.resource.resolve_resource_spec`` function can now
          accept a package object as its ``pname`` argument instead of just a
          package name.
        
        - The ``_renderer_factory_from_name`` and ``_renderer_from_name``
          methods of the Configurator were removed.  These were never APIs.
        
        - The ``_render``, ``_render_to_response`` and ``_make_response``
          functions with ``repoze.bfg.render`` (added in 1.3a6) have been
          removed.
        
        - A new helper class ``repoze.bfg.renderers.RendererHelper`` was
          added.
        
        - The _map_view function of ``repoze.bfg.configuration`` now takes
          only a renderer_name argument instead of both a ``renderer`` and
          ``renderer``_name argument.  It also takes a ``package`` argument
          now.
        
        - Use ``imp.get_suffixes`` indirection in
          ``repoze.bfg.path.package_name`` instead of hardcoded ``.py``
          ``.pyc`` and ``.pyo`` to use for comparison when attemtping to
          decide if a directory is a package.
        
        - Make tests runnable again under Jython (although they do not all
          pass currently).
        
        - The reify decorator now maintains the docstring of the function it
          wraps.
        
        1.3a8 (2010-08-08)
        ==================
        
        Features
        --------
        
        - New public interface: ``repoze.bfg.exceptions.IExceptionResponse``.
          This interface is provided by all internal exception classes (such
          as ``repoze.bfg.exceptions.NotFound`` and
          ``repoze.bfg.exceptions.Forbidden``), instances of which are both
          exception objects and can behave as WSGI response objects.  This
          interface is made public so that exception classes which are also
          valid WSGI response factories can be configured to implement them or
          exception instances which are also or response instances can be
          configured to provide them.
        
        - New API class: ``repoze.bfg.view.AppendSlashNotFoundViewFactory``.
        
          There can only be one Not Found view in any ``repoze.bfg``
          application.  Even if you use
          ``repoze.bfg.view.append_slash_notfound_view`` as the Not Found
          view, ``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 you only
          need redirections to slash-appended route URLs, you may use the
          ``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
          ``repoze.bfg.view.AppendSlashNotFoundViewFactory`` class as the Not
          Found view, supplying the notfound view callable as the first
          argument to its constructor.  For instance::
        
               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).
        
        Documentation
        --------------
        
        - Expanded the "Cleaning Up After a Request" section of the URL
          Dispatch narrative chapter.
        
        - Expanded the "Redirecting to Slash-Appended Routes" section of the
          URL Dispatch narrative chapter.
        
        Internal
        --------
        
        - Previously, two default view functions were registered at
          Configurator setup (one for ``repoze.bfg.exceptions.NotFound`` named
          ``default_notfound_view`` and one for
          ``repoze.bfg.exceptions.Forbidden`` named
          ``default_forbidden_view``) to render internal exception responses.
          Those default view functions have been removed, replaced with a
          generic default view function which is registered at Configurator
          setup for the ``repoze.bfg.interfaces.IExceptionResponse`` interface
          that simply returns the exception instance; the ``NotFound`` and
          ``Forbidden`` classes are now still exception factories but they are
          also response factories which generate instances that implement the
          new ``repoze.bfg.interfaces.IExceptionResponse`` interface.
        
        1.3a7 (2010-08-01)
        ==================
        
        Features
        --------
        
        - The ``repoze.bfg.configuration.Configurator.add_route`` API now
          returns the route object that was added.
        
        - A ``repoze.bfg.events.subscriber`` decorator was added.  This
          decorator decorates module-scope functions, which are then treated
          as event listeners after a scan() is performed.  See the Events
          narrative documentation chapter and the ``repoze.bfg.events`` module
          documentation for more information.
        
        Bug Fixes
        ---------
        
        - When adding a view for a route which did not yet exist ("did not yet
          exist" meaning, temporally, a view was added with a route name for a
          route which had not yet been added via add_route), the value of the
          ``custom_predicate`` argument to ``add_view`` was lost.  Symptom:
          wrong view matches when using URL dispatch and custom view
          predicates together.
        
        - Pattern matches for a ``:segment`` marker in a URL dispatch route
          pattern now always match at least one character.  See "Backwards
          Incompatibilities" below in this changelog.
        
        Backwards Incompatibilities
        ---------------------------
        
        - 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.
        
        Documentation
        --------------
        
        - Added description of the ``repoze.bfg.events.subscriber`` decorator
          to the Events narrative chapter.
        
        - Added ``repoze.bfg.events.subscriber`` API documentation to
          ``repoze.bfg.events`` API docs.
        
        - Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By
          Default; BFG Does Not" to the "Design Defense" chapter.
        
        1.3a6 (2010-07-25)
        ==================
        
        Features
        --------
        
        - New argument to ``repoze.bfg.configuration.Configurator.add_route``
          and the ``route`` ZCML directive: ``traverse``.  If you would like
          to cause the ``context`` to be something other than the ``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).
        
          The syntax of the ``traverse`` argument is the same as it is for
          ``path``. For example, if the ``path`` provided is
          ``articles/:article/edit``, and the ``traverse`` argument provided
          is ``/:article``, when a request comes in that causes the route to
          match in such a way that the ``article`` match value is '1' (when
          the request URI is ``/articles/1/edit``), the traversal path will be
          generated as ``/1``.  This means that the root object's
          ``__getitem__`` will be called with the name ``1`` during the
          traversal phase.  If the ``1`` object exists, it will become the
          ``context`` of the request.  The Traversal narrative has more
          information about traversal.
        
          If the traversal path contains segment marker names which are not
          present in the path argument, a runtime error will occur.  The
          ``traverse`` pattern should not contain segment markers that do not
          exist in the ``path``.
        
          A similar combining of routing and traversal is available when a
          route is matched which contains a ``*traverse`` remainder marker in
          its path.  The ``traverse`` argument allows you to associate route
          patterns with an arbitrary traversal path without using a a
          ``*traverse`` remainder marker; instead you can use other match
          information.
        
          Note that the ``traverse`` argument is ignored when attached to a
          route that has a ``*traverse`` remainder marker in its path.
        
        - A new method of the ``Configurator`` exists:
          ``set_request_factory``.  If used, this method will set the factory
          used by the ``repoze.bfg`` router to create all request objects.
        
        - The ``Configurator`` constructor takes an additional argument:
          ``request_factory``.  If used, this argument will set the factory
          used by the ``repoze.bfg`` router to create all request objects.
        
        - The ``Configurator`` constructor takes an additional argument:
          ``request_factory``.  If used, this argument will set the factory
          used by the ``repoze.bfg`` router to create all request objects.
        
        - A new method of the ``Configurator`` exists:
          ``set_renderer_globals_factory``.  If used, this method will set the
          factory used by the ``repoze.bfg`` router to create renderer
          globals.
        
        - A new method of the ``Configurator`` exists: ``get_settings``.  If
          used, this method will return the current settings object (performs
          the same job as the ``repoze.bfg.settings.get_settings`` API).
        
        - The ``Configurator`` constructor takes an additional argument:
          ``renderer_globals_factory``.  If used, this argument will set the
          factory used by the ``repoze.bfg`` router to create renderer
          globals.
        
        - Add ``repoze.bfg.renderers.render``,
          ``repoze.bfg.renderers.render_to_response`` and
          ``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 ``repoze.bfg.chameleon_zpt`` and
          ``repoze.bfg.chameleon_text`` is now discouraged (although not
          deprecated).  The code the backing older templating-system-specific
          APIs now calls into the newer ``repoze.bfg.renderer`` code.
        
        - The ``repoze.bfg.configuration.Configurator.testing_add_template``
          has been renamed to ``testing_add_renderer``.  A backwards
          compatibility alias is present using the old name.
        
        Documentation
        -------------
        
        - The ``Hybrid`` narrative chapter now contains a description of the
          ``traverse`` route argument.
        
        - The ``Hooks`` narrative chapter now contains sections about
          changing the request factory and adding a renderer globals factory.
        
        - The API documentation includes a new module:
          ``repoze.bfg.renderers``.
        
        - The ``Templates`` chapter was updated; all narrative that used
          templating-specific APIs within examples to perform rendering (such
          as the ``repoze.bfg.chameleon_zpt.render_template_to_response``
          method) was changed to use ``repoze.bfg.renderers.render_*``
          functions.
        
        Bug Fixes
        ---------
        
        - The ``header`` predicate (when used as either a view predicate or a
          route predicate) had a problem when specified with a name/regex
          pair.  When the header did not exist in the headers dictionary, the
          regex match could be fed ``None``, causing it to throw a
          ``TypeError: expected string or buffer`` exception.  Now, the
          predicate returns False as intended.
        
        Deprecations
        ------------
        
        - 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
          ``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 ``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 ``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 ``repoze.bfg.renderers`` module.
        
        Backwards Incompatibilities
        ---------------------------
        
        - 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 ``repoze.bfg.exceptions.NotFound`` 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
          ``repoze.bfg.configuration.Configurator.testing_add_renderer`` (or,
          alternately the deprecated
          ``repoze.bfg.testing.registerTemplateRenderer`` or
          ``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::
        
            config = Configurator()
            config.testing_add_renderer('karl.views:templates/snippets.pt')
        
          This will register a basic dummy renderer for this particular
          missing template.  The ``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 ``setup_registry()`` method of the Configurator .  Eg::
        
            reg = MyRegistry()
            config = Configurator(registry=reg)
            config.setup_registry()
        
          Calling ``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 ``repoze.bfg.testing`` APIs name ``setUp`` or
          ``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 ``testing_register_renderer``
          or ``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 *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).
        
        1.3a5 (2010-07-14)
        ==================
        
        Features
        --------
        
        - New internal exception: ``repoze.bfg.exceptions.URLDecodeError``.
          This URL is a subclass of the built-in Python exception named
          ``UnicodeDecodeError``.
        
        - When decoding a URL segment to Unicode fails, the exception raised
          is now ``repoze.bfg.exceptions.URLDecodeError`` instead of
          ``UnicodeDecodeError``.  This makes it possible to register an
          exception view invoked specifically when ``repoze.bfg`` cannot
          decode a URL.
        
        Bug Fixes
        ---------
        
        - Fix regression in
          ``repoze.bfg.configuration.Configurator.add_static_view``.  Before
          1.3a4, view names that contained a slash were supported as route
          prefixes. 1.3a4 broke this by trying to treat them as full URLs.
        
        Documentation
        -------------
        
        - The ``repoze.bfg.exceptions.URLDecodeError`` exception was added to
          the exceptions chapter of the API documentation.
        
        Backwards Incompatibilities
        ----------------------------
        
        - in previous releases, when a URL could not be decoded from UTF-8
          during traversal, a ``TypeError`` was raised.  Now the error which
          is raised is a ``repoze.bfg.exceptions.URLDecodeError``.
        
        1.3a4 (2010-07-03)
        ==================
        
        Features
        --------
        
        - Undocumented hook: make ``get_app`` and ``get_root`` of the
          ``repoze.bfg.paster.BFGShellCommand`` hookable in cases where
          endware may interfere with the default versions.
        
        - In earlier versions, a custom route predicate associated with a url
          dispatch route (each of the predicate functions fed to the
          ``custom_predicates`` argument of
          ``repoze.bfg.configuration.Configurator.add_route``) has always
          required a 2-positional argument signature, e.g. ``(context,
          request)``.  Before this release, the ``context`` argument was
          always ``None``.
        
          As of this release, the first argument passed to a predicate is now
          a dictionary conventionally named ``info`` consisting of ``route``,
          and ``match``.  ``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.
        
          This is useful when predicates need access to the route match.  For
          example::
        
            def any_of(segment_name, *args):
                def predicate(info, request):
                    if info['match'][segment_name] in args:
                        return True
                return predicate
        
            num_one_two_or_three = any_of('num, 'one', 'two', 'three')
        
            add_route('num', '/:num', custom_predicates=(num_one_two_or_three,))
        
          The ``route`` object is an object that has two useful attributes:
          ``name`` and ``path``.  The ``name`` attribute is the route name.
          The ``path`` attribute is the route pattern.  An example of using
          the route in a set of route predicates::
        
            def twenty_ten(info, request):
                if info['route'].name in ('ymd', 'ym', 'y'):
                    return info['match']['year'] == '2010'
        
            add_route('y', '/:year', custom_predicates=(twenty_ten,))
            add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,))
            add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,))
        
        - The ``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
          ``repoze.bfg.configuration.Configurator.add_static_view``.  When the
          name argument is a URL, the ``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.
        
        Documentation
        -------------
        
        - The authorization chapter of the ZODB Wiki Tutorial
          (docs/tutorials/bfgwiki) was changed to demonstrate authorization
          via a group rather than via a direct username (thanks to Alex
          Marandon).
        
        - The authorization chapter of the SQLAlchemy Wiki Tutorial
          (docs/tutorials/bfgwiki2) was changed to demonstrate authorization
          via a group rather than via a direct username.
        
        - Redirect requests for tutorial sources to
          http://docs.repoze.org/bfgwiki-1.3 and
          http://docs.repoze.org/bfgwiki2-1.3/ respectively.
        
        - A section named ``Custom Route Predicates`` was added to the URL
          Dispatch narrative chapter.
        
        - The Static Resources chapter has been updated to mention using
          ``static_url`` to generate URLs to external webservers.
        
        Internal
        --------
        
        - Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new
          abstraction revolving around the (still-internal)
          ``repoze.bfg.static.StaticURLInfo`` helper class.
        
        1.3a3 (2010-05-01)
        ==================
        
        Paster Templates
        ----------------
        
        - The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer
          register a ``handle_teardown`` event listener which calls
          ``DBSession.remove``.  This was found by Chris Withers to be
          unnecessary.
        
        Documentation
        -------------
        
        - The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation
          was changed to remove the ``handle_teardown`` event listener which
          calls ``DBSession.remove``.
        
        - Any mention of the ``handle_teardown`` event listener as used by the
          paster templates was removed from the URL Dispatch narrative chapter.
        
        - A section entitled Detecting Available Languages was added to the
          i18n narrative docs chapter.
        
        1.3a2 (2010-04-28)
        ==================
        
        Features
        --------
        
        - A locale negotiator no longer needs to be registered explicitly. The
          default locale negotiator at
          ``repoze.bfg.i18n.default_locale_negotiator`` is now used
          unconditionally as... um, the default locale negotiator.
        
        - The default locale negotiator has become more complex.
        
          * First, the negotiator looks for the ``_LOCALE_`` attribute of
            the request object (possibly set by a view or an event listener).
          
          * Then it looks for the ``request.params['_LOCALE_']`` value.
        
          * Then it looks for the ``request.cookies['_LOCALE_']`` value.
        
        Backwards Incompatibilities
        ---------------------------
        
        - The default locale negotiator now looks for the parameter named
          ``_LOCALE_`` rather than a parameter named ``locale`` in
          ``request.params``.
        
        Behavior Changes
        ----------------
        
        - A locale negotiator may now return ``None``, signifying that the
          default locale should be used.
        
        Documentation
        -------------
        
        - Documentation concerning locale negotiation in the
          Internationalizationa and Localization chapter was updated.
        
        - Expanded portion of i18n narrative chapter docs which discuss
          working with gettext files.
        
        1.3a1 (2010-04-26)
        ==================
        
        Features
        --------
        
        - Added "exception views".  When you use an exception (anything that
          inherits from the Python ``Exception`` builtin) as view context
          argument, e.g.::
        
              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 ``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::
        
              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 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.
        
          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.
        
          The feature can be used with any view registration mechanism
          (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view``
          styles).
        
          This feature was kindly contributed by Andrey Popp.
        
        - Use "Venusian" (`http://docs.repoze.org/venusian
          <http://docs.repoze.org/venusian>`_) to perform ``bfg_view``
          decorator scanning rather than relying on a BFG-internal decorator
          scanner.  (Truth be told, Venusian is really just a generalization
          of the BFG-internal decorator scanner).
        
        - Internationalization and localization features as documented in the
          narrative documentation chapter entitled ``Internationalization and
          Localization``.
        
        - A new deployment setting named ``default_locale_name`` was added.
          If this string is present as a Paster ``.ini`` file option, it will
          be considered the default locale name.  The default locale name is
          used during locale-related operations such as language translation.
        
        - 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
          all new projects.
        
        - Add a new method of the Configurator named ``derive_view`` which 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.
          See the ``derive_view`` method in the
          ``repoze.bfg.configuration.Configurator`` docs.
        
        ZCML
        ----
        
        - Add a ``translationdir`` ZCML directive to support localization.
        
        - Add a ``localenegotiator`` ZCML directive to support localization.
        
        Deprecations
        ------------
        
        -  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.
        
        Dependencies
        ------------
        
        - A new install-time dependency on the ``venusian`` distribution was
          added.
        
        - A new install-time dependency on the ``translationstring``
          distribution was added.
        
        - Chameleon 1.2.3 or better is now required (internationalization and
          per-template debug settings).
        
        Internal
        --------
        
        - View registrations and lookups are now done with three "requires"
          arguments instead of two to accomodate orthogonality of exception
          views.
        
        - The ``repoze.bfg.interfaces.IForbiddenView`` and
          ``repoze.bfg.interfaces.INotFoundView`` interfaces were removed;
          they weren't APIs and they became vestigial with the addition of
          exception views.
        
        - Remove ``repoze.bfg.compat.pkgutil_26.py`` and import alias
          ``repoze.bfg.compat.walk_packages``.  These were only required by
          internal scanning machinery; Venusian replaced the internal scanning
          machinery, so these are no longer required.
        
        Documentation
        -------------
        
        - Exception view documentation was added to the ``Hooks`` narrative
          chapter.
        
        - A new narrative chapter entitled ``Internationalization and
          Localization`` was added.
        
        - The "Environment Variables and ``ini`` File Settings" chapter was
          changed: documentation about the ``default_locale_name`` setting was
          added.
        
        - A new API chapter for the ``repoze.bfg.i18n`` module was added.
        
        - Documentation for the new ``translationdir`` and
          ``localenegotiator`` ZCML directives were added.
        
        - A section was added to the Templates chapter entitled "Nicer
          Exceptions in Templates" describing the result of setting
          ``debug_templates = true``.
        
        Paster Templates
        ----------------
        
        - All paster templates now create a ``setup.cfg`` which includes
          commands related to nose testing and Babel message catalog
          extraction/compilation.
        
        - A ``default_locale_name = en`` setting was added to each existing paster
          template.
        
        - A ``debug_templates = true`` setting was added to each existing
          paster template.
        
        Licensing
        ---------
        
        - The Edgewall (BSD) license was added to the LICENSES.txt file, as
          some code in the ``repoze.bfg.i18n`` derives from Babel source.
        
        
Keywords: web wsgi bfg
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Framework :: BFG
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Classifier: License :: Repoze Public License
