Pyramid

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

Deprecation Warning and Import Alias Removals
---------------------------------------------

- Since version 0.6.1, a deprecation warning has been emitted when the
name ``model_url`` is imported from the ``repoze.bfg.traversal``
module. This import alias (and the deprecation warning) has been
removed. Any import of the ``model_url`` function will now need to
be done from ``repoze.bfg.url``; any import of the name
``model_url`` from ``repoze.bfg.traversal`` will now fail. This was
done to remove a dependency on zope.deferredimport.

- Since version 0.6.5, a deprecation warning has been emitted when the
name ``RoutesModelTraverser`` is imported from the
``repoze.bfg.traversal`` module. This import alias (and the
deprecation warning) has been removed. Any import of the
``RoutesModelTraverser`` class will now need to be done from
``repoze.bfg.urldispatch``; any import of the name
``RoutesModelTraverser`` from ``repoze.bfg.traversal`` will now
fail. This was done to remove a dependency on zope.deferredimport.

Features
--------

- This release of ``repoze.bfg`` is "C-free". This means it has no
hard dependencies on any software that must be compiled from C
source at installation time. In particular, ``repoze.bfg`` no
longer depends on the ``lxml`` package.

This change has introduced some backwards incompatibilities,
described in the "Backwards Incompatibilities" section below.

- This release was tested on Windows XP. It appears to work fine and
all the tests pass.

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

Incompatibilities related to making ``repoze.bfg`` "C-free":

- Removed the ``repoze.bfg.chameleon_genshi`` module, and thus support
for Genshi-style chameleon templates. Genshi-style Chameleon
templates depend upon ``lxml``, which is implemented in C (as
opposed to pure Python) and the ``repoze.bfg`` core is "C-free" as
of this release. You may get Genshi-style Chameleon support back by
installing the ``repoze.bfg.chameleon_genshi`` package availalable
from https://pypi.org/project/repoze.bfg.chameleon_genshi/.
All existing code that depended on the ``chameleon_genshi`` module
prior to this release of ``repoze.bfg`` should work without change
after this addon is installed.

