Pyramid

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

Bug Fixes
---------

- An incorrect ZCML conflict would be encountered when the
``request_param`` predicate attribute was used on the ZCML ``view``
directive if any two otherwise same-predicated views had the
combination of a predicate value with an ``=`` sign and one without
(e.g. ``a`` vs. ``a=123``).

Features
--------

- In previous versions of BFG, the "root factory" (the ``get_root``
callable passed to ``make_app`` or a function pointed to by the
``factory`` attribute of a route) was called with a "bare" WSGI
environment. In this version, and going forward, it will be called
with a ``request`` object. The request object passed to the factory
implements dictionary-like methods in such a way that existing root
factory code which expects to be passed an environ will continue to
work.

- The ``__call__`` of a plugin "traverser" implementation (registered
as an adapter for ``ITraverser`` or ``ITraverserFactory``) will now
receive a *request* as the single argument to its ``__call__``
method. In previous versions it was passed a WSGI ``environ``
object. The request object passed to the factory implements
dictionary-like methods in such a way that existing traverser code
which expects to be passed an environ will continue to work.

- The ZCML ``route`` directive's attributes ``xhr``,
``request_method``, ``path_info``, ``request_param``, ``header`` and
``accept`` are now *route* predicates rather than *view* predicates.
If one or more of these predicates is specified in the route
configuration, all of the predicates must return true for the route
to match a request. If one or more of the route predicates
associated with a route returns ``False`` when checked during a
request, the route match fails, and the next match in the routelist
is tried. This differs from the previous behavior, where no route
predicates existed and all predicates were considered view
predicates, because in that scenario, the next route was not tried.

Documentation
-------------

- Various changes were made to narrative and API documentation
supporting the change from passing a request rather than an environ
to root factories and traversers.

Internal
--------

- The request implements dictionary-like methods that mutate and query
the WSGI environ. This is only for the purpose of backwards
compatibility with root factories which expect an ``environ`` rather
than a request.

- The ``repoze.bfg.request.create_route_request_factory`` function,
which returned a request factory was removed in favor of a
``repoze.bfg.request.route_request_interface`` function, which
returns an interface.

- The ``repoze.bfg.request.Request`` class, which is a subclass of
``webob.Request`` now defines its own ``__setattr__``,
``__getattr__`` and ``__delattr__`` methods, which override the
default WebOb behavior. The default WebOb behavior stores
attributes of the request in ``self.environ['webob.adhoc_attrs']``,
and retrieves them from that dictionary during a ``__getattr__``.
This behavior was undesirable for speed and "expectation" reasons.
Now attributes of the ``request`` are stored in ``request.__dict__``
(as you otherwise might expect from an object that did not override
these methods).

- The router no longer calls ``repoze.bfg.traversal._traverse`` and
does its work "inline" (speed).

- Reverse the order in which the router calls the request factory and
the root factory. The request factory is now called first; the
resulting request is passed to the root factory.

- The ``repoze.bfg.request.request_factory`` function has been
removed. Its functionality is no longer required.

- The "routes root factory" that wraps the default root factory when
there are routes mentioned in the configuration now attaches an
interface to the request via ``zope.interface.directlyProvides``.
This replaces logic in the (now-gone)
``repoze.bfg.request.request_factory`` function.

