Pyramid

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

Bug Fixes
---------

- ``config.add_view(<aninstancemethod>)`` raised AttributeError involving
``__text__``. See https://github.com/Pylons/pyramid/issues/461

- Remove references to do-nothing ``pyramid.debug_templates`` setting in all
Pyramid-provided ``.ini`` files. This setting previously told Chameleon to
render better exceptions; now Chameleon always renders nice exceptions
regardless of the value of this setting.

Scaffolds
---------

- The ``alchemy`` scaffold now shows an informative error message in the
browser if the person creating the project forgets to run the
initialization script.

- The ``alchemy`` scaffold initialization script is now called
``initialize_<projectname>_db`` instead of ``populate_<projectname>``.

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

- Wiki tutorials improved due to collaboration at PyCon US 2012 sprints.

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

Bug Fixes
---------

- The method ``pyramid.request.Request.partial_application_url`` is no longer
in the API docs. It was meant to be a private method; its publication in
the documentation as an API method was a mistake, and it has been renamed
to something private.

- When a static view was registered using an absolute filesystem path on
Windows, the ``request.static_url`` function did not work to generate URLs
to its resources. Symptom: "No static URL definition matching
c:\\foo\\bar\\baz".

- Make all tests pass on Windows XP.

- Bug in ACL authentication checking on Python 3: the ``permits`` and
``principals_allowed_by_permission`` method of
``pyramid.authorization.ACLAuthenticationPolicy`` could return an
inappropriate ``True`` value when a permission on an ACL was a string
rather than a sequence, and then only if the ACL permission string was a
substring of the ``permission`` value passed to the function.

This bug effects no Pyramid deployment under Python 2; it is a bug that
exists only in deployments running on Python 3. It has existed since
Pyramid 1.3a1.

This bug was due to the presence of an ``__iter__`` attribute on strings
under Python 3 which is not present under strings in Python 2.

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

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.

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

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.

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

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.

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

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.