Pyramid

===================

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

===================

Bug Fixes
---------

- Process the response callbacks and the NewResponse event earlier, to
enable mutations to the response to take effect.

===================

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 local "static view"
(either via the ``static`` ZCML directive or via the
``add_static_view`` method of the configurator) was incorrect. It
was registered 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)``.

==================

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 instead 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 additional 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 attempting 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.

==================

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.

==================

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.