- The ``route`` and ``view`` ZCML directives now register an interface
as a named utility (retrieved from
``repoze.bfg.request.route_request_interface``) rather than a
request factory (the previous return value of the now-missing
``repoze.bfg.request.create_route_request_factory``.

- The ``repoze.bfg.functional`` module was renamed to
``repoze.bfg.compat``.

Backwards Incompatibilities
---------------------------

- Explicitly revert the feature introduced in 1.1a8: where the name
``root`` is available as an attribute of the request before a
NewRequest event is emitted. This makes some potential future
features impossible, or at least awkward (such as grouping traversal
and view lookup into a single adapter lookup).

- The ``containment``, ``attr`` and ``renderer`` attributes of the
``route`` ZCML directive were removed.

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

Features
--------

- Add ``path_info`` view configuration predicate.

- ``paster bfgshell`` now supports IPython if it's available for
import. Thanks to Daniel Holth for the initial patch.

- Add ``repoze.bfg.testing.registerSettings`` API, which is documented
in the "repoze.bfg.testing" API chapter. This allows for
registration of "settings" values obtained via
``repoze.bfg.settings.get_settings()`` for use in unit tests.

- The name ``root`` is available as an attribute of the request
slightly earlier now (before a NewRequest event is emitted).
``root`` is the result of the application "root factory".

- Added ``max_age`` parameter to ``authtktauthenticationpolicy`` ZCML
directive. If this value is set, it must be an integer representing
the number of seconds which the auth tkt cookie will survive.
Mainly, its existence allows the auth_tkt cookie to survive across
browser sessions.

Bug Fixes
---------

- Fix bug encountered during "scan" (when ``<scan ..>`` directive is
used in ZCML) introduced in 1.1a7. Symptom: ``AttributeError:
object has no attribute __provides__`` raised at startup time.

- The ``reissue_time`` argument to the ``authtktauthenticationpolicy``
ZCML directive now actually works. When it is set to an integer
value, an authticket set-cookie header is appended to the response
whenever a request requires authentication and 'now' minus the
authticket's timestamp is greater than ``reissue_time`` seconds.

Documentation
-------------

- Add a chapter titled "Request and Response" to the narrative
documentation, content cribbed from the WebOb documentation.

- Call out predicate attributes of ZCML directive within "Views"
chapter.

- Fix route_url documentation (``_query`` argument documented as
``query`` and ``_anchor`` argument documented as ``anchor``).

Backwards Incompatibilities
---------------------------

- The ``authtkt`` authentication policy ``remember`` method now no
longer honors ``token`` or ``userdata`` keyword arguments.

Internal
--------

- Change how ``bfg_view`` decorator works when used as a class method
decorator. In 1.1a7, the``scan``directive actually tried to grope
every class in scanned package at startup time, calling ``dir``
against each found class, and subsequently invoking ``getattr``
against each thing found by ``dir`` to see if it was a method. This
led to some strange symptoms (e.g. ``AttributeError: object has no
attribute __provides__``), and was generally just a bad idea. Now,
instead of groping classes for methods at startup time, we just
cause the ``bfg_view`` decorator itself to populate the method's
class' ``__dict__`` when it is used as a method decorator. This
also requires a nasty _getframe thing but it's slightly less nasty
than the startup time groping behavior. This is essentially a
reversion back to 1.1a6 "grokking" behavior plus some special magic
for using the ``bfg_view`` decorator as method decorator inside the
``bfg_view`` class itself.

- The router now checks for a ``global_response_headers`` attribute of
the request object before returning a response. If this value
exists, it is presumed to be a sequence of two-tuples, representing
a set of headers to append to the 'normal' response headers. This
feature is internal, rather than exposed externally, because it's
unclear whether it will stay around in the long term. It was added
to support the ``reissue_time`` feature of the authtkt
authentication policy.

- The interface ITraverserFactory is now just an alias for ITraverser.

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

Features
--------

- More than one ``bfg_view`` decorator may now be stacked on top of
any number of others. Each invocation of the decorator registers a
single view configuration. For instance, the following combination
of decorators and a function will register two view configurations
for the same view callable::

from repoze.bfg.view import bfg_view

bfg_view(name='edit')
bfg_view(name='change')
def edit(context, request):
pass

This makes it possible to associate more than one view configuration
with a single callable without requiring any ZCML.

- The ``bfg_view`` decorator can now be used against a class method::

from webob import Response
from repoze.bfg.view import bfg_view

class MyView(object):
def __init__(self, context, request):
self.context = context
self.request = request

bfg_view(name='hello')
def amethod(self):
return Response('hello from %s!' % self.context)

When the bfg_view decorator is used against a class method, a view
is registered for the *class* (it's a "class view" where the "attr"
happens to be the name of the method it is attached to), so the
class it's defined within must have a suitable constructor: one that
accepts ``context, request`` or just ``request``.

Documentation
-------------

- Added ``Changing the Traverser`` and ``Changing How
:mod:`repoze.bfg.url.model_url` Generates a URL`` to the "Hooks"
narrative chapter of the docs.

Internal
--------

- Remove ``ez_setup.py`` and imports of it within ``setup.py``. In
the new world, and as per virtualenv setup instructions, people will
already have either setuptools or distribute.

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

Features
--------

- Add ``xhr``, ``accept``, and ``header`` view configuration
predicates to ZCML view declaration, ZCML route declaration, and
``bfg_view`` decorator. See the ``Views`` narrative documentation
chapter for more information about these predicates.

- Add ``setUp`` and ``tearDown`` functions to the
``repoze.bfg.testing`` module. Using ``setUp`` in a test setup and
``tearDown`` in a test teardown is now the recommended way to do
component registry setup and teardown. Previously, it was
recommended that a single function named
``repoze.bfg.testing.cleanUp`` be called in both the test setup and
tear down. ``repoze.bfg.testing.cleanUp`` still exists (and will
exist "forever" due to its widespread use); it is now just an alias
for ``repoze.bfg.testing.setUp`` and is nominally deprecated.

- The BFG component registry is now available in view and event
subscriber code as an attribute of the request
ie. ``request.registry``. This fact is currently undocumented
except for this note, because BFG developers never need to interact
with the registry directly anywhere else.

- The BFG component registry now inherits from ``dict``, meaning that
it can optionally be used as a simple dictionary. *Component*
registrations performed against it via e.g. ``registerUtility``,
``registerAdapter``, and similar API methods are kept in a
completely separate namespace than its dict members, so using the
its component API methods won't effect the keys and values in the
dictionary namespace. Likewise, though the component registry
"happens to be" a dictionary, use of mutating dictionary methods
such as ``__setitem__`` will have no influence on any component
registrations made against it. In other words, the registry object
you obtain via e.g. ``repoze.bfg.threadlocal.get_current_registry``
or ``request.registry`` happens to be both a component registry and
a dictionary, but using its component-registry API won't impact data
added to it via its dictionary API and vice versa. This is a
forward compatibility move based on the goals of "marco".

- Expose and document ``repoze.bfg.testing.zcml_configure`` API. This
function populates a component registry from a ZCML file for testing
purposes. It is documented in the "Unit and Integration Testing"
chapter.

Documentation
-------------

- Virtual hosting narrative docs chapter updated with info about
``mod_wsgi``.

- Point all index URLs at the literal 1.1 index (this alpha cycle may
go on a while).

- Various tutorial test modules updated to use
``repoze.bfg.testing.setUp`` and ``repoze.bfg.testing.tearDown``
methods in order to encourage this as best practice going forward.

- Added "Creating Integration Tests" section to unit testing narrative
documentation chapter. As a result, the name of the unittesting
chapter is now "Unit and Integration Testing".

Backwards Incompatibilities
---------------------------

- Importing ``getSiteManager`` and ``get_registry`` from
``repoze.bfg.registry`` is no longer supported. These imports were
deprecated in repoze.bfg 1.0. Import of ``getSiteManager`` should
be done as ``from zope.component import getSiteManager``. Import of
``get_registry`` should be done as ``from repoze.bfg.threadlocal
import get_current_registry``. This was done to prevent a circular
import dependency.

- Code bases which alternately invoke both
``zope.testing.cleanup.cleanUp`` and ``repoze.bfg.testing.cleanUp``
(treating them equivalently, using them interchangeably) in the
setUp/tearDown of unit tests will begin to experience test failures
due to lack of test isolation. The "right" mechanism is
``repoze.bfg.testing.cleanUp`` (or the combination of
``repoze.bfg.testing.setUp`` and
``repoze.bfg.testing.tearDown``). but a good number of legacy
codebases will use ``zope.testing.cleanup.cleanUp`` instead. We
support ``zope.testing.cleanup.cleanUp`` but not in combination with
``repoze.bfg.testing.cleanUp`` in the same codebase. You should use
one or the other test cleanup function in a single codebase, but not
both.

Internal
--------

- Created new ``repoze.bfg.configuration`` module which assumes
responsibilities previously held by the ``repoze.bfg.registry`` and
``repoze.bfg.router`` modules (avoid a circular import dependency).

- The result of the ``zope.component.getSiteManager`` function in unit
tests set up with ``repoze.bfg.testing.cleanUp`` or
``repoze.bfg.testing.setUp`` will be an instance of
``repoze.bfg.registry.Registry`` instead of the global
``zope.component.globalregistry.base`` registry. This also means
that the threadlocal ZCA API functions such as ``getAdapter`` and
``getUtility`` as well as internal BFG machinery (such as
``model_url`` and ``route_url``) will consult this registry within
unit tests. This is a forward compatibility move based on the goals
of "marco".

- Removed ``repoze.bfg.testing.addCleanUp`` function and associated
module-scope globals. This was never an API.

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

Documentation
-------------

- Change "Traversal + ZODB" and "URL Dispatch + SQLAlchemy" Wiki
tutorials to make use of the new-to-1.1 "renderer" feature (return
dictionaries from all views).

- Add tests to the "URL Dispatch + SQLAlchemy" tutorial after the
"view" step.

- Added a diagram of model graph traversal to the "Traversal"
narrative chapter of the documentation.

- An ``exceptions`` API chapter was added, documenting the new
``repoze.bfg.exceptions`` module.

- Describe "request-only" view calling conventions inside the
urldispatch narrative chapter, where it's most helpful.

- Add a diagram which explains the operation of the BFG router to the
"Router" narrative chapter.

Features
--------

- Add a new ``repoze.bfg.testing`` API: ``registerRoute``, for
registering routes to satisfy calls to
e.g. ``repoze.bfg.url.route_url`` in unit tests.

- The ``notfound`` and ``forbidden`` ZCML directives now accept the
following additional attributes: ``attr``, ``renderer``, and
``wrapper``. These have the same meaning as they do in the context
of a ZCML ``view`` directive.

- For behavior like Django's ``APPEND_SLASH=True``, use the
``repoze.bfg.view.append_slash_notfound_view`` view as the Not Found
view in your application. When this view is the Not Found view
(indicating that no view was found), and any routes have been
defined in the configuration of your application, if the value of
``PATH_INFO`` does not already end in a slash, and if the value of
``PATH_INFO`` *plus* a slash matches any route's path, do an HTTP
redirect to the slash-appended PATH_INFO. Note that this will
*lose* ``POST`` data information (turning it into a GET), so you
shouldn't rely on this to redirect POST requests.

- Speed up ``repoze.bfg.location.lineage`` slightly.

- Speed up ``repoze.bfg.encode.urlencode`` (nee'
``repoze.bfg.url.urlencode``) slightly.

- Speed up ``repoze.bfg.traversal.model_path``.

- Speed up ``repoze.bfg.traversal.model_path_tuple`` slightly.

- Speed up ``repoze.bfg.traversal.traverse`` slightly.

- Speed up ``repoze.bfg.url.model_url`` slightly.

- Speed up ``repoze.bfg.url.route_url`` slightly.

- Sped up ``repoze.bfg.traversal.ModelGraphTraverser:__call__``
slightly.

- Minor speedup of ``repoze.bfg.router.Router.__call__``.

- New ``repoze.bfg.exceptions`` module was created to house exceptions
that were previously sprinkled through various modules.

Internal
--------

- Move ``repoze.bfg.traversal._url_quote`` into ``repoze.bfg.encode``
as ``url_quote``.

Deprecations
------------

- The import of ``repoze.bfg.view.NotFound`` is deprecated in favor of
``repoze.bfg.exceptions.NotFound``. The old location still
functions, but emits a deprecation warning.

- The import of ``repoze.bfg.security.Unauthorized`` is deprecated in
favor of ``repoze.bfg.exceptions.Forbidden``. The old location
still functions but emits a deprecation warning. The rename from
``Unauthorized`` to ``Forbidden`` brings parity to the name of
the exception and the system view it invokes when raised.

Backwards Incompatibilities
---------------------------

- We previously had a Unicode-aware wrapper for the
``urllib.urlencode`` function named ``repoze.bfg.url.urlencode``
which delegated to the stdlib function, but which marshalled all
unicode values to utf-8 strings before calling the stdlib version.
A newer replacement now lives in ``repoze.bfg.encode`` The
replacement does not delegate to the stdlib.

The replacement diverges from the stdlib implementation and the
previous ``repoze.bfg.url`` url implementation inasmuch as its
``doseq`` argument is now a decoy: it always behaves in the
``doseq=True`` way (which is the only sane behavior) for speed
purposes.

The old import location (``repoze.bfg.url.urlencode``) still
functions and has not been deprecated.

- In 0.8a7, the return value expected from an object implementing
``ITraverserFactory`` was changed from a sequence of values to a
dictionary containing the keys ``context``, ``view_name``,
``subpath``, ``traversed``, ``virtual_root``, ``virtual_root_path``,
and ``root``. Until now, old-style traversers which returned a
sequence have continued to work but have generated a deprecation
warning. In this release, traversers which return a sequence
instead of a dictionary will no longer work.

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

Bug Fixes
---------

- On 64-bit Linux systems, views that were members of a multiview
(orderings of views with predicates) were not evaluated in the
proper order. Symptom: in a configuration that had two views with
the same name but one with a ``request_method=POST`` predicate and
one without, the one without the predicate would be called
unconditionally (even if the request was a POST request). Thanks
much to Sebastien Douche for providing the buildbots that pointed
this out.

Documentation
-------------

- Added a tutorial which explains how to use ``repoze.session``
(ZODB-based sessions) in a ZODB-based repoze.bfg app.

- Added a tutorial which explains how to add ZEO to a ZODB-based
``repoze.bfg`` application.

- Added a tutorial which explains how to run a ``repoze.bfg``
application under `mod_wsgi <https://modwsgi.readthedocs.io/en/develop/>`_.
See "Running a repoze.bfg Application under mod_wsgi" in the
tutorials section of the documentation.

Features
--------

- Add a ``repoze.bfg.url.static_url`` API which is capable of
generating URLs to static resources defined by the ``<static>`` ZCML
directive. See the "Views" narrative chapter's section titled
"Generating Static Resource URLs" for more information.

- Add a ``string`` renderer. This renderer converts a non-Response
return value of any view callble into a string. It is documented in
the "Views" narrative chapter.

- Give the ``route`` ZCML directive the ``view_attr`` and
``view_renderer`` parameters (bring up to speed with 1.1a3
features). These can also be spelled as ``attr`` and ``renderer``.

Backwards Incompatibilities
---------------------------

- An object implementing the ``IRenderer`` interface (and
``ITemplateRenderer`, which is a subclass of ``IRenderer``) must now
accept an extra ``system`` argument in its ``__call__`` method
implementation. Values computed by the system (as opposed to by the
view) are passed by the system in the ``system`` parameter, which
will always be a dictionary. Keys in the dictionary include:
``view`` (the view object that returned the value),
``renderer_name`` (the template name or simple name of the
renderer), ``context`` (the context object passed to the view), and
``request`` (the request object passed to the view). Previously
only ITemplateRenderers received system arguments as elements inside
the main ``value`` dictionary.

Internal
--------

- The way ``bfg_view`` declarations are scanned for has been modified.
This should have no external effects.

- Speed: do not register an ITraverserFactory in configure.zcml;
instead rely on queryAdapter and a manual default to
ModelGraphTraverser.

- Speed: do not register an IContextURL in configure.zcml; instead
rely on queryAdapter and a manual default to TraversalContextURL.

- General speed microimprovements for helloworld benchmark: replace
try/excepts with statements which use 'in' keyword.