- Removed the ``repoze.bfg.xslt`` module and thus support for XSL
templates. The ``repoze.bfg.xslt`` module depended upon ``lxml``,
which is implemented in C, and the ``repoze.bfg`` core is "C-free"
as of this release. You bay get XSL templating back by installing
the ``repoze.bfg.xslt`` package available from
``http://svn.repoze.org/repoze.bfg.xslt/`` (broken link)
(also available in the index
at ``http://dist.repoze.org/bfg/0.8/simple)`` (broken link).
All existing code that
depended upon the ``xslt`` module prior to this release of
``repoze.bfg`` should work without modification after this addon is
installed.

- Removed the ``repoze.bfg.interfaces.INodeTemplateRenderer``
interface and the an old b/w compat aliases from that interface to
``repoze.bfg.interfaces.INodeTemplate``. This interface must now be
imported from the ``repoze.bfg.xslt.interfaces`` package after
installation of the ``repoze.bfg.xslt`` addon package described
above as ``repoze.bfg.interfaces.INodeTemplateRenderer``. This
interface was never part of any public API.

Other backwards incompatibilities:

- The ``render_template`` function in ``repoze.bfg.chameleon_zpt``
returns Unicode instead of a string. Likewise, the individual
values returned by the iterable created by the
``render_template_to_iterable`` function are also each Unicode.
This is actually a backwards incompatibility inherited from our new
use of the combination of ``chameleon.core`` 1.0b32 (the
non-lxml-depending version) and ``chameleon.zpt`` 1.0b16+ ; the
``chameleon.zpt`` PageTemplateFile implementation used to return a
string, but now returns Unicode.

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

Index-Related
-------------

- The canonical package index location for ``repoze.bfg`` has changed.
The "old" index (``http://dist.repoze.org/lemonade/dev/simple``) (broken link)
has been superseded by a new index location
``http://dist.repoze.org/bfg/current/simple`` (broken link).
The installation
documentation has been updated as well as the ``setup.cfg`` file in
this package. The "lemonade" index still exists, but it is not
guaranteed to have the latest BFG software in it, nor will it be
maintained in the future.

Features
--------

- The "paster create" templates have been modified to use links to the
new "bfg.repoze.org" and "docs.repoze.org" websites.

- Added better documentation for virtual hosting at a URL prefix
within the virtual hosting docs chapter.

- The interface for ``repoze.bfg.interfaces.ITraverser`` and the
built-in implementations that implement the interface
(``repoze.bfg.traversal.ModelGraphTraverser``, and
``repoze.bfg.urldispatch.RoutesModelTraverser``) now expect the
``__call__`` method of an ITraverser to return 3 additional
arguments: ``traversed``, ``virtual_root``, and
``virtual_root_path`` (the old contract was that the ``__call__``
method of an ITraverser returned; three arguments, the contract new
is that it returns six). ``traversed`` will be a sequence of
Unicode names that were traversed (including the virtual root path,
if any) or ``None`` if no traversal was performed, ``virtual_root``
will be a model object representing the virtual root (or the
physical root if traversal was not performed), and
``virtual_root_path`` will be a sequence representing the virtual
root path (a sequence of Unicode names) or ``None`` if traversal was
not performed.

Six arguments are now returned from BFG ITraversers. They are
returned in this order: ``context``, ``view_name``, ``subpath``,
``traversed``, ``virtual_root``, and ``virtual_root_path``.

Places in the BFG code which called an ITraverser continue to accept
a 3-argument return value, although BFG will generate and log a
warning when one is encountered.

- The request object now has the following attributes: ``traversed``
(the sequence of names traversed or ``None`` if traversal was not
performed), ``virtual_root`` (the model object representing the
virtual root, including the virtual root path if any), and
``virtual_root_path`` (the seuquence of names representing the
virtual root path or ``None`` if traversal was not performed).

- A new decorator named ``wsgiapp2`` was added to the
``repoze.bfg.wsgi`` module. This decorator performs the same
function as ``repoze.bfg.wsgi.wsgiapp`` except it fixes up the
``SCRIPT_NAME``, and ``PATH_INFO`` environment values before
invoking the WSGI subapplication.

- The ``repoze.bfg.testing.DummyRequest`` object now has default
attributes for ``traversed``, ``virtual_root``, and
``virtual_root_path``.

- The RoutesModelTraverser now behaves more like the Routes
"RoutesMiddleware" object when an element in the match dict is named
``path_info`` (usually when there's a pattern like
``http://foo/*path_info``). When this is the case, the
``PATH_INFO`` environment variable is set to the value in the match
dict, and the ``SCRIPT_NAME`` is appended to with the prefix of the
original ``PATH_INFO`` not including the value of the new variable.

- The notfound debug now shows the traversed path, the virtual root,
and the virtual root path too.

- Speed up / clarify 'traversal' module's 'model_path', 'model_path_tuple',
and '_model_path_list' functions.

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

- In previous releases, the ``repoze.bfg.url.model_url``,
``repoze.bfg.traversal.model_path`` and
``repoze.bfg.traversal.model_path_tuple`` functions always ignored
the ``__name__`` argument of the root object in a model graph (
effectively replacing it with a leading ``/`` in the returned value)
when a path or URL was generated. The code required to perform this
operation was not efficient. As of this release, the root object in
a model graph *must* have a ``__name__`` attribute that is either
``None`` or the empty string (``''``) for URLs and paths to be
generated properly from these APIs. If your root model object has a
``__name__`` argument that is not one of these values, you will need
to change your code for URLs and paths to be generated properly. If
your model graph has a root node with a string ``__name__`` that is
not null, the value of ``__name__`` will be prepended to every path
and URL generated.

- The ``repoze.bfg.location.LocationProxy`` class and the
``repoze.bfg.location.ClassAndInstanceDescr`` class have both been
removed in order to be able to eventually shed a dependency on
``zope.proxy``. Neither of these classes was ever an API.

- In all previous releases, the ``repoze.bfg.location.locate``
function worked like so: if a model did not explicitly provide the
``repoze.bfg.interfaces.ILocation`` interface, ``locate`` returned a
``LocationProxy`` object representing ``model`` with its
``__parent__`` attribute assigned to ``parent`` and a ``__name__``
attribute assigned to ``__name__``. In this release, the
``repoze.bfg.location.locate`` function simply jams the ``__name__``
and ``__parent__`` attributes on to the supplied model
unconditionally, no matter if the object implements ILocation or
not, and it never returns a proxy. This was done because the
LocationProxy behavior has now moved into an add-on package
(``repoze.bfg.traversalwrapper``), in order to eventually be able to
shed a dependency on ``zope.proxy``.

- In all previous releases, by default, if traversal was used (as
opposed to URL-dispatch), and the root object supplied
the``repoze.bfg.interfaces.ILocation`` interface, but the children
returned via its ``__getitem__`` returned an object that did not
implement the same interface, ``repoze.bfg`` provided some
implicit help during traversal. This traversal feature wrapped
subobjects from the root (and thereafter) that did not implement
``ILocation`` in proxies which automatically provided them with a
``__name__`` and ``__parent__`` attribute based on the name being
traversed and the previous object traversed. This feature has now
been removed from the base ``repoze.bfg`` package for purposes of
eventually shedding a dependency on ``zope.proxy``.

In order to re-enable the wrapper behavior for older applications
which cannot be changed, register the "traversalwrapper"
``ModelGraphTraverser`` as the traversal policy, rather than the
default ``ModelGraphTraverser``. To use this feature, you will need
to install the ``repoze.bfg.traversalwrapper`` package (an add-on
package, available at
https://pypi.org/project/repoze.bfg.traversalwrapper/) Then change your
application's ``configure.zcml`` to include the following stanza:

<adapter
factory="repoze.bfg.traversalwrapper.ModelGraphTraverser"
provides="repoze.bfg.interfaces.ITraverserFactory"
for="*"
/>

When this ITraverserFactory is used instead of the default, no
object in the graph (even the root object) must supply a
``__name__`` or ``__parent__`` attribute. Even if subobjects
returned from the root *do* implement the ILocation interface,
these will still be wrapped in proxies that override the object's
"real" ``__parent__`` and ``__name__`` attributes.

See also changes to the "Models" chapter of the documentation (in
the "Location-Aware Model Instances") section.

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

Bug Fixes
---------

- Fix a bug in ``repoze.bfg.wsgi.HTTPException``: the content length
was returned as an int rather than as a string.

- Add explicit dependencies on ``zope.deferredimport``,
``zope.deprecation``, and ``zope.proxy`` for forward compatibility
reasons (``zope.component`` will stop relying on
``zope.deferredimport`` soon and although we use it directly, it's
only a transitive dependency, and ''zope.deprecation`` and
``zope.proxy`` are used directly even though they're only transitive
dependencies as well).

- Using ``model_url`` or ``model_path`` against a broken model graph
(one with models that had a non-root model with a ``__name__`` of
``None``) caused an inscrutable error to be thrown: ( if not
``_must_quote[cachekey].search(s): TypeError: expected string or
buffer``). Now URLs and paths generated against graphs that have
None names in intermediate nodes will replace the None with the
empty string, and, as a result, the error won't be raised. Of
course the URL or path will still be bogus.

Features
--------

- Make it possible to have ``testing.DummyTemplateRenderer`` return
some nondefault string representation.

- Added a new ``anchor`` keyword argument to ``model_url``. If
``anchor`` is present, its string representation will be used
as a named anchor in the generated URL (e.g. if ``anchor`` is
passed as ``foo`` and the model URL is
``http://example.com/model/url``, the generated URL will be
``http://example.com/model/url#foo``).

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

- The default request charset encoding is now ``utf-8``. As a result,
the request machinery will attempt to decode values from the utf-8
encoding to Unicode automatically when they are obtained via
``request.params``, ``request.GET``, and ``request.POST``. The
previous behavior of BFG was to return a bytestring when a value was
accessed in this manner. This change will break form handling code
in apps that rely on values from those APIs being considered
bytestrings. If you are manually decoding values from form
submissions in your application, you'll either need to change the
code that does that to expect Unicode values from
``request.params``, ``request.GET`` and ``request.POST``, or you'll
need to explicitly reenable the previous behavior. To reenable the
previous behavior, add the following to your application's
``configure.zcml``::

<subscriber for="repoze.bfg.interfaces.INewRequest"
handler="repoze.bfg.request.make_request_ascii"/>

See also the documentation in the "Views" chapter of the BFG docs
entitled "Using Views to Handle Form Submissions (Unicode and
Character Set Issues)".

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

- Add a section to the narrative Views chapter entitled "Using Views
to Handle Form Submissions (Unicode and Character Set Issues)"
explaining implicit decoding of form data values.

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

Bug Fixes
---------

- lru cache was unstable under concurrency (big surprise!) when it
tried to redelete a key in the cache that had already been deleted.
Symptom: line 64 in put:del data[oldkey]:KeyError: '/some/path'.
Now we just ignore the key error if we can't delete the key (it has
already been deleted).

- Empty location names in model paths when generating a URL using
``repoze.bfg.model_url`` based on a model obtained via traversal are
no longer ignored in the generated URL. This means that if a
non-root model object has a ``__name__`` of ``''``, the URL will
reflect it (e.g. ``model_url`` will generate ``http://foo/bar//baz``
if an object with the ``__name__`` of ``''`` is a child of bar and
the parent of baz). URLs generated with empty path segments are,
however, still irresolveable by the model graph traverser on request
ingress (the traverser strips empty path segment names).

Features
--------

- Microspeedups of ``repoze.bfg.traversal.model_path``,
``repoze.bfg.traversal.model_path_tuple``,
``repoze.bfg.traversal.quote_path_segment``, and
``repoze.bfg.url.urlencode``.

- add zip_safe = false to setup.cfg.

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

- Add a note to the ``repoze.bfg.traversal.quote_path_segment`` API
docs about caching of computed values.

Implementation Changes
----------------------

- Simplification of
``repoze.bfg.traversal.TraversalContextURL.__call__`` (it now uses
``repoze.bfg.traversal.model_path`` instead of rolling its own
path-generation).

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

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

- The ``repoze.bfg.traversal.model_path`` API now returns a *quoted*
string rather than a string represented by series of unquoted
elements joined via ``/`` characters. Previously it returned a
string or unicode object representing the model path, with each
segment name in the path joined together via ``/`` characters,
e.g. ``/foo /bar``. Now it returns a string, where each segment is
a UTF-8 encoded and URL-quoted element e.g. ``/foo%20/bar``. This
change was (as discussed briefly on the repoze-dev maillist)
necessary to accommodate model objects which themselves have
``__name__`` attributes that contain the ``/`` character.

For people that have no models that have high-order Unicode
``__name__`` attributes or ``__name__`` attributes with values that
require URL-quoting with in their model graphs, this won't cause any
issue. However, if you have code that currently expects
``model_path`` to return an unquoted string, or you have an existing
application with data generated via the old method, and you're too
lazy to change anything, you may wish replace the BFG-imported
``model_path`` in your code with this function (this is the code of
the "old" ``model_path`` implementation)::

from repoze.bfg.location import lineage

def i_am_too_lazy_to_move_to_the_new_model_path(model, *elements):
rpath = []
for location in lineage(model):
if location.__name__:
rpath.append(location.__name__)
path = '/' + '/'.join(reversed(rpath))
if elements:
suffix = '/'.join(elements)
path = '/'.join([path, suffix])
return path

- The ``repoze.bfg.traversal.find_model`` API no longer implicitly
converts unicode representations of a full path passed to it as a
Unicode object into a UTF-8 string. Callers should either use
prequoted path strings returned by
``repoze.bfg.traversal.model_path``, or tuple values returned by the
result of ``repoze.bfg.traversal.model_path_tuple`` or they should
use the guidelines about passing a string ``path`` argument
described in the ``find_model`` API documentation.

Bugfixes
--------

- Each argument contained in ``elements`` passed to
``repoze.bfg.traversal.model_path`` will now have any ``/``
characters contained within quoted to ``%2F`` in the returned
string. Previously, ``/`` characters in elements were left unquoted
(a bug).

Features
--------

- A ``repoze.bfg.traversal.model_path_tuple`` API was added. This API
is an alternative to ``model_path`` (which returns a string);
``model_path_tuple`` returns a model path as a tuple (much like
Zope's ``getPhysicalPath``).

- A ``repoze.bfg.traversal.quote_path_segment`` API was added. This
API will quote an individual path segment (string or unicode
object). See the ``repoze.bfg.traversal`` API documentation for
more information.

- The ``repoze.bfg.traversal.find_model`` API now accepts "path
tuples" (see the above note regarding ``model_path_tuple``) as well
as string path representations (from
``repoze.bfg.traversal.model_path``) as a ``path`` argument.

- Add ` `renderer`` argument (defaulting to None) to
``repoze.bfg.testing.registerDummyRenderer``. This makes it
possible, for instance, to register a custom renderer that raises an
exception in a unit test.

Implementation Changes
----------------------

- Moved _url_quote function back to ``repoze.bfg.traversal`` from
``repoze.bfg.url``. This is not an API.

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

Features
--------

- The ``repoze.bfg.url.model_url`` API now works against contexts
derived from Routes URL dispatch (``Routes.util.url_for`` is called
under the hood).

- "Virtual root" support for traversal-based applications has been
added. Virtual root support is useful when you'd like to host some
model in a ``repoze.bfg`` model graph as an application under a
URL pathname that does not include the model path itself. For more
information, see the (new) "Virtual Hosting" chapter in the
documentation.

- A ``repoze.bfg.traversal.virtual_root`` API has been added. When
called, it returns the virtual root object (or the physical root
object if no virtual root has been specified).

Implementation Changes
----------------------

- ``repoze.bfg.traversal.RoutesModelTraverser`` has been moved to
``repoze.bfg.urldispatch``.

- ``model_url`` URL generation is now performed via an adapter lookup
based on the context and the request.

- ZCML which registers two adapters for the ``IContextURL`` interface
has been added to the configure.zcml in ``repoze.bfg.includes``.