Pyramid

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

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

- Rather than prepare the "stock" implementations of the ZCML directives
from the ``zope.configuration`` package for use under ``repoze.bfg``,
``repoze.bfg`` now makes available the implementations of directives
from the ``repoze.zcml`` package (see https://pypi.org/project/repoze.zcml/).
As a result, the ``repoze.bfg`` package now depends on the
``repoze.zcml`` package, and no longer depends directly on the
``zope.component``, ``zope.configuration``, ``zope.interface``, or
``zope.proxy`` packages.

The primary reason for this change is to enable us to eventually reduce
the number of inappropriate ``repoze.bfg`` Zope package dependencies,
as well as to shed features of dependent package directives that don't
make sense for ``repoze.bfg``.

Note that currently the set of requirements necessary to use bfg has not
changed. This is due to inappropriate Zope package requirements in
``chameleon.zpt``, which will hopefully be remedied soon. NOTE: in
lemonade index a 1.0b8-repozezcml0 package exists which does away with
these requirements.

- BFG applications written prior to this release which expect the "stock"
``zope.component`` ZCML directive implementations (e.g. ``adapter``,
``subscriber``, or ``utility``) to function now must either 1) include
the ``meta.zcml`` file from ``zope.component`` manually (e.g. ``<include
package="zope.component" file="meta.zcml">``) and include the
``zope.security`` package as an ``install_requires`` dependency or 2)
change the ZCML in their applications to use the declarations from
`repoze.zcml <https://pypi.org/project/repoze.zcml/>`_ instead of the stock
declarations. ``repoze.zcml`` only makes available the ``adapter``,
``subscriber`` and ``utility`` directives.

In short, if you've got an existing BFG application, after this
update, if your application won't start due to an import error for
"zope.security", the fastest way to get it working again is to add
``zope.security`` to the "install_requires" of your BFG
application's ``setup.py``, then add the following ZCML anywhere
in your application's ``configure.zcml``::

<include package="zope.component" file="meta.zcml">

Then re-``setup.py develop`` or reinstall your application.

- The ``http://namespaces.repoze.org/bfg`` XML namespace is now the default
XML namespace in ZCML for paster-generated applications. The docs have
been updated to reflect this.

- The copies of BFG's ``meta.zcml`` and ``configure.zcml`` were removed
from the root of the ``repoze.bfg`` package. In 0.3.6, a new package
named ``repoze.bfg.includes`` was added, which contains the "correct"
copies of these ZCML files; the ones that were removed were for backwards
compatibility purposes.

- The BFG ``view`` ZCML directive no longer calls
``zope.component.interface.provideInterface`` for the ``for`` interface.
We don't support ``provideInterface`` in BFG because it mutates the
global registry.

Other
-----

- The minimum requirement for ``chameleon.core`` is now 1.0b13. The
minimum requirement for ``chameleon.zpt`` is now 1.0b8. The minimum
requirement for ``chameleon.genshi`` is now 1.0b2.

- Updated paster template "ez_setup.py" to one that requires setuptools
0.6c9.

- Turn ``view_execution_permitted`` from the ``repoze.bfg.view`` module
into a documented API.

- Doc cleanups.

- Documented how to create a view capable of serving static resources.

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

- Speed up ``traversal.model_url`` execution by using a custom url quoting
function instead of Python's ``urllib.quote``, by caching URL path
segment quoting and encoding results, by disusing Python's
``urlparse.urljoin`` in favor of a simple string concatenation, and by
using ``ob.__class__ is unicode`` rather than ``isinstance(ob, unicode)``
in one strategic place.

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

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

- In the past, during traversal, the ModelGraphTraverser (the default
traverser) always passed each URL path segment to any ``__getitem__``
method of a model object as a byte string (a ``str`` object). Now, by
default the ModelGraphTraverser attempts to decode the path segment to
Unicode (a ``unicode`` object) using the UTF-8 encoding before passing it
to the ``__getitem__`` method of a model object. This makes it possible
for model objects to be dumber in ``__getitem__`` when trying to resolve
a subobject, as model objects themselves no longer need to try to divine
whether or not to try to decode the path segment passed by the
traverser.

Note that since 0.5.4, URLs generated by repoze.bfg's ``model_url`` API
will contain UTF-8 encoded path segments as necessary, so any URL
generated by BFG itself will be decodeable by the traverser. If another
application generates URLs to a BFG application, to be resolved
successfully, it should generate the URL with UTF-8 encoded path segments
to be successfully resolved. The decoder is not at all magical: if a
non-UTF-8-decodeable path segment (e.g. one encoded using UTF-16 or some
other insanity) is passed in the URL, BFG will raise a ``TypeError`` with
a message indicating it could not decode the path segment.

To turn on the older behavior, where path segments were not decoded to
Unicode before being passed to model object ``__getitem__`` by the
traverser, and were passed as a raw byte string, set the
``unicode_path_segments`` configuration setting to a false value in your
BFG application's section of the paste .ini file, for example::

unicode_path_segments = False

Or start the application using the ``BFG_UNICODE_PATH_SEGMENT`` envvar
set to a false value::

BFG_UNICODE_PATH_SEGMENTS=0

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

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

- URL-quote "extra" element names passed in as ``**elements`` to the
``traversal.model_url`` API. If any of these names is a Unicode string,
encode it to UTF-8 before URL-quoting. This is a slight backwards
incompatibility that will impact you if you were already UTF-8 encoding
or URL-quoting the values you passed in as ``elements`` to this API.

Bugfixes
--------

- UTF-8 encode each segment in the model path used to generate a URL before
url-quoting it within the ``traversal.model_url`` API. This is a bugfix,
as Unicode cannot always be successfully URL-quoted.

Features
--------

- Make it possible to run unit tests using a buildout-generated Python
"interpreter".

- Add ``request.root`` to ``router.Router`` in order to have easy access to
the application root.

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

- Remove the ``ITestingTemplateRenderer`` interface. When
``testing.registerDummyRenderer`` is used, it instead registers a dummy
implementation using ``ITemplateRenderer`` interface, which is checked
for when the built-in templating facilities do rendering. This change
also allows developers to make explicit named utility registrations in
the ZCML registry against ``ITemplateRenderer``; these will be found
before any on-disk template is looked up.

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

- The component registration handler for views (functions or class
instances) now observes component adaptation annotations (see
``zope.component.adaptedBy``) and uses them before the fallback values
for ``for_`` and ``request_type``. This change does not affect existing
code insomuch as the code does not rely on these defaults when an
annotation is set on the view (unlikely). This means that for a
new-style class you can do ``zope.component.adapts(ISomeContext,
ISomeRequest)`` at class scope or at module scope as a decorator to a
bfg view function you can do ``zope.component.adapter(ISomeContext,
ISomeRequest)``. This differs from r.bfg.convention inasmuch as you
still need to put something in ZCML for the registrations to get done;
it's only the defaults that will change if these declarations exist.

- Strip all slashes from end and beginning of path in clean_path within
traversal machinery.