From 6141a7339840701fcff98a4e36152d998b59ea84 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Thu, 8 Mar 2018 12:29:42 -0500 Subject: Mark changelogs as ReST, for better Github rendering. --- BFG_HISTORY.rst | 6373 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ BFG_HISTORY.txt | 6373 ------------------------------------------------------ CHANGES.rst | 40 + CHANGES.txt | 40 - HISTORY.rst | 5773 +++++++++++++++++++++++++++++++++++++++++++++++++ HISTORY.txt | 5773 ------------------------------------------------- MANIFEST.in | 2 +- docs/changes.rst | 6 +- setup.py | 2 +- 9 files changed, 12191 insertions(+), 12191 deletions(-) create mode 100644 BFG_HISTORY.rst delete mode 100644 BFG_HISTORY.txt create mode 100644 CHANGES.rst delete mode 100644 CHANGES.txt create mode 100644 HISTORY.rst delete mode 100644 HISTORY.txt diff --git a/BFG_HISTORY.rst b/BFG_HISTORY.rst new file mode 100644 index 000000000..8a2d40920 --- /dev/null +++ b/BFG_HISTORY.rst @@ -0,0 +1,6373 @@ +1.3b1 (2010-10-25) +================== + +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. + +1.3a15 (2010-09-30) +=================== + +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. + +1.3a14 (2010-09-14) +=================== + +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. + +1.3a13 (2010-09-14) +=================== + +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. + +1.3a12 (2010-09-08) +=================== + +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``. + +1.3a11 (2010-09-05) +=================== + +Bug Fixes +--------- + +- Process the response callbacks and the NewResponse event earlier, to + enable mutations to the response to take effect. + +1.3a10 (2010-09-05) +=================== + +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 regsistered 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)``. + +1.3a9 (2010-08-22) +================== + +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 isntead 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 additonal 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 attemtping 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. + +1.3a8 (2010-08-08) +================== + +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. + +1.3a7 (2010-08-01) +================== + +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. + +1.3a6 (2010-07-25) +================== + +Features +-------- + +- New argument to ``repoze.bfg.configuration.Configurator.add_route`` + and the ``route`` ZCML directive: ``traverse``. If you would like + to cause the ``context`` to be something other than the ``root`` + object when this route matches, you can spell a traversal pattern as + the ``traverse`` argument. This traversal pattern will be used as + the traversal path: traversal will begin at the root object implied + by this route (either the global root, or the object returned by the + ``factory`` associated with this route). + + The syntax of the ``traverse`` argument is the same as it is for + ``path``. For example, if the ``path`` provided is + ``articles/:article/edit``, and the ``traverse`` argument provided + is ``/:article``, when a request comes in that causes the route to + match in such a way that the ``article`` match value is '1' (when + the request URI is ``/articles/1/edit``), the traversal path will be + generated as ``/1``. This means that the root object's + ``__getitem__`` will be called with the name ``1`` during the + traversal phase. If the ``1`` object exists, it will become the + ``context`` of the request. The Traversal narrative has more + information about traversal. + + If the traversal path contains segment marker names which are not + present in the path argument, a runtime error will occur. The + ``traverse`` pattern should not contain segment markers that do not + exist in the ``path``. + + A similar combining of routing and traversal is available when a + route is matched which contains a ``*traverse`` remainder marker in + its path. The ``traverse`` argument allows you to associate route + patterns with an arbitrary traversal path without using a + ``*traverse`` remainder marker; instead you can use other match + information. + + Note that the ``traverse`` argument is ignored when attached to a + route that has a ``*traverse`` remainder marker in its path. + +- A new method of the ``Configurator`` exists: + ``set_request_factory``. If used, this method will set the factory + used by the ``repoze.bfg`` router to create all request objects. + +- The ``Configurator`` constructor takes an additional argument: + ``request_factory``. If used, this argument will set the factory + used by the ``repoze.bfg`` router to create all request objects. + +- The ``Configurator`` constructor takes an additional argument: + ``request_factory``. If used, this argument will set the factory + used by the ``repoze.bfg`` router to create all request objects. + +- A new method of the ``Configurator`` exists: + ``set_renderer_globals_factory``. If used, this method will set the + factory used by the ``repoze.bfg`` router to create renderer + globals. + +- A new method of the ``Configurator`` exists: ``get_settings``. If + used, this method will return the current settings object (performs + the same job as the ``repoze.bfg.settings.get_settings`` API). + +- The ``Configurator`` constructor takes an additional argument: + ``renderer_globals_factory``. If used, this argument will set the + factory used by the ``repoze.bfg`` router to create renderer + globals. + +- Add ``repoze.bfg.renderers.render``, + ``repoze.bfg.renderers.render_to_response`` and + ``repoze.bfg.renderers.get_renderer`` functions. These are + imperative APIs which will use the same rendering machinery used by + view configurations with a ``renderer=`` attribute/argument to + produce a rendering or renderer. Because these APIs provide a + central API for all rendering, they now form the preferred way to + perform imperative template rendering. Using functions named + ``render_*`` from modules such as ``repoze.bfg.chameleon_zpt`` and + ``repoze.bfg.chameleon_text`` is now discouraged (although not + deprecated). The code the backing older templating-system-specific + APIs now calls into the newer ``repoze.bfg.renderer`` code. + +- The ``repoze.bfg.configuration.Configurator.testing_add_template`` + has been renamed to ``testing_add_renderer``. A backwards + compatibility alias is present using the old name. + +Documentation +------------- + +- The ``Hybrid`` narrative chapter now contains a description of the + ``traverse`` route argument. + +- The ``Hooks`` narrative chapter now contains sections about + changing the request factory and adding a renderer globals factory. + +- The API documentation includes a new module: + ``repoze.bfg.renderers``. + +- The ``Templates`` chapter was updated; all narrative that used + templating-specific APIs within examples to perform rendering (such + as the ``repoze.bfg.chameleon_zpt.render_template_to_response`` + method) was changed to use ``repoze.bfg.renderers.render_*`` + functions. + +Bug Fixes +--------- + +- The ``header`` predicate (when used as either a view predicate or a + route predicate) had a problem when specified with a name/regex + pair. When the header did not exist in the headers dictionary, the + regex match could be fed ``None``, causing it to throw a + ``TypeError: expected string or buffer`` exception. Now, the + predicate returns False as intended. + +Deprecations +------------ + +- The ``repoze.bfg.renderers.rendered_response`` function was never an + official API, but may have been imported by extensions in the wild. + It is officially deprecated in this release. Use + ``repoze.bfg.renderers.render_to_response`` instead. + +- The following APIs are *documentation* deprecated (meaning they are + officially deprecated in documentation but do not raise a + deprecation error upon their usage, and may continue to work for an + indefinite period of time): + + In the ``repoze.bfg.chameleon_zpt`` module: ``get_renderer``, + ``get_template``, ``render_template``, + ``render_template_to_response``. The suggested alternatives are + documented within the docstrings of those methods (which are still + present in the documentation). + + In the ``repoze.bfg.chameleon_text`` module: ``get_renderer``, + ``get_template``, ``render_template``, + ``render_template_to_response``. The suggested alternatives are + documented within the docstrings of those methods (which are still + present in the documentation). + + In general, to perform template-related functions, one should now + use the various methods in the ``repoze.bfg.renderers`` module. + +Backwards Incompatibilities +--------------------------- + +- A new internal exception class (*not* an API) named + ``repoze.bfg.exceptions.PredicateMismatch`` now exists. This + exception is currently raised when no constituent view of a + multiview can be called (due to no predicate match). Previously, in + this situation, a ``repoze.bfg.exceptions.NotFound`` was raised. We + provide backwards compatibility for code that expected a + ``NotFound`` to be raised when no predicates match by causing + ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from + ``NotFound``. This will cause any exception view registered for + ``NotFound`` to be called when a predicate mismatch occurs, as was + the previous behavior. + + There is however, one perverse case that will expose a backwards + incompatibility. If 1) you had a view that was registered as a + member of a multiview 2) this view explicitly raised a ``NotFound`` + exception *in order to* proceed to the next predicate check in the + multiview, that code will now behave differently: rather than + skipping to the next view match, a NotFound will be raised to the + top-level exception handling machinery instead. For code to be + depending upon the behavior of a view raising ``NotFound`` to + proceed to the next predicate match, would be tragic, but not + impossible, given that ``NotFound`` is a public interface. + ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and + cannot be depended upon by application code, so you should not + change your view code to raise ``PredicateMismatch``. Instead, move + the logic which raised the ``NotFound`` exception in the view out + into a custom view predicate. + +- If, when you run your application's unit test suite under BFG 1.3, a + ``KeyError`` naming a template or a ``ValueError`` indicating that a + 'renderer factory' is not registered may is raised + (e.g. ``ValueError: No factory for renderer named '.pt' when looking + up karl.views:templates/snippets.pt``), you may need to perform some + extra setup in your test code. + + The best solution is to use the + ``repoze.bfg.configuration.Configurator.testing_add_renderer`` (or, + alternately the deprecated + ``repoze.bfg.testing.registerTemplateRenderer`` or + ``registerDummyRenderer``) API within the code comprising each + individual unit test suite to register a "dummy" renderer for each + of the templates and renderers used by code under test. For + example:: + + config = Configurator() + config.testing_add_renderer('karl.views:templates/snippets.pt') + + This will register a basic dummy renderer for this particular + missing template. The ``testing_add_renderer`` API actually + *returns* the renderer, but if you don't care about how the render + is used, you don't care about having a reference to it either. + + A more rough way to solve the issue exists. It causes the "real" + template implementations to be used while the system is under test, + which is suboptimal, because tests will run slower, and unit tests + won't actually *be* unit tests, but it is easier. Always ensure you + call the ``setup_registry()`` method of the Configurator . Eg:: + + reg = MyRegistry() + config = Configurator(registry=reg) + config.setup_registry() + + Calling ``setup_registry`` only has an effect if you're *passing in* + a ``registry`` argument to the Configurator constructor. + ``setup_registry`` is called by the course of normal operations + anyway if you do not pass in a ``registry``. + + If your test suite isn't using a Configurator yet, and is still + using the older ``repoze.bfg.testing`` APIs name ``setUp`` or + ``cleanUp``, these will register the renderers on your behalf. + + A variant on the symptom for this theme exists: you may already be + dutifully registering a dummy template or renderer for a template + used by the code you're testing using ``testing_register_renderer`` + or ``registerTemplateRenderer``, but (perhaps unbeknownst to you) + the code under test expects to be able to use a "real" template + renderer implementation to retrieve or render *another* template + that you forgot was being rendered as a side effect of calling the + code you're testing. This happened to work because it found the + *real* template while the system was under test previously, and now + it cannot. The solution is the same. + + It may also help reduce confusion to use a *resource specification* + to specify the template path in the test suite and code rather than + a relative path in either. A resource specification is unambiguous, + while a relative path needs to be relative to "here", where "here" + isn't always well-defined ("here" in a test suite may or may not be + the same as "here" in the code under test). + +1.3a5 (2010-07-14) +================== + +Features +-------- + +- New internal exception: ``repoze.bfg.exceptions.URLDecodeError``. + This URL is a subclass of the built-in Python exception named + ``UnicodeDecodeError``. + +- When decoding a URL segment to Unicode fails, the exception raised + is now ``repoze.bfg.exceptions.URLDecodeError`` instead of + ``UnicodeDecodeError``. This makes it possible to register an + exception view invoked specifically when ``repoze.bfg`` cannot + decode a URL. + +Bug Fixes +--------- + +- Fix regression in + ``repoze.bfg.configuration.Configurator.add_static_view``. Before + 1.3a4, view names that contained a slash were supported as route + prefixes. 1.3a4 broke this by trying to treat them as full URLs. + +Documentation +------------- + +- The ``repoze.bfg.exceptions.URLDecodeError`` exception was added to + the exceptions chapter of the API documentation. + +Backwards Incompatibilities +---------------------------- + +- in previous releases, when a URL could not be decoded from UTF-8 + during traversal, a ``TypeError`` was raised. Now the error which + is raised is a ``repoze.bfg.exceptions.URLDecodeError``. + +1.3a4 (2010-07-03) +================== + +Features +-------- + +- Undocumented hook: make ``get_app`` and ``get_root`` of the + ``repoze.bfg.paster.BFGShellCommand`` hookable in cases where + endware may interfere with the default versions. + +- In earlier versions, a custom route predicate associated with a url + dispatch route (each of the predicate functions fed to the + ``custom_predicates`` argument of + ``repoze.bfg.configuration.Configurator.add_route``) has always + required a 2-positional argument signature, e.g. ``(context, + request)``. Before this release, the ``context`` argument was + always ``None``. + + As of this release, the first argument passed to a predicate is now + a dictionary conventionally named ``info`` consisting of ``route``, + and ``match``. ``match`` is a dictionary: it represents the + arguments matched in the URL by the route. ``route`` is an object + representing the route which was matched. + + This is useful when predicates need access to the route match. For + example:: + + def any_of(segment_name, *args): + def predicate(info, request): + if info['match'][segment_name] in args: + return True + return predicate + + num_one_two_or_three = any_of('num, 'one', 'two', 'three') + + add_route('num', '/:num', custom_predicates=(num_one_two_or_three,)) + + The ``route`` object is an object that has two useful attributes: + ``name`` and ``path``. The ``name`` attribute is the route name. + The ``path`` attribute is the route pattern. An example of using + the route in a set of route predicates:: + + def twenty_ten(info, request): + if info['route'].name in ('ymd', 'ym', 'y'): + return info['match']['year'] == '2010' + + add_route('y', '/:year', custom_predicates=(twenty_ten,)) + add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,)) + add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,)) + +- The ``repoze.bfg.url.route_url`` API has changed. If a keyword + ``_app_url`` is present in the arguments passed to ``route_url``, + this value will be used as the protocol/hostname/port/leading path + prefix of the generated URL. For example, using an ``_app_url`` of + ``http://example.com:8080/foo`` would cause the URL + ``http://example.com:8080/foo/fleeb/flub`` to be returned from this + function if the expansion of the route pattern associated with the + ``route_name`` expanded to ``/fleeb/flub``. + +- It is now possible to use a URL as the ``name`` argument fed to + ``repoze.bfg.configuration.Configurator.add_static_view``. When the + name argument is a URL, the ``repoze.bfg.url.static_url`` API will + generate join this URL (as a prefix) to a path including the static + file name. This makes it more possible to put static media on a + separate webserver for production, while keeping static media + package-internal and served by the development webserver during + development. + +Documentation +------------- + +- The authorization chapter of the ZODB Wiki Tutorial + (docs/tutorials/bfgwiki) was changed to demonstrate authorization + via a group rather than via a direct username (thanks to Alex + Marandon). + +- The authorization chapter of the SQLAlchemy Wiki Tutorial + (docs/tutorials/bfgwiki2) was changed to demonstrate authorization + via a group rather than via a direct username. + +- Redirect requests for tutorial sources to + http://docs.repoze.org/bfgwiki-1.3 and + http://docs.repoze.org/bfgwiki2-1.3/ respectively. + +- A section named ``Custom Route Predicates`` was added to the URL + Dispatch narrative chapter. + +- The Static Resources chapter has been updated to mention using + ``static_url`` to generate URLs to external webservers. + +Internal +-------- + +- Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new + abstraction revolving around the (still-internal) + ``repoze.bfg.static.StaticURLInfo`` helper class. + +1.3a3 (2010-05-01) +================== + +Paster Templates +---------------- + +- The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer + register a ``handle_teardown`` event listener which calls + ``DBSession.remove``. This was found by Chris Withers to be + unnecessary. + +Documentation +------------- + +- The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation + was changed to remove the ``handle_teardown`` event listener which + calls ``DBSession.remove``. + +- Any mention of the ``handle_teardown`` event listener as used by the + paster templates was removed from the URL Dispatch narrative chapter. + +- A section entitled Detecting Available Languages was added to the + i18n narrative docs chapter. + +1.3a2 (2010-04-28) +================== + +Features +-------- + +- A locale negotiator no longer needs to be registered explicitly. The + default locale negotiator at + ``repoze.bfg.i18n.default_locale_negotiator`` is now used + unconditionally as... um, the default locale negotiator. + +- The default locale negotiator has become more complex. + + * First, the negotiator looks for the ``_LOCALE_`` attribute of + the request object (possibly set by a view or an event listener). + + * Then it looks for the ``request.params['_LOCALE_']`` value. + + * Then it looks for the ``request.cookies['_LOCALE_']`` value. + +Backwards Incompatibilities +--------------------------- + +- The default locale negotiator now looks for the parameter named + ``_LOCALE_`` rather than a parameter named ``locale`` in + ``request.params``. + +Behavior Changes +---------------- + +- A locale negotiator may now return ``None``, signifying that the + default locale should be used. + +Documentation +------------- + +- Documentation concerning locale negotiation in the + Internationalizationa and Localization chapter was updated. + +- Expanded portion of i18n narrative chapter docs which discuss + working with gettext files. + +1.3a1 (2010-04-26) +================== + +Features +-------- + +- Added "exception views". When you use an exception (anything that + inherits from the Python ``Exception`` builtin) as view context + argument, e.g.:: + + from repoze.bfg.view import bfg_view + from repoze.bfg.exceptions import NotFound + from webob.exc import HTTPNotFound + + @bfg_view(context=NotFound) + def notfound_view(request): + return HTTPNotFound() + + For the above example, when the ``repoze.bfg.exceptions.NotFound`` + exception is raised by any view or any root factory, the + ``notfound_view`` view callable will be invoked and its response + returned. + + Other normal view predicates can also be used in combination with an + exception view registration:: + + from repoze.bfg.view import bfg_view + from repoze.bfg.exceptions import NotFound + from webob.exc import HTTPNotFound + + @bfg_view(context=NotFound, route_name='home') + def notfound_view(request): + return HTTPNotFound() + + The above exception view names the ``route_name`` of ``home``, + meaning that it will only be called when the route matched has a + name of ``home``. You can therefore have more than one exception + view for any given exception in the system: the "most specific" one + will be called when the set of request circumstances which match the + view registration. The only predicate that cannot be not be used + successfully is ``name``. The name used to look up an exception + view is always the empty string. + + Existing (pre-1.3) normal views registered against objects + inheriting from ``Exception`` will continue to work. Exception + views used for user-defined exceptions and system exceptions used as + contexts will also work. + + The feature can be used with any view registration mechanism + (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view`` + styles). + + This feature was kindly contributed by Andrey Popp. + +- Use "Venusian" (`http://docs.repoze.org/venusian + `_) to perform ``bfg_view`` + decorator scanning rather than relying on a BFG-internal decorator + scanner. (Truth be told, Venusian is really just a generalization + of the BFG-internal decorator scanner). + +- Internationalization and localization features as documented in the + narrative documentation chapter entitled ``Internationalization and + Localization``. + +- A new deployment setting named ``default_locale_name`` was added. + If this string is present as a Paster ``.ini`` file option, it will + be considered the default locale name. The default locale name is + used during locale-related operations such as language translation. + +- It is now possible to turn on Chameleon template "debugging mode" + for all Chameleon BFG templates by setting a BFG-related Paster + ``.ini`` file setting named ``debug_templates``. The exceptions + raised by Chameleon templates when a rendering fails are sometimes + less than helpful. ``debug_templates`` allows you to configure your + application development environment so that exceptions generated by + Chameleon during template compilation and execution will contain + more helpful debugging information. This mode is on by default in + all new projects. + +- Add a new method of the Configurator named ``derive_view`` which can + be used to generate a BFG view callable from a user-supplied + function, instance, or class. This useful for external framework and + plugin authors wishing to wrap callables supplied by their users + which follow the same calling conventions and response conventions + as objects that can be supplied directly to BFG as a view callable. + See the ``derive_view`` method in the + ``repoze.bfg.configuration.Configurator`` docs. + +ZCML +---- + +- Add a ``translationdir`` ZCML directive to support localization. + +- Add a ``localenegotiator`` ZCML directive to support localization. + +Deprecations +------------ + +- The exception views feature replaces the need for the + ``set_notfound_view`` and ``set_forbidden_view`` methods of the + ``Configurator`` as well as the ``notfound`` and ``forbidden`` ZCML + directives. Those methods and directives will continue to work for + the foreseeable future, but they are deprecated in the + documentation. + +Dependencies +------------ + +- A new install-time dependency on the ``venusian`` distribution was + added. + +- A new install-time dependency on the ``translationstring`` + distribution was added. + +- Chameleon 1.2.3 or better is now required (internationalization and + per-template debug settings). + +Internal +-------- + +- View registrations and lookups are now done with three "requires" + arguments instead of two to accomodate orthogonality of exception + views. + +- The ``repoze.bfg.interfaces.IForbiddenView`` and + ``repoze.bfg.interfaces.INotFoundView`` interfaces were removed; + they weren't APIs and they became vestigial with the addition of + exception views. + +- Remove ``repoze.bfg.compat.pkgutil_26.py`` and import alias + ``repoze.bfg.compat.walk_packages``. These were only required by + internal scanning machinery; Venusian replaced the internal scanning + machinery, so these are no longer required. + +Documentation +------------- + +- Exception view documentation was added to the ``Hooks`` narrative + chapter. + +- A new narrative chapter entitled ``Internationalization and + Localization`` was added. + +- The "Environment Variables and ``ini`` File Settings" chapter was + changed: documentation about the ``default_locale_name`` setting was + added. + +- A new API chapter for the ``repoze.bfg.i18n`` module was added. + +- Documentation for the new ``translationdir`` and + ``localenegotiator`` ZCML directives were added. + +- A section was added to the Templates chapter entitled "Nicer + Exceptions in Templates" describing the result of setting + ``debug_templates = true``. + +Paster Templates +---------------- + +- All paster templates now create a ``setup.cfg`` which includes + commands related to nose testing and Babel message catalog + extraction/compilation. + +- A ``default_locale_name = en`` setting was added to each existing paster + template. + +- A ``debug_templates = true`` setting was added to each existing + paster template. + +Licensing +--------- + +- The Edgewall (BSD) license was added to the LICENSES.txt file, as + some code in the ``repoze.bfg.i18n`` derives from Babel source. + +1.2 (2010-02-10) +================ + +- No changes from 1.2b6. + +1.2b6 (2010-02-06) +================== + +Backwards Incompatibilities +--------------------------- + +- Remove magical feature of ``repoze.bfg.url.model_url`` which + prepended a fully-expanded urldispatch route URL before a the + model's path if it was noticed that the request had matched a route. + This feature was ill-conceived, and didn't work in all scenarios. + +Bug Fixes +--------- + +- More correct conversion of provided ``renderer`` values to resource + specification values (internal). + +1.2b5 (2010-02-04) +================== + +Bug Fixes +--------- + +- 1.2b4 introduced a bug whereby views added via a route configuration + that named a view callable and also a ``view_attr`` became broken. + Symptom: ``MyViewClass is not callable`` or the ``__call__`` of a + class was being called instead of the method named via + ``view_attr``. + +- Fix a bug whereby a ``renderer`` argument to the ``@bfg_view`` + decorator that provided a package-relative template filename might + not have been resolved properly. Symptom: inappropriate ``Missing + template resource`` errors. + +1.2b4 (2010-02-03) +================== + +Documentation +------------- + +- Update GAE tutorial to use Chameleon instead of Jinja2 (now that + it's possible). + +Bug Fixes +--------- + +- Ensure that ``secure`` flag for AuthTktAuthenticationPolicy + constructor does what it's documented to do (merge Daniel Holth's + fancy-cookies-2 branch). + +Features +-------- + +- Add ``path`` and ``http_only`` options to + AuthTktAuthenticationPolicy constructor (merge Daniel Holth's + fancy-cookies-2 branch). + +Backwards Incompatibilities +--------------------------- + +- Remove ``view_header``, ``view_accept``, ``view_xhr``, + ``view_path_info``, ``view_request_method``, ``view_request_param``, + and ``view_containment`` predicate arguments from the + ``Configurator.add_route`` argument list. These arguments were + speculative. If you need the features exposed by these arguments, + add a view associated with a route using the ``route_name`` argument + to the ``add_view`` method instead. + +- Remove ``view_header``, ``view_accept``, ``view_xhr``, + ``view_path_info``, ``view_request_method``, ``view_request_param``, + and ``view_containment`` predicate arguments from the ``route`` ZCML + directive attribute set. These attributes were speculative. If you + need the features exposed by these attributes, add a view associated + with a route using the ``route_name`` attribute of the ``view`` ZCML + directive instead. + +Dependencies +------------ + +- Remove dependency on ``sourcecodegen`` (not depended upon by + Chameleon 1.1.1+). + +1.2b3 (2010-01-24) +================== + +Bug Fixes +--------- + +- When "hybrid mode" (both traversal and urldispatch) is in use, + default to finding route-related views even if a non-route-related + view registration has been made with a more specific context. The + default used to be to find views with a more specific context first. + Use the new ``use_global_views`` argument to the route definition to + get back the older behavior. + +Features +-------- + +- Add ``use_global_views`` argument to ``add_route`` method of + Configurator. When this argument is true, views registered for *no* + route will be found if no more specific view related to the route is + found. + +- Add ``use_global_views`` attribute to ZCML ```` directive + (see above). + +Internal +-------- + +- When registering a view, register the view adapter with the + "requires" interfaces as ``(request_type, context_type)`` rather + than ``(context_type, request_type)``. This provides for saner + lookup, because the registration will always be made with a specific + request interface, but registration may not be made with a specific + context interface. In general, when creating multiadapters, you + want to order the requires interfaces so that the elements which + are more likely to be registered using specific interfaces are + ordered before those which are less likely. + +1.2b2 (2010-01-21) +================== + +Bug Fixes +--------- + +- When the ``Configurator`` is passed an instance of + ``zope.component.registry.Components`` as a ``registry`` constructor + argument, fix the instance up to have the attributes we expect of an + instance of ``repoze.bfg.registry.Registry`` when ``setup_registry`` + is called. This makes it possible to use the global Zope component + registry as a BFG application registry. + +- When WebOb 0.9.7.1 was used, a deprecation warning was issued for + the class attribute named ``charset`` within + ``repoze.bfg.request.Request``. BFG now *requires* WebOb >= 0.9.7, + and code was added so that this deprecation warning has disappeared. + +- Fix a view lookup ordering bug whereby a view with a larger number + of predicates registered first (literally first, not "earlier") for + a triad would lose during view lookup to one registered with fewer. + +- Make sure views with exactly N custom predicates are always called + before views with exactly N non-custom predicates given all else is + equal in the view configuration. + +Documentation +------------- + +- Change renderings of ZCML directive documentation. + +- Add a narrative documentation chapter: "Using the Zope Component + Architecture in repoze.bfg". + +Dependencies +------------ + +- Require WebOb >= 0.9.7 + +1.2b1 (2010-01-18) +================== + +Bug Fixes +--------- + +- In ``bfg_routesalchemy``, ``bfg_alchemy`` paster templates and the + ``bfgwiki2`` tutorial, clean up the SQLAlchemy connection by + registering a ``repoze.tm.after_end`` callback instead of relying on + a ``__del__`` method of a ``Cleanup`` class added to the WSGI + environment. The ``__del__`` strategy was fragile and caused + problems in the wild. Thanks to Daniel Holth for testing. + +Features +-------- + +- Read logging configuration from PasteDeploy config file ``loggers`` + section (and related) when ``paster bfgshell`` is invoked. + +Documentation +------------- + +- Major rework in preparation for book publication. + +1.2a11 (2010-01-05) +=================== + +Bug Fixes +--------- + +- Make ``paster bfgshell`` and ``paster create -t bfg_xxx`` work on + Jython (fix minor incompatibility with treatment of ``__doc__`` at + the class level). + +- Updated dependency on ``WebOb`` to require a version which supports + features now used in tests. + +Features +-------- + +- Jython compatibility (at least when repoze.bfg.jinja2 is used as the + templating engine; Chameleon does not work under Jython). + +- Show the derived abspath of template resource specifications in the + traceback when a renderer template cannot be found. + +- Show the original traceback when a Chameleon template cannot be + rendered due to a platform incompatibility. + +1.2a10 (2010-01-04) +=================== + +Features +-------- + +- The ``Configurator.add_view`` method now accepts an argument named + ``context``. This is an alias for the older argument named + ``for_``; it is preferred over ``for_``, but ``for_`` will continue + to be supported "forever". + +- The ``view`` ZCML directive now accepts an attribute named + ``context``. This is an alias for the older attribute named + ``for``; it is preferred over ``for``, but ``for`` will continue to + be supported "forever". + +- The ``Configurator.add_route`` method now accepts an argument named + ``view_context``. This is an alias for the older argument named + ``view_for``; it is preferred over ``view_for``, but ``view_for`` + will continue to be supported "forever". + +- The ``route`` ZCML directive now accepts an attribute named + ``view_context``. This is an alias for the older attribute named + ``view_for``; it is preferred over ``view_for``, but ``view_for`` + will continue to be supported "forever". + +Documentation and Paster Templates +---------------------------------- + +- LaTeX rendering tweaks. + +- All uses of the ``Configurator.add_view`` method that used its + ``for_`` argument now use the ``context`` argument instead. + +- All uses of the ``Configurator.add_route`` method that used its + ``view_for`` argument now use the ``view_context`` argument instead. + +- All uses of the ``view`` ZCML directive that used its ``for`` + attribute now use the ``context`` attribute instead. + +- All uses of the ``route`` ZCML directive that used its ``view_for`` + attribute now use the ``view_context`` attribute instead. + +- Add a (minimal) tutorial dealing with use of ``repoze.catalog`` in a + ``repoze.bfg`` application. + +Documentation Licensing +----------------------- + +- Loosen the documentation licensing to allow derivative works: it is + now offered under the `Creative Commons + Attribution-Noncommercial-Share Alike 3.0 United States License + `_. This is + only a documentation licensing change; the ``repoze.bfg`` software + continues to be offered under the Repoze Public License at + http://repoze.org/license.html (BSD-like). + +1.2a9 (2009-12-27) +================== + +Documentation Licensing +----------------------- + +- The *documentation* (the result of ``make `` + within the ``docs`` directory) in this release is now offered under + the Creative Commons Attribution-Noncommercial-No Derivative Works + 3.0 United States License as described by + http://creativecommons.org/licenses/by-nc-nd/3.0/us/ . This is only + a licensing change for the documentation; the ``repoze.bfg`` + software continues to be offered under the Repoze Public License + at http://repoze.org/license.html (BSD-like). + +Documentation +------------- + +- Added manual index entries to generated index. + +- Document the previously existing (but non-API) + ``repoze.bfg.configuration.Configurator.setup_registry`` method as + an official API of a ``Configurator``. + +- Fix syntax errors in various documentation code blocks. + +- Created new top-level documentation section: "ZCML Directives". + This section contains detailed ZCML directive information, some of + which was removed from various narrative chapters. + +- The LaTeX rendering of the documentation has been improved. + +- Added a "Fore-Matter" section with author, copyright, and licensing + information. + +1.2a8 (2009-12-24) +================== + +Features +-------- + +- Add a ``**kw`` arg to the ``Configurator.add_settings`` API. + +- Add ``hook_zca`` and ``unhook_zca`` methods to the ``Configurator`` + API. + +- The ``repoze.bfg.testing.setUp`` method now returns a + ``Configurator`` instance which can be used to do further + configuration during unit tests. + +Bug Fixes +--------- + +- The ``json`` renderer failed to set the response content type to + ``application/json``. It now does, by setting + ``request.response_content_type`` unless this attribute is already + set. + +- The ``string`` renderer failed to set the response content type to + ``text/plain``. It now does, by setting + ``request.response_content_type`` unless this attribute is already + set. + +Documentation +------------- + +- General documentation improvements by using better Sphinx roles such + as "class", "func", "meth", and so on. This means that there are + many more hyperlinks pointing to API documentation for API + definitions in all narrative, tutorial, and API documentation + elements. + +- Added a description of imperative configuration in various places + which only described ZCML configuration. + +- A syntactical refreshing of various tutorials. + +- Added the ``repoze.bfg.authentication``, + ``repoze.bfg.authorization``, and ``repoze.bfg.interfaces`` modules + to API documentation. + +Deprecations +------------ + +- The ``repoze.bfg.testing.registerRoutesMapper`` API (added in an + early 1.2 alpha) was deprecated. Its import now generates a + deprecation warning. + +1.2a7 (2009-12-20) +================== + +Features +-------- + +- Add four new testing-related APIs to the + ``repoze.bfg.configuration.Configurator`` class: + ``testing_securitypolicy``, ``testing_models``, + ``testing_add_subscriber``, and ``testing_add_template``. These + were added in order to provide more direct access to the + functionality of the ``repoze.bfg.testing`` APIs named + ``registerDummySecurityPolicy``, ``registerModels``, + ``registerEventListener``, and ``registerTemplateRenderer`` when a + configurator is used. The ``testing`` APIs named are nominally + deprecated (although they will likely remain around "forever", as + they are in heavy use in the wild). + +- Add a new API to the ``repoze.bfg.configuration.Configurator`` + class: ``add_settings``. This API can be used to add "settings" + (information returned within via the + ``repoze.bfg.settings.get_settings`` API) after the configurator has + been initially set up. This is most useful for testing purposes. + +- Add a ``custom_predicates`` argument to the ``Configurator`` + ``add_view`` method, the ``bfg_view`` decorator and the attribute + list of the ZCML ``view`` directive. If ``custom_predicates`` is + specified, it must be a sequence of predicate callables (a predicate + callable accepts two arguments: ``context`` and ``request`` and + returns ``True`` or ``False``). The associated view callable will + only be invoked if all custom predicates return ``True``. Use one + or more custom predicates when no existing predefined predicate is + useful. Predefined and custom predicates can be mixed freely. + +- Add a ``custom_predicates`` argument to the ``Configurator`` + ``add_route`` and the attribute list of the ZCML ``route`` + directive. If ``custom_predicates`` is specified, it must be a + sequence of predicate callables (a predicate callable accepts two + arguments: ``context`` and ``request`` and returns ``True`` or + ``False``). The associated route will match will only be invoked if + all custom predicates return ``True``, else route matching + continues. Note that the value ``context`` will always be ``None`` + when passed to a custom route predicate. Use one or more custom + predicates when no existing predefined predicate is useful. + Predefined and custom predicates can be mixed freely. + +Internal +-------- + +- Remove the ``repoze.bfg.testing.registerTraverser`` function. This + function was never an API. + +Documenation +------------ + +- Doc-deprecated most helper functions in the ``repoze.bfg.testing`` + module. These helper functions likely won't be removed any time + soon, nor will they generate a warning any time soon, due to their + heavy use in the wild, but equivalent behavior exists in methods of + a Configurator. + +1.2a6 (2009-12-18) +================== + +Features +-------- + +- The ``Configurator`` object now has two new methods: ``begin`` and + ``end``. The ``begin`` method is meant to be called before any + "configuration" begins (e.g. before ``add_view``, et. al are + called). The ``end`` method is meant to be called after all + "configuration" is complete. + + Previously, before there was imperative configuration at all (1.1 + and prior), configuration begin and end was invariably implied by + the process of loading a ZCML file. When a ZCML load happened, the + threadlocal data structure containing the request and registry was + modified before the load, and torn down after the load, making sure + that all framework code that needed ``get_current_registry`` for the + duration of the ZCML load was satisfied. + + Some API methods called during imperative configuration, (such as + ``Configurator.add_view`` when a renderer is involved) end up for + historical reasons calling ``get_current_registry``. However, in + 1.2a5 and below, the Configurator supplied no functionality that + allowed people to make sure that ``get_current_registry`` returned + the registry implied by the configurator being used. ``begin`` now + serves this purpose. Inversely, ``end`` pops the thread local + stack, undoing the actions of ``begin``. + + We make this boundary explicit to reduce the potential for confusion + when the configurator is used in different circumstances (e.g. in + unit tests and app code vs. just in initial app setup). + + Existing code written for 1.2a1-1.2a5 which does not call ``begin`` + or ``end`` continues to work in the same manner it did before. It + is however suggested that this code be changed to call ``begin`` and + ``end`` to reduce the potential for confusion in the future. + +- All ``paster`` templates which generate an application skeleton now + make use of the new ``begin`` and ``end`` methods of the + Configurator they use in their respective copies of ``run.py`` and + ``tests.py``. + +Documentation +------------- + +- All documentation that makes use of a ``Configurator`` object to do + application setup and test setup now makes use of the new ``begin`` + and ``end`` methods of the configurator. + +Bug Fixes +--------- + +- When a ``repoze.bfg.exceptions.NotFound`` or + ``repoze.bfg.exceptions.Forbidden`` *class* (as opposed to instance) + was raised as an exception within a root factory (or route root + factory), the exception would not be caught properly by the + ``repoze.bfg.`` Router and it would propagate to up the call stack, + as opposed to rendering the not found view or the forbidden view as + would have been expected. + +- When Chameleon page or text templates used as renderers were added + imperatively (via ``Configurator.add_view`` or some derivative), + they too-eagerly attempted to look up the ``reload_templates`` + setting via ``get_settings``, meaning they were always registered in + non-auto-reload-mode (the default). Each now waits until its + respective ``template`` attribute is accessed to look up the value. + +- When a route with the same name as a previously registered route was + added, the old route was not removed from the mapper's routelist. + Symptom: the old registered route would be used (and possibly + matched) during route lookup when it should not have had a chance to + ever be used. + +1.2a5 (2009-12-10) +================== + +Features +-------- + +- When the ``repoze.bfg.exceptions.NotFound`` or + ``repoze.bfg.exceptions.Forbidden`` error is raised from within a + custom root factory or the ``factory`` of a route, the appropriate + response is now sent to the requesting user agent (the result of the + notfound view or the forbidden view, respectively). When these + errors are raised from within a root factory, the ``context`` passed + to the notfound or forbidden view will be ``None``. Also, the + request will not be decorated with ``view_name``, ``subpath``, + ``context``, etc. as would normally be the case if traversal had + been allowed to take place. + +Internals +--------- + +- The exception class representing the error raised by various methods + of a ``Configurator`` is now importable as + ``repoze.bfg.exceptions.ConfigurationError``. + +Documentation +------------- + +- General documentation freshening which takes imperative + configuration into account in more places and uses glossary + references more liberally. + +- Remove explanation of changing the request type in a new request + event subscriber, as other predicates are now usually an easier way + to get this done. + +- Added "Thread Locals" narrative chapter to documentation, and added + a API chapter documenting the ``repoze.bfg.threadlocals`` module. + +- Added a "Special Exceptions" section to the "Views" narrative + documentation chapter explaining the effect of raising + ``repoze.bfg.exceptions.NotFound`` and + ``repoze.bfg.exceptions.Forbidden`` from within view code. + +Dependencies +------------ + +- A new dependency on the ``twill`` package was added to the + ``setup.py`` ``tests_require`` argument (Twill will only be + downloaded when ``repoze.bfg`` ``setup.py test`` or ``setup.py + nosetests`` is invoked). + +1.2a4 (2009-12-07) +================== + +Features +-------- + +- ``repoze.bfg.testing.DummyModel`` now accepts a new constructor + keyword argument: ``__provides__``. If this constructor argument is + provided, it should be an interface or a tuple of interfaces. The + resulting model will then provide these interfaces (they will be + attached to the constructed model via + ``zope.interface.alsoProvides``). + +Bug Fixes +--------- + +- Operation on GAE was broken, presumably because the + ``repoze.bfg.configuration`` module began to attempt to import the + ``repoze.bfg.chameleon_zpt`` and ``repoze.bfg.chameleon_text`` + modules, and these cannot be used on non-CPython platforms. It now + tolerates startup time import failures for these modules, and only + raise an import error when a template from one of these packages is + actually used. + +1.2a3 (2009-12-02) +================== + +Bug Fixes +--------- + +- The ``repoze.bfg.url.route_url`` function inappropriately passed + along ``_query`` and/or ``_anchor`` arguments to the + ``mapper.generate`` function, resulting in blowups. + +- When two views were registered with differering ``for`` interfaces + or classes, and the ``for`` of first view registered was a + superclass of the second, the ``repoze.bfg`` view machinery would + incorrectly associate the two views with the same "multiview". + Multiviews are meant to be collections of views that have *exactly* + the same for/request/viewname values, without taking inheritance + into account. Symptom: wrong view callable found even when you had + correctly specified a ``for_`` interface/class during view + configuration for one or both view configurations. + +Backwards Incompatibilities +--------------------------- + +- The ``repoze.bfg.templating`` module has been removed; it had been + deprecated in 1.1 and never actually had any APIs in it. + +1.2a2 (2009-11-29) +================== + +Bug Fixes +--------- + +- The long description of this package (as shown on PyPI) was not + valid reStructuredText, and so was not renderable. + +- Trying to use an HTTP method name string such as ``GET`` as a + ``request_type`` predicate argument caused a startup time failure + when it was encountered in imperative configuration or in a + decorator (symptom: ``Type Error: Required specification must be a + specification``). This now works again, although ``request_method`` + is now the preferred predicate argument for associating a view + configuration with an HTTP request method. + +Documentation +------------- + +- Fixed "Startup" narrative documentation chapter; it was explaining + "the old way" an application constructor worked. + +1.2a1 (2009-11-28) +================== + +Features +-------- + +- An imperative configuration mode. + + A ``repoze.bfg`` application can now begin its life as a single + Python file. Later, the application might evolve into a set of + Python files in a package. Even later, it might start making use of + other configuration features, such as ``ZCML``. But neither the use + of a package nor the use of non-imperative configuration is required + to create a simple ``repoze.bfg`` application any longer. + + Imperative configuration makes ``repoze.bfg`` competetive with + "microframeworks" such as `Bottle `_ and + `Tornado `_. ``repoze.bfg`` has a good + deal of functionality that most microframeworks lack, so this is + hopefully a "best of both worlds" feature. + + The simplest possible ``repoze.bfg`` application is now:: + + from webob import Response + from wsgiref import simple_server + from repoze.bfg.configuration import Configurator + + def hello_world(request): + return Response('Hello world!') + + if __name__ == '__main__': + config = Configurator() + config.add_view(hello_world) + app = config.make_wsgi_app() + simple_server.make_server('', 8080, app).serve_forever() + +- A new class now exists: ``repoze.bfg.configuration.Configurator``. + This class forms the basis for sharing machinery between + "imperatively" configured applications and traditional + declaratively-configured applications. + +- The ``repoze.bfg.testing.setUp`` function now accepts three extra + optional keyword arguments: ``registry``, ``request`` and + ``hook_zca``. + + If the ``registry`` argument is not ``None``, the argument will be + treated as the registry that is set as the "current registry" (it + will be returned by ``repoze.bfg.threadlocal.get_current_registry``) + for the duration of the test. If the ``registry`` argument is + ``None`` (the default), a new registry is created and used for the + duration of the test. + + The value of the ``request`` argument is used as the "current + request" (it will be returned by + ``repoze.bfg.threadlocal.get_current_request``) for the duration of + the test; it defaults to ``None``. + + If ``hook_zca`` is ``True`` (the default), the + ``zope.component.getSiteManager`` function will be hooked with a + function that returns the value of ``registry`` (or the + default-created registry if ``registry`` is ``None``) instead of the + registry returned by ``zope.component.getGlobalSiteManager``, + causing the Zope Component Architecture API (``getSiteManager``, + ``getAdapter``, ``getUtility``, and so on) to use the testing + registry instead of the global ZCA registry. + +- The ``repoze.bfg.testing.tearDown`` function now accepts an + ``unhook_zca`` argument. If this argument is ``True`` (the + default), ``zope.component.getSiteManager.reset()`` will be called. + This will cause the result of the ``zope.component.getSiteManager`` + function to be the global ZCA registry (the result of + ``zope.component.getGlobalSiteManager``) once again. + +- The ``run.py`` module in various ``repoze.bfg`` ``paster`` templates + now use a ``repoze.bfg.configuration.Configurator`` class instead of + the (now-legacy) ``repoze.bfg.router.make_app`` function to produce + a WSGI application. + +Documentation +------------- + +- The documentation now uses the "request-only" view calling + convention in most examples (as opposed to the ``context, request`` + convention). This is a documentation-only change; the ``context, + request`` convention is also supported and documented, and will be + "forever". + +- ``repoze.bfg.configuration`` API documentation has been added. + +- A narrative documentation chapter entitled "Creating Your First + ``repoze.bfg`` Application" has been added. This chapter details + usage of the new ``repoze.bfg.configuration.Configurator`` class, + and demonstrates a simplified "imperative-mode" configuration; doing + ``repoze.bfg`` application configuration imperatively was previously + much more difficult. + +- A narrative documentation chapter entitled "Configuration, + Decorations and Code Scanning" explaining ZCML- vs. imperative- + vs. decorator-based configuration equivalence. + +- The "ZCML Hooks" chapter has been renamed to "Hooks"; it documents + how to override hooks now via imperative configuration and ZCML. + +- The explanation about how to supply an alternate "response factory" + has been removed from the "Hooks" chapter. This feature may be + removed in a later release (it still works now, it's just not + documented). + +- Add a section entitled "Test Set Up and Tear Down" to the + unittesting chapter. + +Bug Fixes +---------- + +- The ACL authorization policy debugging output when + ``debug_authorization`` console debugging output was turned on + wasn't as clear as it could have been when a view execution was + denied due to an authorization failure resulting from the set of + principals passed never having matched any ACE in any ACL in the + lineage. Now in this case, we report ```` as the ACE + value and either the root ACL or ```` if no ACL was found. + +- When two views were registered with the same ``accept`` argument, + but were otherwise registered with the same arguments, if a request + entered the application which had an ``Accept`` header that accepted + *either* of the media types defined by the set of views registered + with predicates that otherwise matched, a more or less "random" one + view would "win". Now, we try harder to use the view callable + associated with the view configuration that has the most specific + ``accept`` argument. Thanks to Alberto Valverde for an initial + patch. + +Internals +--------- + +- The routes mapper is no longer a root factory wrapper. It is now + consulted directly by the router. + +- The ``repoze.bfg.registry.make_registry`` callable has been removed. + +- The ``repoze.bfg.view.map_view`` callable has been removed. + +- The ``repoze.bfg.view.owrap_view`` callable has been removed. + +- The ``repoze.bfg.view.predicate_wrap`` callable has been removed. + +- The ``repoze.bfg.view.secure_view`` callable has been removed. + +- The ``repoze.bfg.view.authdebug_view`` callable has been removed. + +- The ``repoze.bfg.view.renderer_from_name`` callable has been + removed. Use ``repoze.bfg.configuration.Configurator.renderer_from_name`` + instead (still not an API, however). + +- The ``repoze.bfg.view.derive_view`` callable has been removed. Use + ``repoze.bfg.configuration.Configurator.derive_view`` instead (still + not an API, however). + +- The ``repoze.bfg.settings.get_options`` callable has been removed. + Its job has been subsumed by the ``repoze.bfg.settings.Settings`` + class constructor. + +- The ``repoze.bfg.view.requestonly`` function has been moved to + ``repoze.bfg.configuration.requestonly``. + +- The ``repoze.bfg.view.rendered_response`` function has been moved to + ``repoze.bfg.configuration.rendered_response``. + +- The ``repoze.bfg.view.decorate_view`` function has been moved to + ``repoze.bfg.configuration.decorate_view``. + +- The ``repoze.bfg.view.MultiView`` class has been moved to + ``repoze.bfg.configuration.MultiView``. + +- The ``repoze.bfg.zcml.Uncacheable`` class has been removed. + +- The ``repoze.bfg.resource.resource_spec`` function has been removed. + +- All ZCML directives which deal with attributes which are paths now + use the ``path`` method of the ZCML context to resolve a relative + name to an absolute one (imperative configuration requirement). + +- The ``repoze.bfg.scripting.get_root`` API now uses a 'real' WebOb + request rather than a FakeRequest when it sets up the request as a + threadlocal. + +- The ``repoze.bfg.traversal.traverse`` API now uses a 'real' WebOb + request rather than a FakeRequest when it calls the traverser. + +- The ``repoze.bfg.request.FakeRequest`` class has been removed. + +- Most uses of the ZCA threadlocal API (the ``getSiteManager``, + ``getUtility``, ``getAdapter``, ``getMultiAdapter`` threadlocal API) + have been removed from the core. Instead, when a threadlocal is + necessary, the core uses the + ``repoze.bfg.threadlocal.get_current_registry`` API to obtain the + registry. + +- The internal ILogger utility named ``repoze.bfg.debug`` is now just + an IDebugLogger unnamed utility. A named utility with the old name + is registered for b/w compat. + +- The ``repoze.bfg.interfaces.ITemplateRendererFactory`` interface was + removed; it has become unused. + +- Instead of depending on the ``martian`` package to do code scanning, + we now just use our own scanning routines. + +- We now no longer have a dependency on ``repoze.zcml`` package; + instead, the ``repoze.bfg`` package includes implementations of the + ``adapter``, ``subscriber`` and ``utility`` directives. + +- Relating to the following functions: + + ``repoze.bfg.view.render_view`` + + ``repoze.bfg.view.render_view_to_iterable`` + + ``repoze.bfg.view.render_view_to_response`` + + ``repoze.bfg.view.append_slash_notfound_view`` + + ``repoze.bfg.view.default_notfound_view`` + + ``repoze.bfg.view.default_forbidden_view`` + + ``repoze.bfg.configuration.rendered_response`` + + ``repoze.bfg.security.has_permission`` + + ``repoze.bfg.security.authenticated_userid`` + + ``repoze.bfg.security.effective_principals`` + + ``repoze.bfg.security.view_execution_permitted`` + + ``repoze.bfg.security.remember`` + + ``repoze.bfg.security.forget`` + + ``repoze.bfg.url.route_url`` + + ``repoze.bfg.url.model_url`` + + ``repoze.bfg.url.static_url`` + + ``repoze.bfg.traversal.virtual_root`` + + Each of these functions now expects to be called with a request + object that has a ``registry`` attribute which represents the + current ``repoze.bfg`` registry. They fall back to obtaining the + registry from the threadlocal API. + +Backwards Incompatibilites +-------------------------- + +- Unit tests which use ``zope.testing.cleanup.cleanUp`` for the + purpose of isolating tests from one another may now begin to fail + due to lack of isolation between tests. + + Here's why: In repoze.bfg 1.1 and prior, the registry returned by + ``repoze.bfg.threadlocal.get_current_registry`` when no other + registry had been pushed on to the threadlocal stack was the + ``zope.component.globalregistry.base`` global registry (aka the + result of ``zope.component.getGlobalSiteManager()``). In repoze.bfg + 1.2+, however, the registry returned in this situation is the new + module-scope ``repoze.bfg.registry.global_registry`` object. The + ``zope.testing.cleanup.cleanUp`` function clears the + ``zope.component.globalregistry.base`` global registry + unconditionally. However, it does not know about the + ``repoze.bfg.registry.global_registry`` object, so it does not clear + it. + + If you use the ``zope.testing.cleanup.cleanUp`` function in the + ``setUp`` of test cases in your unit test suite instead of using the + (more correct as of 1.1) ``repoze.bfg.testing.setUp``, you will need + to replace all calls to ``zope.testing.cleanup.cleanUp`` with a call + to ``repoze.bfg.testing.setUp``. + + If replacing all calls to ``zope.testing.cleanup.cleanUp`` with a + call to ``repoze.bfg.testing.setUp`` is infeasible, you can put this + bit of code somewhere that is executed exactly **once** (*not* for + each test in a test suite; in the `` __init__.py`` of your package + or your package's ``tests`` subpackage would be a reasonable + place):: + + import zope.testing.cleanup + from repoze.bfg.testing import setUp + zope.testing.cleanup.addCleanUp(setUp) + +- When there is no "current registry" in the + ``repoze.bfg.threadlocal.manager`` threadlocal data structure (this + is the case when there is no "current request" or we're not in the + midst of a ``r.b.testing.setUp``-bounded unit test), the ``.get`` + method of the manager returns a data structure containing a *global* + registry. In previous releases, this function returned the global + Zope "base" registry: the result of + ``zope.component.getGlobalSiteManager``, which is an instance of the + ``zope.component.registry.Component`` class. In this release, + however, the global registry returns a globally importable instance + of the ``repoze.bfg.registry.Registry`` class. This registry + instance can always be imported as + ``repoze.bfg.registry.global_registry``. + + Effectively, this means that when you call + ``repoze.bfg.threadlocal.get_current_registry`` when no request or + ``setUp`` bounded unit test is in effect, you will always get back + the global registry that lives in + ``repoze.bfg.registry.global_registry``. It also means that + ``repoze.bfg`` APIs that *call* ``get_current_registry`` will use + this registry. + + This change was made because ``repoze.bfg`` now expects the registry + it uses to have a slightly different API than a bare instance of + ``zope.component.registry.Components``. + +- View registration no longer registers a + ``repoze.bfg.interfaces.IViewPermission`` adapter (it is no longer + checked by the framework; since 1.1, views have been responsible for + providing their own security). + +- The ``repoze.bfg.router.make_app`` callable no longer accepts the + ``authentication_policy`` nor the ``authorization_policy`` + arguments. This feature was deprecated in version 1.0 and has been + removed. + +- Obscure: the machinery which configured views with a + ``request_type`` *and* a ``route_name`` would ignore the request + interface implied by ``route_name`` registering a view only for the + interface implied by ``request_type``. In the unlikely event that + you were trying to use these two features together, the symptom + would have been that views that named a ``request_type`` but which + were also associated with routes were not found when the route + matched. Now if a view is configured with both a ``request_type`` + and a ``route_name``, an error is raised. + +- The ``route`` ZCML directive now no longer accepts the + ``request_type`` or ``view_request_type`` attributes. These + attributes didn't actually work in any useful way (see entry above + this one). + +- Because the ``repoze.bfg`` package now includes implementations of + the ``adapter``, ``subscriber`` and ``utility`` ZCML directives, it + is now an error to have ```` in the ZCML of a ``repoze.bfg`` application. A + ZCML conflict error will be raised if your ZCML does so. This + shouldn't be an issue for "normal" installations; it has always been + the responsibility of the ``repoze.bfg.includes`` ZCML to include + this file in the past; it now just doesn't. + +- The ``repoze.bfg.testing.zcml_configure`` API was removed. Use + the ``Configurator.load_zcml`` API instead. + +Deprecations +------------ + +- The ``repoze.bfg.router.make_app`` function is now nominally + deprecated. Its import and usage does not throw a warning, nor will + it probably ever disappear. However, using a + ``repoze.bfg.configuration.Configurator`` class is now the preferred + way to generate a WSGI application. + + Note that ``make_app`` calls + ``zope.component.getSiteManager.sethook( + repoze.bfg.threadlocal.get_current_registry)`` on the caller's + behalf, hooking ZCA global API lookups, for backwards compatibility + purposes. If you disuse ``make_app``, your calling code will need + to perform this call itself, at least if your application uses the + ZCA global API (``getSiteManager``, ``getAdapter``, etc). + +Dependencies +------------ + +- A dependency on the ``martian`` package has been removed (its + functionality is replaced internally). + +- A dependency on the ``repoze.zcml`` package has been removed (its + functionality is replaced internally). + +1.1.1 (2009-11-21) +================== + +Bug Fixes +--------- + +- "Hybrid mode" applications (applications which explicitly used + traversal *after* url dispatch via ```` paths containing the + ``*traverse`` element) were broken in 1.1-final and all 1.1 alpha + and beta releases. Views registered without a ``route_name`` route + shadowed views registered with a ``route_name`` inappropriately. + +1.1 (2009-11-15) +================ + +Internals +--------- + +- Remove dead IRouteRequirement interface from ``repoze.bfg.zcml`` + module. + +Documentation +------------- + +- Improve the "Extending an Existing Application" narrative chapter. + +- Add more sections to the "Defending Design" chapter. + +1.1b4 (2009-11-12) +================== + +Bug Fixes +--------- + +- Use ``alsoProvides`` in the urldispatch module to attach an + interface to the request rather than ``directlyProvides`` to avoid + disturbing interfaces set in a NewRequest event handler. + +Documentation +------------- + +- Move 1.0.1 and previous changelog to HISTORY.txt. + +- Add examples to ``repoze.bfg.url.model_url`` docstring. + +- Add "Defending BFG Design" chapter to frontpage docs. + +Templates +--------- + +- Remove ``ez_setup.py`` and its import from all paster templates, + samples, and tutorials for ``distribute`` compatibility. The + documentation already explains how to install virtualenv (which will + include some ``setuptools`` package), so these files, imports and + usages were superfluous. + +Deprecations +------------ + +- The ``options`` kw arg to the ``repoze.bfg.router.make_app`` + function is deprecated. In its place is the keyword argument + ``settings``. The ``options`` keyword continues to work, and a + deprecation warning is not emitted when it is detected. However, + the paster templates, code samples, and documentation now make + reference to ``settings`` rather than ``options``. This + change/deprecation was mainly made for purposes of clarity and + symmetry with the ``get_settings()`` API and dicussions of + "settings" in various places in the docs: we want to use the same + name to refer to the same thing everywhere. + +1.1b3 (2009-11-06) +================== + +Features +-------- + +- ``repoze.bfg.testing.registerRoutesMapper`` testing facility added. + This testing function registers a routes "mapper" object in the + registry, for tests which require its presence. This function is + documented in the ``repoze.bfg.testing`` API documentation. + +Bug Fixes +--------- + +- Compound statements that used an assignment entered into in an + interactive IPython session invoked via ``paster bfgshell`` no + longer fail to mutate the shell namespace correctly. For example, + this set of statements used to fail:: + + In [2]: def bar(x): return x + ...: + In [3]: list(bar(x) for x in 'abc') + Out[3]: NameError: 'bar' + + In this release, the ``bar`` function is found and the correct + output is now sent to the console. Thanks to Daniel Holth for the + patch. + +- The ``bfgshell`` command did not function properly; it was still + expecting to be able to call the root factory with a bare + ``environ`` rather than a request object. + +Backwards Incompatibilities +--------------------------- + +- The ``repoze.bfg.scripting.get_root`` function now expects a + ``request`` object as its second argument rather than an + ``environ``. + +1.1b2 (2009-11-02) +================== + +Bug Fixes +--------- + +- Prevent PyPI installation failure due to ``easy_install`` trying way + too hard to guess the best version of Paste. When ``easy_install`` + pulls from PyPI it reads links off various pages to determine "more + up to date" versions. It incorrectly picks up a link for an ancient + version of a package named "Paste-Deploy-0.1" (note the dash) when + trying to find the "Paste" distribution and somehow believes it's + the latest version of "Paste". It also somehow "helpfully" decides + to check out a version of this package from SVN. We pin the Paste + dependency version to a version greater than 1.7 to work around + this ``easy_install`` bug. + +Documentation +------------- + +- Fix "Hybrid" narrative chapter: stop claiming that ```` + statements that mention a route_name need to come afer (in XML + order) the ```` statement which creates the route. This + hasn't been true since 1.1a1. + +- "What's New in ``repoze.bfg`` 1.1" document added to narrative + documentation. + +Features +-------- + +- Add a new event type: ``repoze.bfg.events.AfterTraversal``. Events + of this type will be sent after traversal is completed, but before + any view code is invoked. Like ``repoze.bfg.events.NewRequest``, + This event will have a single attribute: ``request`` representing + the current request. Unlike the request attribute of + ``repoze.bfg.events.NewRequest`` however, during an AfterTraversal + event, the request object will possess attributes set by the + traverser, most notably ``context``, which will be the context used + when a view is found and invoked. The interface + ``repoze.bfg.events.IAfterTraversal`` can be used to subscribe to + the event. For example:: + + + + Like any framework event, a subscriber function should expect one + parameter: ``event``. + +Dependencies +------------ + +- Rather than depending on ``chameleon.core`` and ``chameleon.zpt`` + distributions individually, depend on Malthe's repackaged + ``Chameleon`` distribution (which includes both ``chameleon.core`` + and ``chameleon.zpt``). + +1.1b1 (2009-11-01) +================== + +Bug Fixes +--------- + +- The routes root factory called route factories and the default route + factory with an environ rather than a request. One of the symptoms + of this bug: applications generated using the ``bfg_zodb`` paster + template in 1.1a9 did not work properly. + +- Reinstate ``renderer`` alias for ``view_renderer`` in the + ```` ZCML directive (in-the-wild 1.1a bw compat). + +- ``bfg_routesalchemy`` paster template: change ```` + declarations: rename ``renderer`` attribute to ``view_renderer``. + +- Header values returned by the ``authtktauthenticationpolicy`` + ``remember`` and ``forget`` methods would be of type ``unicode``. + This violated the WSGI spec, causing a ``TypeError`` to be raised + when these headers were used under ``mod_wsgi``. + +- If a BFG app that had a route matching the root URL was mounted + under a path in modwsgi, ala ``WSGIScriptAlias /myapp + /Users/chrism/projects/modwsgi/env/bfg.wsgi``, the home route (a + route with the path of ``'/'`` or ``''``) would not match when the + path ``/myapp`` was visited (only when the path ``/myapp/`` was + visited). This is now fixed: if the urldispatch root factory notes + that the PATH_INFO is empty, it converts it to a single slash before + trying to do matching. + +Documentation +------------- + +- In ```` declarations in tutorial ZCML, rename ``renderer`` + attribute to ``view_renderer`` (fwd compat). + +- Fix various tutorials broken by 1.1a9 ```` directive changes. + +Internal +-------- + +- Deal with a potential circref in the traversal module. + +1.1a9 (2009-10-31) +================== + +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. + +1.1a8 (2009-10-27) +================== + +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 ```` 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. + +1.1a7 (2009-10-18) +================== + +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. + +1.1a6 (2009-10-15) +================== + +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. + +1.1a5 (2009-10-10) +================== + +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 addtional 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. + +1.1a4 (2009-09-23) +================== + +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 `_. + 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 ```` 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. + +1.1a3 (2009-09-16) +================== + +Documentation +------------- + +- The "Views" narrative chapter in the documentation has been updated + extensively to discuss "renderers". + +Features +-------- + +- A ``renderer`` attribute has been added to view configurations, + replacing the previous (1.1a2) version's ``template`` attribute. A + "renderer" is an object which accepts the return value of a view and + converts it to a string. This includes, but is not limited to, + templating systems. + +- A new interface named ``IRenderer`` was added. The existing + interface, ``ITemplateRenderer`` now derives from this new + interface. This interface is internal. + +- A new interface named ``IRendererFactory`` was added. An existing + interface named ``ITemplateRendererFactory`` now derives from this + interface. This interface is internal. + +- The ``view`` attribute of the ``view`` ZCML directive is no longer + required if the ZCML directive also has a ``renderer`` attribute. + This is useful when the renderer is a template renderer and no names + need be passed to the template at render time. + +- A new zcml directive ``renderer`` has been added. It is documented + in the "Views" narrative chapter of the documentation. + +- A ZCML ``view`` directive (and the associated ``bfg_view`` + decorator) can now accept a "wrapper" value. If a "wrapper" value + is supplied, it is the value of a separate view's *name* attribute. + When a view with a ``wrapper`` attribute is rendered, the "inner" + view is first rendered normally. Its body is then attached to the + request as "wrapped_body", and then a wrapper view name is looked up + and rendered (using ``repoze.bfg.render_view_to_response``), passed + the request and the context. The wrapper view is assumed to do + something sensible with ``request.wrapped_body``, usually inserting + its structure into some other rendered template. This feature makes + it possible to specify (potentially nested) "owrap" relationships + between views using only ZCML or decorators (as opposed always using + ZPT METAL and analogues to wrap view renderings in outer wrappers). + +Dependencies +------------ + +- When used under Python < 2.6, BFG now has an installation time + dependency on the ``simplejson`` package. + +Deprecations +------------ + +- The ``repoze.bfg.testing.registerDummyRenderer`` API has been + deprecated in favor of + ``repoze.bfg.testing.registerTemplateRenderer``. A deprecation + warning is *not* issued at import time for the former name; it will + exist "forever"; its existence has been removed from the + documentation, however. + +- The ``repoze.bfg.templating.renderer_from_cache`` function has been + moved to ``repoze.bfg.renderer.template_renderer_factory``. This + was never an API, but code in the wild was spotted that used it. A + deprecation warning is issued at import time for the former. + +Backwards Incompatibilities +--------------------------- + +- The ``ITemplateRenderer`` interface has been changed. Previously + its ``__call__`` method accepted ``**kw``. It now accepts a single + positional parameter named ``kw`` (REVISED: it accepts two + positional parameters as of 1.1a4: ``value`` and ``system``). This + is mostly an internal change, but it was exposed in APIs in one + place: if you've used the + ``repoze.bfg.testing.registerDummyRenderer`` API in your tests with + a custom "renderer" argument with your own renderer implementation, + you will need to change that renderer implementation to accept + ``kw`` instead of ``**kw`` in its ``__call__`` method (REVISED: make + it accept ``value`` and ``system`` positional arguments as of 1.1a4). + +- The ``ITemplateRendererFactory`` interface has been changed. + Previously its ``__call__`` method accepted an ``auto_reload`` + keyword parameter. Now its ``__call__`` method accepts no keyword + parameters. Renderers are now themselves responsible for + determining details of auto-reload. This is purely an internal + change. This interface was never external. + +- The ``template_renderer`` ZCML directive introduced in 1.1a2 has + been removed. It has been replaced by the ``renderer`` directive. + +- The previous release (1.1a2) added a view configuration attribute + named ``template``. In this release, the attribute has been renamed + to ``renderer``. This signifies that the attribute is more generic: + it can now be not just a template name but any renderer name (ala + ``json``). + +- In the previous release (1.1a2), the Chameleon text template + renderer was used if the system didn't associate the ``template`` + view configuration value with a filename with a "known" extension. + In this release, you must use a ``renderer`` attribute which is a + path that ends with a ``.txt`` extension + (e.g. ``templates/foo.txt``) to use the Chameleon text renderer. + +1.1a2 (2009-09-14) +================== + +Features +-------- + +- A ZCML ``view`` directive (and the associated ``bfg_view`` + decorator) can now accept an "attr" value. If an "attr" value is + supplied, it is considered a method named of the view object to be + called when the response is required. This is typically only good + for views that are classes or instances (not so useful for + functions, as functions typically have no methods other than + ``__call__``). + +- A ZCML ``view`` directive (and the associated ``bfg_view`` + decorator) can now accept a "template" value. If a "template" value + is supplied, and the view callable returns a dictionary, the + associated template is rendered with the dictionary as keyword + arguments. See the section named "Views That Have a ``template``" + in the "Views" narrative documentation chapter for more information. + +1.1a1 (2009-09-06) +================== + +Bug Fixes +--------- + +- "tests" module removed from the bfg_alchemy paster template; these + tests didn't work. + +- Bugfix: the ``discriminator`` for the ZCML "route" directive was + incorrect. It was possible to register two routes that collided + without the system spitting out a ConfigurationConflictError at + startup time. + +Features +-------- + +- Feature addition: view predicates. These are exposed as the + ``request_method``, ``request_param``, and ``containment`` + attributes of a ZCML ``view`` declaration, or the respective + arguments to a ``@bfg_view`` decorator. View predicates can be used + to register a view for a more precise set of environment parameters + than was previously possible. For example, you can register two + views with the same ``name`` with different ``request_param`` + attributes. If the ``request.params`` dict contains 'foo' + (request_param="foo"), one view might be called; if it contains + 'bar' (request_param="bar"), another view might be called. + ``request_param`` can also name a key/value pair ala ``foo=123``. + This will match only when the ``foo`` key is in the request.params + dict and it has the value '123'. This particular example makes it + possible to write separate view functions for different form + submissions. The other predicates, ``containment`` and + ``request_method`` work similarly. ``containment`` is a view + predicate that will match only when the context's graph lineage has + an object possessing a particular class or interface, for example. + ``request_method`` is a view predicate that will match when the HTTP + ``REQUEST_METHOD`` equals some string (eg. 'POST'). + +- The ``@bfg_view`` decorator now accepts three additional arguments: + ``request_method``, ``request_param``, and ``containment``. + ``request_method`` is used when you'd like the view to match only a + request with a particular HTTP ``REQUEST_METHOD``; a string naming + the ``REQUEST_METHOD`` can also be supplied as ``request_type`` for + backwards compatibility. ``request_param`` is used when you'd like + a view to match only a request that contains a particular + ``request.params`` key (with or without a value). ``containment`` + is used when you'd like to match a request that has a context that + has some class or interface in its graph lineage. These are + collectively known as "view predicates". + +- The ``route`` ZCML directive now honors ``view_request_method``, + ``view_request_param`` and ``view_containment`` attributes, which + pass along these values to the associated view if any is provided. + Additionally, the ``request_type`` attribute can now be spelled as + ``view_request_type``, and ``permission`` can be spelled as + ``view_permission``. Any attribute which starts with ``view_`` can + now be spelled without the ``view_`` prefix, so ``view_for`` can be + spelled as ``for`` now, etc. Both forms are documented in the + urldispatch narraitve documentation chapter. + +- The ``request_param`` ZCML view directive attribute (and its + ``bfg_view`` decorator cousin) can now specify both a key and a + value. For example, ``request_param="foo=123"`` means that the foo + key must have a value of ``123`` for the view to "match". + +- Allow ``repoze.bfg.traversal.find_interface`` API to use a class + object as the argument to compare against the ``model`` passed in. + This means you can now do ``find_interface(model, SomeClass)`` and + the first object which is found in the lineage which has + ``SomeClass`` as its class (or the first object found which has + ``SomeClass`` as any of its superclasses) will be returned. + +- Added ``static`` ZCML directive which registers a route for a view + that serves up files in a directory. See the "Views" narrative + documentation chapter's "Serving Static Resources Using a ZCML + Directive" section for more information. + +- The ``repoze.bfg.view.static`` class now accepts a string as its + first argument ("root_dir") that represents a package-relative name + e.g. ``somepackage:foo/bar/static``. This is now the preferred + mechanism for spelling package-relative static paths using this + class. A ``package_name`` keyword argument has been left around for + backwards compatibility. If it is supplied, it will be honored. + +- The API ``repoze.bfg.testing.registerView`` now takes a + ``permission`` argument. Use this instead of using + ``repoze.bfg.testing.registerViewPermission``. + +- The ordering of route declarations vs. the ordering of view + declarations that use a "route_name" in ZCML no longer matters. + Previously it had been impossible to use a route_name from a route + that had not yet been defined in ZCML (order-wise) within a "view" + declaration. + +- The repoze.bfg router now catches both + ``repoze.bfg.security.Unauthorized`` and + ``repoze.bfg.view.NotFound`` exceptions while rendering a view. + When the router catches an ``Unauthorized``, it returns the + registered forbidden view. When the router catches a ``NotFound``, + it returns the registered notfound view. + +Internal +-------- + +- Change urldispatch internals: Route object is now constructed using + a path, a name, and a factory instead of a name, a matcher, a + generator, and a factory. + +- Move (non-API) default_view, default_forbidden_view, and + default_notfound_view functions into the ``repoze.bfg.view`` module + (moved from ``repoze.bfg.router``). + +- Removed ViewPermissionFactory from ``repoze.bfg.security``. View + permission checking is now done by registering and looking up an + ISecuredView. + +- The ``static`` ZCML directive now uses a custom root factory when + constructing a route. + +- The interface ``IRequestFactories`` was removed from the + repoze.bfg.interfaces module. This interface was never an API. + +- The function named ``named_request_factories`` and the data + structure named ``DEFAULT_REQUEST_FACTORIES`` have been removed from + the ``repoze.bfg.request`` module. These were never APIs. + +- The ``IViewPermissionFactory`` interface has been removed. This was + never an API. + +Documentation +------------- + +- Request-only-convention examples in the "Views" narrative + documentation were broken. + +- Fixed documentation bugs related to forget and remember in security API + docs. + +- Fixed documentation for ``repoze.bfg.view.static`` (in narrative + ``Views`` chapter). + +Deprecations +------------ + +- The API ``repoze.bfg.testing.registerViewPermission`` has been + deprecated. + +Backwards Incompatibilities +--------------------------- + +- The interfaces ``IPOSTRequest``, ``IGETRequest``, ``IPUTRequest``, + ``IDELETERequest``, and ``IHEADRequest`` have been removed from the + ``repoze.bfg.interfaces`` module. These were not documented as APIs + post-1.0. Instead of using one of these, use a ``request_method`` + ZCML attribute or ``request_method`` bfg_view decorator parameter + containing an HTTP method name (one of ``GET``, ``POST``, ``HEAD``, + ``PUT``, ``DELETE``) instead of one of these interfaces if you were + using one explicitly. Passing a string in the set (``GET``, + ``HEAD``, ``PUT``, ``POST``, ``DELETE``) as a ``request_type`` + argument will work too. Rationale: instead of relying on interfaces + attached to the request object, BFG now uses a "view predicate" to + determine the request type. + +- Views registered without the help of the ZCML ``view`` directive are + now responsible for performing their own authorization checking. + +- The ``registry_manager`` backwards compatibility alias importable + from "repoze.bfg.registry", deprecated since repoze.bfg 0.9 has been + removed. If you are tring to use the registry manager within a + debug script of your own, use a combination of the + "repoze.bfg.paster.get_app" and "repoze.bfg.scripting.get_root" APIs + instead. + +- The ``INotFoundAppFactory`` interface has been removed; it has + been deprecated since repoze.bfg 0.9. If you have something like + the following in your ``configure.zcml``:: + + + + Replace it with something like:: + + + + See "Changing the Not Found View" in the "Hooks" chapter of the + documentation for more information. + +- The ``IUnauthorizedAppFactory`` interface has been removed; it has + been deprecated since repoze.bfg 0.9. If you have something like + the following in your ``configure.zcml``:: + + + + Replace it with something like:: + + + + See "Changing the Forbidden View" in the "Hooks" chapter of the + documentation for more information. + +- ``ISecurityPolicy``-based security policies, deprecated since + repoze.bfg 0.9, have been removed. If you have something like this + in your ``configure.zcml``, it will no longer work:: + + + + If ZCML like the above exists in your application, you will receive + an error at startup time. Instead of the above, you'll need + something like:: + + + + + This is just an example. See the "Security" chapter of the + repoze.bfg documentation for more information about configuring + security policies. + +- Custom ZCML directives which register an authentication or + authorization policy (ala "authtktauthenticationpolicy" or + "aclauthorizationpolicy") should register the policy "eagerly" in + the ZCML directive instead of from within a ZCML action. If an + authentication or authorization policy is not found in the component + registry by the view machinery during deferred ZCML processing, view + security will not work as expected. + +1.0.1 (2009-07-22) +================== + +- Added support for ``has_resource``, ``resource_isdir``, and + ``resource_listdir`` to the resource "OverrideProvider"; this fixes + a bug with a symptom that a file could not be overridden in a + resource directory unless a file with the same name existed in the + original directory being overridden. + +- Fixed documentation bug showing invalid test for values from the + ``matchdict``: they are stored as attributes of the ``Article``, rather + than subitems. + +- Fixed documentation bug showing wrong environment key for the ``matchdict`` + produced by the matching route. + +- Added a workaround for a bug in Python 2.6, 2.6.1, and 2.6.2 having + to do with a recursion error in the mimetypes module when trying to + serve static files from Paste's FileApp: + http://bugs.python.org/issue5853. Symptom: File + "/usr/lib/python2.6/mimetypes.py", line 244, in guess_type return + guess_type(url, strict) RuntimeError: maximum recursion depth + exceeded. Thanks to Armin Ronacher for identifying the symptom and + pointing out a fix. + +- Minor edits to tutorials for accuracy based on feedback. + +- Declared Paste and PasteDeploy dependencies. + +1.0 (2009-07-05) +================ + +- Retested and added some content to GAE tutorial. + +- Edited "Extending" narrative docs chapter. + +- Added "Deleting the Database" section to the "Defining Models" + chapter of the traversal wiki tutorial. + +- Spell checking of narratives and tutorials. + +1.0b2 (2009-07-03) +================== + +- ``remoteuserauthenticationpolicy`` ZCML directive didn't work + without an ``environ_key`` directive (didn't match docs). + +- Fix ``configure_zcml`` filespec check on Windows. Previously if an + absolute filesystem path including a drive letter was passed as + ``filename`` (or as ``configure_zcml`` in the options dict) to + ``repoze.bfg.router.make_app``, it would be treated as a + package:resource_name specification. + +- Fix inaccuracies and import errors in bfgwiki (traversal+ZODB) and + bfgwiki2 (urldispatch+SA) tutorials. + +- Use bfgsite index for all tutorial setup.cfg files. + +- Full documentation grammar/style/spelling audit. + +1.0b1 (2009-07-02) +================== + +Features +-------- + +- Allow a Paste config file (``configure_zcml``) value or an + environment variable (``BFG_CONFIGURE_ZCML``) to name a ZCML file + (optionally package-relative) that will be used to bootstrap the + application. Previously, the integrator could not influence which + ZCML file was used to do the boostrapping (only the original + application developer could do so). + +Documentation +------------- + +- Added a "Resources" chapter to the narrative documentation which + explains how to override resources within one package from another + package. + +- Added an "Extending" chapter to the narrative documentation which + explains how to extend or modify an existing BFG application using + another Python package and ZCML. + +1.0a9 (2009-07-01) +================== + +Features +-------- + +- Make it possible to pass strings in the form + "package_name:relative/path" to APIs like ``render_template``, + ``render_template_to_response``, and ``get_template``. Sometimes + the package in which a caller lives is a direct namespace package, + so the module which is returned is semi-useless for navigating from. + In this way, the caller can control the horizontal and vertical of + where things get looked up from. + +1.0a8 (2009-07-01) +================== + +Deprecations +------------ + +- Deprecate the ``authentication_policy`` and ``authorization_policy`` + arguments to ``repoze.bfg.router.make_app``. Instead, developers + should use the various authentication policy ZCML directives + (``repozewho1authenticationpolicy``, + ``remoteuserauthenticationpolicy`` and + ``authtktauthenticationpolicy``) and the `aclauthorizationpolicy`` + authorization policy directive as described in the changes to the + "Security" narrative documenation chapter and the wiki tutorials. + +Features +-------- + +- Add three new ZCML directives which configure authentication + policies: + + - ``repozewho1authenticationpolicy`` + + - ``remoteuserauthenticationpolicy`` + + - ``authtktauthenticationpolicy`` + +- Add a new ZCML directive which configures an ACL authorization + policy named ``aclauthorizationpolicy``. + +Bug Fixes +--------- + +- Bug fix: when a ``repoze.bfg.resource.PackageOverrides`` class was + instantiated, and the package it was overriding already had a + ``__loader__`` attribute, it would fail at startup time, even if the + ``__loader__`` attribute was another PackageOverrides instance. We + now replace any ``__loader__`` that is also a PackageOverrides + instance. Symptom: ``ConfigurationExecutionError: : Package + already has a __loader__ (probably a module in a zipped egg)``. + +1.0a7 (2009-06-30) +================== + +Features +-------- + +- Add a ``reload_resources`` configuration file setting (aka the + ``BFG_RELOAD_RESOURCES`` environment variable). When this is set to + true, the server never needs to be restarted when moving files + between directory resource overrides (esp. for templates currently). + +- Add a ``reload_all`` configuration file setting (aka the + ``BFG_RELOAD_ALL`` environment variable) that implies both + ``reload_resources`` and ``reload_templates``. + +- The ``static`` helper view class now uses a ``PackageURLParser`` in + order to allow for the overriding of static resources (CSS / logo + files, etc) using the ``resource`` ZCML directive. The + ``PackageURLParser`` class was added to a (new) ``static`` module in + BFG; it is a subclass of the ``StaticURLParser`` class in + ``paste.urlparser``. + +- The ``repoze.bfg.templating.renderer_from_cache`` function now + checks for the ``reload_resources`` setting; if it's true, it does + not register a template renderer (it won't use the registry as a + template renderer cache). + +Documentation +------------- + +- Add ``pkg_resources`` to the glossary. + +- Update the "Environment" docs to note the existence of + ``reload_resources`` and ``reload_all``. + +- Updated the ``bfg_alchemy`` paster template to include two views: + the view on the root shows a list of links to records; the view on + a record shows the details for that object. + +Internal +-------- + +- Use a colon instead of a tab as the separator between package name + and relpath to form the "spec" when register a ITemplateRenderer. + +- Register a ``repoze.bfg.resource.OverrideProvider`` as a + pkg_resources provider only for modules which are known to have + overrides, instead of globally, when a directive is used + (performance). + +1.0a6 (2009-06-29) +================== + +Bug Fixes +--------- + +- Use ``caller_package`` function instead of ``caller_module`` + function within ``templating`` to avoid needing to name the caller + module in resource overrides (actually match docs). + +- Make it possible to override templates stored directly in a module + with templates in a subdirectory of the same module, stored directly + within another module, or stored in a subdirectory of another module + (actually match docs). + +1.0a5 (2009-06-28) +================== + +Features +-------- + +- A new ZCML directive exists named "resource". This ZCML directive + allows you to override Chameleon templates within a package (both + directories full of templates and individual template files) with + other templates in the same package or within another package. This + allows you to "fake out" a view's use of a template, causing it to + retrieve a different template than the one actually named by a + relative path to a call like + ``render_template_to_response('templates/mytemplate.pt')``. For + example, you can override a template file by doing:: + + + + The string passed to "to_override" and "override_with" is named a + "specification". The colon separator in a specification separates + the package name from a package-relative directory name. The colon + and the following relative path are optional. If they are not + specified, the override attempts to resolve every lookup into a + package from the directory of another package. For example:: + + + + + Individual subdirectories within a package can also be overridden:: + + + + If you wish to override a directory with another directory, you must + make sure to attach the slash to the end of both the ``to_override`` + specification and the ``override_with`` specification. If you fail + to attach a slash to the end of a specification that points a + directory, you will get unexpected results. You cannot override a + directory specification with a file specification, and vice versa (a + startup error will occur if you try). + + You cannot override a resource with itself (a startup error will + occur if you try). + + Only individual *package* resources may be overridden. Overrides + will not traverse through subpackages within an overridden package. + This means that if you want to override resources for both + ``some.package:templates``, and ``some.package.views:templates``, + you will need to register two overrides. + + The package name in a specification may start with a dot, meaning + that the package is relative to the package in which the ZCML file + resides. For example:: + + + + Overrides for the same ``to_overrides`` specification can be named + multiple times within ZCML. Each ``override_with`` path will be + consulted in the order defined within ZCML, forming an override + search path. + + Resource overrides can actually override resources other than + templates. Any software which uses the ``pkg_resources`` + ``get_resource_filename``, ``get_resource_stream`` or + ``get_resource_string`` APIs will obtain an overridden file when an + override is used. However, the only built-in facility which uses + the ``pkg_resources`` API within BFG is the templating stuff, so we + only call out template overrides here. + +- Use the ``pkg_resources`` API to locate template filenames instead + of dead-reckoning using the ``os.path`` module. + +- The ``repoze.bfg.templating`` module now uses ``pkg_resources`` to + locate and register template files instead of using an absolute + path name. + +1.0a4 (2009-06-25) +================== + +Features +-------- + +- Cause ``:segment`` matches in route paths to put a Unicode-decoded + and URL-dequoted value in the matchdict for the value matched. + Previously a non-decoded non-URL-dequoted string was placed in the + matchdict as the value. + +- Cause ``*remainder`` matches in route paths to put a *tuple* in the + matchdict dictionary in order to be able to present Unicode-decoded + and URL-dequoted values for the traversal path. Previously a + non-decoded non-URL-dequoted string was placed in the matchdict as + the value. + +- Add optional ``max_age`` keyword value to the ``remember`` method of + ``repoze.bfg.authentication.AuthTktAuthenticationPolicy``; if this + value is passed to ``remember``, the generated cookie will have a + corresponding Max-Age value. + +Documentation +------------- + +- Add information to the URL Dispatch narrative documentation about + path pattern matching syntax. + +Bug Fixes +--------- + +- Make ``route_url`` URL-quote segment replacements during generation. + Remainder segments are not quoted. + +1.0a3 (2009-06-24) +================== + +Implementation Changes +---------------------- + +- ``repoze.bfg`` no longer relies on the Routes package to interpret + URL paths. All known existing ``path`` patterns will continue to + work with the reimplemented logic, which lives in + ``repoze.bfg.urldispatch``. ```` ZCML directives which use + certain attributes (uncommon ones) may not work (see "Backwards + Incompatibilities" below). + +Bug Fixes +--------- + +- ``model_url`` when passed a request that was generated as a result + of a route match would fail in a call to ``route.generate``. + +- BFG-on-GAE didn't work due to a corner case bug in the fallback + Python implementation of ``threading.local`` (symptom: + "Initialization arguments are not supported"). Thanks to Michael + Bernstein for the bug report. + +Documentation +------------- + +- Added a "corner case" explanation to the "Hybrid Apps" chapter + explaining what to do when "the wrong" view is matched. + +- Use ``repoze.bfg.url.route_url`` API in tutorials rather than Routes + ``url_for`` API. + +Features +-------- + +- Added the ``repoze.bfg.url.route_url`` API. This API allows you to + generate URLs based on ```` declarations. See the URL + Dispatch narrative chapter and the "repoze.bfg.url" module API + documentation for more information. + +Backwards Incompatibilities +--------------------------- + +- As a result of disusing Routes, using the Routes ``url_for`` API + inside a BFG application (as was suggested by previous iterations of + tutorials) will no longer work. Use the + ``repoze.bfg.url.route_url`` method instead. + +- The following attributes on the ```` ZCML directive no longer + work: ``encoding``, ``static``, ``filter``, ``condition_method``, + ``condition_subdomain``, ``condition_function``, ``explicit``, or + ``subdomains``. These were all Routes features. + +- The ```` ZCML directive no longer supports the + ```` subdirective. This was a Routes feature. + +1.0a2 (2009-06-23) +================== + +Bug Fixes +--------- + +- The ``bfg_routesalchemy`` paster template app tests failed due to a + mismatch between test and view signatures. + +Features +-------- + +- Add a ``view_for`` attribute to the ``route`` ZCML directive. This + attribute should refer to an interface or a class (ala the ``for`` + attribute of the ``view`` ZCML directive). + +Documentation +------------- + +- Conditional documentation in installation section ("how to install a + Python interpreter"). + +Backwards Incompatibilities +--------------------------- + +- The ``callback`` argument of the ``repoze.bfg.authentication`` + authentication policies named ``RepozeWho1AuthenticationPolicy``, + ``RemoteUserAuthenticationPolicy``, and + ``AuthTktAuthenticationPolicy`` now must accept two positional + arguments: the orginal argument accepted by each (userid or + identity) plus a second argument, which will be the current request. + Apologies, this is required to service finding groups when there is + no "global" database connection. + +1.0a1 (2009-06-22) +================== + +Features +-------- + +- A new ZCML directive was added named ``notfound``. This ZCML + directive can be used to name a view that should be invoked when the + request can't otherwise be resolved to a view callable. For example:: + + + +- A new ZCML directive was added named ``forbidden``. This ZCML + directive can be used to name a view that should be invoked when a + view callable for a request is found, but cannot be invoked due to + an authorization failure. For example:: + + + +- Allow views to be *optionally* defined as callables that accept only + a request object, instead of both a context and a request (which + still works, and always will). The following types work as views in + this style: + + - functions that accept a single argument ``request``, e.g.:: + + def aview(request): + pass + + - new and old-style classes that have an ``__init__`` method that + accepts ``self, request``, e.g.:: + + def View(object): + __init__(self, request): + pass + + - Arbitrary callables that have a ``__call__`` method that accepts + ``self, request``, e.g.:: + + def AView(object): + def __call__(self, request): + pass + view = AView() + + This likely should have been the calling convention all along, as + the request has ``context`` as an attribute already, and with views + called as a result of URL dispatch, having the context in the + arguments is not very useful. C'est la vie. + +- Cache the absolute path in the caller's package globals within + ``repoze.bfg.path`` to get rid of repeated (expensive) calls to + os.path.abspath. + +- Add ``reissue_time`` and ``timeout`` parameters to + ``repoze.bfg.authentication.AuthTktAuthenticationPolicy`` + constructor. If these are passed, cookies will be reset every so + often (cadged from the same change to repoze.who lately). + +- The matchdict related to the matching of a Routes route is available + on the request as the ``matchdict`` attribute: + ``request.matchdict``. If no route matched, this attribute will be + None. + +- Make 404 responses slightly cheaper by showing + ``environ["PATH_INFO"]`` on the notfound result page rather than the + fullly computed URL. + +- Move LRU cache implementation into a separate package + (``repoze.lru``). + +- The concepts of traversal and URL dispatch have been unified. It is + now possible to use the same sort of factory as both a traversal + "root factory" and what used to be referred to as a urldispatch + "context factory". + +- When the root factory argument (as a first argument) passed to + ``repoze.bfg.router.make_app`` is ``None``, a *default* root factory + is used. This is in support of using routes as "root finders"; it + supplants the idea that there is a default + ``IRoutesContextFactory``. + +- The `view`` ZCML statement and the ``repoze.bfg.view.bfg_view`` + decorator now accept an extra argument: ``route_name``. If a + ``route_name`` is specified, it must match the name of a previously + defined ``route`` statement. When it is specified, the view will + only be called when that route matches during a request. + +- It is now possible to perfom traversal *after* a route has matched. + Use the pattern ``*traverse`` in a ```` ``path`` attribute + within ZCML, and the path remainder which it matches will be used as + a traversal path. + +- When any route defined matches, the WSGI environment will now + contain a key ``bfg.routes.route`` (the Route object which matched), + and a key ``bfg.routes.matchdict`` (the result of calling route.match). + +Deprecations +------------ + +- Utility registrations against + ``repoze.bfg.interfaces.INotFoundView`` and + ``repoze.bfg.interfaces.IForbiddenView`` are now deprecated. Use + the ``notfound`` and ``forbidden`` ZCML directives instead (see the + "Hooks" chapter for more information). Such registrations will + continue to work, but the notfound and forbidden directives do + "extra work" to ensure that the callable named by the directive can + be called by the router even if it's a class or + request-argument-only view. + +Removals +-------- + +- The ``IRoutesContext``, ``IRoutesContextFactory``, and + ``IContextNotFound`` interfaces were removed from + ``repoze.bfg.interfaces``. These were never APIs. + +- The ``repoze.bfg.urldispatch.RoutesContextNotFound``, + ``repoze.bfg.urldispatch.RoutesModelTraverser`` and + ``repoze.bfg.urldispatch.RoutesContextURL`` classes were removed. + These were also never APIs. + +Backwards Incompatibilities +--------------------------- + +- Moved the ``repoze.bfg.push`` module, which implemented the ``pushpage`` + decorator, into a separate distribution, ``repoze.bfg.pushpage``. + Applications which used this decorator should continue to work after + adding that distribution to their installation requirements. + +- Changing the default request factory via an IRequestFactory utility + registration (as used to be documented in the "Hooks" chapter's + "Changing the request factory" section) is no longer supported. The + dance to manufacture a request is complicated as a result of + unifying traversal and url dispatch, making it highly unlikely for + anyone to be able to override it properly. For those who just want + to decorate or modify a request, use a NewRequestEvent subscriber + (see the Events chapter in the documentation). + +- The ``repoze.bfg.IRequestFactory`` interface was removed. See the + bullet above for why. + +- Routes "context factories" (spelled as the factory argument to a + route statement in ZCML) must now expect the WSGI environ as a + single argument rather than a set of keyword arguments. They can + obtain the match dictionary by asking for + environ['bfg.routes.matchdict']. This is the same set of keywords + that used to be passed to urldispatch "context factories" in BFG 0.9 + and below. + +- Using the ``@zope.component.adapter`` decorator on a bfg view + function no longer works. Use the ``@repoze.bfg.view.bfg_view`` + decorator instead to mark a function (or a class) as a view. + +- The name under which the matching route object is found in the + environ was changed from ``bfg.route`` to ``bfg.routes.route``. + +- Finding the root is now done *before* manufacturing a request object + (and sending a new request event) within the router (it used to be + performed afterwards). + +- Adding ``*path_info`` to a route no longer changes the PATH_INFO for + a request that matches using URL dispatch. This feature was only + there to service the ``repoze.bfg.wsgi.wsgiapp2`` decorator and it + did it wrong; use ``*subpath`` instead now. + +- The values of ``subpath``, ``traversed``, and ``virtual_root_path`` + attached to the request object are always now tuples instead of + lists (performance). + +Bug Fixes +--------- + +- The ``bfg_alchemy`` Paster template named "repoze.tm" in its + pipeline rather than "repoze.tm2", causing the startup to fail. + +- Move BBB logic for registering an + IAuthenticationPolicy/IForbiddenView/INotFoundView based on older + concepts from the router module's ``make_app`` function into the + ``repoze.bfg.zcml.zcml_configure`` callable, to service + compatibility with scripts that use "zope.configuration.xmlconfig" + (replace with ``repoze.bfg.zml.zcml_configure`` as necessary to get + BBB logic) + +Documentation +------------- + +- Add interface docs related to how to create authentication policies + and authorization policies to the "Security" narrative chapter. + +- Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter + to the narrative documentation. This explains the usage of + ``*traverse`` and ``*subpath`` in routes URL patters. + +- A "router" chapter explaining the request/response lifecycle at a + high level was added. + +- Replaced all mentions and explanations of a routes "context factory" + with equivalent explanations of a "root factory" (context factories + have been disused). + +- Updated Routes bfgwiki2 tutorial to reflect the fact that context + factories are now no longer used. + +0.9.1 (2009-06-02) +================== + +Features +-------- + +- Add API named ``repoze.bfg.settings.get_settings`` which retrieves a + derivation of values passed as the ``options`` value of + ``repoze.bfg.router.make_app``. This API should be preferred + instead of using getUtility(ISettings). I added a new + ``repoze.bfg.settings`` API document as well. + +Bug Fixes +--------- + +- Restored missing entry point declaration for bfg_alchemy paster + template, which was accidentally removed in 0.9. + +Documentation +------------- + +- Fix a reference to ``wsgiapp`` in the ``wsgiapp2`` API documentation + within the ``repoze.bfg.wsgi`` module. + +API Removals +------------ + +- The ``repoze.bfg.location.locate`` API was removed: it didn't do + enough to be very helpful and had a misleading name. + +0.9 (2009-06-01) +================ + +Bug Fixes +--------- + +- It was not possible to register a custom ``IRoutesContextFactory`` + for use as a default context factory as documented in the "Hooks" + chapter. + +Features +-------- + +- The ``request_type`` argument of ZCML ``view`` declarations and + ``bfg_view`` decorators can now be one of the strings ``GET``, + ``POST``, ``PUT``, ``DELETE``, or ``HEAD`` instead of a reference to + the respective interface type imported from + ``repoze.bfg.interfaces``. + +- The ``route`` ZCML directive now accepts ``request_type`` as an + alias for its ``condition_method`` argument for symmetry with the + ``view`` directive. + +- The ``bfg_routesalchemy`` paster template now provides a unit test + and actually uses the database during a view rendering. + +Removals +-------- + +- Remove ``repoze.bfg.threadlocal.setManager``. It was only used in + unit tests. + +- Remove ``repoze.bfg.wsgi.HTTPException``, + ``repoze.bfg.wsgi.NotFound``, and ``repoze.bfg.wsgi.Unauthorized``. + These classes were disused with the introduction of the + ``IUnauthorizedView`` and ``INotFoundView`` machinery. + +Documentation +------------- + +- Add description to narrative templating chapter about how to use + Chameleon text templates. + +- Changed Views narrative chapter to use method strings rather than + interface types, and moved advanced interface type usage to Events + narrative chapter. + +- Added a Routes+SQLAlchemy wiki tutorial. + +0.9a8 (2009-05-31) +================== + +Features +-------- + +- It is now possible to register a custom + ``repoze.bfg.interfaces.INotFoundView`` for a given application. + This feature replaces the + ``repoze.bfg.interfaces.INotFoundAppFactory`` feature previously + described in the Hooks chapter. The INotFoundView will be called + when the framework detects that a view lookup done as a result of a + request fails; it should accept a context object and a request + object; it should return an IResponse object (a webob response, + basically). See the Hooks narrative chapter of the BFG docs for + more info. + +- The error presented when a view invoked by the router returns a + non-response object now includes the view's name for troubleshooting + purposes. + +Bug Fixes +--------- + +- A "new response" event is emitted for forbidden and notfound views. + +Deprecations +------------ + +- The ``repoze.bfg.interfaces.INotFoundAppFactory`` interface has been + deprecated in favor of using the new + ``repoze.bfg.interfaces.INotFoundView`` mechanism. + +Renames +------- + +- Renamed ``repoze.bfg.interfaces.IForbiddenResponseFactory`` to + ``repoze.bfg.interfaces.IForbiddenView``. + +0.9a7 (2009-05-30) +================== + +Features +-------- + +- Remove "context" argument from ``effective_principals`` and + ``authenticated_userid`` function APIs in ``repoze.bfg.security``, + effectively a doing reversion to 0.8 and before behavior. Both + functions now again accept only the ``request`` parameter. + +0.9a6 (2009-05-29) +================== + +Documentation +------------- + +- Changed "BFG Wiki" tutorial to use AuthTktAuthenticationPolicy + rather than repoze.who. + +Features +-------- + +- Add an AuthTktAuthenticationPolicy. This policy retrieves + credentials from an auth_tkt cookie managed by the application + itself (instead of relying on an upstream data source for + authentication data). See the Security API chapter of the + documentation for more info. + +- Allow RemoteUserAuthenticationPolicy and + RepozeWho1AuthenticationPolicy to accept various constructor + arguments. See the Security API chapter of the documentation for + more info. + +0.9a5 (2009-05-28) +================== + +Features +-------- + +- Add a ``get_app`` API functions to the ``paster`` module. This + obtains a WSGI application from a config file given a config file + name and a section name. See the ``repoze.bfg.paster`` API docs for + more information. + +- Add a new module named ``scripting``. It contains a ``get_root`` + API function, which, provided a Router instance, returns a traversal + root object and a "closer". See the ``repoze.bfg.scripting`` API + docs for more info. + +0.9a4 (2009-05-27) +================== + +Bug Fixes +--------- + +- Try checking for an "old style" security policy *after* we parse + ZCML (thinko). + +0.9a3 (2009-05-27) +================== + +Features +-------- + +- Allow IAuthenticationPolicy and IAuthorizationPolicy to be + overridden via ZCML registrations (do ZCML parsing after + registering these in router.py). + +Documentation +------------- + +- Added "BFG Wiki" tutorial to documentation; it describes + step-by-step how to create a traversal-based ZODB application with + authentication. + +Deprecations +------------ + +- Added deprecations for imports of ``ACLSecurityPolicy``, + ``InheritingACLSecurityPolicy``, ``RemoteUserACLSecurityPolicy``, + ``RemoteUserInheritingACLSecurityPolicy``, ``WhoACLSecurityPolicy``, + and ``WhoInheritingACLSecurityPolicy`` from the + ``repoze.bfg.security`` module; for the meantime (for backwards + compatibility purposes) these live in the ``repoze.bfg.secpols`` + module. Note however, that the entire concept of a "security + policy" is deprecated in BFG in favor of separate authentication and + authorization policies, so any use of a security policy will + generate additional deprecation warnings even if you do start using + ``repoze.bfg.secpols``. ``repoze.bfg.secpols`` will disappear in a + future release of ``repoze.bfg``. + +Deprecated Import Alias Removals +-------------------------------- + +- Remove ``repoze.bfg.template`` module. All imports from this + package have been deprecated since 0.3.8. Instead, import + ``get_template``, ``render_template``, and + ``render_template_to_response`` from the + ``repoze.bfg.chameleon_zpt`` module. + +- Remove backwards compatibility import alias for + ``repoze.bfg.traversal.split_path`` (deprecated since 0.6.5). This + must now be imported as ``repoze.bfg.traversal.traversal_path``). + +- Remove backwards compatibility import alias for + ``repoze.bfg.urldispatch.RoutesContext`` (deprecated since 0.6.5). + This must now be imported as + ``repoze.bfg.urldispatch.DefaultRoutesContext``. + +- Removed backwards compatibility import aliases for + ``repoze.bfg.router.get_options`` and ``repoze.bfg.router.Settings`` + (deprecated since 0.6.2). These both must now be imported from + ``repoze.bfg.settings``. + +- Removed backwards compatibility import alias for + ``repoze.bfg.interfaces.IRootPolicy`` (deprecated since 0.6.2). It + must be imported as ``repoze.bfg.interfaces.IRootFactory`` now. + +- Removed backwards compatibility import alias for + ``repoze.bfg.interfaces.ITemplate`` (deprecated since 0.4.4). It + must be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` now. + +- Removed backwards compatibility import alias for + ``repoze.bfg.interfaces.ITemplateFactory`` (deprecated since 0.4.4). + It must be imported as + ``repoze.bfg.interfaces.ITemplateRendererFactory`` now. + +- Removed backwards compatibility import alias for + ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` (deprecated since + 0.4.4). This must be imported as ``repoze.bfg.ZPTTemplateRenderer`` + now. + +0.9a2 (2009-05-27) +================== + +Features +-------- + +- A paster command has been added named "bfgshell". This command can + be used to get an interactive prompt with your BFG root object in + the global namespace. E.g.:: + + bin/paster bfgshell /path/to/myapp.ini myapp + + See the ``Project`` chapter in the BFG documentation for more + information. + +Deprecations +------------ + +- The name ``repoze.bfg.registry.registry_manager`` was never an API, + but scripts in the wild were using it to set up an environment for + use under a debug shell. A backwards compatibility shim has been + added for this purpose, but the feature is deprecated. + +0.9a1 (2009-5-27) +================= + +Features +-------- + +- New API functions named ``forget`` and ``remember`` are available in + the ``security`` module. The ``forget`` function returns headers + which will cause the currently authenticated user to be logged out + when set in a response. The ``remember`` function (when passed the + proper arguments) will return headers which will cause a principal + to be "logged in" when set in a response. See the Security API + chapter of the docs for more info. + +- New keyword arguments to the ``repoze.bfg.router.make_app`` call + have been added: ``authentication_policy`` and + ``authorization_policy``. These should, respectively, be an + implementation of an authentication policy (an object implementing + the ``repoze.bfg.interfaces.IAuthenticationPolicy`` interface) and + an implementation of an authorization policy (an object implementing + ``repoze.bfg.interfaces.IAuthorizationPolicy)``. Concrete + implementations of authentication policies exist in + ``repoze.bfg.authentication``. Concrete implementations of + authorization policies exist in ``repoze.bfg.authorization``. + + Both ``authentication_policy`` and ``authorization_policy`` default + to ``None``. + + If ``authentication_policy`` is ``None``, but + ``authorization_policy`` is *not* ``None``, then + ``authorization_policy`` is ignored (the ability to do authorization + depends on authentication). + + If the ``authentication_policy`` argument is *not* ``None``, and the + ``authorization_policy`` argument *is* ``None``, the authorization + policy defaults to an authorization implementation that uses ACLs + (``repoze.bfg.authorization.ACLAuthorizationPolicy``). + + We no longer encourage configuration of "security policies" using + ZCML, as previously we did for ``ISecurityPolicy``. This is because + it's not uncommon to need to configure settings for concrete + authorization or authentication policies using paste .ini + parameters; the app entry point for your application is the natural + place to do this. + +- Two new abstractions have been added in the way of adapters used by + the system: an ``IAuthorizationPolicy`` and an + ``IAuthenticationPolicy``. A combination of these (as registered by + the ``securitypolicy`` ZCML directive) take the place of the + ``ISecurityPolicy`` abstraction in previous releases of repoze.who. + The API functions in ``repoze.who.security`` (such as + ``authentication_userid``, ``effective_principals``, + ``has_permission``, and so on) have been changed to try to make use + of these new adapters. If you're using an older ``ISecurityPolicy`` + adapter, the system will still work, but it will print deprecation + warnings when such a policy is used. + +- The way the (internal) IViewPermission utilities registered via ZCML + are invoked has changed. They are purely adapters now, returning a + boolean result, rather than returning a callable. You shouldn't have + been using these anyway. ;-) + +- New concrete implementations of IAuthenticationPolicy have been + added to the ``repoze.bfg.authentication`` module: + ``RepozeWho1AuthenticationPolicy`` which uses ``repoze.who`` + identity to retrieve authentication data from and + ``RemoteUserAuthenticationPolicy``, which uses the ``REMOTE_USER`` + value in the WSGI environment to retrieve authentication data. + +- A new concrete implementation of IAuthorizationPolicy has been added + to the ``repoze.bfg.authorization`` module: + ``ACLAuthorizationPolicy`` which uses ACL inheritance to do + authorization. + +- It is now possible to register a custom + ``repoze.bfg.interfaces.IForbiddenResponseFactory`` for a given + application. This feature replaces the + ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` feature previously + described in the Hooks chapter. The IForbiddenResponseFactory will + be called when the framework detects an authorization failure; it + should accept a context object and a request object; it should + return an IResponse object (a webob response, basically). Read the + below point for more info and see the Hooks narrative chapter of the + BFG docs for more info. + +Backwards Incompatibilities +--------------------------- + +- Custom NotFound and Forbidden (nee' Unauthorized) WSGI applications + (registered as a utility for INotFoundAppFactory and + IUnauthorizedAppFactory) could rely on an environment key named + ``message`` describing the circumstance of the response. This key + has been renamed to ``repoze.bfg.message`` (as per the WSGI spec, + which requires environment extensions to contain dots). + +Deprecations +------------ + +- The ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` interface has + been deprecated in favor of using the new + ``repoze.bfg.interfaces.IForbiddenResponseFactory`` mechanism. + +- The ``view_execution_permitted`` API should now be imported from the + ``repoze.bfg.security`` module instead of the ``repoze.bfg.view`` + module. + +- The ``authenticated_userid`` and ``effective_principals`` APIs in + ``repoze.bfg.security`` used to only take a single argument + (request). They now accept two arguments (``context`` and + ``request``). Calling them with a single argument is still + supported but issues a deprecation warning. (NOTE: this change was + reverted in 0.9a7; meaning the 0.9 versions of these functions + again accept ``request`` only, just like 0.8 and before). + +- Use of "old-style" security policies (those base on ISecurityPolicy) + is now deprecated. See the "Security" chapter of the docs for info + about activating an authorization policy and an authentication poicy. + +0.8.1 (2009-05-21) +================== + +Features +-------- + +- Class objects may now be used as view callables (both via ZCML and + via use of the ``bfg_view`` decorator in Python 2.6 as a class + decorator). The calling semantics when using a class as a view + callable is similar to that of using a class as a Zope "browser + view": the class' ``__init__`` must accept two positional parameters + (conventionally named ``context``, and ``request``). The resulting + instance must be callable (it must have a ``__call__`` method). + When called, the instance should return a response. For example:: + + from webob import Response + + class MyView(object): + def __init__(self, context, request): + self.context = context + self.request = request + + def __call__(self): + return Response('hello from %s!' % self.context) + + See the "Views" chapter in the documentation and the + ``repoze.bfg.view`` API documentation for more information. + +- Removed the pickling of ZCML actions (the code that wrote + ``configure.zcml.cache`` next to ``configure.zcml`` files in + projects). The code which managed writing and reading of the cache + file was a source of subtle bugs when users switched between + imperative (e.g. ``@bfg_view``) registrations and declarative + registrations (e.g. the ``view`` directive in ZCML) on the same + project. On a moderately-sized project (535 ZCML actions and 15 ZCML + files), executing actions read from the pickle was saving us only + about 200ms (2.5 sec vs 2.7 sec average). On very small projects (1 + ZCML file and 4 actions), startup time was comparable, and sometimes + even slower when reading from the pickle, and both ways were so fast + that it really just didn't matter anyway. + +0.8 (2009-05-18) +================ + +Features +-------- + +- Added a ``traverse`` function to the ``repoze.bfg.traversal`` + module. This function may be used to retrieve certain values + computed during path resolution. See the Traversal API chapter of + the documentation for more information about this function. + +Deprecations +------------ + +- Internal: ``ITraverser`` callables should now return a dictionary + rather than a tuple. Up until 0.7.0, all ITraversers were assumed + to return a 3-tuple. In 0.7.1, ITraversers were assumed to return a + 6-tuple. As (by evidence) it's likely we'll need to add further + information to the return value of an ITraverser callable, 0.8 + assumes that an ITraverser return a dictionary with certain elements + in it. See the ``repoze.bfg.interfaces.ITraverser`` interface for + the list of keys that should be present in the dictionary. + ``ITraversers`` which return tuples will still work, although a + deprecation warning will be issued. + +Backwards Incompatibilities +--------------------------- + +- If your code used the ITraverser interface directly (not via an API + function such as ``find_model``) via an adapter lookup, you'll need + to change your code to expect a dictionary rather than a 3- or + 6-tuple if your code ever gets return values from the default + ModelGraphTraverser or RoutesModelTraverser adapters. + +0.8a7 (2009-05-16) +================== + +Backwards Incompatibilities +--------------------------- + +- The ``RoutesMapper`` class in ``repoze.bfg.urldispatch`` has been + removed, as well as its documentation. It had been deprecated since + 0.6.3. Code in ``repoze.bfg.urldispatch.RoutesModelTraverser`` + which catered to it has also been removed. + +- The semantics of the ``route`` ZCML directive have been simplified. + Previously, it was assumed that to use a route, you wanted to map a + route to an externally registered view. The new ``route`` directive + instead has a ``view`` attribute which is required, specifying the + dotted path to a view callable. When a route directive is + processed, a view is *registered* using the name attribute of the + route directive as its name and the callable as its value. The + ``view_name`` and ``provides`` attributes of the ``route`` directive + are therefore no longer used. Effectively, if you were previously + using the ``route`` directive, it means you must change a pair of + ZCML directives that look like this:: + + + + + + To a ZCML directive that looks like this:: + + + + In other words, to make old code work, remove the ``view`` + directives that were only there to serve the purpose of backing + ``route`` directives, and move their ``view=`` attribute into the + ``route`` directive itself. + + This change also necessitated that the ``name`` attribute of the + ``route`` directive is now required. If you were previously using + ``route`` directives without a ``name`` attribute, you'll need to + add one (the name is arbitrary, but must be unique among all + ``route`` and ``view`` statements). + + The ``provides`` attribute of the ``route`` directive has also been + removed. This directive specified a sequence of interface types + that the generated context would be decorated with. Since route + views are always generated now for a single interface + (``repoze.bfg.IRoutesContext``) as opposed to being looked up + arbitrarily, there is no need to decorate any context to ensure a + view is found. + +Documentation +------------- + +- Added API docs for the ``repoze.bfg.testing`` methods + ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and + ``cleanUp``. + +- Added glossary entry for "root factory". + +- Noted existence of ``repoze.bfg.pagetemplate`` template bindings in + "Available Add On Template System Bindings" in Templates chapter in + narrative docs. + +- Update "Templates" narrative chapter in docs (expand to show a + sample template and correct macro example). + +Features +-------- + +- Courtesty Carlos de la Guardia, added an ``alchemy`` Paster + template. This paster template sets up a BFG project that uses + SQAlchemy (with SQLite) and uses traversal to resolve URLs. (no + Routes areused). This template can be used via ``paster create -t + bfg_alchemy``. + +- The Routes ``Route`` object used to resolve the match is now put + into the environment as ``bfg.route`` when URL dispatch is used. + +- You can now change the default Routes "context factory" globally. + See the "ZCML Hooks" chapter of the documentation (in the "Changing + the Default Routes Context Factory" section). + +0.8a6 (2009-05-11) +================== + +Features +-------- + +- Added a ``routesalchemy`` Paster template. This paster template + sets up a BFG project that uses SQAlchemy (with SQLite) and uses + Routes exclusively to resolve URLs (no traversal root factory is + used). This template can be used via ``paster create -t + bfg_routesalchemy``. + +Documentation +------------- + +- Added documentation to the URL Dispatch chapter about how to catch + the root URL using a ZCML ``route`` directive. + +- Added documentation to the URL Dispatch chapter about how to perform + a cleanup function at the end of a request (e.g. close the SQL + connection). + +Bug Fixes +--------- + +- In version 0.6.3, passing a ``get_root`` callback (a "root factory") + to ``repoze.bfg.router.make_app`` became optional if any ``route`` + declaration was made in ZCML. The intent was to make it possible to + disuse traversal entirely, instead relying entirely on URL dispatch + (Routes) to resolve all contexts. However a compound set of bugs + prevented usage of a Routes-based root view (a view which responds + to "/"). One bug existed in `repoze.bfg.urldispatch``, another + existed in Routes itself. + + To resolve this issue, the urldispatch module was fixed, and a fork + of the Routes trunk was put into the "dev" index named + ``Routes-1.11dev-chrism-home``. The source for the fork exists at + `http://bitbucket.org/chrism/routes-home/ + `_ (broken link); + its contents have been merged into the Routes trunk + (what will be Routes 1.11). + +0.8a5 (2009-05-08) +================== + +Features +-------- + +- Two new security policies were added: + RemoteUserInheritingACLSecurityPolicy and + WhoInheritingACLSecurityPolicy. These are security policies which + take into account *all* ACLs defined in the lineage of a context + rather than stopping at the first ACL found in a lineage. See the + "Security" chapter of the API documentation for more information. + +- The API and narrative documentation dealing with security was + changed to introduce the new "inheriting" security policy variants. + +- Added glossary entry for "lineage". + +Deprecations +------------ + +- The security policy previously named + ``RepozeWhoIdentityACLSecurityPolicy`` now has the slightly saner + name of ``WhoACLSecurityPolicy``. A deprecation warning is emitted + when this policy is imported under the "old" name; usually this is + due to its use in ZCML within your application. If you're getting + this deprecation warning, change your ZCML to use the new name, + e.g. change:: + + + + To:: + + + +0.8a4 (2009-05-04) +================== + +Features +-------- + +- ``zope.testing`` is no longer a direct dependency, although our + dependencies (such as ``zope.interface``, ``repoze.zcml``, etc) + still depend on it. + +- Tested on Google App Engine. Added a tutorial to the documentation + explaining how to deploy a BFG app to GAE. + +Backwards Incompatibilities +--------------------------- + +- Applications which rely on ``zope.testing.cleanup.cleanUp`` in unit + tests can still use that function indefinitely. However, for + maximum forward compatibility, they should import ``cleanUp`` from + ``repoze.bfg.testing`` instead of from ``zope.testing.cleanup``. + The BFG paster templates and docs have been changed to use this + function instead of the ``zope.testing.cleanup`` version. + +0.8a3 (2009-05-03) +=================== + +Features +-------- + +- Don't require a successful import of ``zope.testing`` at BFG + application runtime. This allows us to get rid of ``zope.testing`` + on platforms like GAE which have file limits. + +0.8a2 (2009-05-02) +================== + +Features +-------- + +- We no longer include the ``configure.zcml`` of the ``chameleon.zpt`` + package within the ``configure.zcml`` of the "repoze.bfg.includes" + package. This has been a no-op for some time now. + +- The ``repoze.bfg.chameleon_zpt`` package no longer imports from + ``chameleon.zpt`` at module scope, deferring the import until later + within a method call. The ``chameleon.zpt`` package can't be + imported on platforms like GAE. + +0.8a1 (2009-05-02) +================== + +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 http://svn.repoze.org/repoze.bfg.chameleon_genshi (also + available in the index at http://dist.repoze.org/bfg/0.8/simple). + 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/ (also available in the index + at http://dist.repoze.org/bfg/0.8/simple). 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. + +0.7.1 (2009-05-01) +================== + +Index-Related +------------- + +- The canonical package index location for ``repoze.bfg`` has changed. + The "old" index (http://dist.repoze.org/lemonade/dev/simple) has + been superseded by a new index location + (`http://dist.repoze.org/bfg/current/simple + `_). 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 + http://svn.repoze.org/repoze.bfg.traversalwrapper) Then change your + application's ``configure.zcml`` to include the following stanza: + + + + 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. + +0.7.0 (2009-04-11) +================== + +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``:: + + + + 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. + +0.6.9 (2009-02-16) +================== + +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). + +0.6.8 (2009-02-05) +================== + +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 accomodate 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. + +0.6.7 (2009-01-27) +================== + +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``. + +0.6.6 (2009-01-26) +================== + +Implementation Changes +---------------------- + +- There is an indirection in ``repoze.bfg.url.model_url`` now that + consults a utility to generate the base model url (without extra + elements or a query string). Eventually this will service virtual + hosting; for now it's undocumented and should not be hooked. + +0.6.5 (2009-01-26) +================== + +Features +-------- + +- You can now override the NotFound and Unauthorized responses that + ``repoze.bfg`` generates when a view cannot be found or cannot be + invoked due to lack of permission. See the "ZCML Hooks" chapter in + the docs for more information. + +- Added Routes ZCML directive attribute explanations in documentation. + +- Added a ``traversal_path`` API to the traversal module; see the + "traversal" API chapter in the docs. This was a function previously + known as ``split_path`` that was not an API but people were using it + anyway. Unlike ``split_path``, it now returns a tuple instead of a + list (as its values are cached). + +Behavior Changes +---------------- + +- The ``repoze.bfg.view.render_view_to_response`` API will no longer + raise a ValueError if an object returned by a view function it calls + does not possess certain attributes (``headerlist``, ``app_iter``, + ``status``). This API used to attempt to perform a check using the + ``is_response`` function in ``repoze.bfg.view``, and raised a + ``ValueError`` if the ``is_response`` check failed. The + responsibility is now the caller's to ensure that the return value + from a view function is a "real" response. + +- WSGI environ dicts passed to ``repoze.bfg`` 's Router must now + contain a REQUEST_METHOD key/value; if they do not, a KeyError will + be raised (speed). + +- It is no longer permissible to pass a "nested" list of principals to + ``repoze.bfg.ACLAuthorizer.permits`` (e.g. ``['fred', ['larry', + 'bob']]``). The principals list must be fully expanded. This + feature was never documented, and was never an API, so it's not a + backwards incompatibility. + +- It is no longer permissible for a security ACE to contain a "nested" + list of permissions (e.g. ``(Allow, Everyone, ['read', ['view', + ['write', 'manage']]])`)`. The list must instead be fully expanded + (e.g. ``(Allow, Everyone, ['read', 'view', 'write', 'manage])``). This + feature was never documented, and was never an API, so it's not a + backwards incompatibility. + +- The ``repoze.bfg.urldispatch.RoutesRootFactory`` now injects the + ``wsgiorg.routing_args`` environment variable into the environ when + a route matches. This is a tuple of ((), routing_args) where + routing_args is the value that comes back from the routes mapper + match (the "match dict"). + +- The ``repoze.bfg.traversal.RoutesModelTraverser`` class now wants to + obtain the ``view_name`` and ``subpath`` from the + ``wsgiorgs.routing_args`` environment variable. It falls back to + obtaining these from the context for backwards compatibility. + +Implementation Changes +---------------------- + +- Get rid of ``repoze.bfg.security.ACLAuthorizer``: the + ``ACLSecurityPolicy`` now does what it did inline. + +- Get rid of ``repoze.bfg.interfaces.NoAuthorizationInformation`` + exception: it was used only by ``ACLAuthorizer``. + +- Use a homegrown NotFound error instead of ``webob.exc.HTTPNotFound`` + (the latter is slow). + +- Use a homegrown Unauthorized error instead of + ``webob.exc.Unauthorized`` (the latter is slow). + +- the ``repoze.bfg.lru.lru_cached`` decorator now uses functools.wraps + in order to make documentation of LRU-cached functions possible. + +- Various speed micro-tweaks. + +Bug Fixes +--------- + +- ``repoze.bfg.testing.DummyModel`` did not have a ``get`` method; + it now does. + +0.6.4 (2009-01-23) +================== + +Backwards Incompatibilities +--------------------------- + +- The ``unicode_path_segments`` configuration variable and the + ``BFG_UNICODE_PATH_SEGMENTS`` configuration variable have been + removed. Path segments are now always passed to model + ``__getitem__`` methods as unicode. "True" has been the default for + this setting since 0.5.4, but changing this configuration setting to + false allowed you to go back to passing raw path element strings to + model ``__getitem__`` methods. Removal of this knob services a + speed goal (we get about +80 req/s by removing the check), and it's + clearer just to always expect unicode path segments in model + ``__getitem__`` methods. + +Implementation Changes +---------------------- + +- ``repoze.bfg.traversal.split_path`` now also handles decoding + path segments to unicode (for speed, because its results are + cached). + +- ``repoze.bfg.traversal.step`` was made a method of the + ModelGraphTraverser. + +- Use "precooked" Request subclasses + (e.g. ``repoze.bfg.request.GETRequest``) that correspond to HTTP + request methods within ``router.py`` when constructing a request + object rather than using ``alsoProvides`` to attach the proper + interface to an unsubclassed ``webob.Request``. This pattern is + purely an optimization (e.g. preventing calls to ``alsoProvides`` + means the difference between 590 r/s and 690 r/s on a MacBook 2GHz). + +- Tease out an extra 4% performance boost by changing the Router; + instead of using imported ZCA APIs, use the same APIs directly + against the registry that is an attribute of the Router. + +- The registry used by BFG is now a subclass of + ``zope.component.registry.Components`` (defined as + ``repoze.bfg.registry.Registry``); it has a ``notify`` method, a + ``registerSubscriptionAdapter`` and a ``registerHandler`` method. + If no subscribers are registered via ``registerHandler`` or + ``registerSubscriptionAdapter``, ``notify`` is a noop for speed. + +- The Allowed and Denied classes in ``repoze.bfg.security`` now are + lazier about constructing the representation of a reason message for + speed; ``repoze.bfg.view_execution_permitted`` takes advantage of + this. + +- The ``is_response`` check was sped up by about half at the expense + of making its code slightly uglier. + +New Modules +----------- + +- ``repoze.bfg.lru`` implements an LRU cache class and a decorator for + internal use. + +0.6.3 (2009-01-19) +================== + +Bug Fixes +--------- + +- Readd ``root_policy`` attribute on Router object (as a property + which returns the IRootFactory utility). It was inadvertently + removed in 0.6.2. Code in the wild depended upon its presence + (esp. scripts and "debug" helpers). + +Features +-------- + +- URL-dispatch has been overhauled: it is no longer necessary to + manually create a RoutesMapper in your application's entry point + callable in order to use URL-dispatch (aka `Routes + `_). A new ``route`` directive has been + added to the available list of ZCML directives. Each ``route`` + directive inserted into your application's ``configure.zcml`` + establishes a Routes mapper connection. If any ``route`` + declarations are made via ZCML within a particular application, the + ``get_root`` callable passed in to ``repoze.bfg.router.make_app`` + will automatically be wrapped in the equivalent of a RoutesMapper. + Additionally, the new ``route`` directive allows the specification + of a ``context_interfaces`` attribute for a route, this will be used + to tag the manufactured routes context with specific interfaces when + a route specifying a ``context_interfaces`` attribute is matched. + +- A new interface ``repoze.bfg.interfaces.IContextNotFound`` was + added. This interface is attached to a "dummy" context generated + when Routes cannot find a match and there is no "fallback" get_root + callable that uses traversal. + +- The ``bfg_starter`` and ``bfg_zodb`` "paster create" templates now + contain images and CSS which are displayed when the default page is + displayed after initial project generation. + +- Allow the ``repoze.bfg.view.static`` helper to be passed a relative + ``root_path`` name; it will be considered relative to the file in + which it was called. + +- The functionality of ``repoze.bfg.convention`` has been merged into + the core. Applications which make use of ``repoze.bfg.convention`` + will continue to work indefinitely, but it is recommended that apps + stop depending upon it. To do so, substitute imports of + ``repoze.bfg.convention.bfg_view`` with imports of + ``repoze.bfg.view.bfg_view``, and change the stanza in ZCML from + ```` to ````. As a result + of the merge, bfg has grown a new dependency: ``martian``. + +- View functions which use the pushpage decorator are now pickleable + (meaning their use won't prevent a ``configure.zcml.cache`` file + from being written to disk). + +- Instead of invariably using ``webob.Request`` as the "request + factory" (e.g. in the ``Router`` class) and ``webob.Response`` and + the "response factory" (e.g. in ``render_template_to_response``), + allow both to be overridden via a ZCML utility hook. See the "Using + ZCML Hooks" chapter of the documentation for more information. + +Deprecations +------------ + +- The class ``repoze.bfg.urldispatch.RoutesContext`` has been renamed + to ``repoze.bfg.urldispatch.DefaultRoutesContext``. The class + should be imported by the new name as necessary (although in reality + it probably shouldn't be imported from anywhere except internally + within BFG, as it's not part of the API). + +Implementation Changes +---------------------- + +- The ``repoze.bfg.wsgi.wsgiapp`` decorator now uses + ``webob.Request.get_response`` to do its work rather than relying on + homegrown WSGI code. + +- The ``repoze.bfg.view.static`` helper now uses + ``webob.Request.get_response`` to do its work rather than relying on + homegrown WSGI code. + +- The ``repoze.bfg.urldispatch.RoutesModelTraverser`` class has been + moved to ``repoze.bfg.traversal.RoutesModelTraverser``. + +- The ``repoze.bfg.registry.makeRegistry`` function was renamed to + ``repoze.bfg.registry.populateRegistry`` and now accepts a + ``registry`` argument (which should be an instance of + ``zope.component.registry.Components``). + +Documentation Additions +----------------------- + +- Updated narrative urldispatch chapter with changes required by + ```` ZCML directive. + +- Add a section on "Using BFG Security With URL Dispatch" into the + urldispatch chapter of the documentation. + +- Better documentation of security policy implementations that ship + with repoze.bfg. + +- Added a "Using ZPT Macros in repoze.bfg" section to the narrative + templating chapter. + +0.6.2 (2009-01-13) +================== + +Features +-------- + +- Tests can be run with coverage output if you've got ``nose`` + installed in the interpreter which you use to run tests. Using an + interpreter with ``nose`` installed, do ``python setup.py + nosetests`` within a checkout of the ``repoze.bfg`` package to see + test coverage output. + +- Added a ``post`` argument to the ``repoze.bfg.testing:DummyRequest`` + constructor. + +- Added ``__len__`` and ``__nonzero__`` to ``repoze.bfg.testing:DummyModel``. + +- The ``repoze.bfg.registry.get_options`` callable (now renamed to + ``repoze.bfg.setings.get_options``) used to return only + framework-specific keys and values in the dictionary it returned. + It now returns all the keys and values in the dictionary it is + passed *plus* any framework-specific settings culled from the + environment. As a side effect, all PasteDeploy application-specific + config file settings are made available as attributes of the + ``ISettings`` utility from within BFG. + +- Renamed the existing BFG paster template to ``bfg_starter``. Added + another template (``bfg_zodb``) showing default ZODB setup using + ``repoze.zodbconn``. + +- Add a method named ``assert_`` to the DummyTemplateRenderer. This + method accepts keyword arguments. Each key/value pair in the + keyword arguments causes an assertion to be made that the renderer + received this key with a value equal to the asserted value. + +- Projects generated by the paster templates now use the + ``DummyTemplateRenderer.assert_`` method in their view tests. + +- Make the (internal) thread local registry manager maintain a stack + of registries in order to make it possible to call one BFG + application from inside another. + +- An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is + attached to each request object on ingress. The HTTP-verb-related + interfaces are defined in ``repoze.bfg.interfaces`` and are + ``IGETRequest``, ``IPOSTRequest``, ``IPUTRequest``, + ``IDELETERequest`` and ``IHEADRequest``. These interfaces can be + specified as the ``request_type`` attribute of a bfg view + declaration. A view naming a specific HTTP-verb-matching interface + will be found only if the view is defined with a request_type that + matches the HTTP verb in the incoming request. The more general + ``IRequest`` interface can be used as the request_type to catch all + requests (and this is indeed the default). All requests implement + ``IRequest``. The HTTP-verb-matching idea was pioneered by + `repoze.bfg.restrequest + `_ . That + package is no longer required, but still functions fine. + +Bug Fixes +--------- + +- Fix a bug where the Paste configuration's ``unicode_path_segments`` + (and os.environ's ``BFG_UNICODE_PATH_SEGMENTS``) may have been + defaulting to false in some circumstances. It now always defaults + to true, matching the documentation and intent. + +- The ``repoze.bfg.traversal.find_model`` API did not work properly + when passed a ``path`` argument which was unicode and contained + high-order bytes when the ``unicode_path_segments`` or + ``BFG_UNICODE_PATH_SEGMENTS`` configuration variables were "true". + +- A new module was added: ``repoze.bfg.settings``. This contains + deployment-settings-related code. + +Implementation Changes +---------------------- + +- The ``make_app`` callable within ``repoze.bfg.router`` now registers + the ``root_policy`` argument as a utility (unnamed, using the new + ``repoze.bfg.interfaces.IRootFactory`` as a provides interface) + rather than passing it as the first argument to the + ``repoze.bfg.router.Router`` class. As a result, the + ``repoze.bfg.router.Router`` router class only accepts a single + argument: ``registry``. The ``repoze.bfg.router.Router`` class + retrieves the root policy via a utility lookup now. The + ``repoze.bfg.router.make_app`` API also now performs some important + application registrations that were previously handled inside + ``repoze.bfg.registry.makeRegistry``. + +New Modules +----------- + +- A ``repoze.bfg.settings`` module was added. It contains code + related to deployment settings. Most of the code it contains was + moved to it from the ``repoze.bfg.registry`` module. + +Behavior Changes +---------------- + +- The ``repoze.bfg.settings.Settings`` class (an instance of which is + registered as a utility providing + ``repoze.bfg.interfaces.ISettings`` when any application is started) + now automatically calls ``repoze.bfg.settings.get_options`` on the + options passed to its constructor. This means that usage of + ``get_options`` within an application's ``make_app`` function is no + longer required (the "raw" ``options`` dict or None may be passed). + +- Remove old cold which attempts to recover from trying to unpickle a + ``z3c.pt`` template; Chameleon has been the templating engine for a + good long time now. Running repoze.bfg against a sandbox that has + pickled ``z3c.pt`` templates it will now just fail with an + unpickling error, but can be fixed by deleting the template cache + files. + +Deprecations +------------ + +- Moved the ``repoze.bfg.registry.Settings`` class. This has been + moved to ``repoze.bfg.settings.Settings``. A deprecation warning is + issued when it is imported from the older location. + +- Moved the ``repoze.bfg.registry.get_options`` function This has been + moved to ``repoze.bfg.settings.get_options``. A deprecation warning + is issued when it is imported from the older location. + +- The ``repoze.bfg.interfaces.IRootPolicy`` interface was renamed + within the interfaces package. It has been renamed to + ``IRootFactory``. A deprecation warning is issued when it is + imported from the older location. + +0.6.1 (2009-01-06) +================== + +New Modules +----------- + +- A new module ``repoze.bfg.url`` has been added. It contains the + ``model_url`` API (moved from ``repoze.bfg.traversal``) and an + implementation of ``urlencode`` (like Python's + ``urllib.urlencode``) which can handle Unicode keys and values in + parameters to the ``query`` argument. + +Deprecations +------------ + +- The ``model_url`` function has been moved from + ``repoze.bfg.traversal`` into ``repoze.bfg.url``. It can still + be imported from ``repoze.bfg.traversal`` but an import from + ``repoze.bfg.traversal`` will emit a DeprecationWarning. + +Features +-------- + +- A ``static`` helper class was added to the ``repoze.bfg.views`` + module. Instances of this class are willing to act as BFG views + which return static resources using files on disk. See the + ``repoze.bfg.view`` docs for more info. + +- The ``repoze.bfg.url.model_url`` API (nee' + ``repoze.bfg.traversal.model_url``) now accepts and honors a + keyword argument named ``query``. The value of this argument + will be used to compose a query string, which will be attached to + the generated URL before it is returned. See the API docs (in + the docs directory or `on the web + `_) for more information. + +0.6 (2008-12-26) +================ + +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 http://static.repoze.org/zcmldocs). + 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. ````) 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 `_ 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``:: + + + + 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. + +0.5.6 (2008-12-18) +================== + +- 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. + +0.5.5 (2008-12-17) +================== + +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 + successully, 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 + +0.5.4 (2008-12-13) +================== + +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. + +0.5.3 (2008-12-07) +================== + +- 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 explcit named utility registrations in + the ZCML registry against ``ITemplateRenderer``; these will be found + before any on-disk template is looked up. + +0.5.2 (2008-12-05) +================== + +- 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. + +0.5.1 (2008-11-25) +================== + +- Add ``keys``, ``items``, and ``values`` methods to + ``testing.DummyModel``. + +- Add __delitem__ method to ``testing.DummyModel``. + +0.5.0 (2008-11-18) +================== + +- Fix ModelGraphTraverser; don't try to change the ``__name__`` or + ``__parent__`` of an object that claims it implements ILocation during + traversal even if the ``__name__`` or ``__parent__`` of the object + traversed does not match the name used in the traversal step or the or + the traversal parent . Rationale: it was insane to do so. This bug was + only found due to a misconfiguration in an application that mistakenly + had intermediate persistent non-ILocation objects; traversal was causing + a persistent write on every request under this setup. + +- ``repoze.bfg.location.locate`` now unconditionally sets ``__name__`` and + ``__parent__`` on objects which provide ILocation (it previously only set + them conditionally if they didn't match attributes already present on the + object via equality). + +0.4.9 (2008-11-17) +================== + +- Add chameleon text template API (chameleon ${name} renderings where the + template does not need to be wrapped in any containing XML). + +- Change docs to explain install in terms of a virtualenv + (unconditionally). + +- Make pushpage decorator compatible with repoze.bfg.convention's + ``bfg_view`` decorator when they're stacked. + +- Add content_length attribute to testing.DummyRequest. + +- Change paster template ``tests.py`` to include a true unit test. Retain + old test as an integration test. Update documentation. + +- Document view registrations against classes and ``repoze.bfg.convention`` + in context. + +- Change the default paster template to register its single view against a + class rather than an interface. + +- Document adding a request type interface to the request via a subscriber + function in the events narrative documentation. + +0.4.8 (2008-11-12) +================== + +Backwards Incompatibilities +--------------------------- + +- ``repoze.bfg.traversal.model_url`` now always appends a slash to all + generated URLs unless further elements are passed in as the third and + following arguments. Rationale: views often use ``model_url`` without + the third-and-following arguments in order to generate a URL for a model + in order to point at the default view of a model. The URL that points to + the default view of the *root* model is technically ``http://mysite/`` as + opposed to ``http://mysite`` (browsers happen to ask for '/' implicitly + in the GET request). Because URLs are never automatically generated for + anything *except* models by ``model_url``, and because the root model is + not really special, we continue this pattern. The impact of this change + is minimal (at most you will have too many slashes in your URL, which BFG + deals with gracefully anyway). + +0.4.7 (2008-11-11) +================== + +Features +-------- + +- Allow ``testing.registerEventListener`` to be used with Zope 3 style + "object events" (subscribers accept more than a single event argument). + We extend the list with the arguments, rather than append. + +0.4.6 (2008-11-10) +================== + +Bug Fixes +--------- + +- The ``model_path`` and ``model_url`` traversal APIs returned the wrong + value for the root object (e.g. ``model_path`` returned ``''`` for the + root object, while it should have been returning ``'/'``). + +0.4.5 (2008-11-09) +================== + +Features +-------- + +- Added a ``clone`` method and a ``__contains__`` method to the DummyModel + testing object. + +- Allow DummyModel objects to receive extra keyword arguments, which will + be attached as attributes. + +- The DummyTemplateRenderer now returns ``self`` as its implementation. + +0.4.4 (2008-11-08) +================== + +Features +-------- + +- Added a ``repoze.bfg.testing`` module to attempt to make it slightly + easier to write unittest-based automated tests of BFG applications. + Information about this module is in the documentation. + +- The default template renderer now supports testing better by looking for + ``ITestingTemplateRenderer`` using a relative pathname. This is exposed + indirectly through the API named ``registerTemplateRenderer`` in + ``repoze.bfg.testing``. + +Deprecations +------------ + +- The names ``repoze.bfg.interfaces.ITemplate`` , + ``repoze.bfg.interfaces.ITemplateFactory`` and + ``repoze.bfg.interfaces.INodeTemplate`` have been deprecated. These + should now be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` and + ``repoze.bfg.interfaces.ITemplateRendererFactory``, and + ``INodeTemplateRenderer`` respectively. + +- The name ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` is deprecated. + Use ``repoze.bfg.chameleon_zpt.ZPTTemplateRenderer``. + +- The name ``repoze.bfg.chameleon_genshi.GenshiTemplateFactory`` is + deprecated. Use ``repoze.bfg.chameleon_genshi.GenshiTemplateRenderer``. + +- The name ``repoze.bfg.xslt.XSLTemplateFactory`` is deprecated. Use + ``repoze.bfg.xslt.XSLTemplateRenderer``. + +0.4.3 (2008-11-02) +================== + +Bug Fixes +--------- + +- Not passing the result of "get_options" as the second argument of + make_app could cause attribute errors when attempting to look up settings + against the ISettings object (internal). Fixed by giving the Settings + objects defaults for ``debug_authorization`` and ``debug_notfound``. + +- Return an instance of ``Allowed`` (rather than ``True``) from + ``has_permission`` when no security policy is in use. + +- Fix bug where default deny in authorization check would throw a TypeError + (use ``ACLDenied`` instead of ``Denied``). + +0.4.2 (2008-11-02) +================== + +Features +-------- + +- Expose a single ILogger named "repoze.bfg.debug" as a utility; this + logger is registered unconditionally and is used by the authorization + debug machinery. Applications may also make use of it as necessary + rather than inventing their own logger, for convenience. + +- The ``BFG_DEBUG_AUTHORIZATION`` envvar and the ``debug_authorization`` + config file value now only imply debugging of view-invoked security + checks. Previously, information was printed for every call to + ``has_permission`` as well, which made output confusing. To debug + ``has_permission`` checks and other manual permission checks, use the + debugger and print statements in your own code. + +- Authorization debugging info is now only present in the HTTP response + body oif ``debug_authorization`` is true. + +- The format of authorization debug messages was improved. + +- A new ``BFG_DEBUG_NOTFOUND`` envvar was added and a symmetric + ``debug_notfound`` config file value was added. When either is true, and + a NotFound response is returned by the BFG router (because a view could + not be found), debugging information is printed to stderr. When this + value is set true, the body of HTTPNotFound responses will also contain + the same debugging information. + +- ``Allowed`` and ``Denied`` responses from the security machinery are now + specialized into two types: ACL types, and non-ACL types. The + ACL-related responses are instances of ``repoze.bfg.security.ACLAllowed`` + and ``repoze.bfg.security.ACLDenied``. The non-ACL-related responses are + ``repoze.bfg.security.Allowed`` and ``repoze.bfg.security.Denied``. The + allowed-type responses continue to evaluate equal to things that + themselves evaluate equal to the ``True`` boolean, while the denied-type + responses continue to evaluate equal to things that themselves evaluate + equal to the ``False`` boolean. The only difference between the two + types is the information attached to them for debugging purposes. + +- Added a new ``BFG_DEBUG_ALL`` envvar and a symmetric ``debug_all`` config + file value. When either is true, all other debug-related flags are set + true unconditionally (e.g. ``debug_notfound`` and + ``debug_authorization``). + +Documentation +------------- + +- Added info about debug flag changes. + +- Added a section to the security chapter named "Debugging Imperative + Authorization Failures" (for e.g. ``has_permssion``). + +Bug Fixes +--------- + +- Change default paster template generator to use ``Paste#http`` server + rather than ``PasteScript#cherrpy`` server. The cherrypy server has a + security risk in it when ``REMOTE_USER`` is trusted by the downstream + application. + +0.4.1 (2008-10-28) +================== + +Bug Fixes +--------- + +- If the ``render_view_to_response`` function was called, if the view was + found and called, but it returned something that did not implement + IResponse, the error would pass by unflagged. This was noticed when I + created a view function that essentially returned None, but received a + NotFound error rather than a ValueError when the view was rendered. This + was fixed. + +0.4.0 (2008-10-03) +================== + +Docs +---- + +- An "Environment and Configuration" chapter was added to the narrative + portion of the documentation. + +Features +-------- + +- Ensure bfg doesn't generate warnings when running under Python + 2.6. + +- The environment variable ``BFG_RELOAD_TEMPLATES`` is now available + (serves the same purpose as ``reload_templates`` in the config file). + +- A new configuration file option ``debug_authorization`` was added. + This turns on printing of security authorization debug statements + to ``sys.stderr``. The ``BFG_DEBUG_AUTHORIZATION`` environment + variable was also added; this performs the same duty. + +Bug Fixes +--------- + +- The environment variable ``BFG_SECURITY_DEBUG`` did not always work. + It has been renamed to ``BFG_DEBUG_AUTHORIZATION`` and fixed. + +Deprecations +------------ + +- A deprecation warning is now issued when old API names from the + ``repoze.bfg.templates`` module are imported. + +Backwards incompatibilities +--------------------------- + +- The ``BFG_SECURITY_DEBUG`` environment variable was renamed to + ``BFG_DEBUG_AUTHORIZATION``. + +0.3.9 (2008-08-27) +================== + +Features +-------- + +- A ``repoze.bfg.location`` API module was added. + +Backwards incompatibilities +--------------------------- + +- Applications must now use the ``repoze.bfg.interfaces.ILocation`` + interface rather than ``zope.location.interfaces.ILocation`` to + represent that a model object is "location-aware". We've removed + a dependency on ``zope.location`` for cleanliness purposes: as + new versions of zope libraries are released which have improved + dependency information, getting rid of our dependence on + ``zope.location`` will prevent a newly installed repoze.bfg + application from requiring the ``zope.security``, egg, which not + truly used at all in a "stock" repoze.bfg setup. These + dependencies are still required by the stack at this time; this + is purely a futureproofing move. + + The security and model documentation for previous versions of + ``repoze.bfg`` recommended using the + ``zope.location.interfaces.ILocation`` interface to represent + that a model object is "location-aware". This documentation has + been changed to reflect that this interface should now be + imported from ``repoze.bfg.interfaces.ILocation`` instead. + +0.3.8 (2008-08-26) +================== + +Docs +---- + +- Documented URL dispatch better in narrative form. + +Bug fixes +--------- + +- Routes URL dispatch did not have access to the WSGI environment, + so conditions such as method=GET did not work. + +Features +-------- + +- Add ``principals_allowed_by_permission`` API to security module. + +- Replace ``z3c.pt`` support with support for ``chameleon.zpt``. + Chameleon is the new name for the package that used to be named + ``z3c.pt``. NOTE: If you update a ``repoze.bfg`` SVN checkout + that you're using for development, you will need to run "setup.py + install" or "setup.py develop" again in order to obtain the + proper Chameleon packages. ``z3c.pt`` is no longer supported by + ``repoze.bfg``. All API functions that used to render ``z3c.pt`` + templates will work fine with the new packages, and your + templates should render almost identically. + +- Add a ``repoze.bfg.chameleon_zpt`` module. This module provides + Chameleon ZPT support. + +- Add a ``repoze.bfg.xslt`` module. This module provides XSLT + support. + +- Add a ``repoze.bfg.chameleon_genshi`` module. This provides + direct Genshi support, which did not exist previously. + +Deprecations +------------ + +- Importing API functions directly from ``repoze.bfg.template`` is + now deprecated. The ``get_template``, ``render_template``, + ``render_template_to_response`` functions should now be imported + from ``repoze.chameleon_zpt``. The ``render_transform``, and + ``render_transform_to_response`` functions should now be imported + from ``repoze.bfg.xslt``. The ``repoze.bfg.template`` module + will remain around "forever" to support backwards compatibility. + +0.3.7 (2008-09-09) +================== + +Features +-------- + +- Add compatibility with z3c.pt 1.0a7+ (z3c.pt became a namespace package). + +Bug fixes +--------- + +- ``repoze.bfg.traversal.find_model`` function did not function properly. + +0.3.6 (2008-09-04) +================== + +Features +-------- + +- Add startup process docs. + +- Allow configuration cache to be bypassed by actions which include special + "uncacheable" discriminators (for actions that have variable results). + +Bug Fixes +--------- + +- Move core repoze.bfg ZCML into a ``repoze.bfg.includes`` package so we + can use repoze.bfg better as a namespace package. Adjust the code + generator to use it. We've left around the ``configure.zcml`` in the + repoze.bfg package directly so as not to break older apps. + +- When a zcml application registry cache was unpickled, and it contained a + reference to an object that no longer existed (such as a view), bfg would + not start properly. + +0.3.5 (2008-09-01) +================== + +Features +-------- + +- Event notification is issued after application is created and configured + (``IWSGIApplicationCreatedEvent``). + +- New API module: ``repoze.bfg.view``. This module contains the functions + named ``render_view_to_response``, ``render_view_to_iterable``, + ``render_view`` and ``is_response``, which are documented in the API + docs. These features aid programmatic (non-server-driven) view + execution. + +0.3.4 (2008-08-28) +================== + +Backwards incompatibilities +--------------------------- + +- Make ``repoze.bfg`` a namespace package so we can allow folks to create + subpackages (e.g. ``repoze.bfg.otherthing``) within separate eggs. This + is a backwards incompatible change which makes it impossible to import + "make_app" and "get_options" from the ``repoze.bfg`` module directly. + This change will break all existing apps generated by the paster code + generator. Instead, you need to import these functions as + ``repoze.bfg.router:make_app`` and ``repoze.bfg.registry:get_options``, + respectively. Sorry folks, it has to be done now or never, and + definitely better now. + +Features +-------- + +- Add ``model_path`` API function to traversal module. + +Bugfixes + +- Normalize path returned by repoze.bfg.caller_path. + +0.3.3 (2008-08-23) +================== + +- Fix generated test.py module to use project name rather than package + name. + +0.3.2 (2008-08-23) +================== + +- Remove ``sampleapp`` sample application from bfg package itself. + +- Remove dependency on FormEncode (only needed by sampleapp). + +- Fix paster template generation so that case-sensitivity is preserved for + project vs. package name. + +- Depend on ``z3c.pt`` version 1.0a1 (which requires the ``[lxml]`` extra + currently). + +- Read and write a pickled ZCML actions list, stored as + ``configure.zcml.cache`` next to the applications's "normal" + configuration file. A given bfg app will usually start faster if it's + able to read the pickle data. It fails gracefully to reading the real + ZCML file if it cannot read the pickle. + +0.3.1 (2008-08-20) +================== + +- Generated application differences: ``make_app`` entry point renamed to + ``app`` in order to have a different name than the bfg function of the + same name, to prevent confusion. + +- Add "options" processing to bfg's ``make_app`` to support runtime + options. A new API function named ``get_options`` was added to the + registry module. This function is typically used in an application's + ``app`` entry point. The Paste config file section for the app can now + supply the ``reload_templates`` option, which, if true, will prevent the + need to restart the appserver in order for ``z3c.pt`` or XSLT template + changes to be detected. + +- Use only the module name in generated project's "test_suite" (run all + tests found in the package). + +- Default port for generated apps changed from 5432 to 6543 (Postgres + default port is 6543). + +0.3.0 (2008-08-16) +================== + +- Add ``get_template`` API to template module. + +0.2.9 (2008-08-11) +================== + +- 0.2.8 was "brown bag" release. It didn't work at all. Symptom: + ComponentLookupError when trying to render a page. + +0.2.8 (2008-08-11) +================== + +- Add ``find_model`` and ``find_root`` traversal APIs. In the process, + make ITraverser a uni-adapter (on context) rather than a multiadapter (on + context and request). + +0.2.7 (2008-08-05) +================== + +- Add a ``request_type`` attribute to the available attributes of a + ``bfg:view`` configure.zcml element. This attribute will have a value + which is a dotted Python path, pointing at an interface. If the request + object implements this interface when the view lookup is performed, the + appropriate view will be called. This is meant to allow for simple + "skinning" of sites based on request type. An event subscriber should + attach the interface to the request on ingress to support skins. + +- Remove "template only" views. These were just confusing and were never + documented. + +- Small url dispatch overhaul: the ``connect`` method of the + ``urldispatch.RoutesMapper`` object now accepts a keyword parameter named + ``context_factory``. If this parameter is supplied, it must be a + callable which returns an instance. This instance is used as the context + for the request when a route is matched. + +- The registration of a RoutesModelTraverser no longer needs to be + performed by the application; it's in the bfg ZCML now. + +0.2.6 (2008-07-31) +================== + +- Add event sends for INewRequest and INewResponse. See the events.rst + chapter in the documentation's ``api`` directory. + +0.2.5 (2008-07-28) +================== + +- Add ``model_url`` API. + +0.2.4 (2008-07-27) +================== + +- Added url-based dispatch. + +0.2.3 (2008-07-20) +================== + +- Add API functions for authenticated_userid and effective_principals. + +0.2.2 (2008-07-20) +================== + +- Add authenticated_userid and effective_principals API to security + policy. + +0.2.1 (2008-07-20) +================== + +- Add find_interface API. + +0.2 (2008-07-19) +================ + +- Add wsgiapp decorator. + +- The concept of "view factories" was removed in favor of always calling a + view, which is a callable that returns a response directly (as opposed to + returning a view). As a result, the ``factory`` attribute in the + bfg:view ZCML statement has been renamed to ``view``. Various interface + names were changed also. + +- ``render_template`` and ``render_transform`` no longer return a Response + object. Instead, these return strings. The old behavior can be obtained + by using ``render_template_to_response`` and + ``render_transform_to_response``. + +- Added 'repoze.bfg.push:pushpage' decorator, which creates BFG views from + callables which take (context, request) and return a mapping of top-level + names. + +- Added ACL-based security. + +- Support for XSLT templates via a render_transform method + +0.1 (2008-07-08) +================ + +- Initial release. + diff --git a/BFG_HISTORY.txt b/BFG_HISTORY.txt deleted file mode 100644 index 8a2d40920..000000000 --- a/BFG_HISTORY.txt +++ /dev/null @@ -1,6373 +0,0 @@ -1.3b1 (2010-10-25) -================== - -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. - -1.3a15 (2010-09-30) -=================== - -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. - -1.3a14 (2010-09-14) -=================== - -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. - -1.3a13 (2010-09-14) -=================== - -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. - -1.3a12 (2010-09-08) -=================== - -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``. - -1.3a11 (2010-09-05) -=================== - -Bug Fixes ---------- - -- Process the response callbacks and the NewResponse event earlier, to - enable mutations to the response to take effect. - -1.3a10 (2010-09-05) -=================== - -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 regsistered 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)``. - -1.3a9 (2010-08-22) -================== - -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 isntead 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 additonal 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 attemtping 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. - -1.3a8 (2010-08-08) -================== - -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. - -1.3a7 (2010-08-01) -================== - -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. - -1.3a6 (2010-07-25) -================== - -Features --------- - -- New argument to ``repoze.bfg.configuration.Configurator.add_route`` - and the ``route`` ZCML directive: ``traverse``. If you would like - to cause the ``context`` to be something other than the ``root`` - object when this route matches, you can spell a traversal pattern as - the ``traverse`` argument. This traversal pattern will be used as - the traversal path: traversal will begin at the root object implied - by this route (either the global root, or the object returned by the - ``factory`` associated with this route). - - The syntax of the ``traverse`` argument is the same as it is for - ``path``. For example, if the ``path`` provided is - ``articles/:article/edit``, and the ``traverse`` argument provided - is ``/:article``, when a request comes in that causes the route to - match in such a way that the ``article`` match value is '1' (when - the request URI is ``/articles/1/edit``), the traversal path will be - generated as ``/1``. This means that the root object's - ``__getitem__`` will be called with the name ``1`` during the - traversal phase. If the ``1`` object exists, it will become the - ``context`` of the request. The Traversal narrative has more - information about traversal. - - If the traversal path contains segment marker names which are not - present in the path argument, a runtime error will occur. The - ``traverse`` pattern should not contain segment markers that do not - exist in the ``path``. - - A similar combining of routing and traversal is available when a - route is matched which contains a ``*traverse`` remainder marker in - its path. The ``traverse`` argument allows you to associate route - patterns with an arbitrary traversal path without using a - ``*traverse`` remainder marker; instead you can use other match - information. - - Note that the ``traverse`` argument is ignored when attached to a - route that has a ``*traverse`` remainder marker in its path. - -- A new method of the ``Configurator`` exists: - ``set_request_factory``. If used, this method will set the factory - used by the ``repoze.bfg`` router to create all request objects. - -- The ``Configurator`` constructor takes an additional argument: - ``request_factory``. If used, this argument will set the factory - used by the ``repoze.bfg`` router to create all request objects. - -- The ``Configurator`` constructor takes an additional argument: - ``request_factory``. If used, this argument will set the factory - used by the ``repoze.bfg`` router to create all request objects. - -- A new method of the ``Configurator`` exists: - ``set_renderer_globals_factory``. If used, this method will set the - factory used by the ``repoze.bfg`` router to create renderer - globals. - -- A new method of the ``Configurator`` exists: ``get_settings``. If - used, this method will return the current settings object (performs - the same job as the ``repoze.bfg.settings.get_settings`` API). - -- The ``Configurator`` constructor takes an additional argument: - ``renderer_globals_factory``. If used, this argument will set the - factory used by the ``repoze.bfg`` router to create renderer - globals. - -- Add ``repoze.bfg.renderers.render``, - ``repoze.bfg.renderers.render_to_response`` and - ``repoze.bfg.renderers.get_renderer`` functions. These are - imperative APIs which will use the same rendering machinery used by - view configurations with a ``renderer=`` attribute/argument to - produce a rendering or renderer. Because these APIs provide a - central API for all rendering, they now form the preferred way to - perform imperative template rendering. Using functions named - ``render_*`` from modules such as ``repoze.bfg.chameleon_zpt`` and - ``repoze.bfg.chameleon_text`` is now discouraged (although not - deprecated). The code the backing older templating-system-specific - APIs now calls into the newer ``repoze.bfg.renderer`` code. - -- The ``repoze.bfg.configuration.Configurator.testing_add_template`` - has been renamed to ``testing_add_renderer``. A backwards - compatibility alias is present using the old name. - -Documentation -------------- - -- The ``Hybrid`` narrative chapter now contains a description of the - ``traverse`` route argument. - -- The ``Hooks`` narrative chapter now contains sections about - changing the request factory and adding a renderer globals factory. - -- The API documentation includes a new module: - ``repoze.bfg.renderers``. - -- The ``Templates`` chapter was updated; all narrative that used - templating-specific APIs within examples to perform rendering (such - as the ``repoze.bfg.chameleon_zpt.render_template_to_response`` - method) was changed to use ``repoze.bfg.renderers.render_*`` - functions. - -Bug Fixes ---------- - -- The ``header`` predicate (when used as either a view predicate or a - route predicate) had a problem when specified with a name/regex - pair. When the header did not exist in the headers dictionary, the - regex match could be fed ``None``, causing it to throw a - ``TypeError: expected string or buffer`` exception. Now, the - predicate returns False as intended. - -Deprecations ------------- - -- The ``repoze.bfg.renderers.rendered_response`` function was never an - official API, but may have been imported by extensions in the wild. - It is officially deprecated in this release. Use - ``repoze.bfg.renderers.render_to_response`` instead. - -- The following APIs are *documentation* deprecated (meaning they are - officially deprecated in documentation but do not raise a - deprecation error upon their usage, and may continue to work for an - indefinite period of time): - - In the ``repoze.bfg.chameleon_zpt`` module: ``get_renderer``, - ``get_template``, ``render_template``, - ``render_template_to_response``. The suggested alternatives are - documented within the docstrings of those methods (which are still - present in the documentation). - - In the ``repoze.bfg.chameleon_text`` module: ``get_renderer``, - ``get_template``, ``render_template``, - ``render_template_to_response``. The suggested alternatives are - documented within the docstrings of those methods (which are still - present in the documentation). - - In general, to perform template-related functions, one should now - use the various methods in the ``repoze.bfg.renderers`` module. - -Backwards Incompatibilities ---------------------------- - -- A new internal exception class (*not* an API) named - ``repoze.bfg.exceptions.PredicateMismatch`` now exists. This - exception is currently raised when no constituent view of a - multiview can be called (due to no predicate match). Previously, in - this situation, a ``repoze.bfg.exceptions.NotFound`` was raised. We - provide backwards compatibility for code that expected a - ``NotFound`` to be raised when no predicates match by causing - ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from - ``NotFound``. This will cause any exception view registered for - ``NotFound`` to be called when a predicate mismatch occurs, as was - the previous behavior. - - There is however, one perverse case that will expose a backwards - incompatibility. If 1) you had a view that was registered as a - member of a multiview 2) this view explicitly raised a ``NotFound`` - exception *in order to* proceed to the next predicate check in the - multiview, that code will now behave differently: rather than - skipping to the next view match, a NotFound will be raised to the - top-level exception handling machinery instead. For code to be - depending upon the behavior of a view raising ``NotFound`` to - proceed to the next predicate match, would be tragic, but not - impossible, given that ``NotFound`` is a public interface. - ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and - cannot be depended upon by application code, so you should not - change your view code to raise ``PredicateMismatch``. Instead, move - the logic which raised the ``NotFound`` exception in the view out - into a custom view predicate. - -- If, when you run your application's unit test suite under BFG 1.3, a - ``KeyError`` naming a template or a ``ValueError`` indicating that a - 'renderer factory' is not registered may is raised - (e.g. ``ValueError: No factory for renderer named '.pt' when looking - up karl.views:templates/snippets.pt``), you may need to perform some - extra setup in your test code. - - The best solution is to use the - ``repoze.bfg.configuration.Configurator.testing_add_renderer`` (or, - alternately the deprecated - ``repoze.bfg.testing.registerTemplateRenderer`` or - ``registerDummyRenderer``) API within the code comprising each - individual unit test suite to register a "dummy" renderer for each - of the templates and renderers used by code under test. For - example:: - - config = Configurator() - config.testing_add_renderer('karl.views:templates/snippets.pt') - - This will register a basic dummy renderer for this particular - missing template. The ``testing_add_renderer`` API actually - *returns* the renderer, but if you don't care about how the render - is used, you don't care about having a reference to it either. - - A more rough way to solve the issue exists. It causes the "real" - template implementations to be used while the system is under test, - which is suboptimal, because tests will run slower, and unit tests - won't actually *be* unit tests, but it is easier. Always ensure you - call the ``setup_registry()`` method of the Configurator . Eg:: - - reg = MyRegistry() - config = Configurator(registry=reg) - config.setup_registry() - - Calling ``setup_registry`` only has an effect if you're *passing in* - a ``registry`` argument to the Configurator constructor. - ``setup_registry`` is called by the course of normal operations - anyway if you do not pass in a ``registry``. - - If your test suite isn't using a Configurator yet, and is still - using the older ``repoze.bfg.testing`` APIs name ``setUp`` or - ``cleanUp``, these will register the renderers on your behalf. - - A variant on the symptom for this theme exists: you may already be - dutifully registering a dummy template or renderer for a template - used by the code you're testing using ``testing_register_renderer`` - or ``registerTemplateRenderer``, but (perhaps unbeknownst to you) - the code under test expects to be able to use a "real" template - renderer implementation to retrieve or render *another* template - that you forgot was being rendered as a side effect of calling the - code you're testing. This happened to work because it found the - *real* template while the system was under test previously, and now - it cannot. The solution is the same. - - It may also help reduce confusion to use a *resource specification* - to specify the template path in the test suite and code rather than - a relative path in either. A resource specification is unambiguous, - while a relative path needs to be relative to "here", where "here" - isn't always well-defined ("here" in a test suite may or may not be - the same as "here" in the code under test). - -1.3a5 (2010-07-14) -================== - -Features --------- - -- New internal exception: ``repoze.bfg.exceptions.URLDecodeError``. - This URL is a subclass of the built-in Python exception named - ``UnicodeDecodeError``. - -- When decoding a URL segment to Unicode fails, the exception raised - is now ``repoze.bfg.exceptions.URLDecodeError`` instead of - ``UnicodeDecodeError``. This makes it possible to register an - exception view invoked specifically when ``repoze.bfg`` cannot - decode a URL. - -Bug Fixes ---------- - -- Fix regression in - ``repoze.bfg.configuration.Configurator.add_static_view``. Before - 1.3a4, view names that contained a slash were supported as route - prefixes. 1.3a4 broke this by trying to treat them as full URLs. - -Documentation -------------- - -- The ``repoze.bfg.exceptions.URLDecodeError`` exception was added to - the exceptions chapter of the API documentation. - -Backwards Incompatibilities ----------------------------- - -- in previous releases, when a URL could not be decoded from UTF-8 - during traversal, a ``TypeError`` was raised. Now the error which - is raised is a ``repoze.bfg.exceptions.URLDecodeError``. - -1.3a4 (2010-07-03) -================== - -Features --------- - -- Undocumented hook: make ``get_app`` and ``get_root`` of the - ``repoze.bfg.paster.BFGShellCommand`` hookable in cases where - endware may interfere with the default versions. - -- In earlier versions, a custom route predicate associated with a url - dispatch route (each of the predicate functions fed to the - ``custom_predicates`` argument of - ``repoze.bfg.configuration.Configurator.add_route``) has always - required a 2-positional argument signature, e.g. ``(context, - request)``. Before this release, the ``context`` argument was - always ``None``. - - As of this release, the first argument passed to a predicate is now - a dictionary conventionally named ``info`` consisting of ``route``, - and ``match``. ``match`` is a dictionary: it represents the - arguments matched in the URL by the route. ``route`` is an object - representing the route which was matched. - - This is useful when predicates need access to the route match. For - example:: - - def any_of(segment_name, *args): - def predicate(info, request): - if info['match'][segment_name] in args: - return True - return predicate - - num_one_two_or_three = any_of('num, 'one', 'two', 'three') - - add_route('num', '/:num', custom_predicates=(num_one_two_or_three,)) - - The ``route`` object is an object that has two useful attributes: - ``name`` and ``path``. The ``name`` attribute is the route name. - The ``path`` attribute is the route pattern. An example of using - the route in a set of route predicates:: - - def twenty_ten(info, request): - if info['route'].name in ('ymd', 'ym', 'y'): - return info['match']['year'] == '2010' - - add_route('y', '/:year', custom_predicates=(twenty_ten,)) - add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,)) - add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,)) - -- The ``repoze.bfg.url.route_url`` API has changed. If a keyword - ``_app_url`` is present in the arguments passed to ``route_url``, - this value will be used as the protocol/hostname/port/leading path - prefix of the generated URL. For example, using an ``_app_url`` of - ``http://example.com:8080/foo`` would cause the URL - ``http://example.com:8080/foo/fleeb/flub`` to be returned from this - function if the expansion of the route pattern associated with the - ``route_name`` expanded to ``/fleeb/flub``. - -- It is now possible to use a URL as the ``name`` argument fed to - ``repoze.bfg.configuration.Configurator.add_static_view``. When the - name argument is a URL, the ``repoze.bfg.url.static_url`` API will - generate join this URL (as a prefix) to a path including the static - file name. This makes it more possible to put static media on a - separate webserver for production, while keeping static media - package-internal and served by the development webserver during - development. - -Documentation -------------- - -- The authorization chapter of the ZODB Wiki Tutorial - (docs/tutorials/bfgwiki) was changed to demonstrate authorization - via a group rather than via a direct username (thanks to Alex - Marandon). - -- The authorization chapter of the SQLAlchemy Wiki Tutorial - (docs/tutorials/bfgwiki2) was changed to demonstrate authorization - via a group rather than via a direct username. - -- Redirect requests for tutorial sources to - http://docs.repoze.org/bfgwiki-1.3 and - http://docs.repoze.org/bfgwiki2-1.3/ respectively. - -- A section named ``Custom Route Predicates`` was added to the URL - Dispatch narrative chapter. - -- The Static Resources chapter has been updated to mention using - ``static_url`` to generate URLs to external webservers. - -Internal --------- - -- Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new - abstraction revolving around the (still-internal) - ``repoze.bfg.static.StaticURLInfo`` helper class. - -1.3a3 (2010-05-01) -================== - -Paster Templates ----------------- - -- The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer - register a ``handle_teardown`` event listener which calls - ``DBSession.remove``. This was found by Chris Withers to be - unnecessary. - -Documentation -------------- - -- The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation - was changed to remove the ``handle_teardown`` event listener which - calls ``DBSession.remove``. - -- Any mention of the ``handle_teardown`` event listener as used by the - paster templates was removed from the URL Dispatch narrative chapter. - -- A section entitled Detecting Available Languages was added to the - i18n narrative docs chapter. - -1.3a2 (2010-04-28) -================== - -Features --------- - -- A locale negotiator no longer needs to be registered explicitly. The - default locale negotiator at - ``repoze.bfg.i18n.default_locale_negotiator`` is now used - unconditionally as... um, the default locale negotiator. - -- The default locale negotiator has become more complex. - - * First, the negotiator looks for the ``_LOCALE_`` attribute of - the request object (possibly set by a view or an event listener). - - * Then it looks for the ``request.params['_LOCALE_']`` value. - - * Then it looks for the ``request.cookies['_LOCALE_']`` value. - -Backwards Incompatibilities ---------------------------- - -- The default locale negotiator now looks for the parameter named - ``_LOCALE_`` rather than a parameter named ``locale`` in - ``request.params``. - -Behavior Changes ----------------- - -- A locale negotiator may now return ``None``, signifying that the - default locale should be used. - -Documentation -------------- - -- Documentation concerning locale negotiation in the - Internationalizationa and Localization chapter was updated. - -- Expanded portion of i18n narrative chapter docs which discuss - working with gettext files. - -1.3a1 (2010-04-26) -================== - -Features --------- - -- Added "exception views". When you use an exception (anything that - inherits from the Python ``Exception`` builtin) as view context - argument, e.g.:: - - from repoze.bfg.view import bfg_view - from repoze.bfg.exceptions import NotFound - from webob.exc import HTTPNotFound - - @bfg_view(context=NotFound) - def notfound_view(request): - return HTTPNotFound() - - For the above example, when the ``repoze.bfg.exceptions.NotFound`` - exception is raised by any view or any root factory, the - ``notfound_view`` view callable will be invoked and its response - returned. - - Other normal view predicates can also be used in combination with an - exception view registration:: - - from repoze.bfg.view import bfg_view - from repoze.bfg.exceptions import NotFound - from webob.exc import HTTPNotFound - - @bfg_view(context=NotFound, route_name='home') - def notfound_view(request): - return HTTPNotFound() - - The above exception view names the ``route_name`` of ``home``, - meaning that it will only be called when the route matched has a - name of ``home``. You can therefore have more than one exception - view for any given exception in the system: the "most specific" one - will be called when the set of request circumstances which match the - view registration. The only predicate that cannot be not be used - successfully is ``name``. The name used to look up an exception - view is always the empty string. - - Existing (pre-1.3) normal views registered against objects - inheriting from ``Exception`` will continue to work. Exception - views used for user-defined exceptions and system exceptions used as - contexts will also work. - - The feature can be used with any view registration mechanism - (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view`` - styles). - - This feature was kindly contributed by Andrey Popp. - -- Use "Venusian" (`http://docs.repoze.org/venusian - `_) to perform ``bfg_view`` - decorator scanning rather than relying on a BFG-internal decorator - scanner. (Truth be told, Venusian is really just a generalization - of the BFG-internal decorator scanner). - -- Internationalization and localization features as documented in the - narrative documentation chapter entitled ``Internationalization and - Localization``. - -- A new deployment setting named ``default_locale_name`` was added. - If this string is present as a Paster ``.ini`` file option, it will - be considered the default locale name. The default locale name is - used during locale-related operations such as language translation. - -- It is now possible to turn on Chameleon template "debugging mode" - for all Chameleon BFG templates by setting a BFG-related Paster - ``.ini`` file setting named ``debug_templates``. The exceptions - raised by Chameleon templates when a rendering fails are sometimes - less than helpful. ``debug_templates`` allows you to configure your - application development environment so that exceptions generated by - Chameleon during template compilation and execution will contain - more helpful debugging information. This mode is on by default in - all new projects. - -- Add a new method of the Configurator named ``derive_view`` which can - be used to generate a BFG view callable from a user-supplied - function, instance, or class. This useful for external framework and - plugin authors wishing to wrap callables supplied by their users - which follow the same calling conventions and response conventions - as objects that can be supplied directly to BFG as a view callable. - See the ``derive_view`` method in the - ``repoze.bfg.configuration.Configurator`` docs. - -ZCML ----- - -- Add a ``translationdir`` ZCML directive to support localization. - -- Add a ``localenegotiator`` ZCML directive to support localization. - -Deprecations ------------- - -- The exception views feature replaces the need for the - ``set_notfound_view`` and ``set_forbidden_view`` methods of the - ``Configurator`` as well as the ``notfound`` and ``forbidden`` ZCML - directives. Those methods and directives will continue to work for - the foreseeable future, but they are deprecated in the - documentation. - -Dependencies ------------- - -- A new install-time dependency on the ``venusian`` distribution was - added. - -- A new install-time dependency on the ``translationstring`` - distribution was added. - -- Chameleon 1.2.3 or better is now required (internationalization and - per-template debug settings). - -Internal --------- - -- View registrations and lookups are now done with three "requires" - arguments instead of two to accomodate orthogonality of exception - views. - -- The ``repoze.bfg.interfaces.IForbiddenView`` and - ``repoze.bfg.interfaces.INotFoundView`` interfaces were removed; - they weren't APIs and they became vestigial with the addition of - exception views. - -- Remove ``repoze.bfg.compat.pkgutil_26.py`` and import alias - ``repoze.bfg.compat.walk_packages``. These were only required by - internal scanning machinery; Venusian replaced the internal scanning - machinery, so these are no longer required. - -Documentation -------------- - -- Exception view documentation was added to the ``Hooks`` narrative - chapter. - -- A new narrative chapter entitled ``Internationalization and - Localization`` was added. - -- The "Environment Variables and ``ini`` File Settings" chapter was - changed: documentation about the ``default_locale_name`` setting was - added. - -- A new API chapter for the ``repoze.bfg.i18n`` module was added. - -- Documentation for the new ``translationdir`` and - ``localenegotiator`` ZCML directives were added. - -- A section was added to the Templates chapter entitled "Nicer - Exceptions in Templates" describing the result of setting - ``debug_templates = true``. - -Paster Templates ----------------- - -- All paster templates now create a ``setup.cfg`` which includes - commands related to nose testing and Babel message catalog - extraction/compilation. - -- A ``default_locale_name = en`` setting was added to each existing paster - template. - -- A ``debug_templates = true`` setting was added to each existing - paster template. - -Licensing ---------- - -- The Edgewall (BSD) license was added to the LICENSES.txt file, as - some code in the ``repoze.bfg.i18n`` derives from Babel source. - -1.2 (2010-02-10) -================ - -- No changes from 1.2b6. - -1.2b6 (2010-02-06) -================== - -Backwards Incompatibilities ---------------------------- - -- Remove magical feature of ``repoze.bfg.url.model_url`` which - prepended a fully-expanded urldispatch route URL before a the - model's path if it was noticed that the request had matched a route. - This feature was ill-conceived, and didn't work in all scenarios. - -Bug Fixes ---------- - -- More correct conversion of provided ``renderer`` values to resource - specification values (internal). - -1.2b5 (2010-02-04) -================== - -Bug Fixes ---------- - -- 1.2b4 introduced a bug whereby views added via a route configuration - that named a view callable and also a ``view_attr`` became broken. - Symptom: ``MyViewClass is not callable`` or the ``__call__`` of a - class was being called instead of the method named via - ``view_attr``. - -- Fix a bug whereby a ``renderer`` argument to the ``@bfg_view`` - decorator that provided a package-relative template filename might - not have been resolved properly. Symptom: inappropriate ``Missing - template resource`` errors. - -1.2b4 (2010-02-03) -================== - -Documentation -------------- - -- Update GAE tutorial to use Chameleon instead of Jinja2 (now that - it's possible). - -Bug Fixes ---------- - -- Ensure that ``secure`` flag for AuthTktAuthenticationPolicy - constructor does what it's documented to do (merge Daniel Holth's - fancy-cookies-2 branch). - -Features --------- - -- Add ``path`` and ``http_only`` options to - AuthTktAuthenticationPolicy constructor (merge Daniel Holth's - fancy-cookies-2 branch). - -Backwards Incompatibilities ---------------------------- - -- Remove ``view_header``, ``view_accept``, ``view_xhr``, - ``view_path_info``, ``view_request_method``, ``view_request_param``, - and ``view_containment`` predicate arguments from the - ``Configurator.add_route`` argument list. These arguments were - speculative. If you need the features exposed by these arguments, - add a view associated with a route using the ``route_name`` argument - to the ``add_view`` method instead. - -- Remove ``view_header``, ``view_accept``, ``view_xhr``, - ``view_path_info``, ``view_request_method``, ``view_request_param``, - and ``view_containment`` predicate arguments from the ``route`` ZCML - directive attribute set. These attributes were speculative. If you - need the features exposed by these attributes, add a view associated - with a route using the ``route_name`` attribute of the ``view`` ZCML - directive instead. - -Dependencies ------------- - -- Remove dependency on ``sourcecodegen`` (not depended upon by - Chameleon 1.1.1+). - -1.2b3 (2010-01-24) -================== - -Bug Fixes ---------- - -- When "hybrid mode" (both traversal and urldispatch) is in use, - default to finding route-related views even if a non-route-related - view registration has been made with a more specific context. The - default used to be to find views with a more specific context first. - Use the new ``use_global_views`` argument to the route definition to - get back the older behavior. - -Features --------- - -- Add ``use_global_views`` argument to ``add_route`` method of - Configurator. When this argument is true, views registered for *no* - route will be found if no more specific view related to the route is - found. - -- Add ``use_global_views`` attribute to ZCML ```` directive - (see above). - -Internal --------- - -- When registering a view, register the view adapter with the - "requires" interfaces as ``(request_type, context_type)`` rather - than ``(context_type, request_type)``. This provides for saner - lookup, because the registration will always be made with a specific - request interface, but registration may not be made with a specific - context interface. In general, when creating multiadapters, you - want to order the requires interfaces so that the elements which - are more likely to be registered using specific interfaces are - ordered before those which are less likely. - -1.2b2 (2010-01-21) -================== - -Bug Fixes ---------- - -- When the ``Configurator`` is passed an instance of - ``zope.component.registry.Components`` as a ``registry`` constructor - argument, fix the instance up to have the attributes we expect of an - instance of ``repoze.bfg.registry.Registry`` when ``setup_registry`` - is called. This makes it possible to use the global Zope component - registry as a BFG application registry. - -- When WebOb 0.9.7.1 was used, a deprecation warning was issued for - the class attribute named ``charset`` within - ``repoze.bfg.request.Request``. BFG now *requires* WebOb >= 0.9.7, - and code was added so that this deprecation warning has disappeared. - -- Fix a view lookup ordering bug whereby a view with a larger number - of predicates registered first (literally first, not "earlier") for - a triad would lose during view lookup to one registered with fewer. - -- Make sure views with exactly N custom predicates are always called - before views with exactly N non-custom predicates given all else is - equal in the view configuration. - -Documentation -------------- - -- Change renderings of ZCML directive documentation. - -- Add a narrative documentation chapter: "Using the Zope Component - Architecture in repoze.bfg". - -Dependencies ------------- - -- Require WebOb >= 0.9.7 - -1.2b1 (2010-01-18) -================== - -Bug Fixes ---------- - -- In ``bfg_routesalchemy``, ``bfg_alchemy`` paster templates and the - ``bfgwiki2`` tutorial, clean up the SQLAlchemy connection by - registering a ``repoze.tm.after_end`` callback instead of relying on - a ``__del__`` method of a ``Cleanup`` class added to the WSGI - environment. The ``__del__`` strategy was fragile and caused - problems in the wild. Thanks to Daniel Holth for testing. - -Features --------- - -- Read logging configuration from PasteDeploy config file ``loggers`` - section (and related) when ``paster bfgshell`` is invoked. - -Documentation -------------- - -- Major rework in preparation for book publication. - -1.2a11 (2010-01-05) -=================== - -Bug Fixes ---------- - -- Make ``paster bfgshell`` and ``paster create -t bfg_xxx`` work on - Jython (fix minor incompatibility with treatment of ``__doc__`` at - the class level). - -- Updated dependency on ``WebOb`` to require a version which supports - features now used in tests. - -Features --------- - -- Jython compatibility (at least when repoze.bfg.jinja2 is used as the - templating engine; Chameleon does not work under Jython). - -- Show the derived abspath of template resource specifications in the - traceback when a renderer template cannot be found. - -- Show the original traceback when a Chameleon template cannot be - rendered due to a platform incompatibility. - -1.2a10 (2010-01-04) -=================== - -Features --------- - -- The ``Configurator.add_view`` method now accepts an argument named - ``context``. This is an alias for the older argument named - ``for_``; it is preferred over ``for_``, but ``for_`` will continue - to be supported "forever". - -- The ``view`` ZCML directive now accepts an attribute named - ``context``. This is an alias for the older attribute named - ``for``; it is preferred over ``for``, but ``for`` will continue to - be supported "forever". - -- The ``Configurator.add_route`` method now accepts an argument named - ``view_context``. This is an alias for the older argument named - ``view_for``; it is preferred over ``view_for``, but ``view_for`` - will continue to be supported "forever". - -- The ``route`` ZCML directive now accepts an attribute named - ``view_context``. This is an alias for the older attribute named - ``view_for``; it is preferred over ``view_for``, but ``view_for`` - will continue to be supported "forever". - -Documentation and Paster Templates ----------------------------------- - -- LaTeX rendering tweaks. - -- All uses of the ``Configurator.add_view`` method that used its - ``for_`` argument now use the ``context`` argument instead. - -- All uses of the ``Configurator.add_route`` method that used its - ``view_for`` argument now use the ``view_context`` argument instead. - -- All uses of the ``view`` ZCML directive that used its ``for`` - attribute now use the ``context`` attribute instead. - -- All uses of the ``route`` ZCML directive that used its ``view_for`` - attribute now use the ``view_context`` attribute instead. - -- Add a (minimal) tutorial dealing with use of ``repoze.catalog`` in a - ``repoze.bfg`` application. - -Documentation Licensing ------------------------ - -- Loosen the documentation licensing to allow derivative works: it is - now offered under the `Creative Commons - Attribution-Noncommercial-Share Alike 3.0 United States License - `_. This is - only a documentation licensing change; the ``repoze.bfg`` software - continues to be offered under the Repoze Public License at - http://repoze.org/license.html (BSD-like). - -1.2a9 (2009-12-27) -================== - -Documentation Licensing ------------------------ - -- The *documentation* (the result of ``make `` - within the ``docs`` directory) in this release is now offered under - the Creative Commons Attribution-Noncommercial-No Derivative Works - 3.0 United States License as described by - http://creativecommons.org/licenses/by-nc-nd/3.0/us/ . This is only - a licensing change for the documentation; the ``repoze.bfg`` - software continues to be offered under the Repoze Public License - at http://repoze.org/license.html (BSD-like). - -Documentation -------------- - -- Added manual index entries to generated index. - -- Document the previously existing (but non-API) - ``repoze.bfg.configuration.Configurator.setup_registry`` method as - an official API of a ``Configurator``. - -- Fix syntax errors in various documentation code blocks. - -- Created new top-level documentation section: "ZCML Directives". - This section contains detailed ZCML directive information, some of - which was removed from various narrative chapters. - -- The LaTeX rendering of the documentation has been improved. - -- Added a "Fore-Matter" section with author, copyright, and licensing - information. - -1.2a8 (2009-12-24) -================== - -Features --------- - -- Add a ``**kw`` arg to the ``Configurator.add_settings`` API. - -- Add ``hook_zca`` and ``unhook_zca`` methods to the ``Configurator`` - API. - -- The ``repoze.bfg.testing.setUp`` method now returns a - ``Configurator`` instance which can be used to do further - configuration during unit tests. - -Bug Fixes ---------- - -- The ``json`` renderer failed to set the response content type to - ``application/json``. It now does, by setting - ``request.response_content_type`` unless this attribute is already - set. - -- The ``string`` renderer failed to set the response content type to - ``text/plain``. It now does, by setting - ``request.response_content_type`` unless this attribute is already - set. - -Documentation -------------- - -- General documentation improvements by using better Sphinx roles such - as "class", "func", "meth", and so on. This means that there are - many more hyperlinks pointing to API documentation for API - definitions in all narrative, tutorial, and API documentation - elements. - -- Added a description of imperative configuration in various places - which only described ZCML configuration. - -- A syntactical refreshing of various tutorials. - -- Added the ``repoze.bfg.authentication``, - ``repoze.bfg.authorization``, and ``repoze.bfg.interfaces`` modules - to API documentation. - -Deprecations ------------- - -- The ``repoze.bfg.testing.registerRoutesMapper`` API (added in an - early 1.2 alpha) was deprecated. Its import now generates a - deprecation warning. - -1.2a7 (2009-12-20) -================== - -Features --------- - -- Add four new testing-related APIs to the - ``repoze.bfg.configuration.Configurator`` class: - ``testing_securitypolicy``, ``testing_models``, - ``testing_add_subscriber``, and ``testing_add_template``. These - were added in order to provide more direct access to the - functionality of the ``repoze.bfg.testing`` APIs named - ``registerDummySecurityPolicy``, ``registerModels``, - ``registerEventListener``, and ``registerTemplateRenderer`` when a - configurator is used. The ``testing`` APIs named are nominally - deprecated (although they will likely remain around "forever", as - they are in heavy use in the wild). - -- Add a new API to the ``repoze.bfg.configuration.Configurator`` - class: ``add_settings``. This API can be used to add "settings" - (information returned within via the - ``repoze.bfg.settings.get_settings`` API) after the configurator has - been initially set up. This is most useful for testing purposes. - -- Add a ``custom_predicates`` argument to the ``Configurator`` - ``add_view`` method, the ``bfg_view`` decorator and the attribute - list of the ZCML ``view`` directive. If ``custom_predicates`` is - specified, it must be a sequence of predicate callables (a predicate - callable accepts two arguments: ``context`` and ``request`` and - returns ``True`` or ``False``). The associated view callable will - only be invoked if all custom predicates return ``True``. Use one - or more custom predicates when no existing predefined predicate is - useful. Predefined and custom predicates can be mixed freely. - -- Add a ``custom_predicates`` argument to the ``Configurator`` - ``add_route`` and the attribute list of the ZCML ``route`` - directive. If ``custom_predicates`` is specified, it must be a - sequence of predicate callables (a predicate callable accepts two - arguments: ``context`` and ``request`` and returns ``True`` or - ``False``). The associated route will match will only be invoked if - all custom predicates return ``True``, else route matching - continues. Note that the value ``context`` will always be ``None`` - when passed to a custom route predicate. Use one or more custom - predicates when no existing predefined predicate is useful. - Predefined and custom predicates can be mixed freely. - -Internal --------- - -- Remove the ``repoze.bfg.testing.registerTraverser`` function. This - function was never an API. - -Documenation ------------- - -- Doc-deprecated most helper functions in the ``repoze.bfg.testing`` - module. These helper functions likely won't be removed any time - soon, nor will they generate a warning any time soon, due to their - heavy use in the wild, but equivalent behavior exists in methods of - a Configurator. - -1.2a6 (2009-12-18) -================== - -Features --------- - -- The ``Configurator`` object now has two new methods: ``begin`` and - ``end``. The ``begin`` method is meant to be called before any - "configuration" begins (e.g. before ``add_view``, et. al are - called). The ``end`` method is meant to be called after all - "configuration" is complete. - - Previously, before there was imperative configuration at all (1.1 - and prior), configuration begin and end was invariably implied by - the process of loading a ZCML file. When a ZCML load happened, the - threadlocal data structure containing the request and registry was - modified before the load, and torn down after the load, making sure - that all framework code that needed ``get_current_registry`` for the - duration of the ZCML load was satisfied. - - Some API methods called during imperative configuration, (such as - ``Configurator.add_view`` when a renderer is involved) end up for - historical reasons calling ``get_current_registry``. However, in - 1.2a5 and below, the Configurator supplied no functionality that - allowed people to make sure that ``get_current_registry`` returned - the registry implied by the configurator being used. ``begin`` now - serves this purpose. Inversely, ``end`` pops the thread local - stack, undoing the actions of ``begin``. - - We make this boundary explicit to reduce the potential for confusion - when the configurator is used in different circumstances (e.g. in - unit tests and app code vs. just in initial app setup). - - Existing code written for 1.2a1-1.2a5 which does not call ``begin`` - or ``end`` continues to work in the same manner it did before. It - is however suggested that this code be changed to call ``begin`` and - ``end`` to reduce the potential for confusion in the future. - -- All ``paster`` templates which generate an application skeleton now - make use of the new ``begin`` and ``end`` methods of the - Configurator they use in their respective copies of ``run.py`` and - ``tests.py``. - -Documentation -------------- - -- All documentation that makes use of a ``Configurator`` object to do - application setup and test setup now makes use of the new ``begin`` - and ``end`` methods of the configurator. - -Bug Fixes ---------- - -- When a ``repoze.bfg.exceptions.NotFound`` or - ``repoze.bfg.exceptions.Forbidden`` *class* (as opposed to instance) - was raised as an exception within a root factory (or route root - factory), the exception would not be caught properly by the - ``repoze.bfg.`` Router and it would propagate to up the call stack, - as opposed to rendering the not found view or the forbidden view as - would have been expected. - -- When Chameleon page or text templates used as renderers were added - imperatively (via ``Configurator.add_view`` or some derivative), - they too-eagerly attempted to look up the ``reload_templates`` - setting via ``get_settings``, meaning they were always registered in - non-auto-reload-mode (the default). Each now waits until its - respective ``template`` attribute is accessed to look up the value. - -- When a route with the same name as a previously registered route was - added, the old route was not removed from the mapper's routelist. - Symptom: the old registered route would be used (and possibly - matched) during route lookup when it should not have had a chance to - ever be used. - -1.2a5 (2009-12-10) -================== - -Features --------- - -- When the ``repoze.bfg.exceptions.NotFound`` or - ``repoze.bfg.exceptions.Forbidden`` error is raised from within a - custom root factory or the ``factory`` of a route, the appropriate - response is now sent to the requesting user agent (the result of the - notfound view or the forbidden view, respectively). When these - errors are raised from within a root factory, the ``context`` passed - to the notfound or forbidden view will be ``None``. Also, the - request will not be decorated with ``view_name``, ``subpath``, - ``context``, etc. as would normally be the case if traversal had - been allowed to take place. - -Internals ---------- - -- The exception class representing the error raised by various methods - of a ``Configurator`` is now importable as - ``repoze.bfg.exceptions.ConfigurationError``. - -Documentation -------------- - -- General documentation freshening which takes imperative - configuration into account in more places and uses glossary - references more liberally. - -- Remove explanation of changing the request type in a new request - event subscriber, as other predicates are now usually an easier way - to get this done. - -- Added "Thread Locals" narrative chapter to documentation, and added - a API chapter documenting the ``repoze.bfg.threadlocals`` module. - -- Added a "Special Exceptions" section to the "Views" narrative - documentation chapter explaining the effect of raising - ``repoze.bfg.exceptions.NotFound`` and - ``repoze.bfg.exceptions.Forbidden`` from within view code. - -Dependencies ------------- - -- A new dependency on the ``twill`` package was added to the - ``setup.py`` ``tests_require`` argument (Twill will only be - downloaded when ``repoze.bfg`` ``setup.py test`` or ``setup.py - nosetests`` is invoked). - -1.2a4 (2009-12-07) -================== - -Features --------- - -- ``repoze.bfg.testing.DummyModel`` now accepts a new constructor - keyword argument: ``__provides__``. If this constructor argument is - provided, it should be an interface or a tuple of interfaces. The - resulting model will then provide these interfaces (they will be - attached to the constructed model via - ``zope.interface.alsoProvides``). - -Bug Fixes ---------- - -- Operation on GAE was broken, presumably because the - ``repoze.bfg.configuration`` module began to attempt to import the - ``repoze.bfg.chameleon_zpt`` and ``repoze.bfg.chameleon_text`` - modules, and these cannot be used on non-CPython platforms. It now - tolerates startup time import failures for these modules, and only - raise an import error when a template from one of these packages is - actually used. - -1.2a3 (2009-12-02) -================== - -Bug Fixes ---------- - -- The ``repoze.bfg.url.route_url`` function inappropriately passed - along ``_query`` and/or ``_anchor`` arguments to the - ``mapper.generate`` function, resulting in blowups. - -- When two views were registered with differering ``for`` interfaces - or classes, and the ``for`` of first view registered was a - superclass of the second, the ``repoze.bfg`` view machinery would - incorrectly associate the two views with the same "multiview". - Multiviews are meant to be collections of views that have *exactly* - the same for/request/viewname values, without taking inheritance - into account. Symptom: wrong view callable found even when you had - correctly specified a ``for_`` interface/class during view - configuration for one or both view configurations. - -Backwards Incompatibilities ---------------------------- - -- The ``repoze.bfg.templating`` module has been removed; it had been - deprecated in 1.1 and never actually had any APIs in it. - -1.2a2 (2009-11-29) -================== - -Bug Fixes ---------- - -- The long description of this package (as shown on PyPI) was not - valid reStructuredText, and so was not renderable. - -- Trying to use an HTTP method name string such as ``GET`` as a - ``request_type`` predicate argument caused a startup time failure - when it was encountered in imperative configuration or in a - decorator (symptom: ``Type Error: Required specification must be a - specification``). This now works again, although ``request_method`` - is now the preferred predicate argument for associating a view - configuration with an HTTP request method. - -Documentation -------------- - -- Fixed "Startup" narrative documentation chapter; it was explaining - "the old way" an application constructor worked. - -1.2a1 (2009-11-28) -================== - -Features --------- - -- An imperative configuration mode. - - A ``repoze.bfg`` application can now begin its life as a single - Python file. Later, the application might evolve into a set of - Python files in a package. Even later, it might start making use of - other configuration features, such as ``ZCML``. But neither the use - of a package nor the use of non-imperative configuration is required - to create a simple ``repoze.bfg`` application any longer. - - Imperative configuration makes ``repoze.bfg`` competetive with - "microframeworks" such as `Bottle `_ and - `Tornado `_. ``repoze.bfg`` has a good - deal of functionality that most microframeworks lack, so this is - hopefully a "best of both worlds" feature. - - The simplest possible ``repoze.bfg`` application is now:: - - from webob import Response - from wsgiref import simple_server - from repoze.bfg.configuration import Configurator - - def hello_world(request): - return Response('Hello world!') - - if __name__ == '__main__': - config = Configurator() - config.add_view(hello_world) - app = config.make_wsgi_app() - simple_server.make_server('', 8080, app).serve_forever() - -- A new class now exists: ``repoze.bfg.configuration.Configurator``. - This class forms the basis for sharing machinery between - "imperatively" configured applications and traditional - declaratively-configured applications. - -- The ``repoze.bfg.testing.setUp`` function now accepts three extra - optional keyword arguments: ``registry``, ``request`` and - ``hook_zca``. - - If the ``registry`` argument is not ``None``, the argument will be - treated as the registry that is set as the "current registry" (it - will be returned by ``repoze.bfg.threadlocal.get_current_registry``) - for the duration of the test. If the ``registry`` argument is - ``None`` (the default), a new registry is created and used for the - duration of the test. - - The value of the ``request`` argument is used as the "current - request" (it will be returned by - ``repoze.bfg.threadlocal.get_current_request``) for the duration of - the test; it defaults to ``None``. - - If ``hook_zca`` is ``True`` (the default), the - ``zope.component.getSiteManager`` function will be hooked with a - function that returns the value of ``registry`` (or the - default-created registry if ``registry`` is ``None``) instead of the - registry returned by ``zope.component.getGlobalSiteManager``, - causing the Zope Component Architecture API (``getSiteManager``, - ``getAdapter``, ``getUtility``, and so on) to use the testing - registry instead of the global ZCA registry. - -- The ``repoze.bfg.testing.tearDown`` function now accepts an - ``unhook_zca`` argument. If this argument is ``True`` (the - default), ``zope.component.getSiteManager.reset()`` will be called. - This will cause the result of the ``zope.component.getSiteManager`` - function to be the global ZCA registry (the result of - ``zope.component.getGlobalSiteManager``) once again. - -- The ``run.py`` module in various ``repoze.bfg`` ``paster`` templates - now use a ``repoze.bfg.configuration.Configurator`` class instead of - the (now-legacy) ``repoze.bfg.router.make_app`` function to produce - a WSGI application. - -Documentation -------------- - -- The documentation now uses the "request-only" view calling - convention in most examples (as opposed to the ``context, request`` - convention). This is a documentation-only change; the ``context, - request`` convention is also supported and documented, and will be - "forever". - -- ``repoze.bfg.configuration`` API documentation has been added. - -- A narrative documentation chapter entitled "Creating Your First - ``repoze.bfg`` Application" has been added. This chapter details - usage of the new ``repoze.bfg.configuration.Configurator`` class, - and demonstrates a simplified "imperative-mode" configuration; doing - ``repoze.bfg`` application configuration imperatively was previously - much more difficult. - -- A narrative documentation chapter entitled "Configuration, - Decorations and Code Scanning" explaining ZCML- vs. imperative- - vs. decorator-based configuration equivalence. - -- The "ZCML Hooks" chapter has been renamed to "Hooks"; it documents - how to override hooks now via imperative configuration and ZCML. - -- The explanation about how to supply an alternate "response factory" - has been removed from the "Hooks" chapter. This feature may be - removed in a later release (it still works now, it's just not - documented). - -- Add a section entitled "Test Set Up and Tear Down" to the - unittesting chapter. - -Bug Fixes ----------- - -- The ACL authorization policy debugging output when - ``debug_authorization`` console debugging output was turned on - wasn't as clear as it could have been when a view execution was - denied due to an authorization failure resulting from the set of - principals passed never having matched any ACE in any ACL in the - lineage. Now in this case, we report ```` as the ACE - value and either the root ACL or ```` if no ACL was found. - -- When two views were registered with the same ``accept`` argument, - but were otherwise registered with the same arguments, if a request - entered the application which had an ``Accept`` header that accepted - *either* of the media types defined by the set of views registered - with predicates that otherwise matched, a more or less "random" one - view would "win". Now, we try harder to use the view callable - associated with the view configuration that has the most specific - ``accept`` argument. Thanks to Alberto Valverde for an initial - patch. - -Internals ---------- - -- The routes mapper is no longer a root factory wrapper. It is now - consulted directly by the router. - -- The ``repoze.bfg.registry.make_registry`` callable has been removed. - -- The ``repoze.bfg.view.map_view`` callable has been removed. - -- The ``repoze.bfg.view.owrap_view`` callable has been removed. - -- The ``repoze.bfg.view.predicate_wrap`` callable has been removed. - -- The ``repoze.bfg.view.secure_view`` callable has been removed. - -- The ``repoze.bfg.view.authdebug_view`` callable has been removed. - -- The ``repoze.bfg.view.renderer_from_name`` callable has been - removed. Use ``repoze.bfg.configuration.Configurator.renderer_from_name`` - instead (still not an API, however). - -- The ``repoze.bfg.view.derive_view`` callable has been removed. Use - ``repoze.bfg.configuration.Configurator.derive_view`` instead (still - not an API, however). - -- The ``repoze.bfg.settings.get_options`` callable has been removed. - Its job has been subsumed by the ``repoze.bfg.settings.Settings`` - class constructor. - -- The ``repoze.bfg.view.requestonly`` function has been moved to - ``repoze.bfg.configuration.requestonly``. - -- The ``repoze.bfg.view.rendered_response`` function has been moved to - ``repoze.bfg.configuration.rendered_response``. - -- The ``repoze.bfg.view.decorate_view`` function has been moved to - ``repoze.bfg.configuration.decorate_view``. - -- The ``repoze.bfg.view.MultiView`` class has been moved to - ``repoze.bfg.configuration.MultiView``. - -- The ``repoze.bfg.zcml.Uncacheable`` class has been removed. - -- The ``repoze.bfg.resource.resource_spec`` function has been removed. - -- All ZCML directives which deal with attributes which are paths now - use the ``path`` method of the ZCML context to resolve a relative - name to an absolute one (imperative configuration requirement). - -- The ``repoze.bfg.scripting.get_root`` API now uses a 'real' WebOb - request rather than a FakeRequest when it sets up the request as a - threadlocal. - -- The ``repoze.bfg.traversal.traverse`` API now uses a 'real' WebOb - request rather than a FakeRequest when it calls the traverser. - -- The ``repoze.bfg.request.FakeRequest`` class has been removed. - -- Most uses of the ZCA threadlocal API (the ``getSiteManager``, - ``getUtility``, ``getAdapter``, ``getMultiAdapter`` threadlocal API) - have been removed from the core. Instead, when a threadlocal is - necessary, the core uses the - ``repoze.bfg.threadlocal.get_current_registry`` API to obtain the - registry. - -- The internal ILogger utility named ``repoze.bfg.debug`` is now just - an IDebugLogger unnamed utility. A named utility with the old name - is registered for b/w compat. - -- The ``repoze.bfg.interfaces.ITemplateRendererFactory`` interface was - removed; it has become unused. - -- Instead of depending on the ``martian`` package to do code scanning, - we now just use our own scanning routines. - -- We now no longer have a dependency on ``repoze.zcml`` package; - instead, the ``repoze.bfg`` package includes implementations of the - ``adapter``, ``subscriber`` and ``utility`` directives. - -- Relating to the following functions: - - ``repoze.bfg.view.render_view`` - - ``repoze.bfg.view.render_view_to_iterable`` - - ``repoze.bfg.view.render_view_to_response`` - - ``repoze.bfg.view.append_slash_notfound_view`` - - ``repoze.bfg.view.default_notfound_view`` - - ``repoze.bfg.view.default_forbidden_view`` - - ``repoze.bfg.configuration.rendered_response`` - - ``repoze.bfg.security.has_permission`` - - ``repoze.bfg.security.authenticated_userid`` - - ``repoze.bfg.security.effective_principals`` - - ``repoze.bfg.security.view_execution_permitted`` - - ``repoze.bfg.security.remember`` - - ``repoze.bfg.security.forget`` - - ``repoze.bfg.url.route_url`` - - ``repoze.bfg.url.model_url`` - - ``repoze.bfg.url.static_url`` - - ``repoze.bfg.traversal.virtual_root`` - - Each of these functions now expects to be called with a request - object that has a ``registry`` attribute which represents the - current ``repoze.bfg`` registry. They fall back to obtaining the - registry from the threadlocal API. - -Backwards Incompatibilites --------------------------- - -- Unit tests which use ``zope.testing.cleanup.cleanUp`` for the - purpose of isolating tests from one another may now begin to fail - due to lack of isolation between tests. - - Here's why: In repoze.bfg 1.1 and prior, the registry returned by - ``repoze.bfg.threadlocal.get_current_registry`` when no other - registry had been pushed on to the threadlocal stack was the - ``zope.component.globalregistry.base`` global registry (aka the - result of ``zope.component.getGlobalSiteManager()``). In repoze.bfg - 1.2+, however, the registry returned in this situation is the new - module-scope ``repoze.bfg.registry.global_registry`` object. The - ``zope.testing.cleanup.cleanUp`` function clears the - ``zope.component.globalregistry.base`` global registry - unconditionally. However, it does not know about the - ``repoze.bfg.registry.global_registry`` object, so it does not clear - it. - - If you use the ``zope.testing.cleanup.cleanUp`` function in the - ``setUp`` of test cases in your unit test suite instead of using the - (more correct as of 1.1) ``repoze.bfg.testing.setUp``, you will need - to replace all calls to ``zope.testing.cleanup.cleanUp`` with a call - to ``repoze.bfg.testing.setUp``. - - If replacing all calls to ``zope.testing.cleanup.cleanUp`` with a - call to ``repoze.bfg.testing.setUp`` is infeasible, you can put this - bit of code somewhere that is executed exactly **once** (*not* for - each test in a test suite; in the `` __init__.py`` of your package - or your package's ``tests`` subpackage would be a reasonable - place):: - - import zope.testing.cleanup - from repoze.bfg.testing import setUp - zope.testing.cleanup.addCleanUp(setUp) - -- When there is no "current registry" in the - ``repoze.bfg.threadlocal.manager`` threadlocal data structure (this - is the case when there is no "current request" or we're not in the - midst of a ``r.b.testing.setUp``-bounded unit test), the ``.get`` - method of the manager returns a data structure containing a *global* - registry. In previous releases, this function returned the global - Zope "base" registry: the result of - ``zope.component.getGlobalSiteManager``, which is an instance of the - ``zope.component.registry.Component`` class. In this release, - however, the global registry returns a globally importable instance - of the ``repoze.bfg.registry.Registry`` class. This registry - instance can always be imported as - ``repoze.bfg.registry.global_registry``. - - Effectively, this means that when you call - ``repoze.bfg.threadlocal.get_current_registry`` when no request or - ``setUp`` bounded unit test is in effect, you will always get back - the global registry that lives in - ``repoze.bfg.registry.global_registry``. It also means that - ``repoze.bfg`` APIs that *call* ``get_current_registry`` will use - this registry. - - This change was made because ``repoze.bfg`` now expects the registry - it uses to have a slightly different API than a bare instance of - ``zope.component.registry.Components``. - -- View registration no longer registers a - ``repoze.bfg.interfaces.IViewPermission`` adapter (it is no longer - checked by the framework; since 1.1, views have been responsible for - providing their own security). - -- The ``repoze.bfg.router.make_app`` callable no longer accepts the - ``authentication_policy`` nor the ``authorization_policy`` - arguments. This feature was deprecated in version 1.0 and has been - removed. - -- Obscure: the machinery which configured views with a - ``request_type`` *and* a ``route_name`` would ignore the request - interface implied by ``route_name`` registering a view only for the - interface implied by ``request_type``. In the unlikely event that - you were trying to use these two features together, the symptom - would have been that views that named a ``request_type`` but which - were also associated with routes were not found when the route - matched. Now if a view is configured with both a ``request_type`` - and a ``route_name``, an error is raised. - -- The ``route`` ZCML directive now no longer accepts the - ``request_type`` or ``view_request_type`` attributes. These - attributes didn't actually work in any useful way (see entry above - this one). - -- Because the ``repoze.bfg`` package now includes implementations of - the ``adapter``, ``subscriber`` and ``utility`` ZCML directives, it - is now an error to have ```` in the ZCML of a ``repoze.bfg`` application. A - ZCML conflict error will be raised if your ZCML does so. This - shouldn't be an issue for "normal" installations; it has always been - the responsibility of the ``repoze.bfg.includes`` ZCML to include - this file in the past; it now just doesn't. - -- The ``repoze.bfg.testing.zcml_configure`` API was removed. Use - the ``Configurator.load_zcml`` API instead. - -Deprecations ------------- - -- The ``repoze.bfg.router.make_app`` function is now nominally - deprecated. Its import and usage does not throw a warning, nor will - it probably ever disappear. However, using a - ``repoze.bfg.configuration.Configurator`` class is now the preferred - way to generate a WSGI application. - - Note that ``make_app`` calls - ``zope.component.getSiteManager.sethook( - repoze.bfg.threadlocal.get_current_registry)`` on the caller's - behalf, hooking ZCA global API lookups, for backwards compatibility - purposes. If you disuse ``make_app``, your calling code will need - to perform this call itself, at least if your application uses the - ZCA global API (``getSiteManager``, ``getAdapter``, etc). - -Dependencies ------------- - -- A dependency on the ``martian`` package has been removed (its - functionality is replaced internally). - -- A dependency on the ``repoze.zcml`` package has been removed (its - functionality is replaced internally). - -1.1.1 (2009-11-21) -================== - -Bug Fixes ---------- - -- "Hybrid mode" applications (applications which explicitly used - traversal *after* url dispatch via ```` paths containing the - ``*traverse`` element) were broken in 1.1-final and all 1.1 alpha - and beta releases. Views registered without a ``route_name`` route - shadowed views registered with a ``route_name`` inappropriately. - -1.1 (2009-11-15) -================ - -Internals ---------- - -- Remove dead IRouteRequirement interface from ``repoze.bfg.zcml`` - module. - -Documentation -------------- - -- Improve the "Extending an Existing Application" narrative chapter. - -- Add more sections to the "Defending Design" chapter. - -1.1b4 (2009-11-12) -================== - -Bug Fixes ---------- - -- Use ``alsoProvides`` in the urldispatch module to attach an - interface to the request rather than ``directlyProvides`` to avoid - disturbing interfaces set in a NewRequest event handler. - -Documentation -------------- - -- Move 1.0.1 and previous changelog to HISTORY.txt. - -- Add examples to ``repoze.bfg.url.model_url`` docstring. - -- Add "Defending BFG Design" chapter to frontpage docs. - -Templates ---------- - -- Remove ``ez_setup.py`` and its import from all paster templates, - samples, and tutorials for ``distribute`` compatibility. The - documentation already explains how to install virtualenv (which will - include some ``setuptools`` package), so these files, imports and - usages were superfluous. - -Deprecations ------------- - -- The ``options`` kw arg to the ``repoze.bfg.router.make_app`` - function is deprecated. In its place is the keyword argument - ``settings``. The ``options`` keyword continues to work, and a - deprecation warning is not emitted when it is detected. However, - the paster templates, code samples, and documentation now make - reference to ``settings`` rather than ``options``. This - change/deprecation was mainly made for purposes of clarity and - symmetry with the ``get_settings()`` API and dicussions of - "settings" in various places in the docs: we want to use the same - name to refer to the same thing everywhere. - -1.1b3 (2009-11-06) -================== - -Features --------- - -- ``repoze.bfg.testing.registerRoutesMapper`` testing facility added. - This testing function registers a routes "mapper" object in the - registry, for tests which require its presence. This function is - documented in the ``repoze.bfg.testing`` API documentation. - -Bug Fixes ---------- - -- Compound statements that used an assignment entered into in an - interactive IPython session invoked via ``paster bfgshell`` no - longer fail to mutate the shell namespace correctly. For example, - this set of statements used to fail:: - - In [2]: def bar(x): return x - ...: - In [3]: list(bar(x) for x in 'abc') - Out[3]: NameError: 'bar' - - In this release, the ``bar`` function is found and the correct - output is now sent to the console. Thanks to Daniel Holth for the - patch. - -- The ``bfgshell`` command did not function properly; it was still - expecting to be able to call the root factory with a bare - ``environ`` rather than a request object. - -Backwards Incompatibilities ---------------------------- - -- The ``repoze.bfg.scripting.get_root`` function now expects a - ``request`` object as its second argument rather than an - ``environ``. - -1.1b2 (2009-11-02) -================== - -Bug Fixes ---------- - -- Prevent PyPI installation failure due to ``easy_install`` trying way - too hard to guess the best version of Paste. When ``easy_install`` - pulls from PyPI it reads links off various pages to determine "more - up to date" versions. It incorrectly picks up a link for an ancient - version of a package named "Paste-Deploy-0.1" (note the dash) when - trying to find the "Paste" distribution and somehow believes it's - the latest version of "Paste". It also somehow "helpfully" decides - to check out a version of this package from SVN. We pin the Paste - dependency version to a version greater than 1.7 to work around - this ``easy_install`` bug. - -Documentation -------------- - -- Fix "Hybrid" narrative chapter: stop claiming that ```` - statements that mention a route_name need to come afer (in XML - order) the ```` statement which creates the route. This - hasn't been true since 1.1a1. - -- "What's New in ``repoze.bfg`` 1.1" document added to narrative - documentation. - -Features --------- - -- Add a new event type: ``repoze.bfg.events.AfterTraversal``. Events - of this type will be sent after traversal is completed, but before - any view code is invoked. Like ``repoze.bfg.events.NewRequest``, - This event will have a single attribute: ``request`` representing - the current request. Unlike the request attribute of - ``repoze.bfg.events.NewRequest`` however, during an AfterTraversal - event, the request object will possess attributes set by the - traverser, most notably ``context``, which will be the context used - when a view is found and invoked. The interface - ``repoze.bfg.events.IAfterTraversal`` can be used to subscribe to - the event. For example:: - - - - Like any framework event, a subscriber function should expect one - parameter: ``event``. - -Dependencies ------------- - -- Rather than depending on ``chameleon.core`` and ``chameleon.zpt`` - distributions individually, depend on Malthe's repackaged - ``Chameleon`` distribution (which includes both ``chameleon.core`` - and ``chameleon.zpt``). - -1.1b1 (2009-11-01) -================== - -Bug Fixes ---------- - -- The routes root factory called route factories and the default route - factory with an environ rather than a request. One of the symptoms - of this bug: applications generated using the ``bfg_zodb`` paster - template in 1.1a9 did not work properly. - -- Reinstate ``renderer`` alias for ``view_renderer`` in the - ```` ZCML directive (in-the-wild 1.1a bw compat). - -- ``bfg_routesalchemy`` paster template: change ```` - declarations: rename ``renderer`` attribute to ``view_renderer``. - -- Header values returned by the ``authtktauthenticationpolicy`` - ``remember`` and ``forget`` methods would be of type ``unicode``. - This violated the WSGI spec, causing a ``TypeError`` to be raised - when these headers were used under ``mod_wsgi``. - -- If a BFG app that had a route matching the root URL was mounted - under a path in modwsgi, ala ``WSGIScriptAlias /myapp - /Users/chrism/projects/modwsgi/env/bfg.wsgi``, the home route (a - route with the path of ``'/'`` or ``''``) would not match when the - path ``/myapp`` was visited (only when the path ``/myapp/`` was - visited). This is now fixed: if the urldispatch root factory notes - that the PATH_INFO is empty, it converts it to a single slash before - trying to do matching. - -Documentation -------------- - -- In ```` declarations in tutorial ZCML, rename ``renderer`` - attribute to ``view_renderer`` (fwd compat). - -- Fix various tutorials broken by 1.1a9 ```` directive changes. - -Internal --------- - -- Deal with a potential circref in the traversal module. - -1.1a9 (2009-10-31) -================== - -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. - -1.1a8 (2009-10-27) -================== - -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 ```` 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. - -1.1a7 (2009-10-18) -================== - -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. - -1.1a6 (2009-10-15) -================== - -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. - -1.1a5 (2009-10-10) -================== - -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 addtional 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. - -1.1a4 (2009-09-23) -================== - -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 `_. - 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 ```` 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. - -1.1a3 (2009-09-16) -================== - -Documentation -------------- - -- The "Views" narrative chapter in the documentation has been updated - extensively to discuss "renderers". - -Features --------- - -- A ``renderer`` attribute has been added to view configurations, - replacing the previous (1.1a2) version's ``template`` attribute. A - "renderer" is an object which accepts the return value of a view and - converts it to a string. This includes, but is not limited to, - templating systems. - -- A new interface named ``IRenderer`` was added. The existing - interface, ``ITemplateRenderer`` now derives from this new - interface. This interface is internal. - -- A new interface named ``IRendererFactory`` was added. An existing - interface named ``ITemplateRendererFactory`` now derives from this - interface. This interface is internal. - -- The ``view`` attribute of the ``view`` ZCML directive is no longer - required if the ZCML directive also has a ``renderer`` attribute. - This is useful when the renderer is a template renderer and no names - need be passed to the template at render time. - -- A new zcml directive ``renderer`` has been added. It is documented - in the "Views" narrative chapter of the documentation. - -- A ZCML ``view`` directive (and the associated ``bfg_view`` - decorator) can now accept a "wrapper" value. If a "wrapper" value - is supplied, it is the value of a separate view's *name* attribute. - When a view with a ``wrapper`` attribute is rendered, the "inner" - view is first rendered normally. Its body is then attached to the - request as "wrapped_body", and then a wrapper view name is looked up - and rendered (using ``repoze.bfg.render_view_to_response``), passed - the request and the context. The wrapper view is assumed to do - something sensible with ``request.wrapped_body``, usually inserting - its structure into some other rendered template. This feature makes - it possible to specify (potentially nested) "owrap" relationships - between views using only ZCML or decorators (as opposed always using - ZPT METAL and analogues to wrap view renderings in outer wrappers). - -Dependencies ------------- - -- When used under Python < 2.6, BFG now has an installation time - dependency on the ``simplejson`` package. - -Deprecations ------------- - -- The ``repoze.bfg.testing.registerDummyRenderer`` API has been - deprecated in favor of - ``repoze.bfg.testing.registerTemplateRenderer``. A deprecation - warning is *not* issued at import time for the former name; it will - exist "forever"; its existence has been removed from the - documentation, however. - -- The ``repoze.bfg.templating.renderer_from_cache`` function has been - moved to ``repoze.bfg.renderer.template_renderer_factory``. This - was never an API, but code in the wild was spotted that used it. A - deprecation warning is issued at import time for the former. - -Backwards Incompatibilities ---------------------------- - -- The ``ITemplateRenderer`` interface has been changed. Previously - its ``__call__`` method accepted ``**kw``. It now accepts a single - positional parameter named ``kw`` (REVISED: it accepts two - positional parameters as of 1.1a4: ``value`` and ``system``). This - is mostly an internal change, but it was exposed in APIs in one - place: if you've used the - ``repoze.bfg.testing.registerDummyRenderer`` API in your tests with - a custom "renderer" argument with your own renderer implementation, - you will need to change that renderer implementation to accept - ``kw`` instead of ``**kw`` in its ``__call__`` method (REVISED: make - it accept ``value`` and ``system`` positional arguments as of 1.1a4). - -- The ``ITemplateRendererFactory`` interface has been changed. - Previously its ``__call__`` method accepted an ``auto_reload`` - keyword parameter. Now its ``__call__`` method accepts no keyword - parameters. Renderers are now themselves responsible for - determining details of auto-reload. This is purely an internal - change. This interface was never external. - -- The ``template_renderer`` ZCML directive introduced in 1.1a2 has - been removed. It has been replaced by the ``renderer`` directive. - -- The previous release (1.1a2) added a view configuration attribute - named ``template``. In this release, the attribute has been renamed - to ``renderer``. This signifies that the attribute is more generic: - it can now be not just a template name but any renderer name (ala - ``json``). - -- In the previous release (1.1a2), the Chameleon text template - renderer was used if the system didn't associate the ``template`` - view configuration value with a filename with a "known" extension. - In this release, you must use a ``renderer`` attribute which is a - path that ends with a ``.txt`` extension - (e.g. ``templates/foo.txt``) to use the Chameleon text renderer. - -1.1a2 (2009-09-14) -================== - -Features --------- - -- A ZCML ``view`` directive (and the associated ``bfg_view`` - decorator) can now accept an "attr" value. If an "attr" value is - supplied, it is considered a method named of the view object to be - called when the response is required. This is typically only good - for views that are classes or instances (not so useful for - functions, as functions typically have no methods other than - ``__call__``). - -- A ZCML ``view`` directive (and the associated ``bfg_view`` - decorator) can now accept a "template" value. If a "template" value - is supplied, and the view callable returns a dictionary, the - associated template is rendered with the dictionary as keyword - arguments. See the section named "Views That Have a ``template``" - in the "Views" narrative documentation chapter for more information. - -1.1a1 (2009-09-06) -================== - -Bug Fixes ---------- - -- "tests" module removed from the bfg_alchemy paster template; these - tests didn't work. - -- Bugfix: the ``discriminator`` for the ZCML "route" directive was - incorrect. It was possible to register two routes that collided - without the system spitting out a ConfigurationConflictError at - startup time. - -Features --------- - -- Feature addition: view predicates. These are exposed as the - ``request_method``, ``request_param``, and ``containment`` - attributes of a ZCML ``view`` declaration, or the respective - arguments to a ``@bfg_view`` decorator. View predicates can be used - to register a view for a more precise set of environment parameters - than was previously possible. For example, you can register two - views with the same ``name`` with different ``request_param`` - attributes. If the ``request.params`` dict contains 'foo' - (request_param="foo"), one view might be called; if it contains - 'bar' (request_param="bar"), another view might be called. - ``request_param`` can also name a key/value pair ala ``foo=123``. - This will match only when the ``foo`` key is in the request.params - dict and it has the value '123'. This particular example makes it - possible to write separate view functions for different form - submissions. The other predicates, ``containment`` and - ``request_method`` work similarly. ``containment`` is a view - predicate that will match only when the context's graph lineage has - an object possessing a particular class or interface, for example. - ``request_method`` is a view predicate that will match when the HTTP - ``REQUEST_METHOD`` equals some string (eg. 'POST'). - -- The ``@bfg_view`` decorator now accepts three additional arguments: - ``request_method``, ``request_param``, and ``containment``. - ``request_method`` is used when you'd like the view to match only a - request with a particular HTTP ``REQUEST_METHOD``; a string naming - the ``REQUEST_METHOD`` can also be supplied as ``request_type`` for - backwards compatibility. ``request_param`` is used when you'd like - a view to match only a request that contains a particular - ``request.params`` key (with or without a value). ``containment`` - is used when you'd like to match a request that has a context that - has some class or interface in its graph lineage. These are - collectively known as "view predicates". - -- The ``route`` ZCML directive now honors ``view_request_method``, - ``view_request_param`` and ``view_containment`` attributes, which - pass along these values to the associated view if any is provided. - Additionally, the ``request_type`` attribute can now be spelled as - ``view_request_type``, and ``permission`` can be spelled as - ``view_permission``. Any attribute which starts with ``view_`` can - now be spelled without the ``view_`` prefix, so ``view_for`` can be - spelled as ``for`` now, etc. Both forms are documented in the - urldispatch narraitve documentation chapter. - -- The ``request_param`` ZCML view directive attribute (and its - ``bfg_view`` decorator cousin) can now specify both a key and a - value. For example, ``request_param="foo=123"`` means that the foo - key must have a value of ``123`` for the view to "match". - -- Allow ``repoze.bfg.traversal.find_interface`` API to use a class - object as the argument to compare against the ``model`` passed in. - This means you can now do ``find_interface(model, SomeClass)`` and - the first object which is found in the lineage which has - ``SomeClass`` as its class (or the first object found which has - ``SomeClass`` as any of its superclasses) will be returned. - -- Added ``static`` ZCML directive which registers a route for a view - that serves up files in a directory. See the "Views" narrative - documentation chapter's "Serving Static Resources Using a ZCML - Directive" section for more information. - -- The ``repoze.bfg.view.static`` class now accepts a string as its - first argument ("root_dir") that represents a package-relative name - e.g. ``somepackage:foo/bar/static``. This is now the preferred - mechanism for spelling package-relative static paths using this - class. A ``package_name`` keyword argument has been left around for - backwards compatibility. If it is supplied, it will be honored. - -- The API ``repoze.bfg.testing.registerView`` now takes a - ``permission`` argument. Use this instead of using - ``repoze.bfg.testing.registerViewPermission``. - -- The ordering of route declarations vs. the ordering of view - declarations that use a "route_name" in ZCML no longer matters. - Previously it had been impossible to use a route_name from a route - that had not yet been defined in ZCML (order-wise) within a "view" - declaration. - -- The repoze.bfg router now catches both - ``repoze.bfg.security.Unauthorized`` and - ``repoze.bfg.view.NotFound`` exceptions while rendering a view. - When the router catches an ``Unauthorized``, it returns the - registered forbidden view. When the router catches a ``NotFound``, - it returns the registered notfound view. - -Internal --------- - -- Change urldispatch internals: Route object is now constructed using - a path, a name, and a factory instead of a name, a matcher, a - generator, and a factory. - -- Move (non-API) default_view, default_forbidden_view, and - default_notfound_view functions into the ``repoze.bfg.view`` module - (moved from ``repoze.bfg.router``). - -- Removed ViewPermissionFactory from ``repoze.bfg.security``. View - permission checking is now done by registering and looking up an - ISecuredView. - -- The ``static`` ZCML directive now uses a custom root factory when - constructing a route. - -- The interface ``IRequestFactories`` was removed from the - repoze.bfg.interfaces module. This interface was never an API. - -- The function named ``named_request_factories`` and the data - structure named ``DEFAULT_REQUEST_FACTORIES`` have been removed from - the ``repoze.bfg.request`` module. These were never APIs. - -- The ``IViewPermissionFactory`` interface has been removed. This was - never an API. - -Documentation -------------- - -- Request-only-convention examples in the "Views" narrative - documentation were broken. - -- Fixed documentation bugs related to forget and remember in security API - docs. - -- Fixed documentation for ``repoze.bfg.view.static`` (in narrative - ``Views`` chapter). - -Deprecations ------------- - -- The API ``repoze.bfg.testing.registerViewPermission`` has been - deprecated. - -Backwards Incompatibilities ---------------------------- - -- The interfaces ``IPOSTRequest``, ``IGETRequest``, ``IPUTRequest``, - ``IDELETERequest``, and ``IHEADRequest`` have been removed from the - ``repoze.bfg.interfaces`` module. These were not documented as APIs - post-1.0. Instead of using one of these, use a ``request_method`` - ZCML attribute or ``request_method`` bfg_view decorator parameter - containing an HTTP method name (one of ``GET``, ``POST``, ``HEAD``, - ``PUT``, ``DELETE``) instead of one of these interfaces if you were - using one explicitly. Passing a string in the set (``GET``, - ``HEAD``, ``PUT``, ``POST``, ``DELETE``) as a ``request_type`` - argument will work too. Rationale: instead of relying on interfaces - attached to the request object, BFG now uses a "view predicate" to - determine the request type. - -- Views registered without the help of the ZCML ``view`` directive are - now responsible for performing their own authorization checking. - -- The ``registry_manager`` backwards compatibility alias importable - from "repoze.bfg.registry", deprecated since repoze.bfg 0.9 has been - removed. If you are tring to use the registry manager within a - debug script of your own, use a combination of the - "repoze.bfg.paster.get_app" and "repoze.bfg.scripting.get_root" APIs - instead. - -- The ``INotFoundAppFactory`` interface has been removed; it has - been deprecated since repoze.bfg 0.9. If you have something like - the following in your ``configure.zcml``:: - - - - Replace it with something like:: - - - - See "Changing the Not Found View" in the "Hooks" chapter of the - documentation for more information. - -- The ``IUnauthorizedAppFactory`` interface has been removed; it has - been deprecated since repoze.bfg 0.9. If you have something like - the following in your ``configure.zcml``:: - - - - Replace it with something like:: - - - - See "Changing the Forbidden View" in the "Hooks" chapter of the - documentation for more information. - -- ``ISecurityPolicy``-based security policies, deprecated since - repoze.bfg 0.9, have been removed. If you have something like this - in your ``configure.zcml``, it will no longer work:: - - - - If ZCML like the above exists in your application, you will receive - an error at startup time. Instead of the above, you'll need - something like:: - - - - - This is just an example. See the "Security" chapter of the - repoze.bfg documentation for more information about configuring - security policies. - -- Custom ZCML directives which register an authentication or - authorization policy (ala "authtktauthenticationpolicy" or - "aclauthorizationpolicy") should register the policy "eagerly" in - the ZCML directive instead of from within a ZCML action. If an - authentication or authorization policy is not found in the component - registry by the view machinery during deferred ZCML processing, view - security will not work as expected. - -1.0.1 (2009-07-22) -================== - -- Added support for ``has_resource``, ``resource_isdir``, and - ``resource_listdir`` to the resource "OverrideProvider"; this fixes - a bug with a symptom that a file could not be overridden in a - resource directory unless a file with the same name existed in the - original directory being overridden. - -- Fixed documentation bug showing invalid test for values from the - ``matchdict``: they are stored as attributes of the ``Article``, rather - than subitems. - -- Fixed documentation bug showing wrong environment key for the ``matchdict`` - produced by the matching route. - -- Added a workaround for a bug in Python 2.6, 2.6.1, and 2.6.2 having - to do with a recursion error in the mimetypes module when trying to - serve static files from Paste's FileApp: - http://bugs.python.org/issue5853. Symptom: File - "/usr/lib/python2.6/mimetypes.py", line 244, in guess_type return - guess_type(url, strict) RuntimeError: maximum recursion depth - exceeded. Thanks to Armin Ronacher for identifying the symptom and - pointing out a fix. - -- Minor edits to tutorials for accuracy based on feedback. - -- Declared Paste and PasteDeploy dependencies. - -1.0 (2009-07-05) -================ - -- Retested and added some content to GAE tutorial. - -- Edited "Extending" narrative docs chapter. - -- Added "Deleting the Database" section to the "Defining Models" - chapter of the traversal wiki tutorial. - -- Spell checking of narratives and tutorials. - -1.0b2 (2009-07-03) -================== - -- ``remoteuserauthenticationpolicy`` ZCML directive didn't work - without an ``environ_key`` directive (didn't match docs). - -- Fix ``configure_zcml`` filespec check on Windows. Previously if an - absolute filesystem path including a drive letter was passed as - ``filename`` (or as ``configure_zcml`` in the options dict) to - ``repoze.bfg.router.make_app``, it would be treated as a - package:resource_name specification. - -- Fix inaccuracies and import errors in bfgwiki (traversal+ZODB) and - bfgwiki2 (urldispatch+SA) tutorials. - -- Use bfgsite index for all tutorial setup.cfg files. - -- Full documentation grammar/style/spelling audit. - -1.0b1 (2009-07-02) -================== - -Features --------- - -- Allow a Paste config file (``configure_zcml``) value or an - environment variable (``BFG_CONFIGURE_ZCML``) to name a ZCML file - (optionally package-relative) that will be used to bootstrap the - application. Previously, the integrator could not influence which - ZCML file was used to do the boostrapping (only the original - application developer could do so). - -Documentation -------------- - -- Added a "Resources" chapter to the narrative documentation which - explains how to override resources within one package from another - package. - -- Added an "Extending" chapter to the narrative documentation which - explains how to extend or modify an existing BFG application using - another Python package and ZCML. - -1.0a9 (2009-07-01) -================== - -Features --------- - -- Make it possible to pass strings in the form - "package_name:relative/path" to APIs like ``render_template``, - ``render_template_to_response``, and ``get_template``. Sometimes - the package in which a caller lives is a direct namespace package, - so the module which is returned is semi-useless for navigating from. - In this way, the caller can control the horizontal and vertical of - where things get looked up from. - -1.0a8 (2009-07-01) -================== - -Deprecations ------------- - -- Deprecate the ``authentication_policy`` and ``authorization_policy`` - arguments to ``repoze.bfg.router.make_app``. Instead, developers - should use the various authentication policy ZCML directives - (``repozewho1authenticationpolicy``, - ``remoteuserauthenticationpolicy`` and - ``authtktauthenticationpolicy``) and the `aclauthorizationpolicy`` - authorization policy directive as described in the changes to the - "Security" narrative documenation chapter and the wiki tutorials. - -Features --------- - -- Add three new ZCML directives which configure authentication - policies: - - - ``repozewho1authenticationpolicy`` - - - ``remoteuserauthenticationpolicy`` - - - ``authtktauthenticationpolicy`` - -- Add a new ZCML directive which configures an ACL authorization - policy named ``aclauthorizationpolicy``. - -Bug Fixes ---------- - -- Bug fix: when a ``repoze.bfg.resource.PackageOverrides`` class was - instantiated, and the package it was overriding already had a - ``__loader__`` attribute, it would fail at startup time, even if the - ``__loader__`` attribute was another PackageOverrides instance. We - now replace any ``__loader__`` that is also a PackageOverrides - instance. Symptom: ``ConfigurationExecutionError: : Package - already has a __loader__ (probably a module in a zipped egg)``. - -1.0a7 (2009-06-30) -================== - -Features --------- - -- Add a ``reload_resources`` configuration file setting (aka the - ``BFG_RELOAD_RESOURCES`` environment variable). When this is set to - true, the server never needs to be restarted when moving files - between directory resource overrides (esp. for templates currently). - -- Add a ``reload_all`` configuration file setting (aka the - ``BFG_RELOAD_ALL`` environment variable) that implies both - ``reload_resources`` and ``reload_templates``. - -- The ``static`` helper view class now uses a ``PackageURLParser`` in - order to allow for the overriding of static resources (CSS / logo - files, etc) using the ``resource`` ZCML directive. The - ``PackageURLParser`` class was added to a (new) ``static`` module in - BFG; it is a subclass of the ``StaticURLParser`` class in - ``paste.urlparser``. - -- The ``repoze.bfg.templating.renderer_from_cache`` function now - checks for the ``reload_resources`` setting; if it's true, it does - not register a template renderer (it won't use the registry as a - template renderer cache). - -Documentation -------------- - -- Add ``pkg_resources`` to the glossary. - -- Update the "Environment" docs to note the existence of - ``reload_resources`` and ``reload_all``. - -- Updated the ``bfg_alchemy`` paster template to include two views: - the view on the root shows a list of links to records; the view on - a record shows the details for that object. - -Internal --------- - -- Use a colon instead of a tab as the separator between package name - and relpath to form the "spec" when register a ITemplateRenderer. - -- Register a ``repoze.bfg.resource.OverrideProvider`` as a - pkg_resources provider only for modules which are known to have - overrides, instead of globally, when a directive is used - (performance). - -1.0a6 (2009-06-29) -================== - -Bug Fixes ---------- - -- Use ``caller_package`` function instead of ``caller_module`` - function within ``templating`` to avoid needing to name the caller - module in resource overrides (actually match docs). - -- Make it possible to override templates stored directly in a module - with templates in a subdirectory of the same module, stored directly - within another module, or stored in a subdirectory of another module - (actually match docs). - -1.0a5 (2009-06-28) -================== - -Features --------- - -- A new ZCML directive exists named "resource". This ZCML directive - allows you to override Chameleon templates within a package (both - directories full of templates and individual template files) with - other templates in the same package or within another package. This - allows you to "fake out" a view's use of a template, causing it to - retrieve a different template than the one actually named by a - relative path to a call like - ``render_template_to_response('templates/mytemplate.pt')``. For - example, you can override a template file by doing:: - - - - The string passed to "to_override" and "override_with" is named a - "specification". The colon separator in a specification separates - the package name from a package-relative directory name. The colon - and the following relative path are optional. If they are not - specified, the override attempts to resolve every lookup into a - package from the directory of another package. For example:: - - - - - Individual subdirectories within a package can also be overridden:: - - - - If you wish to override a directory with another directory, you must - make sure to attach the slash to the end of both the ``to_override`` - specification and the ``override_with`` specification. If you fail - to attach a slash to the end of a specification that points a - directory, you will get unexpected results. You cannot override a - directory specification with a file specification, and vice versa (a - startup error will occur if you try). - - You cannot override a resource with itself (a startup error will - occur if you try). - - Only individual *package* resources may be overridden. Overrides - will not traverse through subpackages within an overridden package. - This means that if you want to override resources for both - ``some.package:templates``, and ``some.package.views:templates``, - you will need to register two overrides. - - The package name in a specification may start with a dot, meaning - that the package is relative to the package in which the ZCML file - resides. For example:: - - - - Overrides for the same ``to_overrides`` specification can be named - multiple times within ZCML. Each ``override_with`` path will be - consulted in the order defined within ZCML, forming an override - search path. - - Resource overrides can actually override resources other than - templates. Any software which uses the ``pkg_resources`` - ``get_resource_filename``, ``get_resource_stream`` or - ``get_resource_string`` APIs will obtain an overridden file when an - override is used. However, the only built-in facility which uses - the ``pkg_resources`` API within BFG is the templating stuff, so we - only call out template overrides here. - -- Use the ``pkg_resources`` API to locate template filenames instead - of dead-reckoning using the ``os.path`` module. - -- The ``repoze.bfg.templating`` module now uses ``pkg_resources`` to - locate and register template files instead of using an absolute - path name. - -1.0a4 (2009-06-25) -================== - -Features --------- - -- Cause ``:segment`` matches in route paths to put a Unicode-decoded - and URL-dequoted value in the matchdict for the value matched. - Previously a non-decoded non-URL-dequoted string was placed in the - matchdict as the value. - -- Cause ``*remainder`` matches in route paths to put a *tuple* in the - matchdict dictionary in order to be able to present Unicode-decoded - and URL-dequoted values for the traversal path. Previously a - non-decoded non-URL-dequoted string was placed in the matchdict as - the value. - -- Add optional ``max_age`` keyword value to the ``remember`` method of - ``repoze.bfg.authentication.AuthTktAuthenticationPolicy``; if this - value is passed to ``remember``, the generated cookie will have a - corresponding Max-Age value. - -Documentation -------------- - -- Add information to the URL Dispatch narrative documentation about - path pattern matching syntax. - -Bug Fixes ---------- - -- Make ``route_url`` URL-quote segment replacements during generation. - Remainder segments are not quoted. - -1.0a3 (2009-06-24) -================== - -Implementation Changes ----------------------- - -- ``repoze.bfg`` no longer relies on the Routes package to interpret - URL paths. All known existing ``path`` patterns will continue to - work with the reimplemented logic, which lives in - ``repoze.bfg.urldispatch``. ```` ZCML directives which use - certain attributes (uncommon ones) may not work (see "Backwards - Incompatibilities" below). - -Bug Fixes ---------- - -- ``model_url`` when passed a request that was generated as a result - of a route match would fail in a call to ``route.generate``. - -- BFG-on-GAE didn't work due to a corner case bug in the fallback - Python implementation of ``threading.local`` (symptom: - "Initialization arguments are not supported"). Thanks to Michael - Bernstein for the bug report. - -Documentation -------------- - -- Added a "corner case" explanation to the "Hybrid Apps" chapter - explaining what to do when "the wrong" view is matched. - -- Use ``repoze.bfg.url.route_url`` API in tutorials rather than Routes - ``url_for`` API. - -Features --------- - -- Added the ``repoze.bfg.url.route_url`` API. This API allows you to - generate URLs based on ```` declarations. See the URL - Dispatch narrative chapter and the "repoze.bfg.url" module API - documentation for more information. - -Backwards Incompatibilities ---------------------------- - -- As a result of disusing Routes, using the Routes ``url_for`` API - inside a BFG application (as was suggested by previous iterations of - tutorials) will no longer work. Use the - ``repoze.bfg.url.route_url`` method instead. - -- The following attributes on the ```` ZCML directive no longer - work: ``encoding``, ``static``, ``filter``, ``condition_method``, - ``condition_subdomain``, ``condition_function``, ``explicit``, or - ``subdomains``. These were all Routes features. - -- The ```` ZCML directive no longer supports the - ```` subdirective. This was a Routes feature. - -1.0a2 (2009-06-23) -================== - -Bug Fixes ---------- - -- The ``bfg_routesalchemy`` paster template app tests failed due to a - mismatch between test and view signatures. - -Features --------- - -- Add a ``view_for`` attribute to the ``route`` ZCML directive. This - attribute should refer to an interface or a class (ala the ``for`` - attribute of the ``view`` ZCML directive). - -Documentation -------------- - -- Conditional documentation in installation section ("how to install a - Python interpreter"). - -Backwards Incompatibilities ---------------------------- - -- The ``callback`` argument of the ``repoze.bfg.authentication`` - authentication policies named ``RepozeWho1AuthenticationPolicy``, - ``RemoteUserAuthenticationPolicy``, and - ``AuthTktAuthenticationPolicy`` now must accept two positional - arguments: the orginal argument accepted by each (userid or - identity) plus a second argument, which will be the current request. - Apologies, this is required to service finding groups when there is - no "global" database connection. - -1.0a1 (2009-06-22) -================== - -Features --------- - -- A new ZCML directive was added named ``notfound``. This ZCML - directive can be used to name a view that should be invoked when the - request can't otherwise be resolved to a view callable. For example:: - - - -- A new ZCML directive was added named ``forbidden``. This ZCML - directive can be used to name a view that should be invoked when a - view callable for a request is found, but cannot be invoked due to - an authorization failure. For example:: - - - -- Allow views to be *optionally* defined as callables that accept only - a request object, instead of both a context and a request (which - still works, and always will). The following types work as views in - this style: - - - functions that accept a single argument ``request``, e.g.:: - - def aview(request): - pass - - - new and old-style classes that have an ``__init__`` method that - accepts ``self, request``, e.g.:: - - def View(object): - __init__(self, request): - pass - - - Arbitrary callables that have a ``__call__`` method that accepts - ``self, request``, e.g.:: - - def AView(object): - def __call__(self, request): - pass - view = AView() - - This likely should have been the calling convention all along, as - the request has ``context`` as an attribute already, and with views - called as a result of URL dispatch, having the context in the - arguments is not very useful. C'est la vie. - -- Cache the absolute path in the caller's package globals within - ``repoze.bfg.path`` to get rid of repeated (expensive) calls to - os.path.abspath. - -- Add ``reissue_time`` and ``timeout`` parameters to - ``repoze.bfg.authentication.AuthTktAuthenticationPolicy`` - constructor. If these are passed, cookies will be reset every so - often (cadged from the same change to repoze.who lately). - -- The matchdict related to the matching of a Routes route is available - on the request as the ``matchdict`` attribute: - ``request.matchdict``. If no route matched, this attribute will be - None. - -- Make 404 responses slightly cheaper by showing - ``environ["PATH_INFO"]`` on the notfound result page rather than the - fullly computed URL. - -- Move LRU cache implementation into a separate package - (``repoze.lru``). - -- The concepts of traversal and URL dispatch have been unified. It is - now possible to use the same sort of factory as both a traversal - "root factory" and what used to be referred to as a urldispatch - "context factory". - -- When the root factory argument (as a first argument) passed to - ``repoze.bfg.router.make_app`` is ``None``, a *default* root factory - is used. This is in support of using routes as "root finders"; it - supplants the idea that there is a default - ``IRoutesContextFactory``. - -- The `view`` ZCML statement and the ``repoze.bfg.view.bfg_view`` - decorator now accept an extra argument: ``route_name``. If a - ``route_name`` is specified, it must match the name of a previously - defined ``route`` statement. When it is specified, the view will - only be called when that route matches during a request. - -- It is now possible to perfom traversal *after* a route has matched. - Use the pattern ``*traverse`` in a ```` ``path`` attribute - within ZCML, and the path remainder which it matches will be used as - a traversal path. - -- When any route defined matches, the WSGI environment will now - contain a key ``bfg.routes.route`` (the Route object which matched), - and a key ``bfg.routes.matchdict`` (the result of calling route.match). - -Deprecations ------------- - -- Utility registrations against - ``repoze.bfg.interfaces.INotFoundView`` and - ``repoze.bfg.interfaces.IForbiddenView`` are now deprecated. Use - the ``notfound`` and ``forbidden`` ZCML directives instead (see the - "Hooks" chapter for more information). Such registrations will - continue to work, but the notfound and forbidden directives do - "extra work" to ensure that the callable named by the directive can - be called by the router even if it's a class or - request-argument-only view. - -Removals --------- - -- The ``IRoutesContext``, ``IRoutesContextFactory``, and - ``IContextNotFound`` interfaces were removed from - ``repoze.bfg.interfaces``. These were never APIs. - -- The ``repoze.bfg.urldispatch.RoutesContextNotFound``, - ``repoze.bfg.urldispatch.RoutesModelTraverser`` and - ``repoze.bfg.urldispatch.RoutesContextURL`` classes were removed. - These were also never APIs. - -Backwards Incompatibilities ---------------------------- - -- Moved the ``repoze.bfg.push`` module, which implemented the ``pushpage`` - decorator, into a separate distribution, ``repoze.bfg.pushpage``. - Applications which used this decorator should continue to work after - adding that distribution to their installation requirements. - -- Changing the default request factory via an IRequestFactory utility - registration (as used to be documented in the "Hooks" chapter's - "Changing the request factory" section) is no longer supported. The - dance to manufacture a request is complicated as a result of - unifying traversal and url dispatch, making it highly unlikely for - anyone to be able to override it properly. For those who just want - to decorate or modify a request, use a NewRequestEvent subscriber - (see the Events chapter in the documentation). - -- The ``repoze.bfg.IRequestFactory`` interface was removed. See the - bullet above for why. - -- Routes "context factories" (spelled as the factory argument to a - route statement in ZCML) must now expect the WSGI environ as a - single argument rather than a set of keyword arguments. They can - obtain the match dictionary by asking for - environ['bfg.routes.matchdict']. This is the same set of keywords - that used to be passed to urldispatch "context factories" in BFG 0.9 - and below. - -- Using the ``@zope.component.adapter`` decorator on a bfg view - function no longer works. Use the ``@repoze.bfg.view.bfg_view`` - decorator instead to mark a function (or a class) as a view. - -- The name under which the matching route object is found in the - environ was changed from ``bfg.route`` to ``bfg.routes.route``. - -- Finding the root is now done *before* manufacturing a request object - (and sending a new request event) within the router (it used to be - performed afterwards). - -- Adding ``*path_info`` to a route no longer changes the PATH_INFO for - a request that matches using URL dispatch. This feature was only - there to service the ``repoze.bfg.wsgi.wsgiapp2`` decorator and it - did it wrong; use ``*subpath`` instead now. - -- The values of ``subpath``, ``traversed``, and ``virtual_root_path`` - attached to the request object are always now tuples instead of - lists (performance). - -Bug Fixes ---------- - -- The ``bfg_alchemy`` Paster template named "repoze.tm" in its - pipeline rather than "repoze.tm2", causing the startup to fail. - -- Move BBB logic for registering an - IAuthenticationPolicy/IForbiddenView/INotFoundView based on older - concepts from the router module's ``make_app`` function into the - ``repoze.bfg.zcml.zcml_configure`` callable, to service - compatibility with scripts that use "zope.configuration.xmlconfig" - (replace with ``repoze.bfg.zml.zcml_configure`` as necessary to get - BBB logic) - -Documentation -------------- - -- Add interface docs related to how to create authentication policies - and authorization policies to the "Security" narrative chapter. - -- Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter - to the narrative documentation. This explains the usage of - ``*traverse`` and ``*subpath`` in routes URL patters. - -- A "router" chapter explaining the request/response lifecycle at a - high level was added. - -- Replaced all mentions and explanations of a routes "context factory" - with equivalent explanations of a "root factory" (context factories - have been disused). - -- Updated Routes bfgwiki2 tutorial to reflect the fact that context - factories are now no longer used. - -0.9.1 (2009-06-02) -================== - -Features --------- - -- Add API named ``repoze.bfg.settings.get_settings`` which retrieves a - derivation of values passed as the ``options`` value of - ``repoze.bfg.router.make_app``. This API should be preferred - instead of using getUtility(ISettings). I added a new - ``repoze.bfg.settings`` API document as well. - -Bug Fixes ---------- - -- Restored missing entry point declaration for bfg_alchemy paster - template, which was accidentally removed in 0.9. - -Documentation -------------- - -- Fix a reference to ``wsgiapp`` in the ``wsgiapp2`` API documentation - within the ``repoze.bfg.wsgi`` module. - -API Removals ------------- - -- The ``repoze.bfg.location.locate`` API was removed: it didn't do - enough to be very helpful and had a misleading name. - -0.9 (2009-06-01) -================ - -Bug Fixes ---------- - -- It was not possible to register a custom ``IRoutesContextFactory`` - for use as a default context factory as documented in the "Hooks" - chapter. - -Features --------- - -- The ``request_type`` argument of ZCML ``view`` declarations and - ``bfg_view`` decorators can now be one of the strings ``GET``, - ``POST``, ``PUT``, ``DELETE``, or ``HEAD`` instead of a reference to - the respective interface type imported from - ``repoze.bfg.interfaces``. - -- The ``route`` ZCML directive now accepts ``request_type`` as an - alias for its ``condition_method`` argument for symmetry with the - ``view`` directive. - -- The ``bfg_routesalchemy`` paster template now provides a unit test - and actually uses the database during a view rendering. - -Removals --------- - -- Remove ``repoze.bfg.threadlocal.setManager``. It was only used in - unit tests. - -- Remove ``repoze.bfg.wsgi.HTTPException``, - ``repoze.bfg.wsgi.NotFound``, and ``repoze.bfg.wsgi.Unauthorized``. - These classes were disused with the introduction of the - ``IUnauthorizedView`` and ``INotFoundView`` machinery. - -Documentation -------------- - -- Add description to narrative templating chapter about how to use - Chameleon text templates. - -- Changed Views narrative chapter to use method strings rather than - interface types, and moved advanced interface type usage to Events - narrative chapter. - -- Added a Routes+SQLAlchemy wiki tutorial. - -0.9a8 (2009-05-31) -================== - -Features --------- - -- It is now possible to register a custom - ``repoze.bfg.interfaces.INotFoundView`` for a given application. - This feature replaces the - ``repoze.bfg.interfaces.INotFoundAppFactory`` feature previously - described in the Hooks chapter. The INotFoundView will be called - when the framework detects that a view lookup done as a result of a - request fails; it should accept a context object and a request - object; it should return an IResponse object (a webob response, - basically). See the Hooks narrative chapter of the BFG docs for - more info. - -- The error presented when a view invoked by the router returns a - non-response object now includes the view's name for troubleshooting - purposes. - -Bug Fixes ---------- - -- A "new response" event is emitted for forbidden and notfound views. - -Deprecations ------------- - -- The ``repoze.bfg.interfaces.INotFoundAppFactory`` interface has been - deprecated in favor of using the new - ``repoze.bfg.interfaces.INotFoundView`` mechanism. - -Renames -------- - -- Renamed ``repoze.bfg.interfaces.IForbiddenResponseFactory`` to - ``repoze.bfg.interfaces.IForbiddenView``. - -0.9a7 (2009-05-30) -================== - -Features --------- - -- Remove "context" argument from ``effective_principals`` and - ``authenticated_userid`` function APIs in ``repoze.bfg.security``, - effectively a doing reversion to 0.8 and before behavior. Both - functions now again accept only the ``request`` parameter. - -0.9a6 (2009-05-29) -================== - -Documentation -------------- - -- Changed "BFG Wiki" tutorial to use AuthTktAuthenticationPolicy - rather than repoze.who. - -Features --------- - -- Add an AuthTktAuthenticationPolicy. This policy retrieves - credentials from an auth_tkt cookie managed by the application - itself (instead of relying on an upstream data source for - authentication data). See the Security API chapter of the - documentation for more info. - -- Allow RemoteUserAuthenticationPolicy and - RepozeWho1AuthenticationPolicy to accept various constructor - arguments. See the Security API chapter of the documentation for - more info. - -0.9a5 (2009-05-28) -================== - -Features --------- - -- Add a ``get_app`` API functions to the ``paster`` module. This - obtains a WSGI application from a config file given a config file - name and a section name. See the ``repoze.bfg.paster`` API docs for - more information. - -- Add a new module named ``scripting``. It contains a ``get_root`` - API function, which, provided a Router instance, returns a traversal - root object and a "closer". See the ``repoze.bfg.scripting`` API - docs for more info. - -0.9a4 (2009-05-27) -================== - -Bug Fixes ---------- - -- Try checking for an "old style" security policy *after* we parse - ZCML (thinko). - -0.9a3 (2009-05-27) -================== - -Features --------- - -- Allow IAuthenticationPolicy and IAuthorizationPolicy to be - overridden via ZCML registrations (do ZCML parsing after - registering these in router.py). - -Documentation -------------- - -- Added "BFG Wiki" tutorial to documentation; it describes - step-by-step how to create a traversal-based ZODB application with - authentication. - -Deprecations ------------- - -- Added deprecations for imports of ``ACLSecurityPolicy``, - ``InheritingACLSecurityPolicy``, ``RemoteUserACLSecurityPolicy``, - ``RemoteUserInheritingACLSecurityPolicy``, ``WhoACLSecurityPolicy``, - and ``WhoInheritingACLSecurityPolicy`` from the - ``repoze.bfg.security`` module; for the meantime (for backwards - compatibility purposes) these live in the ``repoze.bfg.secpols`` - module. Note however, that the entire concept of a "security - policy" is deprecated in BFG in favor of separate authentication and - authorization policies, so any use of a security policy will - generate additional deprecation warnings even if you do start using - ``repoze.bfg.secpols``. ``repoze.bfg.secpols`` will disappear in a - future release of ``repoze.bfg``. - -Deprecated Import Alias Removals --------------------------------- - -- Remove ``repoze.bfg.template`` module. All imports from this - package have been deprecated since 0.3.8. Instead, import - ``get_template``, ``render_template``, and - ``render_template_to_response`` from the - ``repoze.bfg.chameleon_zpt`` module. - -- Remove backwards compatibility import alias for - ``repoze.bfg.traversal.split_path`` (deprecated since 0.6.5). This - must now be imported as ``repoze.bfg.traversal.traversal_path``). - -- Remove backwards compatibility import alias for - ``repoze.bfg.urldispatch.RoutesContext`` (deprecated since 0.6.5). - This must now be imported as - ``repoze.bfg.urldispatch.DefaultRoutesContext``. - -- Removed backwards compatibility import aliases for - ``repoze.bfg.router.get_options`` and ``repoze.bfg.router.Settings`` - (deprecated since 0.6.2). These both must now be imported from - ``repoze.bfg.settings``. - -- Removed backwards compatibility import alias for - ``repoze.bfg.interfaces.IRootPolicy`` (deprecated since 0.6.2). It - must be imported as ``repoze.bfg.interfaces.IRootFactory`` now. - -- Removed backwards compatibility import alias for - ``repoze.bfg.interfaces.ITemplate`` (deprecated since 0.4.4). It - must be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` now. - -- Removed backwards compatibility import alias for - ``repoze.bfg.interfaces.ITemplateFactory`` (deprecated since 0.4.4). - It must be imported as - ``repoze.bfg.interfaces.ITemplateRendererFactory`` now. - -- Removed backwards compatibility import alias for - ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` (deprecated since - 0.4.4). This must be imported as ``repoze.bfg.ZPTTemplateRenderer`` - now. - -0.9a2 (2009-05-27) -================== - -Features --------- - -- A paster command has been added named "bfgshell". This command can - be used to get an interactive prompt with your BFG root object in - the global namespace. E.g.:: - - bin/paster bfgshell /path/to/myapp.ini myapp - - See the ``Project`` chapter in the BFG documentation for more - information. - -Deprecations ------------- - -- The name ``repoze.bfg.registry.registry_manager`` was never an API, - but scripts in the wild were using it to set up an environment for - use under a debug shell. A backwards compatibility shim has been - added for this purpose, but the feature is deprecated. - -0.9a1 (2009-5-27) -================= - -Features --------- - -- New API functions named ``forget`` and ``remember`` are available in - the ``security`` module. The ``forget`` function returns headers - which will cause the currently authenticated user to be logged out - when set in a response. The ``remember`` function (when passed the - proper arguments) will return headers which will cause a principal - to be "logged in" when set in a response. See the Security API - chapter of the docs for more info. - -- New keyword arguments to the ``repoze.bfg.router.make_app`` call - have been added: ``authentication_policy`` and - ``authorization_policy``. These should, respectively, be an - implementation of an authentication policy (an object implementing - the ``repoze.bfg.interfaces.IAuthenticationPolicy`` interface) and - an implementation of an authorization policy (an object implementing - ``repoze.bfg.interfaces.IAuthorizationPolicy)``. Concrete - implementations of authentication policies exist in - ``repoze.bfg.authentication``. Concrete implementations of - authorization policies exist in ``repoze.bfg.authorization``. - - Both ``authentication_policy`` and ``authorization_policy`` default - to ``None``. - - If ``authentication_policy`` is ``None``, but - ``authorization_policy`` is *not* ``None``, then - ``authorization_policy`` is ignored (the ability to do authorization - depends on authentication). - - If the ``authentication_policy`` argument is *not* ``None``, and the - ``authorization_policy`` argument *is* ``None``, the authorization - policy defaults to an authorization implementation that uses ACLs - (``repoze.bfg.authorization.ACLAuthorizationPolicy``). - - We no longer encourage configuration of "security policies" using - ZCML, as previously we did for ``ISecurityPolicy``. This is because - it's not uncommon to need to configure settings for concrete - authorization or authentication policies using paste .ini - parameters; the app entry point for your application is the natural - place to do this. - -- Two new abstractions have been added in the way of adapters used by - the system: an ``IAuthorizationPolicy`` and an - ``IAuthenticationPolicy``. A combination of these (as registered by - the ``securitypolicy`` ZCML directive) take the place of the - ``ISecurityPolicy`` abstraction in previous releases of repoze.who. - The API functions in ``repoze.who.security`` (such as - ``authentication_userid``, ``effective_principals``, - ``has_permission``, and so on) have been changed to try to make use - of these new adapters. If you're using an older ``ISecurityPolicy`` - adapter, the system will still work, but it will print deprecation - warnings when such a policy is used. - -- The way the (internal) IViewPermission utilities registered via ZCML - are invoked has changed. They are purely adapters now, returning a - boolean result, rather than returning a callable. You shouldn't have - been using these anyway. ;-) - -- New concrete implementations of IAuthenticationPolicy have been - added to the ``repoze.bfg.authentication`` module: - ``RepozeWho1AuthenticationPolicy`` which uses ``repoze.who`` - identity to retrieve authentication data from and - ``RemoteUserAuthenticationPolicy``, which uses the ``REMOTE_USER`` - value in the WSGI environment to retrieve authentication data. - -- A new concrete implementation of IAuthorizationPolicy has been added - to the ``repoze.bfg.authorization`` module: - ``ACLAuthorizationPolicy`` which uses ACL inheritance to do - authorization. - -- It is now possible to register a custom - ``repoze.bfg.interfaces.IForbiddenResponseFactory`` for a given - application. This feature replaces the - ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` feature previously - described in the Hooks chapter. The IForbiddenResponseFactory will - be called when the framework detects an authorization failure; it - should accept a context object and a request object; it should - return an IResponse object (a webob response, basically). Read the - below point for more info and see the Hooks narrative chapter of the - BFG docs for more info. - -Backwards Incompatibilities ---------------------------- - -- Custom NotFound and Forbidden (nee' Unauthorized) WSGI applications - (registered as a utility for INotFoundAppFactory and - IUnauthorizedAppFactory) could rely on an environment key named - ``message`` describing the circumstance of the response. This key - has been renamed to ``repoze.bfg.message`` (as per the WSGI spec, - which requires environment extensions to contain dots). - -Deprecations ------------- - -- The ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` interface has - been deprecated in favor of using the new - ``repoze.bfg.interfaces.IForbiddenResponseFactory`` mechanism. - -- The ``view_execution_permitted`` API should now be imported from the - ``repoze.bfg.security`` module instead of the ``repoze.bfg.view`` - module. - -- The ``authenticated_userid`` and ``effective_principals`` APIs in - ``repoze.bfg.security`` used to only take a single argument - (request). They now accept two arguments (``context`` and - ``request``). Calling them with a single argument is still - supported but issues a deprecation warning. (NOTE: this change was - reverted in 0.9a7; meaning the 0.9 versions of these functions - again accept ``request`` only, just like 0.8 and before). - -- Use of "old-style" security policies (those base on ISecurityPolicy) - is now deprecated. See the "Security" chapter of the docs for info - about activating an authorization policy and an authentication poicy. - -0.8.1 (2009-05-21) -================== - -Features --------- - -- Class objects may now be used as view callables (both via ZCML and - via use of the ``bfg_view`` decorator in Python 2.6 as a class - decorator). The calling semantics when using a class as a view - callable is similar to that of using a class as a Zope "browser - view": the class' ``__init__`` must accept two positional parameters - (conventionally named ``context``, and ``request``). The resulting - instance must be callable (it must have a ``__call__`` method). - When called, the instance should return a response. For example:: - - from webob import Response - - class MyView(object): - def __init__(self, context, request): - self.context = context - self.request = request - - def __call__(self): - return Response('hello from %s!' % self.context) - - See the "Views" chapter in the documentation and the - ``repoze.bfg.view`` API documentation for more information. - -- Removed the pickling of ZCML actions (the code that wrote - ``configure.zcml.cache`` next to ``configure.zcml`` files in - projects). The code which managed writing and reading of the cache - file was a source of subtle bugs when users switched between - imperative (e.g. ``@bfg_view``) registrations and declarative - registrations (e.g. the ``view`` directive in ZCML) on the same - project. On a moderately-sized project (535 ZCML actions and 15 ZCML - files), executing actions read from the pickle was saving us only - about 200ms (2.5 sec vs 2.7 sec average). On very small projects (1 - ZCML file and 4 actions), startup time was comparable, and sometimes - even slower when reading from the pickle, and both ways were so fast - that it really just didn't matter anyway. - -0.8 (2009-05-18) -================ - -Features --------- - -- Added a ``traverse`` function to the ``repoze.bfg.traversal`` - module. This function may be used to retrieve certain values - computed during path resolution. See the Traversal API chapter of - the documentation for more information about this function. - -Deprecations ------------- - -- Internal: ``ITraverser`` callables should now return a dictionary - rather than a tuple. Up until 0.7.0, all ITraversers were assumed - to return a 3-tuple. In 0.7.1, ITraversers were assumed to return a - 6-tuple. As (by evidence) it's likely we'll need to add further - information to the return value of an ITraverser callable, 0.8 - assumes that an ITraverser return a dictionary with certain elements - in it. See the ``repoze.bfg.interfaces.ITraverser`` interface for - the list of keys that should be present in the dictionary. - ``ITraversers`` which return tuples will still work, although a - deprecation warning will be issued. - -Backwards Incompatibilities ---------------------------- - -- If your code used the ITraverser interface directly (not via an API - function such as ``find_model``) via an adapter lookup, you'll need - to change your code to expect a dictionary rather than a 3- or - 6-tuple if your code ever gets return values from the default - ModelGraphTraverser or RoutesModelTraverser adapters. - -0.8a7 (2009-05-16) -================== - -Backwards Incompatibilities ---------------------------- - -- The ``RoutesMapper`` class in ``repoze.bfg.urldispatch`` has been - removed, as well as its documentation. It had been deprecated since - 0.6.3. Code in ``repoze.bfg.urldispatch.RoutesModelTraverser`` - which catered to it has also been removed. - -- The semantics of the ``route`` ZCML directive have been simplified. - Previously, it was assumed that to use a route, you wanted to map a - route to an externally registered view. The new ``route`` directive - instead has a ``view`` attribute which is required, specifying the - dotted path to a view callable. When a route directive is - processed, a view is *registered* using the name attribute of the - route directive as its name and the callable as its value. The - ``view_name`` and ``provides`` attributes of the ``route`` directive - are therefore no longer used. Effectively, if you were previously - using the ``route`` directive, it means you must change a pair of - ZCML directives that look like this:: - - - - - - To a ZCML directive that looks like this:: - - - - In other words, to make old code work, remove the ``view`` - directives that were only there to serve the purpose of backing - ``route`` directives, and move their ``view=`` attribute into the - ``route`` directive itself. - - This change also necessitated that the ``name`` attribute of the - ``route`` directive is now required. If you were previously using - ``route`` directives without a ``name`` attribute, you'll need to - add one (the name is arbitrary, but must be unique among all - ``route`` and ``view`` statements). - - The ``provides`` attribute of the ``route`` directive has also been - removed. This directive specified a sequence of interface types - that the generated context would be decorated with. Since route - views are always generated now for a single interface - (``repoze.bfg.IRoutesContext``) as opposed to being looked up - arbitrarily, there is no need to decorate any context to ensure a - view is found. - -Documentation -------------- - -- Added API docs for the ``repoze.bfg.testing`` methods - ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and - ``cleanUp``. - -- Added glossary entry for "root factory". - -- Noted existence of ``repoze.bfg.pagetemplate`` template bindings in - "Available Add On Template System Bindings" in Templates chapter in - narrative docs. - -- Update "Templates" narrative chapter in docs (expand to show a - sample template and correct macro example). - -Features --------- - -- Courtesty Carlos de la Guardia, added an ``alchemy`` Paster - template. This paster template sets up a BFG project that uses - SQAlchemy (with SQLite) and uses traversal to resolve URLs. (no - Routes areused). This template can be used via ``paster create -t - bfg_alchemy``. - -- The Routes ``Route`` object used to resolve the match is now put - into the environment as ``bfg.route`` when URL dispatch is used. - -- You can now change the default Routes "context factory" globally. - See the "ZCML Hooks" chapter of the documentation (in the "Changing - the Default Routes Context Factory" section). - -0.8a6 (2009-05-11) -================== - -Features --------- - -- Added a ``routesalchemy`` Paster template. This paster template - sets up a BFG project that uses SQAlchemy (with SQLite) and uses - Routes exclusively to resolve URLs (no traversal root factory is - used). This template can be used via ``paster create -t - bfg_routesalchemy``. - -Documentation -------------- - -- Added documentation to the URL Dispatch chapter about how to catch - the root URL using a ZCML ``route`` directive. - -- Added documentation to the URL Dispatch chapter about how to perform - a cleanup function at the end of a request (e.g. close the SQL - connection). - -Bug Fixes ---------- - -- In version 0.6.3, passing a ``get_root`` callback (a "root factory") - to ``repoze.bfg.router.make_app`` became optional if any ``route`` - declaration was made in ZCML. The intent was to make it possible to - disuse traversal entirely, instead relying entirely on URL dispatch - (Routes) to resolve all contexts. However a compound set of bugs - prevented usage of a Routes-based root view (a view which responds - to "/"). One bug existed in `repoze.bfg.urldispatch``, another - existed in Routes itself. - - To resolve this issue, the urldispatch module was fixed, and a fork - of the Routes trunk was put into the "dev" index named - ``Routes-1.11dev-chrism-home``. The source for the fork exists at - `http://bitbucket.org/chrism/routes-home/ - `_ (broken link); - its contents have been merged into the Routes trunk - (what will be Routes 1.11). - -0.8a5 (2009-05-08) -================== - -Features --------- - -- Two new security policies were added: - RemoteUserInheritingACLSecurityPolicy and - WhoInheritingACLSecurityPolicy. These are security policies which - take into account *all* ACLs defined in the lineage of a context - rather than stopping at the first ACL found in a lineage. See the - "Security" chapter of the API documentation for more information. - -- The API and narrative documentation dealing with security was - changed to introduce the new "inheriting" security policy variants. - -- Added glossary entry for "lineage". - -Deprecations ------------- - -- The security policy previously named - ``RepozeWhoIdentityACLSecurityPolicy`` now has the slightly saner - name of ``WhoACLSecurityPolicy``. A deprecation warning is emitted - when this policy is imported under the "old" name; usually this is - due to its use in ZCML within your application. If you're getting - this deprecation warning, change your ZCML to use the new name, - e.g. change:: - - - - To:: - - - -0.8a4 (2009-05-04) -================== - -Features --------- - -- ``zope.testing`` is no longer a direct dependency, although our - dependencies (such as ``zope.interface``, ``repoze.zcml``, etc) - still depend on it. - -- Tested on Google App Engine. Added a tutorial to the documentation - explaining how to deploy a BFG app to GAE. - -Backwards Incompatibilities ---------------------------- - -- Applications which rely on ``zope.testing.cleanup.cleanUp`` in unit - tests can still use that function indefinitely. However, for - maximum forward compatibility, they should import ``cleanUp`` from - ``repoze.bfg.testing`` instead of from ``zope.testing.cleanup``. - The BFG paster templates and docs have been changed to use this - function instead of the ``zope.testing.cleanup`` version. - -0.8a3 (2009-05-03) -=================== - -Features --------- - -- Don't require a successful import of ``zope.testing`` at BFG - application runtime. This allows us to get rid of ``zope.testing`` - on platforms like GAE which have file limits. - -0.8a2 (2009-05-02) -================== - -Features --------- - -- We no longer include the ``configure.zcml`` of the ``chameleon.zpt`` - package within the ``configure.zcml`` of the "repoze.bfg.includes" - package. This has been a no-op for some time now. - -- The ``repoze.bfg.chameleon_zpt`` package no longer imports from - ``chameleon.zpt`` at module scope, deferring the import until later - within a method call. The ``chameleon.zpt`` package can't be - imported on platforms like GAE. - -0.8a1 (2009-05-02) -================== - -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 http://svn.repoze.org/repoze.bfg.chameleon_genshi (also - available in the index at http://dist.repoze.org/bfg/0.8/simple). - 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/ (also available in the index - at http://dist.repoze.org/bfg/0.8/simple). 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. - -0.7.1 (2009-05-01) -================== - -Index-Related -------------- - -- The canonical package index location for ``repoze.bfg`` has changed. - The "old" index (http://dist.repoze.org/lemonade/dev/simple) has - been superseded by a new index location - (`http://dist.repoze.org/bfg/current/simple - `_). 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 - http://svn.repoze.org/repoze.bfg.traversalwrapper) Then change your - application's ``configure.zcml`` to include the following stanza: - - - - 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. - -0.7.0 (2009-04-11) -================== - -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``:: - - - - 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. - -0.6.9 (2009-02-16) -================== - -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). - -0.6.8 (2009-02-05) -================== - -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 accomodate 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. - -0.6.7 (2009-01-27) -================== - -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``. - -0.6.6 (2009-01-26) -================== - -Implementation Changes ----------------------- - -- There is an indirection in ``repoze.bfg.url.model_url`` now that - consults a utility to generate the base model url (without extra - elements or a query string). Eventually this will service virtual - hosting; for now it's undocumented and should not be hooked. - -0.6.5 (2009-01-26) -================== - -Features --------- - -- You can now override the NotFound and Unauthorized responses that - ``repoze.bfg`` generates when a view cannot be found or cannot be - invoked due to lack of permission. See the "ZCML Hooks" chapter in - the docs for more information. - -- Added Routes ZCML directive attribute explanations in documentation. - -- Added a ``traversal_path`` API to the traversal module; see the - "traversal" API chapter in the docs. This was a function previously - known as ``split_path`` that was not an API but people were using it - anyway. Unlike ``split_path``, it now returns a tuple instead of a - list (as its values are cached). - -Behavior Changes ----------------- - -- The ``repoze.bfg.view.render_view_to_response`` API will no longer - raise a ValueError if an object returned by a view function it calls - does not possess certain attributes (``headerlist``, ``app_iter``, - ``status``). This API used to attempt to perform a check using the - ``is_response`` function in ``repoze.bfg.view``, and raised a - ``ValueError`` if the ``is_response`` check failed. The - responsibility is now the caller's to ensure that the return value - from a view function is a "real" response. - -- WSGI environ dicts passed to ``repoze.bfg`` 's Router must now - contain a REQUEST_METHOD key/value; if they do not, a KeyError will - be raised (speed). - -- It is no longer permissible to pass a "nested" list of principals to - ``repoze.bfg.ACLAuthorizer.permits`` (e.g. ``['fred', ['larry', - 'bob']]``). The principals list must be fully expanded. This - feature was never documented, and was never an API, so it's not a - backwards incompatibility. - -- It is no longer permissible for a security ACE to contain a "nested" - list of permissions (e.g. ``(Allow, Everyone, ['read', ['view', - ['write', 'manage']]])`)`. The list must instead be fully expanded - (e.g. ``(Allow, Everyone, ['read', 'view', 'write', 'manage])``). This - feature was never documented, and was never an API, so it's not a - backwards incompatibility. - -- The ``repoze.bfg.urldispatch.RoutesRootFactory`` now injects the - ``wsgiorg.routing_args`` environment variable into the environ when - a route matches. This is a tuple of ((), routing_args) where - routing_args is the value that comes back from the routes mapper - match (the "match dict"). - -- The ``repoze.bfg.traversal.RoutesModelTraverser`` class now wants to - obtain the ``view_name`` and ``subpath`` from the - ``wsgiorgs.routing_args`` environment variable. It falls back to - obtaining these from the context for backwards compatibility. - -Implementation Changes ----------------------- - -- Get rid of ``repoze.bfg.security.ACLAuthorizer``: the - ``ACLSecurityPolicy`` now does what it did inline. - -- Get rid of ``repoze.bfg.interfaces.NoAuthorizationInformation`` - exception: it was used only by ``ACLAuthorizer``. - -- Use a homegrown NotFound error instead of ``webob.exc.HTTPNotFound`` - (the latter is slow). - -- Use a homegrown Unauthorized error instead of - ``webob.exc.Unauthorized`` (the latter is slow). - -- the ``repoze.bfg.lru.lru_cached`` decorator now uses functools.wraps - in order to make documentation of LRU-cached functions possible. - -- Various speed micro-tweaks. - -Bug Fixes ---------- - -- ``repoze.bfg.testing.DummyModel`` did not have a ``get`` method; - it now does. - -0.6.4 (2009-01-23) -================== - -Backwards Incompatibilities ---------------------------- - -- The ``unicode_path_segments`` configuration variable and the - ``BFG_UNICODE_PATH_SEGMENTS`` configuration variable have been - removed. Path segments are now always passed to model - ``__getitem__`` methods as unicode. "True" has been the default for - this setting since 0.5.4, but changing this configuration setting to - false allowed you to go back to passing raw path element strings to - model ``__getitem__`` methods. Removal of this knob services a - speed goal (we get about +80 req/s by removing the check), and it's - clearer just to always expect unicode path segments in model - ``__getitem__`` methods. - -Implementation Changes ----------------------- - -- ``repoze.bfg.traversal.split_path`` now also handles decoding - path segments to unicode (for speed, because its results are - cached). - -- ``repoze.bfg.traversal.step`` was made a method of the - ModelGraphTraverser. - -- Use "precooked" Request subclasses - (e.g. ``repoze.bfg.request.GETRequest``) that correspond to HTTP - request methods within ``router.py`` when constructing a request - object rather than using ``alsoProvides`` to attach the proper - interface to an unsubclassed ``webob.Request``. This pattern is - purely an optimization (e.g. preventing calls to ``alsoProvides`` - means the difference between 590 r/s and 690 r/s on a MacBook 2GHz). - -- Tease out an extra 4% performance boost by changing the Router; - instead of using imported ZCA APIs, use the same APIs directly - against the registry that is an attribute of the Router. - -- The registry used by BFG is now a subclass of - ``zope.component.registry.Components`` (defined as - ``repoze.bfg.registry.Registry``); it has a ``notify`` method, a - ``registerSubscriptionAdapter`` and a ``registerHandler`` method. - If no subscribers are registered via ``registerHandler`` or - ``registerSubscriptionAdapter``, ``notify`` is a noop for speed. - -- The Allowed and Denied classes in ``repoze.bfg.security`` now are - lazier about constructing the representation of a reason message for - speed; ``repoze.bfg.view_execution_permitted`` takes advantage of - this. - -- The ``is_response`` check was sped up by about half at the expense - of making its code slightly uglier. - -New Modules ------------ - -- ``repoze.bfg.lru`` implements an LRU cache class and a decorator for - internal use. - -0.6.3 (2009-01-19) -================== - -Bug Fixes ---------- - -- Readd ``root_policy`` attribute on Router object (as a property - which returns the IRootFactory utility). It was inadvertently - removed in 0.6.2. Code in the wild depended upon its presence - (esp. scripts and "debug" helpers). - -Features --------- - -- URL-dispatch has been overhauled: it is no longer necessary to - manually create a RoutesMapper in your application's entry point - callable in order to use URL-dispatch (aka `Routes - `_). A new ``route`` directive has been - added to the available list of ZCML directives. Each ``route`` - directive inserted into your application's ``configure.zcml`` - establishes a Routes mapper connection. If any ``route`` - declarations are made via ZCML within a particular application, the - ``get_root`` callable passed in to ``repoze.bfg.router.make_app`` - will automatically be wrapped in the equivalent of a RoutesMapper. - Additionally, the new ``route`` directive allows the specification - of a ``context_interfaces`` attribute for a route, this will be used - to tag the manufactured routes context with specific interfaces when - a route specifying a ``context_interfaces`` attribute is matched. - -- A new interface ``repoze.bfg.interfaces.IContextNotFound`` was - added. This interface is attached to a "dummy" context generated - when Routes cannot find a match and there is no "fallback" get_root - callable that uses traversal. - -- The ``bfg_starter`` and ``bfg_zodb`` "paster create" templates now - contain images and CSS which are displayed when the default page is - displayed after initial project generation. - -- Allow the ``repoze.bfg.view.static`` helper to be passed a relative - ``root_path`` name; it will be considered relative to the file in - which it was called. - -- The functionality of ``repoze.bfg.convention`` has been merged into - the core. Applications which make use of ``repoze.bfg.convention`` - will continue to work indefinitely, but it is recommended that apps - stop depending upon it. To do so, substitute imports of - ``repoze.bfg.convention.bfg_view`` with imports of - ``repoze.bfg.view.bfg_view``, and change the stanza in ZCML from - ```` to ````. As a result - of the merge, bfg has grown a new dependency: ``martian``. - -- View functions which use the pushpage decorator are now pickleable - (meaning their use won't prevent a ``configure.zcml.cache`` file - from being written to disk). - -- Instead of invariably using ``webob.Request`` as the "request - factory" (e.g. in the ``Router`` class) and ``webob.Response`` and - the "response factory" (e.g. in ``render_template_to_response``), - allow both to be overridden via a ZCML utility hook. See the "Using - ZCML Hooks" chapter of the documentation for more information. - -Deprecations ------------- - -- The class ``repoze.bfg.urldispatch.RoutesContext`` has been renamed - to ``repoze.bfg.urldispatch.DefaultRoutesContext``. The class - should be imported by the new name as necessary (although in reality - it probably shouldn't be imported from anywhere except internally - within BFG, as it's not part of the API). - -Implementation Changes ----------------------- - -- The ``repoze.bfg.wsgi.wsgiapp`` decorator now uses - ``webob.Request.get_response`` to do its work rather than relying on - homegrown WSGI code. - -- The ``repoze.bfg.view.static`` helper now uses - ``webob.Request.get_response`` to do its work rather than relying on - homegrown WSGI code. - -- The ``repoze.bfg.urldispatch.RoutesModelTraverser`` class has been - moved to ``repoze.bfg.traversal.RoutesModelTraverser``. - -- The ``repoze.bfg.registry.makeRegistry`` function was renamed to - ``repoze.bfg.registry.populateRegistry`` and now accepts a - ``registry`` argument (which should be an instance of - ``zope.component.registry.Components``). - -Documentation Additions ------------------------ - -- Updated narrative urldispatch chapter with changes required by - ```` ZCML directive. - -- Add a section on "Using BFG Security With URL Dispatch" into the - urldispatch chapter of the documentation. - -- Better documentation of security policy implementations that ship - with repoze.bfg. - -- Added a "Using ZPT Macros in repoze.bfg" section to the narrative - templating chapter. - -0.6.2 (2009-01-13) -================== - -Features --------- - -- Tests can be run with coverage output if you've got ``nose`` - installed in the interpreter which you use to run tests. Using an - interpreter with ``nose`` installed, do ``python setup.py - nosetests`` within a checkout of the ``repoze.bfg`` package to see - test coverage output. - -- Added a ``post`` argument to the ``repoze.bfg.testing:DummyRequest`` - constructor. - -- Added ``__len__`` and ``__nonzero__`` to ``repoze.bfg.testing:DummyModel``. - -- The ``repoze.bfg.registry.get_options`` callable (now renamed to - ``repoze.bfg.setings.get_options``) used to return only - framework-specific keys and values in the dictionary it returned. - It now returns all the keys and values in the dictionary it is - passed *plus* any framework-specific settings culled from the - environment. As a side effect, all PasteDeploy application-specific - config file settings are made available as attributes of the - ``ISettings`` utility from within BFG. - -- Renamed the existing BFG paster template to ``bfg_starter``. Added - another template (``bfg_zodb``) showing default ZODB setup using - ``repoze.zodbconn``. - -- Add a method named ``assert_`` to the DummyTemplateRenderer. This - method accepts keyword arguments. Each key/value pair in the - keyword arguments causes an assertion to be made that the renderer - received this key with a value equal to the asserted value. - -- Projects generated by the paster templates now use the - ``DummyTemplateRenderer.assert_`` method in their view tests. - -- Make the (internal) thread local registry manager maintain a stack - of registries in order to make it possible to call one BFG - application from inside another. - -- An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is - attached to each request object on ingress. The HTTP-verb-related - interfaces are defined in ``repoze.bfg.interfaces`` and are - ``IGETRequest``, ``IPOSTRequest``, ``IPUTRequest``, - ``IDELETERequest`` and ``IHEADRequest``. These interfaces can be - specified as the ``request_type`` attribute of a bfg view - declaration. A view naming a specific HTTP-verb-matching interface - will be found only if the view is defined with a request_type that - matches the HTTP verb in the incoming request. The more general - ``IRequest`` interface can be used as the request_type to catch all - requests (and this is indeed the default). All requests implement - ``IRequest``. The HTTP-verb-matching idea was pioneered by - `repoze.bfg.restrequest - `_ . That - package is no longer required, but still functions fine. - -Bug Fixes ---------- - -- Fix a bug where the Paste configuration's ``unicode_path_segments`` - (and os.environ's ``BFG_UNICODE_PATH_SEGMENTS``) may have been - defaulting to false in some circumstances. It now always defaults - to true, matching the documentation and intent. - -- The ``repoze.bfg.traversal.find_model`` API did not work properly - when passed a ``path`` argument which was unicode and contained - high-order bytes when the ``unicode_path_segments`` or - ``BFG_UNICODE_PATH_SEGMENTS`` configuration variables were "true". - -- A new module was added: ``repoze.bfg.settings``. This contains - deployment-settings-related code. - -Implementation Changes ----------------------- - -- The ``make_app`` callable within ``repoze.bfg.router`` now registers - the ``root_policy`` argument as a utility (unnamed, using the new - ``repoze.bfg.interfaces.IRootFactory`` as a provides interface) - rather than passing it as the first argument to the - ``repoze.bfg.router.Router`` class. As a result, the - ``repoze.bfg.router.Router`` router class only accepts a single - argument: ``registry``. The ``repoze.bfg.router.Router`` class - retrieves the root policy via a utility lookup now. The - ``repoze.bfg.router.make_app`` API also now performs some important - application registrations that were previously handled inside - ``repoze.bfg.registry.makeRegistry``. - -New Modules ------------ - -- A ``repoze.bfg.settings`` module was added. It contains code - related to deployment settings. Most of the code it contains was - moved to it from the ``repoze.bfg.registry`` module. - -Behavior Changes ----------------- - -- The ``repoze.bfg.settings.Settings`` class (an instance of which is - registered as a utility providing - ``repoze.bfg.interfaces.ISettings`` when any application is started) - now automatically calls ``repoze.bfg.settings.get_options`` on the - options passed to its constructor. This means that usage of - ``get_options`` within an application's ``make_app`` function is no - longer required (the "raw" ``options`` dict or None may be passed). - -- Remove old cold which attempts to recover from trying to unpickle a - ``z3c.pt`` template; Chameleon has been the templating engine for a - good long time now. Running repoze.bfg against a sandbox that has - pickled ``z3c.pt`` templates it will now just fail with an - unpickling error, but can be fixed by deleting the template cache - files. - -Deprecations ------------- - -- Moved the ``repoze.bfg.registry.Settings`` class. This has been - moved to ``repoze.bfg.settings.Settings``. A deprecation warning is - issued when it is imported from the older location. - -- Moved the ``repoze.bfg.registry.get_options`` function This has been - moved to ``repoze.bfg.settings.get_options``. A deprecation warning - is issued when it is imported from the older location. - -- The ``repoze.bfg.interfaces.IRootPolicy`` interface was renamed - within the interfaces package. It has been renamed to - ``IRootFactory``. A deprecation warning is issued when it is - imported from the older location. - -0.6.1 (2009-01-06) -================== - -New Modules ------------ - -- A new module ``repoze.bfg.url`` has been added. It contains the - ``model_url`` API (moved from ``repoze.bfg.traversal``) and an - implementation of ``urlencode`` (like Python's - ``urllib.urlencode``) which can handle Unicode keys and values in - parameters to the ``query`` argument. - -Deprecations ------------- - -- The ``model_url`` function has been moved from - ``repoze.bfg.traversal`` into ``repoze.bfg.url``. It can still - be imported from ``repoze.bfg.traversal`` but an import from - ``repoze.bfg.traversal`` will emit a DeprecationWarning. - -Features --------- - -- A ``static`` helper class was added to the ``repoze.bfg.views`` - module. Instances of this class are willing to act as BFG views - which return static resources using files on disk. See the - ``repoze.bfg.view`` docs for more info. - -- The ``repoze.bfg.url.model_url`` API (nee' - ``repoze.bfg.traversal.model_url``) now accepts and honors a - keyword argument named ``query``. The value of this argument - will be used to compose a query string, which will be attached to - the generated URL before it is returned. See the API docs (in - the docs directory or `on the web - `_) for more information. - -0.6 (2008-12-26) -================ - -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 http://static.repoze.org/zcmldocs). - 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. ````) 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 `_ 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``:: - - - - 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. - -0.5.6 (2008-12-18) -================== - -- 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. - -0.5.5 (2008-12-17) -================== - -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 - successully, 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 - -0.5.4 (2008-12-13) -================== - -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. - -0.5.3 (2008-12-07) -================== - -- 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 explcit named utility registrations in - the ZCML registry against ``ITemplateRenderer``; these will be found - before any on-disk template is looked up. - -0.5.2 (2008-12-05) -================== - -- 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. - -0.5.1 (2008-11-25) -================== - -- Add ``keys``, ``items``, and ``values`` methods to - ``testing.DummyModel``. - -- Add __delitem__ method to ``testing.DummyModel``. - -0.5.0 (2008-11-18) -================== - -- Fix ModelGraphTraverser; don't try to change the ``__name__`` or - ``__parent__`` of an object that claims it implements ILocation during - traversal even if the ``__name__`` or ``__parent__`` of the object - traversed does not match the name used in the traversal step or the or - the traversal parent . Rationale: it was insane to do so. This bug was - only found due to a misconfiguration in an application that mistakenly - had intermediate persistent non-ILocation objects; traversal was causing - a persistent write on every request under this setup. - -- ``repoze.bfg.location.locate`` now unconditionally sets ``__name__`` and - ``__parent__`` on objects which provide ILocation (it previously only set - them conditionally if they didn't match attributes already present on the - object via equality). - -0.4.9 (2008-11-17) -================== - -- Add chameleon text template API (chameleon ${name} renderings where the - template does not need to be wrapped in any containing XML). - -- Change docs to explain install in terms of a virtualenv - (unconditionally). - -- Make pushpage decorator compatible with repoze.bfg.convention's - ``bfg_view`` decorator when they're stacked. - -- Add content_length attribute to testing.DummyRequest. - -- Change paster template ``tests.py`` to include a true unit test. Retain - old test as an integration test. Update documentation. - -- Document view registrations against classes and ``repoze.bfg.convention`` - in context. - -- Change the default paster template to register its single view against a - class rather than an interface. - -- Document adding a request type interface to the request via a subscriber - function in the events narrative documentation. - -0.4.8 (2008-11-12) -================== - -Backwards Incompatibilities ---------------------------- - -- ``repoze.bfg.traversal.model_url`` now always appends a slash to all - generated URLs unless further elements are passed in as the third and - following arguments. Rationale: views often use ``model_url`` without - the third-and-following arguments in order to generate a URL for a model - in order to point at the default view of a model. The URL that points to - the default view of the *root* model is technically ``http://mysite/`` as - opposed to ``http://mysite`` (browsers happen to ask for '/' implicitly - in the GET request). Because URLs are never automatically generated for - anything *except* models by ``model_url``, and because the root model is - not really special, we continue this pattern. The impact of this change - is minimal (at most you will have too many slashes in your URL, which BFG - deals with gracefully anyway). - -0.4.7 (2008-11-11) -================== - -Features --------- - -- Allow ``testing.registerEventListener`` to be used with Zope 3 style - "object events" (subscribers accept more than a single event argument). - We extend the list with the arguments, rather than append. - -0.4.6 (2008-11-10) -================== - -Bug Fixes ---------- - -- The ``model_path`` and ``model_url`` traversal APIs returned the wrong - value for the root object (e.g. ``model_path`` returned ``''`` for the - root object, while it should have been returning ``'/'``). - -0.4.5 (2008-11-09) -================== - -Features --------- - -- Added a ``clone`` method and a ``__contains__`` method to the DummyModel - testing object. - -- Allow DummyModel objects to receive extra keyword arguments, which will - be attached as attributes. - -- The DummyTemplateRenderer now returns ``self`` as its implementation. - -0.4.4 (2008-11-08) -================== - -Features --------- - -- Added a ``repoze.bfg.testing`` module to attempt to make it slightly - easier to write unittest-based automated tests of BFG applications. - Information about this module is in the documentation. - -- The default template renderer now supports testing better by looking for - ``ITestingTemplateRenderer`` using a relative pathname. This is exposed - indirectly through the API named ``registerTemplateRenderer`` in - ``repoze.bfg.testing``. - -Deprecations ------------- - -- The names ``repoze.bfg.interfaces.ITemplate`` , - ``repoze.bfg.interfaces.ITemplateFactory`` and - ``repoze.bfg.interfaces.INodeTemplate`` have been deprecated. These - should now be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` and - ``repoze.bfg.interfaces.ITemplateRendererFactory``, and - ``INodeTemplateRenderer`` respectively. - -- The name ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` is deprecated. - Use ``repoze.bfg.chameleon_zpt.ZPTTemplateRenderer``. - -- The name ``repoze.bfg.chameleon_genshi.GenshiTemplateFactory`` is - deprecated. Use ``repoze.bfg.chameleon_genshi.GenshiTemplateRenderer``. - -- The name ``repoze.bfg.xslt.XSLTemplateFactory`` is deprecated. Use - ``repoze.bfg.xslt.XSLTemplateRenderer``. - -0.4.3 (2008-11-02) -================== - -Bug Fixes ---------- - -- Not passing the result of "get_options" as the second argument of - make_app could cause attribute errors when attempting to look up settings - against the ISettings object (internal). Fixed by giving the Settings - objects defaults for ``debug_authorization`` and ``debug_notfound``. - -- Return an instance of ``Allowed`` (rather than ``True``) from - ``has_permission`` when no security policy is in use. - -- Fix bug where default deny in authorization check would throw a TypeError - (use ``ACLDenied`` instead of ``Denied``). - -0.4.2 (2008-11-02) -================== - -Features --------- - -- Expose a single ILogger named "repoze.bfg.debug" as a utility; this - logger is registered unconditionally and is used by the authorization - debug machinery. Applications may also make use of it as necessary - rather than inventing their own logger, for convenience. - -- The ``BFG_DEBUG_AUTHORIZATION`` envvar and the ``debug_authorization`` - config file value now only imply debugging of view-invoked security - checks. Previously, information was printed for every call to - ``has_permission`` as well, which made output confusing. To debug - ``has_permission`` checks and other manual permission checks, use the - debugger and print statements in your own code. - -- Authorization debugging info is now only present in the HTTP response - body oif ``debug_authorization`` is true. - -- The format of authorization debug messages was improved. - -- A new ``BFG_DEBUG_NOTFOUND`` envvar was added and a symmetric - ``debug_notfound`` config file value was added. When either is true, and - a NotFound response is returned by the BFG router (because a view could - not be found), debugging information is printed to stderr. When this - value is set true, the body of HTTPNotFound responses will also contain - the same debugging information. - -- ``Allowed`` and ``Denied`` responses from the security machinery are now - specialized into two types: ACL types, and non-ACL types. The - ACL-related responses are instances of ``repoze.bfg.security.ACLAllowed`` - and ``repoze.bfg.security.ACLDenied``. The non-ACL-related responses are - ``repoze.bfg.security.Allowed`` and ``repoze.bfg.security.Denied``. The - allowed-type responses continue to evaluate equal to things that - themselves evaluate equal to the ``True`` boolean, while the denied-type - responses continue to evaluate equal to things that themselves evaluate - equal to the ``False`` boolean. The only difference between the two - types is the information attached to them for debugging purposes. - -- Added a new ``BFG_DEBUG_ALL`` envvar and a symmetric ``debug_all`` config - file value. When either is true, all other debug-related flags are set - true unconditionally (e.g. ``debug_notfound`` and - ``debug_authorization``). - -Documentation -------------- - -- Added info about debug flag changes. - -- Added a section to the security chapter named "Debugging Imperative - Authorization Failures" (for e.g. ``has_permssion``). - -Bug Fixes ---------- - -- Change default paster template generator to use ``Paste#http`` server - rather than ``PasteScript#cherrpy`` server. The cherrypy server has a - security risk in it when ``REMOTE_USER`` is trusted by the downstream - application. - -0.4.1 (2008-10-28) -================== - -Bug Fixes ---------- - -- If the ``render_view_to_response`` function was called, if the view was - found and called, but it returned something that did not implement - IResponse, the error would pass by unflagged. This was noticed when I - created a view function that essentially returned None, but received a - NotFound error rather than a ValueError when the view was rendered. This - was fixed. - -0.4.0 (2008-10-03) -================== - -Docs ----- - -- An "Environment and Configuration" chapter was added to the narrative - portion of the documentation. - -Features --------- - -- Ensure bfg doesn't generate warnings when running under Python - 2.6. - -- The environment variable ``BFG_RELOAD_TEMPLATES`` is now available - (serves the same purpose as ``reload_templates`` in the config file). - -- A new configuration file option ``debug_authorization`` was added. - This turns on printing of security authorization debug statements - to ``sys.stderr``. The ``BFG_DEBUG_AUTHORIZATION`` environment - variable was also added; this performs the same duty. - -Bug Fixes ---------- - -- The environment variable ``BFG_SECURITY_DEBUG`` did not always work. - It has been renamed to ``BFG_DEBUG_AUTHORIZATION`` and fixed. - -Deprecations ------------- - -- A deprecation warning is now issued when old API names from the - ``repoze.bfg.templates`` module are imported. - -Backwards incompatibilities ---------------------------- - -- The ``BFG_SECURITY_DEBUG`` environment variable was renamed to - ``BFG_DEBUG_AUTHORIZATION``. - -0.3.9 (2008-08-27) -================== - -Features --------- - -- A ``repoze.bfg.location`` API module was added. - -Backwards incompatibilities ---------------------------- - -- Applications must now use the ``repoze.bfg.interfaces.ILocation`` - interface rather than ``zope.location.interfaces.ILocation`` to - represent that a model object is "location-aware". We've removed - a dependency on ``zope.location`` for cleanliness purposes: as - new versions of zope libraries are released which have improved - dependency information, getting rid of our dependence on - ``zope.location`` will prevent a newly installed repoze.bfg - application from requiring the ``zope.security``, egg, which not - truly used at all in a "stock" repoze.bfg setup. These - dependencies are still required by the stack at this time; this - is purely a futureproofing move. - - The security and model documentation for previous versions of - ``repoze.bfg`` recommended using the - ``zope.location.interfaces.ILocation`` interface to represent - that a model object is "location-aware". This documentation has - been changed to reflect that this interface should now be - imported from ``repoze.bfg.interfaces.ILocation`` instead. - -0.3.8 (2008-08-26) -================== - -Docs ----- - -- Documented URL dispatch better in narrative form. - -Bug fixes ---------- - -- Routes URL dispatch did not have access to the WSGI environment, - so conditions such as method=GET did not work. - -Features --------- - -- Add ``principals_allowed_by_permission`` API to security module. - -- Replace ``z3c.pt`` support with support for ``chameleon.zpt``. - Chameleon is the new name for the package that used to be named - ``z3c.pt``. NOTE: If you update a ``repoze.bfg`` SVN checkout - that you're using for development, you will need to run "setup.py - install" or "setup.py develop" again in order to obtain the - proper Chameleon packages. ``z3c.pt`` is no longer supported by - ``repoze.bfg``. All API functions that used to render ``z3c.pt`` - templates will work fine with the new packages, and your - templates should render almost identically. - -- Add a ``repoze.bfg.chameleon_zpt`` module. This module provides - Chameleon ZPT support. - -- Add a ``repoze.bfg.xslt`` module. This module provides XSLT - support. - -- Add a ``repoze.bfg.chameleon_genshi`` module. This provides - direct Genshi support, which did not exist previously. - -Deprecations ------------- - -- Importing API functions directly from ``repoze.bfg.template`` is - now deprecated. The ``get_template``, ``render_template``, - ``render_template_to_response`` functions should now be imported - from ``repoze.chameleon_zpt``. The ``render_transform``, and - ``render_transform_to_response`` functions should now be imported - from ``repoze.bfg.xslt``. The ``repoze.bfg.template`` module - will remain around "forever" to support backwards compatibility. - -0.3.7 (2008-09-09) -================== - -Features --------- - -- Add compatibility with z3c.pt 1.0a7+ (z3c.pt became a namespace package). - -Bug fixes ---------- - -- ``repoze.bfg.traversal.find_model`` function did not function properly. - -0.3.6 (2008-09-04) -================== - -Features --------- - -- Add startup process docs. - -- Allow configuration cache to be bypassed by actions which include special - "uncacheable" discriminators (for actions that have variable results). - -Bug Fixes ---------- - -- Move core repoze.bfg ZCML into a ``repoze.bfg.includes`` package so we - can use repoze.bfg better as a namespace package. Adjust the code - generator to use it. We've left around the ``configure.zcml`` in the - repoze.bfg package directly so as not to break older apps. - -- When a zcml application registry cache was unpickled, and it contained a - reference to an object that no longer existed (such as a view), bfg would - not start properly. - -0.3.5 (2008-09-01) -================== - -Features --------- - -- Event notification is issued after application is created and configured - (``IWSGIApplicationCreatedEvent``). - -- New API module: ``repoze.bfg.view``. This module contains the functions - named ``render_view_to_response``, ``render_view_to_iterable``, - ``render_view`` and ``is_response``, which are documented in the API - docs. These features aid programmatic (non-server-driven) view - execution. - -0.3.4 (2008-08-28) -================== - -Backwards incompatibilities ---------------------------- - -- Make ``repoze.bfg`` a namespace package so we can allow folks to create - subpackages (e.g. ``repoze.bfg.otherthing``) within separate eggs. This - is a backwards incompatible change which makes it impossible to import - "make_app" and "get_options" from the ``repoze.bfg`` module directly. - This change will break all existing apps generated by the paster code - generator. Instead, you need to import these functions as - ``repoze.bfg.router:make_app`` and ``repoze.bfg.registry:get_options``, - respectively. Sorry folks, it has to be done now or never, and - definitely better now. - -Features --------- - -- Add ``model_path`` API function to traversal module. - -Bugfixes - -- Normalize path returned by repoze.bfg.caller_path. - -0.3.3 (2008-08-23) -================== - -- Fix generated test.py module to use project name rather than package - name. - -0.3.2 (2008-08-23) -================== - -- Remove ``sampleapp`` sample application from bfg package itself. - -- Remove dependency on FormEncode (only needed by sampleapp). - -- Fix paster template generation so that case-sensitivity is preserved for - project vs. package name. - -- Depend on ``z3c.pt`` version 1.0a1 (which requires the ``[lxml]`` extra - currently). - -- Read and write a pickled ZCML actions list, stored as - ``configure.zcml.cache`` next to the applications's "normal" - configuration file. A given bfg app will usually start faster if it's - able to read the pickle data. It fails gracefully to reading the real - ZCML file if it cannot read the pickle. - -0.3.1 (2008-08-20) -================== - -- Generated application differences: ``make_app`` entry point renamed to - ``app`` in order to have a different name than the bfg function of the - same name, to prevent confusion. - -- Add "options" processing to bfg's ``make_app`` to support runtime - options. A new API function named ``get_options`` was added to the - registry module. This function is typically used in an application's - ``app`` entry point. The Paste config file section for the app can now - supply the ``reload_templates`` option, which, if true, will prevent the - need to restart the appserver in order for ``z3c.pt`` or XSLT template - changes to be detected. - -- Use only the module name in generated project's "test_suite" (run all - tests found in the package). - -- Default port for generated apps changed from 5432 to 6543 (Postgres - default port is 6543). - -0.3.0 (2008-08-16) -================== - -- Add ``get_template`` API to template module. - -0.2.9 (2008-08-11) -================== - -- 0.2.8 was "brown bag" release. It didn't work at all. Symptom: - ComponentLookupError when trying to render a page. - -0.2.8 (2008-08-11) -================== - -- Add ``find_model`` and ``find_root`` traversal APIs. In the process, - make ITraverser a uni-adapter (on context) rather than a multiadapter (on - context and request). - -0.2.7 (2008-08-05) -================== - -- Add a ``request_type`` attribute to the available attributes of a - ``bfg:view`` configure.zcml element. This attribute will have a value - which is a dotted Python path, pointing at an interface. If the request - object implements this interface when the view lookup is performed, the - appropriate view will be called. This is meant to allow for simple - "skinning" of sites based on request type. An event subscriber should - attach the interface to the request on ingress to support skins. - -- Remove "template only" views. These were just confusing and were never - documented. - -- Small url dispatch overhaul: the ``connect`` method of the - ``urldispatch.RoutesMapper`` object now accepts a keyword parameter named - ``context_factory``. If this parameter is supplied, it must be a - callable which returns an instance. This instance is used as the context - for the request when a route is matched. - -- The registration of a RoutesModelTraverser no longer needs to be - performed by the application; it's in the bfg ZCML now. - -0.2.6 (2008-07-31) -================== - -- Add event sends for INewRequest and INewResponse. See the events.rst - chapter in the documentation's ``api`` directory. - -0.2.5 (2008-07-28) -================== - -- Add ``model_url`` API. - -0.2.4 (2008-07-27) -================== - -- Added url-based dispatch. - -0.2.3 (2008-07-20) -================== - -- Add API functions for authenticated_userid and effective_principals. - -0.2.2 (2008-07-20) -================== - -- Add authenticated_userid and effective_principals API to security - policy. - -0.2.1 (2008-07-20) -================== - -- Add find_interface API. - -0.2 (2008-07-19) -================ - -- Add wsgiapp decorator. - -- The concept of "view factories" was removed in favor of always calling a - view, which is a callable that returns a response directly (as opposed to - returning a view). As a result, the ``factory`` attribute in the - bfg:view ZCML statement has been renamed to ``view``. Various interface - names were changed also. - -- ``render_template`` and ``render_transform`` no longer return a Response - object. Instead, these return strings. The old behavior can be obtained - by using ``render_template_to_response`` and - ``render_transform_to_response``. - -- Added 'repoze.bfg.push:pushpage' decorator, which creates BFG views from - callables which take (context, request) and return a mapping of top-level - names. - -- Added ACL-based security. - -- Support for XSLT templates via a render_transform method - -0.1 (2008-07-08) -================ - -- Initial release. - diff --git a/CHANGES.rst b/CHANGES.rst new file mode 100644 index 000000000..482610319 --- /dev/null +++ b/CHANGES.rst @@ -0,0 +1,40 @@ +unreleased +========== + +Features +-------- + +- Add a ``_depth`` and ``_category`` arguments to all of the venusian + decorators. The ``_category`` argument can be used to affect which actions + are registered when performing a ``config.scan(..., category=...)`` with a + specific category. The ``_depth`` argument should be used when wrapping + the decorator in your own. This change affects ``pyramid.view.view_config``, + ``pyramid.view.exception_view_config``, + ``pyramid.view.forbidden_view_config``, ``pyramid.view.notfound_view_config``, + ``pyramid.events.subscriber`` and ``pyramid.response.response_adapter`` + decorators. See https://github.com/Pylons/pyramid/pull/3105 and + https://github.com/Pylons/pyramid/pull/3122 + +- Fix the ``pyramid.request.Request`` class name after using + ``set_property`` or ``config.add_request_method`` such that the + ``str(request.__class__)`` would appear as ``pyramid.request.Request`` + instead of ``pyramid.util.Request``. + See https://github.com/Pylons/pyramid/pull/3129 + +Bug Fixes +--------- + +Deprecations +------------ + +Backward Incompatibilities +-------------------------- + +- On Python 3.4+ the ``repoze.lru`` dependency is dropped. If you were using + this package directly in your apps you should make sure that you are + depending on it directly within your project. + See https://github.com/Pylons/pyramid/pull/3140 + +Documentation Changes +--------------------- + diff --git a/CHANGES.txt b/CHANGES.txt deleted file mode 100644 index 482610319..000000000 --- a/CHANGES.txt +++ /dev/null @@ -1,40 +0,0 @@ -unreleased -========== - -Features --------- - -- Add a ``_depth`` and ``_category`` arguments to all of the venusian - decorators. The ``_category`` argument can be used to affect which actions - are registered when performing a ``config.scan(..., category=...)`` with a - specific category. The ``_depth`` argument should be used when wrapping - the decorator in your own. This change affects ``pyramid.view.view_config``, - ``pyramid.view.exception_view_config``, - ``pyramid.view.forbidden_view_config``, ``pyramid.view.notfound_view_config``, - ``pyramid.events.subscriber`` and ``pyramid.response.response_adapter`` - decorators. See https://github.com/Pylons/pyramid/pull/3105 and - https://github.com/Pylons/pyramid/pull/3122 - -- Fix the ``pyramid.request.Request`` class name after using - ``set_property`` or ``config.add_request_method`` such that the - ``str(request.__class__)`` would appear as ``pyramid.request.Request`` - instead of ``pyramid.util.Request``. - See https://github.com/Pylons/pyramid/pull/3129 - -Bug Fixes ---------- - -Deprecations ------------- - -Backward Incompatibilities --------------------------- - -- On Python 3.4+ the ``repoze.lru`` dependency is dropped. If you were using - this package directly in your apps you should make sure that you are - depending on it directly within your project. - See https://github.com/Pylons/pyramid/pull/3140 - -Documentation Changes ---------------------- - diff --git a/HISTORY.rst b/HISTORY.rst new file mode 100644 index 000000000..8a92eadcc --- /dev/null +++ b/HISTORY.rst @@ -0,0 +1,5773 @@ +1.9 (2017-06-26) +================ + +- No major changes from 1.9b1. + +- Updated documentation links for ``docs.pylonsproject.org`` to use HTTPS. + +1.9b1 (2017-06-19) +================== + +- Add an informative error message when unknown predicates are supplied. The + new message suggests alternatives based on the list of known predicates. + See https://github.com/Pylons/pyramid/pull/3054 + +- Added integrity attributes for JavaScripts in cookiecutters, scaffolds, and + resulting source files in tutorials. + See https://github.com/Pylons/pyramid/issues/2548 + +- Update RELEASING.txt for updating cookiecutters. Change cookiecutter URLs to + use shortcut. + See https://github.com/Pylons/pyramid/issues/3042 + +- Ensure the correct threadlocals are pushed during view execution when + invoked from ``request.invoke_exception_view``. + See https://github.com/Pylons/pyramid/pull/3060 + +- Fix a bug in which ``pyramid.security.ALL_PERMISSIONS`` failed to return + a valid iterator in its ``__iter__`` implementation. + See https://github.com/Pylons/pyramid/pull/3074 + +- Normalize the permission results to a proper class hierarchy. + ``pyramid.security.ACLAllowed`` is now a subclass of + ``pyramid.security.Allowed`` and ``pyramid.security.ACLDenied`` is now a + subclass of ``pyramid.security.Denied``. + See https://github.com/Pylons/pyramid/pull/3084 + +- Add a ``quote_via`` argument to ``pyramid.encode.urlencode`` to follow + the stdlib's version and enable custom quoting functions. + See https://github.com/Pylons/pyramid/pull/3088 + +- Support `_query=None` and `_anchor=None` in ``request.route_url`` as well + as ``query=None`` and ``anchor=None`` in ``request.resource_url``. + Previously this would cause an `?` and a `#`, respectively, in the url + with nothing after it. Now the unnecessary parts are dropped from the + generated URL. See https://github.com/Pylons/pyramid/pull/3034 + +- Revamp the ``IRouter`` API used by ``IExecutionPolicy`` to force + pushing/popping the request threadlocals. The + ``IRouter.make_request(environ)`` API has been replaced by + ``IRouter.request_context(environ)`` which should be used as a context + manager. See https://github.com/Pylons/pyramid/pull/3086 + +1.9a2 (2017-05-09) +================== + +Backward Incompatibilities +-------------------------- + +- ``request.exception`` and ``request.exc_info`` will only be set if the + response was generated by the EXCVIEW tween. This is to avoid any confusion + where a response was generated elsewhere in the pipeline and not in + direct relation to the original exception. If anyone upstream wants to + catch and render responses for exceptions they should set + ``request.exception`` and ``request.exc_info`` themselves to indicate + the exception that was squashed when generating the response. + + Similar behavior occurs with ``request.invoke_exception_view`` in which + the exception properties are set to reflect the exception if a response + is successfully generated by the method. + + This is a very minor incompatibility. Most tweens right now would give + priority to the raised exception and ignore ``request.exception``. This + change just improves and clarifies that bookkeeping by trying to be + more clear about the relationship between the response and its squashed + exception. See https://github.com/Pylons/pyramid/pull/3029 and + https://github.com/Pylons/pyramid/pull/3031 + +1.9a1 (2017-05-01) +================== + +Major Features +-------------- + +- The file format used by all ``p*`` command line scripts such as ``pserve`` + and ``pshell``, as well as the ``pyramid.paster.bootstrap`` function + is now replaceable thanks to a new dependency on + `plaster `_. + + For now, Pyramid is still shipping with integrated support for the + PasteDeploy INI format by depending on the + `plaster_pastedeploy `_ + binding library. This may change in the future. + + See https://github.com/Pylons/pyramid/pull/2985 + +- Added an execution policy hook to the request pipeline. An execution + policy has the ability to control creation and execution of the request + objects before they enter the rest of the pipeline. This means for a single + request environ the policy may create more than one request object. + + The first library to use this feature is + `pyramid_retry + `_. + + See https://github.com/Pylons/pyramid/pull/2964 + +- CSRF support has been refactored out of sessions and into its own + independent API in the ``pyramid.csrf`` module. It supports a pluggable + ``pyramid.interfaces.ICSRFStoragePolicy`` which can be used to define your + own mechanism for generating and validating CSRF tokens. By default, + Pyramid continues to use the ``pyramid.csrf.LegacySessionCSRFStoragePolicy`` + that uses the ``request.session.get_csrf_token`` and + ``request.session.new_csrf_token`` APIs under the hood to preserve + compatibility. Two new policies are shipped as well, + ``pyramid.csrf.SessionCSRFStoragePolicy`` and + ``pyramid.csrf.CookieCSRFStoragePolicy`` which will store the CSRF tokens + in the session and in a standalone cookie, respectively. The storage policy + can be changed by using the new + ``pyramid.config.Configurator.set_csrf_storage_policy`` config directive. + + CSRF tokens should be used via the new ``pyramid.csrf.get_csrf_token``, + ``pyramid.csrf.new_csrf_token`` and ``pyramid.csrf.check_csrf_token`` APIs + in order to continue working if the storage policy is changed. Also, the + ``pyramid.csrf.get_csrf_token`` function is injected into templates to be + used conveniently in UI code. + + See https://github.com/Pylons/pyramid/pull/2854 and + https://github.com/Pylons/pyramid/pull/3019 + +Minor Features +-------------- + +- Support an ``open_url`` config setting in the ``pserve`` section of the + config file. This url is used to open a web browser when ``pserve --browser`` + is invoked. When this setting is unavailable the ``pserve`` script will + attempt to guess the port the server is using from the + ``server:`` section of the config file but there is no + requirement that the server is being run in this format so it may fail. + See https://github.com/Pylons/pyramid/pull/2984 + +- The ``pyramid.config.Configurator`` can now be used as a context manager + which will automatically push/pop threadlocals (similar to + ``config.begin()`` and ``config.end()``). It will also automatically perform + a ``config.commit()`` and thus it is only recommended to be used at the + top-level of your app. See https://github.com/Pylons/pyramid/pull/2874 + +- The threadlocals are now available inside any function invoked via + ``config.include``. This means the only config-time code that cannot rely + on threadlocals is code executed from non-actions inside the main. This + can be alleviated by invoking ``config.begin()`` and ``config.end()`` + appropriately or using the new context manager feature of the configurator. + See https://github.com/Pylons/pyramid/pull/2989 + +Bug Fixes +--------- + +- HTTPException's accepts a detail kwarg that may be used to pass additional + details to the exception. You may now pass objects so long as they have a + valid __str__ method. See https://github.com/Pylons/pyramid/pull/2951 + +- Fix a reference cycle causing memory leaks in which the registry + would keep a ``Configurator`` instance alive even after the configurator + was discarded. Another fix was also added for the ``global_registries`` + object in which the registry was stored in a closure preventing it from + being deallocated. See https://github.com/Pylons/pyramid/pull/2967 + +- Fix a bug directly invoking ``pyramid.scripts.pserve.main`` with the + ``--reload`` option in which ``sys.argv`` is always used in the subprocess + instead of the supplied ``argv``. + See https://github.com/Pylons/pyramid/pull/2962 + +Deprecations +------------ + +- Pyramid currently depends on ``plaster_pastedeploy`` to simplify the + transition to ``plaster`` by maintaining integrated support for INI files. + This dependency on ``plaster_pastedeploy`` should be considered subject to + Pyramid's deprecation policy and may be removed in the future. + Applications should depend on the appropriate plaster binding to satisfy + their needs. + +- Retrieving CSRF token from the session has been deprecated in favor of + equivalent methods in the ``pyramid.csrf`` module. The CSRF methods + (``ISession.get_csrf_token`` and ``ISession.new_csrf_token``) are no longer + required on the ``ISession`` interface except when using the default + ``pyramid.csrf.LegacySessionCSRFStoragePolicy``. + + Also, ``pyramid.session.check_csrf_token`` is now located at + ``pyramid.csrf.check_csrf_token``. + + See https://github.com/Pylons/pyramid/pull/2854 and + https://github.com/Pylons/pyramid/pull/3019 + +Documentation Changes +--------------------- + +- Added the execution policy to the routing diagram in the Request Processing + chapter. See https://github.com/Pylons/pyramid/pull/2993 + +1.8 (2017-01-21) +================ + +- No major changes from 1.8b1. + +1.8b1 (2017-01-17) +================== + +Features +-------- + +- Added an ``override`` option to ``config.add_translation_dirs`` to allow + later calls to place translation directories at a higher priority than + earlier calls. See https://github.com/Pylons/pyramid/pull/2902 + +Documentation Changes +--------------------- + +- Improve registry documentation to discuss uses as a component registry + and as a dictionary. See https://github.com/Pylons/pyramid/pull/2893 + +- Quick Tour, Quick Tutorial, and most other remaining documentation updated to + use cookiecutters instead of pcreate and scaffolds. + See https://github.com/Pylons/pyramid/pull/2888 and + https://github.com/Pylons/pyramid/pull/2889 + +- Fix unittests in wiki2 to work without different dependencies between + py2 and py3. See https://github.com/Pylons/pyramid/pull/2899 + +- Update Windows documentation to track newer Python 3 improvements to the + installer. See https://github.com/Pylons/pyramid/pull/2900 + +- Updated the ``mod_wsgi`` tutorial to use cookiecutters and Apache 2.4+. + See https://github.com/Pylons/pyramid/pull/2901 + +1.8a1 (2016-12-25) +================== + +Backward Incompatibilities +-------------------------- + +- Support for the ``IContextURL`` interface that was deprecated in Pyramid 1.3 + has been removed. See https://github.com/Pylons/pyramid/pull/2822 + +- Following the Pyramid deprecation period (1.6 -> 1.8), + daemon support for pserve has been removed. This includes removing the + daemon commands (start, stop, restart, status) as well as the following + arguments: ``--daemon``, ``--pid-file``, ``--log-file``, + ``--monitor-restart``, ``--status``, ``--user``, ``--group``, + ``--stop-daemon`` + + To run your server as a daemon you should use a process manager instead of + pserve. + + See https://github.com/Pylons/pyramid/pull/2615 + +- ``pcreate`` is now interactive by default. You will be prompted if a file + already exists with different content. Previously if there were similar + files it would silently skip them unless you specified ``--interactive`` + or ``--overwrite``. + See https://github.com/Pylons/pyramid/pull/2775 + +- Removed undocumented argument ``cachebust_match`` from + ``pyramid.static.static_view``. This argument was shipped accidentally + in Pyramid 1.6. See https://github.com/Pylons/pyramid/pull/2681 + +- Change static view to avoid setting the ``Content-Encoding`` response header + to an encoding guessed using Python's ``mimetypes`` module. This was causing + clients to decode the content of gzipped files when downloading them. The + client would end up with a ``foo.txt.gz`` file on disk that was already + decoded, thus should really be ``foo.txt``. Also, the ``Content-Encoding`` + should only have been used if the client itself broadcast support for the + encoding via ``Accept-Encoding`` request headers. + See https://github.com/Pylons/pyramid/pull/2810 + +- Settings are no longer accessible as attributes on the settings object + (e.g. ``request.registry.settings.foo``). This was deprecated in Pyramid 1.2. + See https://github.com/Pylons/pyramid/pull/2823 + +Features +-------- + +- Python 3.6 compatibility. + https://github.com/Pylons/pyramid/issues/2835 + +- ``pcreate`` learned about ``--package-name`` to allow you to create a new + project in an existing folder with a different package name than the project + name. See https://github.com/Pylons/pyramid/pull/2783 + +- The ``_get_credentials`` private method of ``BasicAuthAuthenticationPolicy`` + has been extracted into standalone function ``extract_http_basic_credentials`` + in ``pyramid.authentication`` module, this function extracts HTTP Basic + credentials from a ``request`` object, and returns them as a named tuple. + See https://github.com/Pylons/pyramid/pull/2662 + +- Pyramid 1.4 silently dropped a feature of the configurator that has been + restored. It's again possible for action discriminators to conflict across + different action orders. + See https://github.com/Pylons/pyramid/pull/2757 + +- ``pyramid.paster.bootstrap`` and its sibling ``pyramid.scripting.prepare`` + can now be used as context managers to automatically invoke the ``closer`` + and pop threadlocals off of the stack to prevent memory leaks. + See https://github.com/Pylons/pyramid/pull/2760 + +- Added ``pyramid.config.Configurator.add_exception_view`` and the + ``pyramid.view.exception_view_config`` decorator. It is now possible using + these methods or via the new ``exception_only=True`` option to ``add_view`` + to add a view which will only be matched when handling an exception. + Previously any exception views were also registered for a traversal + context that inherited from the exception class which prevented any + exception-only optimizations. + See https://github.com/Pylons/pyramid/pull/2660 + +- Added the ``exception_only`` boolean to + ``pyramid.interfaces.IViewDeriverInfo`` which can be used by view derivers + to determine if they are wrapping a view which only handles exceptions. + This means that it is no longer necessary to perform request-time checks + for ``request.exception`` to determine if the view is handling an exception + - the pipeline can be optimized at config-time. + See https://github.com/Pylons/pyramid/pull/2660 + +- ``pserve`` should now work with ``gevent`` and other workers that need + to monkeypatch the process, assuming the server and / or the app do so + as soon as possible before importing the rest of pyramid. + See https://github.com/Pylons/pyramid/pull/2797 + +- Pyramid no longer copies the settings object passed to the + ``pyramid.config.Configurator(settings=)``. The original ``dict`` is kept. + See https://github.com/Pylons/pyramid/pull/2823 + +- The csrf trusted origins setting may now be a whitespace-separated list of + domains. Previously only a python list was allowed. Also, it can now be set + using the ``PYRAMID_CSRF_TRUSTED_ORIGINS`` environment variable similar to + other settings. See https://github.com/Pylons/pyramid/pull/2823 + +- ``pserve --reload`` now uses the + `hupper ` + library to monitor file changes. This comes with many improvements: + + - If the `watchdog `_ package is + installed then monitoring will be done using inotify instead of + cpu and disk-intensive polling. + + - The monitor is now a separate process that will not crash and starts up + before any of your code. + + - The monitor will not restart the process after a crash until a file is + saved. + + - The monitor works on windows. + + - You can now trigger a reload manually from a pyramid view or any other + code via ``hupper.get_reloader().trigger_reload()``. Kind of neat. + + - You can trigger a reload by issuing a ``SIGHUP`` to the monitor process. + + See https://github.com/Pylons/pyramid/pull/2805 + +- A new ``[pserve]`` section is supported in your config files with a + ``watch_files`` key that can configure ``pserve --reload`` to monitor custom + file paths. See https://github.com/Pylons/pyramid/pull/2827 + +- Allow streaming responses to be made from subclasses of + ``pyramid.httpexceptions.HTTPException``. Previously the response would + be unrolled while testing for a body, making it impossible to stream + a response. + See https://github.com/Pylons/pyramid/pull/2863 + +- Update starter, alchemy and zodb scaffolds to support IPv6 by using the + new ``listen`` directives in waitress. + See https://github.com/Pylons/pyramid/pull/2853 + +- All p* scripts now use argparse instead of optparse. This improves their + ``--help`` output as well as enabling nicer documentation of their options. + See https://github.com/Pylons/pyramid/pull/2864 + +- Any deferred configuration action registered via ``config.action`` may now + depend on threadlocal state, such as asset overrides, being active when + the action is executed. + See https://github.com/Pylons/pyramid/pull/2873 + +- Asset specifications for directories passed to + ``config.add_translation_dirs`` now support overriding the entire asset + specification, including the folder name. Previously only the package name + was supported and the folder would always need to have the same name. + See https://github.com/Pylons/pyramid/pull/2873 + +- ``config.begin()`` will propagate the current threadlocal request through + as long as the registry is the same. For example: + + .. code-block:: python + + request = Request.blank(...) + config.begin(request) # pushes a request + config.begin() # propagates the previous request through unchanged + assert get_current_request() is request + + See https://github.com/Pylons/pyramid/pull/2873 + +- Added a new ``callback`` option to ``config.set_default_csrf_options`` which + can be used to determine per-request whether CSRF checking should be enabled + to allow for a mix authentication methods. Only cookie-based methods + generally require CSRF checking. + See https://github.com/Pylons/pyramid/pull/2778 + +Bug Fixes +--------- + +- Fixed bug in ``proutes`` such that it now shows the correct view when a + class and ``attr`` is involved. + See: https://github.com/Pylons/pyramid/pull/2687 + +- Fix a ``FutureWarning`` in Python 3.5 when using ``re.split`` on the + ``format`` setting to the ``proutes`` script. + See https://github.com/Pylons/pyramid/pull/2714 + +- Fix a ``RuntimeWarning`` emitted by WebOb when using arbitrary objects + as the ``userid`` in the ``AuthTktAuthenticationPolicy``. This is now caught + by the policy and the object is serialized as a base64 string to avoid + the cryptic warning. Since the userid will be read back as a string on + subsequent requests a more useful warning is emitted encouraging you to + use a primitive type instead. + See https://github.com/Pylons/pyramid/pull/2715 + +- Pyramid 1.6 introduced the ability for an action to invoke another action. + There was a bug in the way that ``config.add_view`` would interact with + custom view derivers introduced in Pyramid 1.7 because the view's + discriminator cannot be computed until view derivers and view predicates + have been created in earlier orders. Invoking an action from another action + would trigger an unrolling of the pipeline and would compute discriminators + before they were ready. The new behavior respects the ``order`` of the action + and ensures the discriminators are not computed until dependent actions + from previous orders have executed. + See https://github.com/Pylons/pyramid/pull/2757 + +- Fix bug in i18n where the default domain would always use the Germanic plural + style, even if a different plural function is defined in the relevant + messages file. See https://github.com/Pylons/pyramid/pull/2859 + +- The ``config.override_asset`` method now occurs during + ``pyramid.config.PHASE1_CONFIG`` such that it is ordered to execute before + any calls to ``config.add_translation_dirs``. + See https://github.com/Pylons/pyramid/pull/2873 + +Deprecations +------------ + +- The ``pcreate`` script and related scaffolds have been deprecated in favor + of the popular + `cookiecutter `_ project. + + All of Pyramid's official scaffolds as well as the tutorials have been + ported to cookiecutters: + + - `pyramid-cookiecutter-starter + `_ + + - `pyramid-cookiecutter-alchemy + `_ + + - `pyramid-cookiecutter-zodb + `_ + + See https://github.com/Pylons/pyramid/pull/2780 + +Documentation Changes +--------------------- + +- Update Typographical Conventions. + https://github.com/Pylons/pyramid/pull/2838 + +- Add `pyramid_nacl_session + `_ + to session factories. See https://github.com/Pylons/pyramid/issues/2791 + +- Update ``HACKING.txt`` from stale branch that was never merged to master. + See https://github.com/Pylons/pyramid/pull/2782 + +- Updated Windows installation instructions and related bits. + See https://github.com/Pylons/pyramid/issues/2661 + +- Fix an inconsistency in the documentation between view predicates and + route predicates and highlight the differences in their APIs. + See https://github.com/Pylons/pyramid/pull/2764 + +- Clarify a possible misuse of the ``headers`` kwarg to subclasses of + ``pyramid.httpexceptions.HTTPException`` in which more appropriate + kwargs from the parent class ``pyramid.response.Response`` should be + used instead. See https://github.com/Pylons/pyramid/pull/2750 + +- The SQLAlchemy + URL Dispatch + Jinja2 (``wiki2``) and + ZODB + Traversal + Chameleon (``wiki``) tutorials have been updated to + utilize the new cookiecutters and drop support for the ``pcreate`` + scaffolds. + + See https://github.com/Pylons/pyramid/pull/2881 and + https://github.com/Pylons/pyramid/pull/2883. + +- Improve output of p* script descriptions for help. + See https://github.com/Pylons/pyramid/pull/2886 + +- Quick Tour updated to use cookiecutters instead of pcreate and scaffolds. + See https://github.com/Pylons/pyramid/pull/2888 + +1.7 (2016-05-19) +================ + +- Fix a bug in the wiki2 tutorial where bcrypt is always expecting byte + strings. See https://github.com/Pylons/pyramid/pull/2576 + +- Simplify windows detection code and remove some duplicated data. + See https://github.com/Pylons/pyramid/pull/2585 and + https://github.com/Pylons/pyramid/pull/2586 + +1.7b4 (2016-05-12) +================== + +- Fixed the exception view tween to re-raise the original exception if + no exception view could be found to handle the exception. This better + allows tweens further up the chain to handle exceptions that were + left unhandled. Previously they would be converted into a + ``PredicateMismatch`` exception if predicates failed to allow the view to + handle the exception. + See https://github.com/Pylons/pyramid/pull/2567 + +- Exposed the ``pyramid.interfaces.IRequestFactory`` interface to mirror + the public ``pyramid.interfaces.IResponseFactory`` interface. + +1.7b3 (2016-05-10) +================== + +- Fix ``request.invoke_exception_view`` to raise an ``HTTPNotFound`` + exception if no view is matched. Previously ``None`` would be returned + if no views were matched and a ``PredicateMismatch`` would be raised if + a view "almost" matched (a view was found matching the context). + See https://github.com/Pylons/pyramid/pull/2564 + +- Add defaults for py.test configuration and coverage to all three scaffolds, + and update documentation accordingly. + See https://github.com/Pylons/pyramid/pull/2550 + +- Add ``linkcheck`` to ``Makefile`` for Sphinx. To check the documentation for + broken links, use the command ``make linkcheck + SPHINXBUILD=$VENV/bin/sphinx-build``. Also removed and fixed dozens of broken + external links. + +- Fix the internal runner for scaffold tests to ensure they work with pip + and py.test. + See https://github.com/Pylons/pyramid/pull/2565 + +1.7b2 (2016-05-01) +================== + +- Removed inclusion of pyramid_tm in development.ini for alchemy scaffold + See https://github.com/Pylons/pyramid/issues/2538 + +- A default permission set via ``config.set_default_permission`` will no + longer be enforced on an exception view. This has been the case for a while + with the default exception views (``config.add_notfound_view`` and + ``config.add_forbidden_view``), however for any other exception view a + developer had to remember to set ``permission=NO_PERMISSION_REQUIRED`` or + be surprised when things didn't work. It is still possible to force a + permission check on an exception view by setting the ``permission`` argument + manually to ``config.add_view``. This behavior is consistent with the new + CSRF features added in the 1.7 series. + See https://github.com/Pylons/pyramid/pull/2534 + +1.7b1 (2016-04-25) +================== + +- This release announces the beta period for 1.7. + +- Fix an issue where some files were being included in the alchemy scafffold + which had been removed from the 1.7 series. + See https://github.com/Pylons/pyramid/issues/2525 + +1.7a2 (2016-04-19) +================== + +Features +-------- + +- Automatic CSRF checks are now disabled by default on exception views. They + can be turned back on by setting the appropriate `require_csrf` option on + the view. + See https://github.com/Pylons/pyramid/pull/2517 + +- The automatic CSRF API was reworked to use a config directive for + setting the options. The ``pyramid.require_default_csrf`` setting is + no longer supported. Instead, a new ``config.set_default_csrf_options`` + directive has been introduced that allows the developer to specify + the default value for ``require_csrf`` as well as change the CSRF token, + header and safe request methods. The ``pyramid.csrf_trusted_origins`` + setting is still supported. + See https://github.com/Pylons/pyramid/pull/2518 + +Bug fixes +--------- + +- CSRF origin checks had a bug causing the checks to always fail. + See https://github.com/Pylons/pyramid/pull/2512 + +- Fix the test suite to pass on windows. + See https://github.com/Pylons/pyramid/pull/2520 + +1.7a1 (2016-04-16) +================== + +Backward Incompatibilities +-------------------------- + +- Following the Pyramid deprecation period (1.4 -> 1.6), + AuthTktAuthenticationPolicy's default hashing algorithm is changing from md5 + to sha512. If you are using the authentication policy and need to continue + using md5, please explicitly set hashalg to 'md5'. + + This change does mean that any existing auth tickets (and associated cookies) + will no longer be valid, and users will no longer be logged in, and have to + login to their accounts again. + + See https://github.com/Pylons/pyramid/pull/2496 + +- The ``check_csrf_token`` function no longer validates a csrf token in the + query string of a request. Only headers and request bodies are supported. + See https://github.com/Pylons/pyramid/pull/2500 + +Features +-------- + +- Added a new setting, ``pyramid.require_default_csrf`` which may be used + to turn on CSRF checks globally for every POST request in the application. + This should be considered a good default for websites built on Pyramid. + It is possible to opt-out of CSRF checks on a per-view basis by setting + ``require_csrf=False`` on those views. + See https://github.com/Pylons/pyramid/pull/2413 + +- Added a ``require_csrf`` view option which will enforce CSRF checks on any + request with an unsafe method as defined by RFC2616. If the CSRF check fails + a ``BadCSRFToken`` exception will be raised and may be caught by exception + views (the default response is a ``400 Bad Request``). This option should be + used in place of the deprecated ``check_csrf`` view predicate which would + normally result in unexpected ``404 Not Found`` response to the client + instead of a catchable exception. See + https://github.com/Pylons/pyramid/pull/2413 and + https://github.com/Pylons/pyramid/pull/2500 + +- Added an additional CSRF validation that checks the origin/referrer of a + request and makes sure it matches the current ``request.domain``. This + particular check is only active when accessing a site over HTTPS as otherwise + browsers don't always send the required information. If this additional CSRF + validation fails a ``BadCSRFOrigin`` exception will be raised and may be + caught by exception views (the default response is ``400 Bad Request``). + Additional allowed origins may be configured by setting + ``pyramid.csrf_trusted_origins`` to a list of domain names (with ports if on + a non standard port) to allow. Subdomains are not allowed unless the domain + name has been prefixed with a ``.``. See + https://github.com/Pylons/pyramid/pull/2501 + +- Added a new ``pyramid.session.check_csrf_origin`` API for validating the + origin or referrer headers against the request's domain. + See https://github.com/Pylons/pyramid/pull/2501 + +- Pyramid HTTPExceptions will now take into account the best match for the + clients Accept header, and depending on what is requested will return + text/html, application/json or text/plain. The default for */* is still + text/html, but if application/json is explicitly mentioned it will now + receive a valid JSON response. See + https://github.com/Pylons/pyramid/pull/2489 + +- A new event and interface (BeforeTraversal) has been introduced that will + notify listeners before traversal starts in the router. See + https://github.com/Pylons/pyramid/pull/2469 and + https://github.com/Pylons/pyramid/pull/1876 + +- Add a new "view deriver" concept to Pyramid to allow framework authors to + inject elements into the standard Pyramid view pipeline and affect all + views in an application. This is similar to a decorator except that it + has access to options passed to ``config.add_view`` and can affect other + stages of the pipeline such as the raw response from a view or prior to + security checks. See https://github.com/Pylons/pyramid/pull/2021 + +- Allow a leading ``=`` on the key of the request param predicate. + For example, '=abc=1' is equivalent down to + ``request.params['=abc'] == '1'``. + See https://github.com/Pylons/pyramid/pull/1370 + +- A new ``request.invoke_exception_view(...)`` method which can be used to + invoke an exception view and get back a response. This is useful for + rendering an exception view outside of the context of the excview tween + where you may need more control over the request. + See https://github.com/Pylons/pyramid/pull/2393 + +- Allow using variable substitutions like ``%(LOGGING_LOGGER_ROOT_LEVEL)s`` + for logging sections of the .ini file and populate these variables from + the ``pserve`` command line -- e.g.: + ``pserve development.ini LOGGING_LOGGER_ROOT_LEVEL=DEBUG`` + See https://github.com/Pylons/pyramid/pull/2399 + +Documentation Changes +--------------------- + +- A complete overhaul of the docs: + + - Use pip instead of easy_install. + - Become opinionated by preferring Python 3.4 or greater to simplify + installation of Python and its required packaging tools. + - Use venv for the tool, and virtual environment for the thing created, + instead of virtualenv. + - Use py.test and pytest-cov instead of nose and coverage. + - Further updates to the scaffolds as well as tutorials and their src files. + + See https://github.com/Pylons/pyramid/pull/2468 + +- A complete overhaul of the ``alchemy`` scaffold as well as the + Wiki2 SQLAlchemy + URLDispatch tutorial to introduce more modern features + into the usage of SQLAlchemy with Pyramid and provide a better starting + point for new projects. + See https://github.com/Pylons/pyramid/pull/2024 + +Bug Fixes +--------- + +- Fix ``pserve --browser`` to use the ``--server-name`` instead of the + app name when selecting a section to use. This was only working for people + who had server and app sections with the same name, for example + ``[app:main]`` and ``[server:main]``. + See https://github.com/Pylons/pyramid/pull/2292 + +Deprecations +------------ + +- The ``check_csrf`` view predicate has been deprecated. Use the + new ``require_csrf`` option or the ``pyramid.require_default_csrf`` setting + to ensure that the ``BadCSRFToken`` exception is raised. + See https://github.com/Pylons/pyramid/pull/2413 + +- Support for Python 3.3 will be removed in Pyramid 1.8. + https://github.com/Pylons/pyramid/issues/2477 + +- Python 2.6 is no longer supported by Pyramid. See + https://github.com/Pylons/pyramid/issues/2368 + +- Dropped Python 3.2 support. + See https://github.com/Pylons/pyramid/pull/2256 + +1.6 (2016-01-03) +================ + +Deprecations +------------ + +- Continue removal of ``pserve`` daemon/process management features + by deprecating ``--user`` and ``--group`` options. + See https://github.com/Pylons/pyramid/pull/2190 + +1.6b3 (2015-12-17) +================== + +Backward Incompatibilities +-------------------------- + +- Remove the ``cachebust`` option from ``config.add_static_view``. See + ``config.add_cache_buster`` for the new way to attach cache busters to + static assets. + See https://github.com/Pylons/pyramid/pull/2186 + +- Modify the ``pyramid.interfaces.ICacheBuster`` API to be a simple callable + instead of an object with ``match`` and ``pregenerate`` methods. Cache + busters are now focused solely on generation. Matching has been dropped. + + Note this affects usage of ``pyramid.static.QueryStringCacheBuster`` and + ``pyramid.static.ManifestCacheBuster``. + + See https://github.com/Pylons/pyramid/pull/2186 + +Features +-------- + +- Add a new ``config.add_cache_buster`` API for attaching cache busters to + static assets. See https://github.com/Pylons/pyramid/pull/2186 + +Bug Fixes +--------- + +- Ensure that ``IAssetDescriptor.abspath`` always returns an absolute path. + There were cases depending on the process CWD that a relative path would + be returned. See https://github.com/Pylons/pyramid/issues/2188 + +1.6b2 (2015-10-15) +================== + +Features +-------- + +- Allow asset specifications to be supplied to + ``pyramid.static.ManifestCacheBuster`` instead of requiring a + filesystem path. + +1.6b1 (2015-10-15) +================== + +Backward Incompatibilities +-------------------------- + +- IPython and BPython support have been removed from pshell in the core. + To continue using them on Pyramid 1.6+ you must install the binding + packages explicitly:: + + $ pip install pyramid_ipython + + or + + $ pip install pyramid_bpython + +- Remove default cache busters introduced in 1.6a1 including + ``PathSegmentCacheBuster``, ``PathSegmentMd5CacheBuster``, and + ``QueryStringMd5CacheBuster``. + See https://github.com/Pylons/pyramid/pull/2116 + +Features +-------- + +- Additional shells for ``pshell`` can now be registered as entrypoints. See + https://github.com/Pylons/pyramid/pull/1891 and + https://github.com/Pylons/pyramid/pull/2012 + +- The variables injected into ``pshell`` are now displayed with their + docstrings instead of the default ``str(obj)`` when possible. + See https://github.com/Pylons/pyramid/pull/1929 + +- Add new ``pyramid.static.ManifestCacheBuster`` for use with external + asset pipelines as well as examples of common usages in the narrative. + See https://github.com/Pylons/pyramid/pull/2116 + +- Fix ``pserve --reload`` to not crash on syntax errors!!! + See https://github.com/Pylons/pyramid/pull/2125 + +- Fix an issue when user passes unparsed strings to ``pyramid.session.CookieSession`` + and ``pyramid.authentication.AuthTktCookieHelper`` for time related parameters + ``timeout``, ``reissue_time``, ``max_age`` that expect an integer value. + See https://github.com/Pylons/pyramid/pull/2050 + +Bug Fixes +--------- + +- ``pyramid.httpexceptions.HTTPException`` now defaults to + ``520 Unknown Error`` instead of ``None None`` to conform with changes in + WebOb 1.5. + See https://github.com/Pylons/pyramid/pull/1865 + +- ``pshell`` will now preserve the capitalization of variables in the + ``[pshell]`` section of the INI file. This makes exposing classes to the + shell a little more straightfoward. + See https://github.com/Pylons/pyramid/pull/1883 + +- Fixed usage of ``pserve --monitor-restart --daemon`` which would fail in + horrible ways. See https://github.com/Pylons/pyramid/pull/2118 + +- Explicitly prevent ``pserve --reload --daemon`` from being used. It's never + been supported but would work and fail in weird ways. + See https://github.com/Pylons/pyramid/pull/2119 + +- Fix an issue on Windows when running ``pserve --reload`` in which the + process failed to fork because it could not find the pserve script to + run. See https://github.com/Pylons/pyramid/pull/2138 + +Deprecations +------------ + +- Deprecate ``pserve --monitor-restart`` in favor of user's using a real + process manager such as Systemd or Upstart as well as Python-based + solutions like Circus and Supervisor. + See https://github.com/Pylons/pyramid/pull/2120 + +1.6a2 (2015-06-30) +================== + +Bug Fixes +--------- + +- Ensure that ``pyramid.httpexceptions.exception_response`` returns the + appropriate "concrete" class for ``400`` and ``500`` status codes. + See https://github.com/Pylons/pyramid/issues/1832 + +- Fix an infinite recursion bug introduced in 1.6a1 when + ``pyramid.view.render_view_to_response`` was called directly or indirectly. + See https://github.com/Pylons/pyramid/issues/1643 + +- Further fix the JSONP renderer by prefixing the returned content with + a comment. This should mitigate attacks from Flash (See CVE-2014-4671). + See https://github.com/Pylons/pyramid/pull/1649 + +- Allow periods and brackets (``[]``) in the JSONP callback. The original + fix was overly-restrictive and broke Angular. + See https://github.com/Pylons/pyramid/pull/1649 + +1.6a1 (2015-04-15) +================== + +Features +-------- + +- pcreate will now ask for confirmation if invoked with + an argument for a project name that already exists or + is importable in the current environment. + See https://github.com/Pylons/pyramid/issues/1357 and + https://github.com/Pylons/pyramid/pull/1837 + +- Make it possible to subclass ``pyramid.request.Request`` and also use + ``pyramid.request.Request.add_request.method``. See + https://github.com/Pylons/pyramid/issues/1529 + +- The ``pyramid.config.Configurator`` has grown the ability to allow + actions to call other actions during a commit-cycle. This enables much more + logic to be placed into actions, such as the ability to invoke other actions + or group them for improved conflict detection. We have also exposed and + documented the config phases that Pyramid uses in order to further assist + in building conforming addons. + See https://github.com/Pylons/pyramid/pull/1513 + +- Add ``pyramid.request.apply_request_extensions`` function which can be + used in testing to apply any request extensions configured via + ``config.add_request_method``. Previously it was only possible to test + the extensions by going through Pyramid's router. + See https://github.com/Pylons/pyramid/pull/1581 + +- pcreate when run without a scaffold argument will now print information on + the missing flag, as well as a list of available scaffolds. + See https://github.com/Pylons/pyramid/pull/1566 and + https://github.com/Pylons/pyramid/issues/1297 + +- Added support / testing for 'pypy3' under Tox and Travis. + See https://github.com/Pylons/pyramid/pull/1469 + +- Automate code coverage metrics across py2 and py3 instead of just py2. + See https://github.com/Pylons/pyramid/pull/1471 + +- Cache busting for static resources has been added and is available via a new + argument to ``pyramid.config.Configurator.add_static_view``: ``cachebust``. + Core APIs are shipped for both cache busting via query strings and + path segments and may be extended to fit into custom asset pipelines. + See https://github.com/Pylons/pyramid/pull/1380 and + https://github.com/Pylons/pyramid/pull/1583 + +- Add ``pyramid.config.Configurator.root_package`` attribute and init + parameter to assist with includeable packages that wish to resolve + resources relative to the package in which the ``Configurator`` was created. + This is especially useful for addons that need to load asset specs from + settings, in which case it is may be natural for a developer to define + imports or assets relative to the top-level package. + See https://github.com/Pylons/pyramid/pull/1337 + +- Added line numbers to the log formatters in the scaffolds to assist with + debugging. See https://github.com/Pylons/pyramid/pull/1326 + +- Add new HTTP exception objects for status codes + ``428 Precondition Required``, ``429 Too Many Requests`` and + ``431 Request Header Fields Too Large`` in ``pyramid.httpexceptions``. + See https://github.com/Pylons/pyramid/pull/1372/files + +- The ``pshell`` script will now load a ``PYTHONSTARTUP`` file if one is + defined in the environment prior to launching the interpreter. + See https://github.com/Pylons/pyramid/pull/1448 + +- Make it simple to define notfound and forbidden views that wish to use + the default exception-response view but with altered predicates and other + configuration options. The ``view`` argument is now optional in + ``config.add_notfound_view`` and ``config.add_forbidden_view``.. + See https://github.com/Pylons/pyramid/issues/494 + +- Greatly improve the readability of the ``pcreate`` shell script output. + See https://github.com/Pylons/pyramid/pull/1453 + +- Improve robustness to timing attacks in the ``AuthTktCookieHelper`` and + the ``SignedCookieSessionFactory`` classes by using the stdlib's + ``hmac.compare_digest`` if it is available (such as Python 2.7.7+ and 3.3+). + See https://github.com/Pylons/pyramid/pull/1457 + +- Assets can now be overidden by an absolute path on the filesystem when using + the ``config.override_asset`` API. This makes it possible to fully support + serving up static content from a mutable directory while still being able + to use the ``request.static_url`` API and ``config.add_static_view``. + Previously it was not possible to use ``config.add_static_view`` with an + absolute path **and** generate urls to the content. This change replaces + the call, ``config.add_static_view('/abs/path', 'static')``, with + ``config.add_static_view('myapp:static', 'static')`` and + ``config.override_asset(to_override='myapp:static/', + override_with='/abs/path/')``. The ``myapp:static`` asset spec is completely + made up and does not need to exist - it is used for generating urls + via ``request.static_url('myapp:static/foo.png')``. + See https://github.com/Pylons/pyramid/issues/1252 + +- Added ``pyramid.config.Configurator.set_response_factory`` and the + ``response_factory`` keyword argument to the ``Configurator`` for defining + a factory that will return a custom ``Response`` class. + See https://github.com/Pylons/pyramid/pull/1499 + +- Allow an iterator to be returned from a renderer. Previously it was only + possible to return bytes or unicode. + See https://github.com/Pylons/pyramid/pull/1417 + +- ``pserve`` can now take a ``-b`` or ``--browser`` option to open the server + URL in a web browser. See https://github.com/Pylons/pyramid/pull/1533 + +- Overall improvments for the ``proutes`` command. Added ``--format`` and + ``--glob`` arguments to the command, introduced the ``method`` + column for displaying available request methods, and improved the ``view`` + output by showing the module instead of just ``__repr__``. + See https://github.com/Pylons/pyramid/pull/1488 + +- Support keyword-only arguments and function annotations in views in + Python 3. See https://github.com/Pylons/pyramid/pull/1556 + +- ``request.response`` will no longer be mutated when using the + ``pyramid.renderers.render_to_response()`` API. It is now necessary to + pass in a ``response=`` argument to ``render_to_response`` if you wish to + supply the renderer with a custom response object for it to use. If you + do not pass one then a response object will be created using the + application's ``IResponseFactory``. Almost all renderers + mutate the ``request.response`` response object (for example, the JSON + renderer sets ``request.response.content_type`` to ``application/json``). + However, when invoking ``render_to_response`` it is not expected that the + response object being returned would be the same one used later in the + request. The response object returned from ``render_to_response`` is now + explicitly different from ``request.response``. This does not change the + API of a renderer. See https://github.com/Pylons/pyramid/pull/1563 + +- The ``append_slash`` argument of ```Configurator().add_notfound_view()`` will + now accept anything that implements the ``IResponse`` interface and will use + that as the response class instead of the default ``HTTPFound``. See + https://github.com/Pylons/pyramid/pull/1610 + +Bug Fixes +--------- + +- The JSONP renderer created JavaScript code in such a way that a callback + variable could be used to arbitrarily inject javascript into the response + object. https://github.com/Pylons/pyramid/pull/1627 + +- Work around an issue where ``pserve --reload`` would leave terminal echo + disabled if it reloaded during a pdb session. + See https://github.com/Pylons/pyramid/pull/1577, + https://github.com/Pylons/pyramid/pull/1592 + +- ``pyramid.wsgi.wsgiapp`` and ``pyramid.wsgi.wsgiapp2`` now raise + ``ValueError`` when accidentally passed ``None``. + See https://github.com/Pylons/pyramid/pull/1320 + +- Fix an issue whereby predicates would be resolved as maybe_dotted in the + introspectable but not when passed for registration. This would mean that + ``add_route_predicate`` for example can not take a string and turn it into + the actual callable function. + See https://github.com/Pylons/pyramid/pull/1306 + +- Fix ``pyramid.testing.setUp`` to return a ``Configurator`` with a proper + package. Previously it was not possible to do package-relative includes + using the returned ``Configurator`` during testing. There is now a + ``package`` argument that can override this behavior as well. + See https://github.com/Pylons/pyramid/pull/1322 + +- Fix an issue where a ``pyramid.response.FileResponse`` may apply a charset + where it does not belong. See https://github.com/Pylons/pyramid/pull/1251 + +- Work around a bug introduced in Python 2.7.7 on Windows where + ``mimetypes.guess_type`` returns Unicode rather than str for the content + type, unlike any previous version of Python. See + https://github.com/Pylons/pyramid/issues/1360 for more information. + +- ``pcreate`` now normalizes the package name by converting hyphens to + underscores. See https://github.com/Pylons/pyramid/pull/1376 + +- Fix an issue with the final response/finished callback being unable to + add another callback to the list. See + https://github.com/Pylons/pyramid/pull/1373 + +- Fix a failing unittest caused by differing mimetypes across various OSs. + See https://github.com/Pylons/pyramid/issues/1405 + +- Fix route generation for static view asset specifications having no path. + See https://github.com/Pylons/pyramid/pull/1377 + +- Allow the ``pyramid.renderers.JSONP`` renderer to work even if there is no + valid request object. In this case it will not wrap the object in a + callback and thus behave just like the ``pyramid.renderers.JSON`` renderer. + See https://github.com/Pylons/pyramid/pull/1561 + +- Prevent "parameters to load are deprecated" ``DeprecationWarning`` + from setuptools>=11.3. See https://github.com/Pylons/pyramid/pull/1541 + +- Avoiding sharing the ``IRenderer`` objects across threads when attached to + a view using the `renderer=` argument. These renderers were instantiated + at time of first render and shared between requests, causing potentially + subtle effects like `pyramid.reload_templates = true` failing to work + in `pyramid_mako`. See https://github.com/Pylons/pyramid/pull/1575 + and https://github.com/Pylons/pyramid/issues/1268 + +- Avoiding timing attacks against CSRF tokens. + See https://github.com/Pylons/pyramid/pull/1574 + +- ``request.finished_callbacks`` and ``request.response_callbacks`` now + default to an iterable instead of ``None``. It may be checked for a length + of 0. This was the behavior in 1.5. + +Deprecations +------------ + +- The ``pserve`` command's daemonization features have been deprecated. This + includes the ``[start,stop,restart,status]`` subcommands as well as the + ``--daemon``, ``--stop-server``, ``--pid-file``, and ``--status`` flags. + + Please use a real process manager in the future instead of relying on the + ``pserve`` to daemonize itself. Many options exist including your Operating + System's services such as Systemd or Upstart, as well as Python-based + solutions like Circus and Supervisor. + + See https://github.com/Pylons/pyramid/pull/1641 + +- Renamed the ``principal`` argument to ``pyramid.security.remember()`` to + ``userid`` in order to clarify its intended purpose. + See https://github.com/Pylons/pyramid/pull/1399 + +Docs +---- + +- Moved the documentation for ``accept`` on ``Configurator.add_view`` to no + longer be part of the predicate list. See + https://github.com/Pylons/pyramid/issues/1391 for a bug report stating + ``not_`` was failing on ``accept``. Discussion with @mcdonc led to the + conclusion that it should not be documented as a predicate. + See https://github.com/Pylons/pyramid/pull/1487 for this PR + +- Removed logging configuration from Quick Tutorial ini files except for + scaffolding- and logging-related chapters to avoid needing to explain it too + early. + +- Clarify a previously-implied detail of the ``ISession.invalidate`` API + documentation. + +- Improve and clarify the documentation on what Pyramid defines as a + ``principal`` and a ``userid`` in its security APIs. + See https://github.com/Pylons/pyramid/pull/1399 + +- Add documentation of command line programs (``p*`` scripts). See + https://github.com/Pylons/pyramid/pull/2191 + +Scaffolds +--------- + +- Update scaffold generating machinery to return the version of pyramid and + pyramid docs for use in scaffolds. Updated starter, alchemy and zodb + templates to have links to correctly versioned documentation and reflect + which pyramid was used to generate the scaffold. + +- Removed non-ascii copyright symbol from templates, as this was + causing the scaffolds to fail for project generation. + +- You can now run the scaffolding func tests via ``tox py2-scaffolds`` and + ``tox py3-scaffolds``. + + +1.5 (2014-04-08) +================ + +- Python 3.4 compatibility. + +- Avoid crash in ``pserve --reload`` under Py3k, when iterating over possibly + mutated ``sys.modules``. + +- ``UnencryptedCookieSessionFactoryConfig`` failed if the secret contained + higher order characters. See https://github.com/Pylons/pyramid/issues/1246 + +- Fixed a bug in ``UnencryptedCookieSessionFactoryConfig`` and + ``SignedCookieSessionFactory`` where ``timeout=None`` would cause a new + session to always be created. Also in ``SignedCookieSessionFactory`` a + ``reissue_time=None`` would cause an exception when modifying the session. + See https://github.com/Pylons/pyramid/issues/1247 + +- Updated docs and scaffolds to keep in step with new 2.0 release of + ``Lingua``. This included removing all ``setup.cfg`` files from scaffolds + and documentation environments. + +1.5b1 (2014-02-08) +================== + +Features +-------- + +- We no longer eagerly clear ``request.exception`` and ``request.exc_info`` in + the exception view tween. This makes it possible to inspect exception + information within a finished callback. See + https://github.com/Pylons/pyramid/issues/1223. + +1.5a4 (2014-01-28) +================== + +Features +-------- + +- Updated scaffolds with new theme, fixed documentation and sample project. + +Bug Fixes +--------- + +- Depend on a newer version of WebOb so that we pull in some crucial bug-fixes + that were showstoppers for functionality in Pyramid. + +- Add a trailing semicolon to the JSONP response. This fixes JavaScript syntax + errors for old IE versions. See https://github.com/Pylons/pyramid/pull/1205 + +- Fix a memory leak when the configurator's ``set_request_property`` method was + used or when the configurator's ``add_request_method`` method was used with + the ``property=True`` attribute. See + https://github.com/Pylons/pyramid/issues/1212 . + +1.5a3 (2013-12-10) +================== + +Features +-------- + +- An authorization API has been added as a method of the + request: ``request.has_permission``. + + ``request.has_permission`` is a method-based alternative to the + ``pyramid.security.has_permission`` API and works exactly the same. The + older API is now deprecated. + +- Property API attributes have been added to the request for easier access to + authentication data: ``request.authenticated_userid``, + ``request.unauthenticated_userid``, and ``request.effective_principals``. + + These are analogues, respectively, of + ``pyramid.security.authenticated_userid``, + ``pyramid.security.unauthenticated_userid``, and + ``pyramid.security.effective_principals``. They operate exactly the same, + except they are attributes of the request instead of functions accepting a + request. They are properties, so they cannot be assigned to. The older + function-based APIs are now deprecated. + +- Pyramid's console scripts (``pserve``, ``pviews``, etc) can now be run + directly, allowing custom arguments to be sent to the python interpreter + at runtime. For example:: + + python -3 -m pyramid.scripts.pserve development.ini + +- Added a specific subclass of ``HTTPBadRequest`` named + ``pyramid.exceptions.BadCSRFToken`` which will now be raised in response + to failures in ``check_csrf_token``. + See https://github.com/Pylons/pyramid/pull/1149 + +- Added a new ``SignedCookieSessionFactory`` which is very similar to the + ``UnencryptedCookieSessionFactoryConfig`` but with a clearer focus on signing + content. The custom serializer arguments to this function should only focus + on serializing, unlike its predecessor which required the serializer to also + perform signing. See https://github.com/Pylons/pyramid/pull/1142 . Note + that cookies generated using ``SignedCookieSessionFactory`` are not + compatible with cookies generated using ``UnencryptedCookieSessionFactory``, + so existing user session data will be destroyed if you switch to it. + +- Added a new ``BaseCookieSessionFactory`` which acts as a generic cookie + factory that can be used by framework implementors to create their own + session implementations. It provides a reusable API which focuses strictly + on providing a dictionary-like object that properly handles renewals, + timeouts, and conformance with the ``ISession`` API. + See https://github.com/Pylons/pyramid/pull/1142 + +- The anchor argument to ``pyramid.request.Request.route_url`` and + ``pyramid.request.Request.resource_url`` and their derivatives will now be + escaped via URL quoting to ensure minimal conformance. See + https://github.com/Pylons/pyramid/pull/1183 + +- Allow sending of ``_query`` and ``_anchor`` options to + ``pyramid.request.Request.static_url`` when an external URL is being + generated. + See https://github.com/Pylons/pyramid/pull/1183 + +- You can now send a string as the ``_query`` argument to + ``pyramid.request.Request.route_url`` and + ``pyramid.request.Request.resource_url`` and their derivatives. When a + string is sent instead of a list or dictionary. it is URL-quoted however it + does not need to be in ``k=v`` form. This is useful if you want to be able + to use a different query string format than ``x-www-form-urlencoded``. See + https://github.com/Pylons/pyramid/pull/1183 + +- ``pyramid.testing.DummyRequest`` now has a ``domain`` attribute to match the + new WebOb 1.3 API. Its value is ``example.com``. + +Bug Fixes +--------- + +- Fix the ``pcreate`` script so that when the target directory name ends with a + slash it does not produce a non-working project directory structure. + Previously saying ``pcreate -s starter /foo/bar/`` produced different output + than saying ``pcreate -s starter /foo/bar``. The former did not work + properly. + +- Fix the ``principals_allowed_by_permission`` method of + ``ACLAuthorizationPolicy`` so it anticipates a callable ``__acl__`` + on resources. Previously it did not try to call the ``__acl__`` + if it was callable. + +- The ``pviews`` script did not work when a url required custom request + methods in order to perform traversal. Custom methods and descriptors added + via ``pyramid.config.Configurator.add_request_method`` will now be present, + allowing traversal to continue. + See https://github.com/Pylons/pyramid/issues/1104 + +- Remove unused ``renderer`` argument from ``Configurator.add_route``. + +- Allow the ``BasicAuthenticationPolicy`` to work with non-ascii usernames + and passwords. The charset is not passed as part of the header and different + browsers alternate between UTF-8 and Latin-1, so the policy now attempts + to decode with UTF-8 first, and will fallback to Latin-1. + See https://github.com/Pylons/pyramid/pull/1170 + +- The ``@view_defaults`` now apply to notfound and forbidden views + that are defined as methods of a decorated class. + See https://github.com/Pylons/pyramid/issues/1173 + +Documentation +------------- + +- Added a "Quick Tutorial" to go with the Quick Tour + +- Removed mention of ``pyramid_beaker`` from docs. Beaker is no longer + maintained. Point people at ``pyramid_redis_sessions`` instead. + +- Add documentation for ``pyramid.interfaces.IRendererFactory`` and + ``pyramid.interfaces.IRenderer``. + +Backwards Incompatibilities +--------------------------- + +- The key/values in the ``_query`` parameter of ``request.route_url`` and the + ``query`` parameter of ``request.resource_url`` (and their variants), used + to encode a value of ``None`` as the string ``'None'``, leaving the resulting + query string to be ``a=b&key=None``. The value is now dropped in this + situation, leaving a query string of ``a=b&key=``. + See https://github.com/Pylons/pyramid/issues/1119 + +Deprecations +------------ + +- Deprecate the ``pyramid.interfaces.ITemplateRenderer`` interface. It was + ill-defined and became unused when Mako and Chameleon template bindings were + split into their own packages. + +- The ``pyramid.session.UnencryptedCookieSessionFactoryConfig`` API has been + deprecated and is superseded by the + ``pyramid.session.SignedCookieSessionFactory``. Note that while the cookies + generated by the ``UnencryptedCookieSessionFactoryConfig`` + are compatible with cookies generated by old releases, cookies generated by + the SignedCookieSessionFactory are not. See + https://github.com/Pylons/pyramid/pull/1142 + +- The ``pyramid.security.has_permission`` API is now deprecated. Instead, use + the newly-added ``has_permission`` method of the request object. + +- The ``pyramid.security.effective_principals`` API is now deprecated. + Instead, use the newly-added ``effective_principals`` attribute of the + request object. + +- The ``pyramid.security.authenticated_userid`` API is now deprecated. + Instead, use the newly-added ``authenticated_userid`` attribute of the + request object. + +- The ``pyramid.security.unauthenticated_userid`` API is now deprecated. + Instead, use the newly-added ``unauthenticated_userid`` attribute of the + request object. + +Dependencies +------------ + +- Pyramid now depends on WebOb>=1.3 (it uses ``webob.cookies.CookieProfile`` + from 1.3+). + +1.5a2 (2013-09-22) +================== + +Features +-------- + +- Users can now provide dotted Python names to as the ``factory`` argument + the Configurator methods named ``add_{view,route,subscriber}_predicate`` + (instead of passing the predicate factory directly, you can pass a + dotted name which refers to the factory). + +Bug Fixes +--------- + +- Fix an exception in ``pyramid.path.package_name`` when resolving the package + name for namespace packages that had no ``__file__`` attribute. + +Backwards Incompatibilities +--------------------------- + +- Pyramid no longer depends on or configures the Mako and Chameleon templating + system renderers by default. Disincluding these templating systems by + default means that the Pyramid core has fewer dependencies and can run on + future platforms without immediate concern for the compatibility of its + templating add-ons. It also makes maintenance slightly more effective, as + different people can maintain the templating system add-ons that they + understand and care about without needing commit access to the Pyramid core, + and it allows users who just don't want to see any packages they don't use + come along for the ride when they install Pyramid. + + This means that upon upgrading to Pyramid 1.5a2+, projects that use either + of these templating systems will see a traceback that ends something like + this when their application attempts to render a Chameleon or Mako template:: + + ValueError: No such renderer factory .pt + + Or:: + + ValueError: No such renderer factory .mako + + Or:: + + ValueError: No such renderer factory .mak + + Support for Mako templating has been moved into an add-on package named + ``pyramid_mako``, and support for Chameleon templating has been moved into + an add-on package named ``pyramid_chameleon``. These packages are drop-in + replacements for the old built-in support for these templating langauges. + All you have to do is install them and make them active in your configuration + to register renderer factories for ``.pt`` and/or ``.mako`` (or ``.mak``) to + make your application work again. + + To re-add support for Chameleon and/or Mako template renderers into your + existing projects, follow the below steps. + + If you depend on Mako templates: + + * Make sure the ``pyramid_mako`` package is installed. One way to do this + is by adding ``pyramid_mako`` to the ``install_requires`` section of your + package's ``setup.py`` file and afterwards rerunning ``setup.py develop``:: + + setup( + #... + install_requires=[ + 'pyramid_mako', # new dependency + 'pyramid', + #... + ], + ) + + * Within the portion of your application which instantiates a Pyramid + ``pyramid.config.Configurator`` (often the ``main()`` function in + your project's ``__init__.py`` file), tell Pyramid to include the + ``pyramid_mako`` includeme:: + + config = Configurator(.....) + config.include('pyramid_mako') + + If you depend on Chameleon templates: + + * Make sure the ``pyramid_chameleon`` package is installed. One way to do + this is by adding ``pyramid_chameleon`` to the ``install_requires`` section + of your package's ``setup.py`` file and afterwards rerunning + ``setup.py develop``:: + + setup( + #... + install_requires=[ + 'pyramid_chameleon', # new dependency + 'pyramid', + #... + ], + ) + + * Within the portion of your application which instantiates a Pyramid + ``~pyramid.config.Configurator`` (often the ``main()`` function in + your project's ``__init__.py`` file), tell Pyramid to include the + ``pyramid_chameleon`` includeme:: + + config = Configurator(.....) + config.include('pyramid_chameleon') + + Note that it's also fine to install these packages into *older* Pyramids for + forward compatibility purposes. Even if you don't upgrade to Pyramid 1.5 + immediately, performing the above steps in a Pyramid 1.4 installation is + perfectly fine, won't cause any difference, and will give you forward + compatibility when you eventually do upgrade to Pyramid 1.5. + + With the removal of Mako and Chameleon support from the core, some + unit tests that use the ``pyramid.renderers.render*`` methods may begin to + fail. If any of your unit tests are invoking either + ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response()`` + with either Mako or Chameleon templates then the + ``pyramid.config.Configurator`` instance in effect during + the unit test should be also be updated to include the addons, as shown + above. For example:: + + class ATest(unittest.TestCase): + def setUp(self): + self.config = pyramid.testing.setUp() + self.config.include('pyramid_mako') + + def test_it(self): + result = pyramid.renderers.render('mypkg:templates/home.mako', {}) + + Or:: + + class ATest(unittest.TestCase): + def setUp(self): + self.config = pyramid.testing.setUp() + self.config.include('pyramid_chameleon') + + def test_it(self): + result = pyramid.renderers.render('mypkg:templates/home.pt', {}) + +- If you're using the Pyramid debug toolbar, when you upgrade Pyramid to + 1.5a2+, you'll also need to upgrade the ``pyramid_debugtoolbar`` package to + at least version 1.0.8, as older toolbar versions are not compatible with + Pyramid 1.5a2+ due to the removal of Mako support from the core. It's + fine to use this newer version of the toolbar code with older Pyramids too. + +- Removed the ``request.response_*`` varying attributes. These attributes + have been deprecated since Pyramid 1.1, and as per the deprecation policy, + have now been removed. + +- ``request.response`` will no longer be mutated when using the + ``pyramid.renderers.render()`` API. Almost all renderers mutate the + ``request.response`` response object (for example, the JSON renderer sets + ``request.response.content_type`` to ``application/json``), but this is + only necessary when the renderer is generating a response; it was a bug + when it was done as a side effect of calling ``pyramid.renderers.render()``. + +- Removed the ``bfg2pyramid`` fixer script. + +- The ``pyramid.events.NewResponse`` event is now sent **after** response + callbacks are executed. It previously executed before response callbacks + were executed. Rationale: it's more useful to be able to inspect the response + after response callbacks have done their jobs instead of before. + +- Removed the class named ``pyramid.view.static`` that had been deprecated + since Pyramid 1.1. Instead use ``pyramid.static.static_view`` with + ``use_subpath=True`` argument. + +- Removed the ``pyramid.view.is_response`` function that had been deprecated + since Pyramid 1.1. Use the ``pyramid.request.Request.is_response`` method + instead. + +- Removed the ability to pass the following arguments to + ``pyramid.config.Configurator.add_route``: ``view``, ``view_context``. + ``view_for``, ``view_permission``, ``view_renderer``, and ``view_attr``. + Using these arguments had been deprecated since Pyramid 1.1. Instead of + passing view-related arguments to ``add_route``, use a separate call to + ``pyramid.config.Configurator.add_view`` to associate a view with a route + using its ``route_name`` argument. Note that this impacts the + ``pyramid.config.Configurator.add_static_view`` function too, because it + delegates to ``add_route``. + +- Removed the ability to influence and query a ``pyramid.request.Request`` + object as if it were a dictionary. Previously it was possible to use methods + like ``__getitem__``, ``get``, ``items``, and other dictlike methods to + access values in the WSGI environment. This behavior had been deprecated + since Pyramid 1.1. Use methods of ``request.environ`` (a real dictionary) + instead. + +- Removed ancient backwards compatibily hack in + ``pyramid.traversal.DefaultRootFactory`` which populated the ``__dict__`` of + the factory with the matchdict values for compatibility with BFG 0.9. + +- The ``renderer_globals_factory`` argument to the + ``pyramid.config.Configurator` constructor and its ``setup_registry`` method + has been removed. The ``set_renderer_globals_factory`` method of + ``pyramid.config.Configurator`` has also been removed. The (internal) + ``pyramid.interfaces.IRendererGlobals`` interface was also removed. These + arguments, methods and interfaces had been deprecated since 1.1. Use a + ``BeforeRender`` event subscriber as documented in the "Hooks" chapter of the + Pyramid narrative documentation instead of providing renderer globals values + to the configurator. + +Deprecations +------------ + +- The ``pyramid.config.Configurator.set_request_property`` method now issues + a deprecation warning when used. It had been docs-deprecated in 1.4 + but did not issue a deprecation warning when used. + +1.5a1 (2013-08-30) +================== + +Features +-------- + +- A new http exception subclass named ``pyramid.httpexceptions.HTTPSuccessful`` + was added. You can use this class as the ``context`` of an exception + view to catch all 200-series "exceptions" (e.g. "raise HTTPOk"). This + also allows you to catch *only* the ``HTTPOk`` exception itself; previously + this was impossible because a number of other exceptions + (such as ``HTTPNoContent``) inherited from ``HTTPOk``, but now they do not. + +- You can now generate "hybrid" urldispatch/traversal URLs more easily + by using the new ``route_name``, ``route_kw`` and ``route_remainder_name`` + arguments to ``request.resource_url`` and ``request.resource_path``. See + the new section of the "Combining Traversal and URL Dispatch" documentation + chapter entitled "Hybrid URL Generation". + +- It is now possible to escape double braces in Pyramid scaffolds (unescaped, + these represent replacement values). You can use ``\{\{a\}\}`` to + represent a "bare" ``{{a}}``. See + https://github.com/Pylons/pyramid/pull/862 + +- Add ``localizer`` and ``locale_name`` properties (reified) to the request. + See https://github.com/Pylons/pyramid/issues/508. Note that the + ``pyramid.i18n.get_localizer`` and ``pyramid.i18n.get_locale_name`` functions + now simply look up these properties on the request. + +- Add ``pdistreport`` script, which prints the Python version in use, the + Pyramid version in use, and the version number and location of all Python + distributions currently installed. + +- Add the ability to invert the result of any view, route, or subscriber + predicate using the ``not_`` class. For example:: + + from pyramid.config import not_ + + @view_config(route_name='myroute', request_method=not_('POST')) + def myview(request): ... + + The above example will ensure that the view is called if the request method + is not POST (at least if no other view is more specific). + + The ``pyramid.config.not_`` class can be used against any value that is + a predicate value passed in any of these contexts: + + - ``pyramid.config.Configurator.add_view`` + + - ``pyramid.config.Configurator.add_route`` + + - ``pyramid.config.Configurator.add_subscriber`` + + - ``pyramid.view.view_config`` + + - ``pyramid.events.subscriber`` + +- ``scripts/prequest.py``: add support for submitting ``PUT`` and ``PATCH`` + requests. See https://github.com/Pylons/pyramid/pull/1033. add support for + submitting ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify + basic authentication credentials in the request via a ``--login`` argument to + the script. See https://github.com/Pylons/pyramid/pull/1039. + +- ``ACLAuthorizationPolicy`` supports ``__acl__`` as a callable. This + removes the ambiguity between the potential ``AttributeError`` that would + be raised on the ``context`` when the property was not defined and the + ``AttributeError`` that could be raised from any user-defined code within + a dynamic property. It is recommended to define a dynamic ACL as a callable + to avoid this ambiguity. See https://github.com/Pylons/pyramid/issues/735. + +- Allow a protocol-relative URL (e.g. ``//example.com/images``) to be passed to + ``pyramid.config.Configurator.add_static_view``. This allows + externally-hosted static URLs to be generated based on the current protocol. + +- The ``AuthTktAuthenticationPolicy`` has two new options to configure its + domain usage: + + * ``parent_domain``: if set the authentication cookie is set on + the parent domain. This is useful if you have multiple sites sharing the + same domain. + * ``domain``: if provided the cookie is always set for this domain, bypassing + all usual logic. + + See https://github.com/Pylons/pyramid/pull/1028, + https://github.com/Pylons/pyramid/pull/1072 and + https://github.com/Pylons/pyramid/pull/1078. + +- The ``AuthTktAuthenticationPolicy`` now supports IPv6 addresses when using + the ``include_ip=True`` option. This is possibly incompatible with + alternative ``auth_tkt`` implementations, as the specification does not + define how to properly handle IPv6. See + https://github.com/Pylons/pyramid/issues/831. + +- Make it possible to use variable arguments via + ``pyramid.paster.get_appsettings``. This also allowed the generated + ``initialize_db`` script from the ``alchemy`` scaffold to grow support + for options in the form ``a=1 b=2`` so you can fill in + values in a parameterized ``.ini`` file, e.g. + ``initialize_myapp_db etc/development.ini a=1 b=2``. + See https://github.com/Pylons/pyramid/pull/911 + +- The ``request.session.check_csrf_token()`` method and the ``check_csrf`` view + predicate now take into account the value of the HTTP header named + ``X-CSRF-Token`` (as well as the ``csrf_token`` form parameter, which they + always did). The header is tried when the form parameter does not exist. + +- View lookup will now search for valid views based on the inheritance + hierarchy of the context. It tries to find views based on the most + specific context first, and upon predicate failure, will move up the + inheritance chain to test views found by the super-type of the context. + In the past, only the most specific type containing views would be checked + and if no matching view could be found then a PredicateMismatch would be + raised. Now predicate mismatches don't hide valid views registered on + super-types. Here's an example that now works:: + + class IResource(Interface): + + ... + + @view_config(context=IResource) + def get(context, request): + + ... + + @view_config(context=IResource, request_method='POST') + def post(context, request): + + ... + + @view_config(context=IResource, request_method='DELETE') + def delete(context, request): + + ... + + @implementer(IResource) + class MyResource: + + ... + + @view_config(context=MyResource, request_method='POST') + def override_post(context, request): + + ... + + Previously the override_post view registration would hide the get + and delete views in the context of MyResource -- leading to a + predicate mismatch error when trying to use GET or DELETE + methods. Now the views are found and no predicate mismatch is + raised. + See https://github.com/Pylons/pyramid/pull/786 and + https://github.com/Pylons/pyramid/pull/1004 and + https://github.com/Pylons/pyramid/pull/1046 + +- The ``pserve`` command now takes a ``-v`` (or ``--verbose``) flag and a + ``-q`` (or ``--quiet``) flag. Output from running ``pserve`` can be + controlled using these flags. ``-v`` can be specified multiple times to + increase verbosity. ``-q`` sets verbosity to ``0`` unconditionally. The + default verbosity level is ``1``. + +- The ``alchemy`` scaffold tests now provide better coverage. See + https://github.com/Pylons/pyramid/pull/1029 + +- The ``pyramid.config.Configurator.add_route`` method now supports being + called with an external URL as pattern. See + https://github.com/Pylons/pyramid/issues/611 and the documentation section + in the "URL Dispatch" chapter entitled "External Routes" for more information. + +Bug Fixes +--------- + +- It was not possible to use ``pyramid.httpexceptions.HTTPException`` as + the ``context`` of an exception view as very general catchall for + http-related exceptions when you wanted that exception view to override the + default exception view. See https://github.com/Pylons/pyramid/issues/985 + +- When the ``pyramid.reload_templates`` setting was true, and a Chameleon + template was reloaded, and the renderer specification named a macro + (e.g. ``foo#macroname.pt``), renderings of the template after the template + was reloaded due to a file change would produce the entire template body + instead of just a rendering of the macro. See + https://github.com/Pylons/pyramid/issues/1013. + +- Fix an obscure problem when combining a virtual root with a route with a + ``*traverse`` in its pattern. Now the traversal path generated in + such a configuration will be correct, instead of an element missing + a leading slash. + +- Fixed a Mako renderer bug returning a tuple with a previous defname value + in some circumstances. See https://github.com/Pylons/pyramid/issues/1037 + for more information. + +- Make the ``pyramid.config.assets.PackageOverrides`` object implement the API + for ``__loader__`` objects specified in PEP 302. Proxies to the + ``__loader__`` set by the importer, if present; otherwise, raises + ``NotImplementedError``. This makes Pyramid static view overrides work + properly under Python 3.3 (previously they would not). See + https://github.com/Pylons/pyramid/pull/1015 for more information. + +- ``mako_templating``: added defensive workaround for non-importability of + ``mako`` due to upstream ``markupsafe`` dropping Python 3.2 support. Mako + templating will no longer work under the combination of MarkupSafe 0.17 and + Python 3.2 (although the combination of MarkupSafe 0.17 and Python 3.3 or any + supported Python 2 version will work OK). + +- Spaces and dots may now be in mako renderer template paths. This was + broken when support for the new makodef syntax was added in 1.4a1. + See https://github.com/Pylons/pyramid/issues/950 + +- ``pyramid.debug_authorization=true`` will now correctly print out + ``Allowed`` for views registered with ``NO_PERMISSION_REQUIRED`` instead + of invoking the ``permits`` method of the authorization policy. + See https://github.com/Pylons/pyramid/issues/954 + +- Pyramid failed to install on some systems due to being packaged with + some test files containing higher order characters in their names. These + files have now been removed. See + https://github.com/Pylons/pyramid/issues/981 + +- ``pyramid.testing.DummyResource`` didn't define ``__bool__``, so code under + Python 3 would use ``__len__`` to find truthiness; this usually caused an + instance of DummyResource to be "falsy" instead of "truthy". See + https://github.com/Pylons/pyramid/pull/1032 + +- The ``alchemy`` scaffold would break when the database was MySQL during + tables creation. See https://github.com/Pylons/pyramid/pull/1049 + +- The ``current_route_url`` method now attaches the query string to the URL by + default. See + https://github.com/Pylons/pyramid/issues/1040 + +- Make ``pserve.cherrypy_server_runner`` Python 3 compatible. See + https://github.com/Pylons/pyramid/issues/718 + +Backwards Incompatibilities +--------------------------- + +- Modified the ``current_route_url`` method in pyramid.Request. The method + previously returned the URL without the query string by default, it now does + attach the query string unless it is overriden. + +- The ``route_url`` and ``route_path`` APIs no longer quote ``/`` + to ``%2F`` when a replacement value contains a ``/``. This was pointless, + as WSGI servers always unquote the slash anyway, and Pyramid never sees the + quoted value. + +- It is no longer possible to set a ``locale_name`` attribute of the request, + nor is it possible to set a ``localizer`` attribute of the request. These + are now "reified" properties that look up a locale name and localizer + respectively using the machinery described in the "Internationalization" + chapter of the documentation. + +- If you send an ``X-Vhm-Root`` header with a value that ends with a slash (or + any number of slashes), the trailing slash(es) will be removed before a URL + is generated when you use use ``request.resource_url`` or + ``request.resource_path``. Previously the virtual root path would not have + trailing slashes stripped, which would influence URL generation. + +- The ``pyramid.interfaces.IResourceURL`` interface has now grown two new + attributes: ``virtual_path_tuple`` and ``physical_path_tuple``. These should + be the tuple form of the resource's path (physical and virtual). + +1.4 (2012-12-18) +================ + +Docs +---- + +- Fix functional tests in the ZODB tutorial + +1.4b3 (2012-12-10) +================== + +- Packaging release only, no code changes. 1.4b2 was a brownbag release due to + missing directories in the tarball. + +1.4b2 (2012-12-10) +================== + +Docs +---- + +- Scaffolding is now PEP-8 compliant (at least for a brief shining moment). + +- Tutorial improvements. + +Backwards Incompatibilities +--------------------------- + +- Modified the ``_depth`` argument to ``pyramid.view.view_config`` to accept + a value relative to the invocation of ``view_config`` itself. Thus, when it + was previously expecting a value of ``1`` or greater, to reflect that + the caller of ``view_config`` is 1 stack frame away from ``venusian.attach``, + this implementation detail is now hidden. + +- Modified the ``_backframes`` argument to ``pyramid.util.action_method`` in a + similar way to the changes described to ``_depth`` above. This argument + remains undocumented, but might be used in the wild by some insane person. + +1.4b1 (2012-11-21) +================== + +Features +-------- + +- Small microspeed enhancement which anticipates that a + ``pyramid.response.Response`` object is likely to be returned from a view. + Some code is shortcut if the class of the object returned by a view is this + class. A similar microoptimization was done to + ``pyramid.request.Request.is_response``. + +- Make it possible to use variable arguments on ``p*`` commands (``pserve``, + ``pshell``, ``pviews``, etc) in the form ``a=1 b=2`` so you can fill in + values in parameterized ``.ini`` file, e.g. ``pshell etc/development.ini + http_port=8080``. See https://github.com/Pylons/pyramid/pull/714 + +- A somewhat advanced and obscure feature of Pyramid event handlers is their + ability to handle "multi-interface" notifications. These notifications have + traditionally presented multiple objects to the subscriber callable. For + instance, if an event was sent by code like this:: + + registry.notify(event, context) + + In the past, in order to catch such an event, you were obligated to write and + register an event subscriber that mentioned both the event and the context in + its argument list:: + + @subscriber([SomeEvent, SomeContextType]) + def asubscriber(event, context): + pass + + In many subscriber callables registered this way, it was common for the logic + in the subscriber callable to completely ignore the second and following + arguments (e.g. ``context`` in the above example might be ignored), because + they usually existed as attributes of the event anyway. You could usually + get the same value by doing ``event.context`` or similar. + + The fact that you needed to put an extra argument which you usually ignored + in the subscriber callable body was only a minor annoyance until we added + "subscriber predicates", used to narrow the set of circumstances under which + a subscriber will be executed, in a prior 1.4 alpha release. Once those were + added, the annoyance was escalated, because subscriber predicates needed to + accept the same argument list and arity as the subscriber callables that they + were configured against. So, for example, if you had these two subscriber + registrations in your code:: + + @subscriber([SomeEvent, SomeContextType]) + def asubscriber(event, context): + pass + + @subscriber(SomeOtherEvent) + def asubscriber(event): + pass + + And you wanted to use a subscriber predicate:: + + @subscriber([SomeEvent, SomeContextType], mypredicate=True) + def asubscriber1(event, context): + pass + + @subscriber(SomeOtherEvent, mypredicate=True) + def asubscriber2(event): + pass + + If an existing ``mypredicate`` subscriber predicate had been written in such + a way that it accepted only one argument in its ``__call__``, you could not + use it against a subscription which named more than one interface in its + subscriber interface list. Similarly, if you had written a subscriber + predicate that accepted two arguments, you couldn't use it against a + registration that named only a single interface type. + + For example, if you created this predicate:: + + class MyPredicate(object): + # portions elided... + def __call__(self, event): + return self.val == event.context.foo + + It would not work against a multi-interface-registered subscription, so in + the above example, when you attempted to use it against ``asubscriber1``, it + would fail at runtime with a TypeError, claiming something was attempting to + call it with too many arguments. + + To hack around this limitation, you were obligated to design the + ``mypredicate`` predicate to expect to receive in its ``__call__`` either a + single ``event`` argument (a SomeOtherEvent object) *or* a pair of arguments + (a SomeEvent object and a SomeContextType object), presumably by doing + something like this:: + + class MyPredicate(object): + # portions elided... + def __call__(self, event, context=None): + return self.val == event.context.foo + + This was confusing and bad. + + In order to allow people to ignore unused arguments to subscriber callables + and to normalize the relationship between event subscribers and subscriber + predicates, we now allow both subscribers and subscriber predicates to accept + only a single ``event`` argument even if they've been subscribed for + notifications that involve multiple interfaces. Subscribers and subscriber + predicates that accept only one argument will receive the first object passed + to ``notify``; this is typically (but not always) the event object. The + other objects involved in the subscription lookup will be discarded. You can + now write an event subscriber that accepts only ``event`` even if it + subscribes to multiple interfaces:: + + @subscriber([SomeEvent, SomeContextType]) + def asubscriber(event): + # this will work! + + This prevents you from needing to match the subscriber callable parameters to + the subscription type unnecessarily, especially when you don't make use of + any argument in your subscribers except for the event object itself. + + Note, however, that if the event object is not the first + object in the call to ``notify``, you'll run into trouble. For example, if + notify is called with the context argument first:: + + registry.notify(context, event) + + You won't be able to take advantage of the event-only feature. It will + "work", but the object received by your event handler won't be the event + object, it will be the context object, which won't be very useful:: + + @subscriber([SomeContextType, SomeEvent]) + def asubscriber(event): + # bzzt! you'll be getting the context here as ``event``, and it'll + # be useless + + Existing multiple-argument subscribers continue to work without issue, so you + should continue use those if your system notifies using multiple interfaces + and the first interface is not the event interface. For example:: + + @subscriber([SomeContextType, SomeEvent]) + def asubscriber(context, event): + # this will still work! + + The event-only feature makes it possible to use a subscriber predicate that + accepts only a request argument within both multiple-interface subscriber + registrations and single-interface subscriber registrations. You needn't + make slightly different variations of predicates depending on the + subscription type arguments. Instead, just write all your subscriber + predicates so they only accept ``event`` in their ``__call__`` and they'll be + useful across all registrations for subscriptions that use an event as their + first argument, even ones which accept more than just ``event``. + + However, the same caveat applies to predicates as to subscriber callables: if + you're subscribing to a multi-interface event, and the first interface is not + the event interface, the predicate won't work properly. In such a case, + you'll need to match the predicate ``__call__`` argument ordering and + composition to the ordering of the interfaces. For example, if the + registration for the subscription uses ``[SomeContext, SomeEvent]``, you'll + need to reflect that in the ordering of the parameters of the predicate's + ``__call__`` method:: + + def __call__(self, context, event): + return event.request.path.startswith(self.val) + + tl;dr: 1) When using multi-interface subscriptions, always use the event type + as the first subscription registration argument and 2) When 1 is true, use + only ``event`` in your subscriber and subscriber predicate parameter lists, + no matter how many interfaces the subscriber is notified with. This + combination will result in the maximum amount of reusability of subscriber + predicates and the least amount of thought on your part. Drink responsibly. + +Bug Fixes +--------- + +- A failure when trying to locate the attribute ``__text__`` on route and view + predicates existed when the ``debug_routematch`` setting was true or when the + ``pviews`` command was used. See https://github.com/Pylons/pyramid/pull/727 + +Documentation +------------- + +- Sync up tutorial source files with the files that are rendered by the + scaffold that each uses. + +1.4a4 (2012-11-14) +================== + +Features +-------- + +- ``pyramid.authentication.AuthTktAuthenticationPolicy`` has been updated to + support newer hashing algorithms such as ``sha512``. Existing applications + should consider updating if possible for improved security over the default + md5 hashing. + +- Added an ``effective_principals`` route and view predicate. + +- Do not allow the userid returned from the ``authenticated_userid`` or the + userid that is one of the list of principals returned by + ``effective_principals`` to be either of the strings ``system.Everyone`` or + ``system.Authenticated`` when any of the built-in authorization policies that + live in ``pyramid.authentication`` are in use. These two strings are + reserved for internal usage by Pyramid and they will not be accepted as valid + userids. + +- Slightly better debug logging from + ``pyramid.authentication.RepozeWho1AuthenticationPolicy``. + +- ``pyramid.security.view_execution_permitted`` used to return ``True`` if no + view could be found. It now raises a ``TypeError`` exception in that case, as + it doesn't make sense to assert that a nonexistent view is + execution-permitted. See https://github.com/Pylons/pyramid/issues/299. + +- Allow a ``_depth`` argument to ``pyramid.view.view_config``, which will + permit limited composition reuse of the decorator by other software that + wants to provide custom decorators that are much like view_config. + +- Allow an iterable of decorators to be passed to + ``pyramid.config.Configurator.add_view``. This allows views to be wrapped + by more than one decorator without requiring combining the decorators + yourself. + +Bug Fixes +--------- + +- In the past if a renderer returned ``None``, the body of the resulting + response would be set explicitly to the empty string. Instead, now, the body + is left unchanged, which allows the renderer to set a body itself by using + e.g. ``request.response.body = b'foo'``. The body set by the renderer will + be unmolested on the way out. See + https://github.com/Pylons/pyramid/issues/709 + +- In uncommon cases, the ``pyramid_excview_tween_factory`` might have + inadvertently raised a ``KeyError`` looking for ``request_iface`` as an + attribute of the request. It no longer fails in this case. See + https://github.com/Pylons/pyramid/issues/700 + +- Be more tolerant of potential error conditions in ``match_param`` and + ``physical_path`` predicate implementations; instead of raising an exception, + return False. + +- ``pyramid.view.render_view`` was not functioning properly under Python 3.x + due to a byte/unicode discrepancy. See + https://github.com/Pylons/pyramid/issues/721 + +Deprecations +------------ + +- ``pyramid.authentication.AuthTktAuthenticationPolicy`` will emit a warning if + an application is using the policy without explicitly passing a ``hashalg`` + argument. This is because the default is "md5" which is considered + theoretically subject to collision attacks. If you really want "md5" then you + must specify it explicitly to get rid of the warning. + +Documentation +------------- + +- All of the tutorials that use + ``pyramid.authentication.AuthTktAuthenticationPolicy`` now explicitly pass + ``sha512`` as a ``hashalg`` argument. + + +Internals +--------- + +- Move ``TopologicalSorter`` from ``pyramid.config.util`` to ``pyramid.util``, + move ``CyclicDependencyError`` from ``pyramid.config.util`` to + ``pyramid.exceptions``, rename ``Singleton`` to ``Sentinel`` and move from + ``pyramid.config.util`` to ``pyramid.util``; this is in an effort to + move that stuff that may be an API one day out of ``pyramid.config.util``, + because that package should never be imported from non-Pyramid code. + TopologicalSorter is still not an API, but may become one. + +- Get rid of shady monkeypatching of ``pyramid.request.Request`` and + ``pyramid.response.Response`` done within the ``__init__.py`` of Pyramid. + Webob no longer relies on this being done. Instead, the ResponseClass + attribute of the Pyramid Request class is assigned to the Pyramid response + class; that's enough to satisfy WebOb and behave as it did before with the + monkeypatching. + +1.4a3 (2012-10-26) +================== + +Bug Fixes +--------- + +- The match_param predicate's text method was fixed to sort its values. + Part of https://github.com/Pylons/pyramid/pull/705 + +- 1.4a ``pyramid.scripting.prepare`` behaved differently than 1.3 series + function of same name. In particular, if passed a request, it would not + set the ``registry`` attribute of the request like 1.3 did. A symptom + would be that passing a request to ``pyramid.paster.bootstrap`` (which uses + the function) that did not have a ``registry`` attribute could assume that + the registry would be attached to the request by Pyramid. This assumption + could be made in 1.3, but not in 1.4. The assumption can now be made in + 1.4 too (a registry is attached to a request passed to bootstrap or + prepare). + +- When registering a view configuration that named a Chameleon ZPT renderer + with a macro name in it (e.g. ``renderer='some/template#somemacro.pt``) as + well as a view configuration without a macro name in it that pointed to the + same template (e.g. ``renderer='some/template.pt'``), internal caching could + confuse the two, and your code might have rendered one instead of the + other. + +Features +-------- + +- Allow multiple values to be specified to the ``request_param`` view/route + predicate as a sequence. Previously only a single string value was allowed. + See https://github.com/Pylons/pyramid/pull/705 + +- Comments with references to documentation sections placed in scaffold + ``.ini`` files. + +- Added an HTTP Basic authentication policy + at ``pyramid.authentication.BasicAuthAuthenticationPolicy``. + +- The Configurator ``testing_securitypolicy`` method now returns the policy + object it creates. + +- The Configurator ``testing_securitypolicy`` method accepts two new + arguments: ``remember_result`` and ``forget_result``. If supplied, these + values influence the result of the policy's ``remember`` and ``forget`` + methods, respectively. + +- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a + ``forgotten`` value on the policy (the value ``True``) when its ``forget`` + method is called. + +- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a + ``remembered`` value on the policy, which is the value of the ``principal`` + argument it's called with when its ``remember`` method is called. + +- New ``physical_path`` view predicate. If specified, this value should be a + string or a tuple representing the physical traversal path of the context + found via traversal for this predicate to match as true. For example: + ``physical_path='/'`` or ``physical_path='/a/b/c'`` or ``physical_path=('', + 'a', 'b', 'c')``. This is not a path prefix match or a regex, it's a + whole-path match. It's useful when you want to always potentially show a + view when some object is traversed to, but you can't be sure about what kind + of object it will be, so you can't use the ``context`` predicate. The + individual path elements inbetween slash characters or in tuple elements + should be the Unicode representation of the name of the resource and should + not be encoded in any way. + +1.4a2 (2012-09-27) +================== + +Bug Fixes +--------- + +- When trying to determine Mako defnames and Chameleon macro names in asset + specifications, take into account that the filename may have a hyphen in + it. See https://github.com/Pylons/pyramid/pull/692 + +Features +-------- + +- A new ``pyramid.session.check_csrf_token`` convenience function was added. + +- A ``check_csrf`` view predicate was added. For example, you can now do + ``config.add_view(someview, check_csrf=True)``. When the predicate is + checked, if the ``csrf_token`` value in ``request.params`` matches the CSRF + token in the request's session, the view will be permitted to execute. + Otherwise, it will not be permitted to execute. + +- Add ``Base.metadata.bind = engine`` to alchemy template, so that tables + defined imperatively will work. + +Documentation +------------- + +- update wiki2 SQLA tutorial with the changes required after inserting + ``Base.metadata.bind = engine`` into the alchemy scaffold. + +1.4a1 (2012-09-16) +================== + +Bug Fixes +--------- + +- Forward port from 1.3 branch: When no authentication policy was configured, + a call to ``pyramid.security.effective_principals`` would unconditionally + return the empty list. This was incorrect, it should have unconditionally + returned ``[Everyone]``, and now does. + +- Explicit url dispatch regexes can now contain colons. + https://github.com/Pylons/pyramid/issues/629 + +- On at least one 64-bit Ubuntu system under Python 3.2, using the + ``view_config`` decorator caused a ``RuntimeError: dictionary changed size + during iteration`` exception. It no longer does. See + https://github.com/Pylons/pyramid/issues/635 for more information. + +- In Mako Templates lookup, check if the uri is already adjusted and bring + it back to an asset spec. Normally occurs with inherited templates or + included components. + https://github.com/Pylons/pyramid/issues/606 + https://github.com/Pylons/pyramid/issues/607 + +- In Mako Templates lookup, check for absolute uri (using mako directories) + when mixing up inheritance with asset specs. + https://github.com/Pylons/pyramid/issues/662 + +- HTTP Accept headers were not being normalized causing potentially + conflicting view registrations to go unnoticed. Two views that only + differ in the case ('text/html' vs. 'text/HTML') will now raise an error. + https://github.com/Pylons/pyramid/pull/620 + +- Forward-port from 1.3 branch: when registering multiple views with an + ``accept`` predicate in a Pyramid application runing under Python 3, you + might have received a ``TypeError: unorderable types: function() < + function()`` exception. + +Features +-------- + +- Python 3.3 compatibility. + +- Configurator.add_directive now accepts arbitrary callables like partials or + objects implementing ``__call__`` which dont have ``__name__`` and + ``__doc__`` attributes. See https://github.com/Pylons/pyramid/issues/621 + and https://github.com/Pylons/pyramid/pull/647. + +- Third-party custom view, route, and subscriber predicates can now be added + for use by view authors via + ``pyramid.config.Configurator.add_view_predicate``, + ``pyramid.config.Configurator.add_route_predicate`` and + ``pyramid.config.Configurator.add_subscriber_predicate``. So, for example, + doing this:: + + config.add_view_predicate('abc', my.package.ABCPredicate) + + Might allow a view author to do this in an application that configured that + predicate:: + + @view_config(abc=1) + + Similar features exist for ``add_route``, and ``add_subscriber``. See + "Adding A Third Party View, Route, or Subscriber Predicate" in the Hooks + chapter for more information. + + Note that changes made to support the above feature now means that only + actions registered using the same "order" can conflict with one another. + It used to be the case that actions registered at different orders could + potentially conflict, but to my knowledge nothing ever depended on this + behavior (it was a bit silly). + +- Custom objects can be made easily JSON-serializable in Pyramid by defining + a ``__json__`` method on the object's class. This method should return + values natively serializable by ``json.dumps`` (such as ints, lists, + dictionaries, strings, and so forth). + +- The JSON renderer now allows for the definition of custom type adapters to + convert unknown objects to JSON serializations. + +- As of this release, the ``request_method`` predicate, when used, will also + imply that ``HEAD`` is implied when you use ``GET``. For example, using + ``@view_config(request_method='GET')`` is equivalent to using + ``@view_config(request_method=('GET', 'HEAD'))``. Using + ``@view_config(request_method=('GET', 'POST')`` is equivalent to using + ``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because + HEAD is a variant of GET that omits the body, and WebOb has special support + to return an empty body when a HEAD is used. + +- ``config.add_request_method`` has been introduced to support extending + request objects with arbitrary callables. This method expands on the + previous ``config.set_request_property`` by supporting methods as well as + properties. This method now causes less code to be executed at + request construction time than ``config.set_request_property`` in + version 1.3. + +- Don't add a ``?`` to URLs generated by ``request.resource_url`` if the + ``query`` argument is provided but empty. + +- Don't add a ``?`` to URLs generated by ``request.route_url`` if the + ``_query`` argument is provided but empty. + +- The static view machinery now raises (rather than returns) ``HTTPNotFound`` + and ``HTTPMovedPermanently`` exceptions, so these can be caught by the + Not Found View (and other exception views). + +- The Mako renderer now supports a def name in an asset spec. When the def + name is present in the asset spec, the system will render the template def + within the template and will return the result. An example asset spec is + ``package:path/to/template#defname.mako``. This will render the def named + ``defname`` inside the ``template.mako`` template instead of rendering the + entire template. The old way of returning a tuple in the form + ``('defname', {})`` from the view is supported for backward compatibility, + +- The Chameleon ZPT renderer now accepts a macro name in an asset spec. When + the macro name is present in the asset spec, the system will render the + macro listed as a ``define-macro`` and return the result instead of + rendering the entire template. An example asset spec: + ``package:path/to/template#macroname.pt``. This will render the macro + defined as ``macroname`` within the ``template.pt`` template instead of the + entire templae. + +- When there is a predicate mismatch exception (seen when no view matches for + a given request due to predicates not working), the exception now contains + a textual description of the predicate which didn't match. + +- An ``add_permission`` directive method was added to the Configurator. This + directive registers a free-standing permission introspectable into the + Pyramid introspection system. Frameworks built atop Pyramid can thus use + the ``permissions`` introspectable category data to build a + comprehensive list of permissions supported by a running system. Before + this method was added, permissions were already registered in this + introspectable category as a side effect of naming them in an ``add_view`` + call, this method just makes it possible to arrange for a permission to be + put into the ``permissions`` introspectable category without naming it + along with an associated view. Here's an example of usage of + ``add_permission``:: + + config = Configurator() + config.add_permission('view') + +- The ``UnencryptedCookieSessionFactoryConfig`` now accepts + ``signed_serialize`` and ``signed_deserialize`` hooks which may be used + to influence how the sessions are marshalled (by default this is done + with HMAC+pickle). + +- ``pyramid.testing.DummyRequest`` now supports methods supplied by the + ``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. + +- Request properties and methods added via ``config.set_request_property`` or + ``config.add_request_method`` are now available to tweens. + +- Request properties and methods added via ``config.set_request_property`` or + ``config.add_request_method`` are now available in the request object + returned from ``pyramid.paster.bootstrap``. + +- ``request.context`` of environment request during ``bootstrap`` is now the + root object if a context isn't already set on a provided request. + +- The ``pyramid.decorator.reify`` function is now an API, and was added to + the API documentation. + +- Added the ``pyramid.testing.testConfig`` context manager, which can be used + to generate a configurator in a test, e.g. ``with testing.testConfig(...):``. + +- Users can now invoke a subrequest from within view code using a new + ``request.invoke_subrequest`` API. + +Deprecations +------------ + +- The ``pyramid.config.Configurator.set_request_property`` has been + documentation-deprecated. The method remains usable but the more + featureful ``pyramid.config.Configurator.add_request_method`` should be + used in its place (it has all of the same capabilities but can also extend + the request object with methods). + +Backwards Incompatibilities +--------------------------- + +- The Pyramid router no longer adds the values ``bfg.routes.route`` or + ``bfg.routes.matchdict`` to the request's WSGI environment dictionary. + These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven + minor releases ago). If your code depended on these values, use + request.matched_route and request.matchdict instead. + +- It is no longer possible to pass an environ dictionary directly to + ``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka + ``ModelGraphTraverser.__call__``). Instead, you must pass a request + object. Passing an environment instead of a request has generated a + deprecation warning since Pyramid 1.1. + +- Pyramid will no longer work properly if you use the + ``webob.request.LegacyRequest`` as a request factory. Instances of the + LegacyRequest class have a ``request.path_info`` which return a string. + This Pyramid release assumes that ``request.path_info`` will + unconditionally be Unicode. + +- The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text`` + named ``get_renderer``, ``get_template``, ``render_template``, and + ``render_template_to_response`` have been removed. These have issued a + deprecation warning upon import since Pyramid 1.0. Use + ``pyramid.renderers.get_renderer()``, + ``pyramid.renderers.get_renderer().implementation()``, + ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response`` + respectively instead of these functions. + +- The ``pyramid.configuration`` module was removed. It had been deprecated + since Pyramid 1.0 and printed a deprecation warning upon its use. Use + ``pyramid.config`` instead. + +- The ``pyramid.paster.PyramidTemplate`` API was removed. It had been + deprecated since Pyramid 1.1 and issued a warning on import. If your code + depended on this, adjust your code to import + ``pyramid.scaffolds.PyramidTemplate`` instead. + +- The ``pyramid.settings.get_settings()`` API was removed. It had been + printing a deprecation warning since Pyramid 1.0. If your code depended on + this API, use ``pyramid.threadlocal.get_current_registry().settings`` + instead or use the ``settings`` attribute of the registry available from + the request (``request.registry.settings``). + +- These APIs from the ``pyramid.testing`` module were removed. They have + been printing deprecation warnings since Pyramid 1.0: + + * ``registerDummySecurityPolicy``, use + ``pyramid.config.Configurator.testing_securitypolicy`` instead. + + * ``registerResources`` (aka ``registerModels``, use + ``pyramid.config.Configurator.testing_resources`` instead. + + * ``registerEventListener``, use + ``pyramid.config.Configurator.testing_add_subscriber`` instead. + + * ``registerTemplateRenderer`` (aka `registerDummyRenderer``), use + ``pyramid.config.Configurator.testing_add_template`` instead. + + * ``registerView``, use ``pyramid.config.Configurator.add_view`` instead. + + * ``registerUtility``, use + ``pyramid.config.Configurator.registry.registerUtility`` instead. + + * ``registerAdapter``, use + ``pyramid.config.Configurator.registry.registerAdapter`` instead. + + * ``registerSubscriber``, use + ``pyramid.config.Configurator.add_subscriber`` instead. + + * ``registerRoute``, use + ``pyramid.config.Configurator.add_route`` instead. + + * ``registerSettings``, use + ``pyramid.config.Configurator.add_settings`` instead. + +- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object + was invoked before any finished callbacks were executed. As of this + release, the ``__call__`` method of a Response object is invoked *after* + finished callbacks are executed. This is in support of the + ``request.invoke_subrequest`` feature. + +- The 200-series exception responses named ``HTTPCreated``, ``HTTPAccepted``, + ``HTTPNonAuthoritativeInformation``, ``HTTPNoContent``, ``HTTPResetContent``, + and ``HTTPPartialContent`` in ``pyramid.httpexceptions`` no longer inherit + from ``HTTPOk``. Instead they inherit from a new base class named + ``HTTPSuccessful``. This will have no effect on you unless you've registered + an exception view for ``HTTPOk`` and expect that exception view to + catch all the aforementioned exceptions. + +Documentation +------------- + +- Added an "Upgrading Pyramid" chapter to the narrative documentation. It + describes how to cope with deprecations and removals of Pyramid APIs and + how to show Pyramid-generated deprecation warnings while running tests and + while running a server. + +- Added a "Invoking a Subrequest" chapter to the documentation. It describes + how to use the new ``request.invoke_subrequest`` API. + +Dependencies +------------ + +- Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on + 1.2dev+). This is to ensure that we obtain a version of WebOb that returns + ``request.path_info`` as text. + +1.3 (2012-03-21) +================ + +Bug Fixes +--------- + +- When ``pyramid.wsgi.wsgiapp2`` calls the downstream WSGI app, the app's + environ will no longer have (deprecated and potentially misleading) + ``bfg.routes.matchdict`` or ``bfg.routes.route`` keys in it. A symptom of + this bug would be a ``wsgiapp2``-wrapped Pyramid app finding the wrong view + because it mistakenly detects that a route was matched when, in fact, it + was not. + +- The fix for issue https://github.com/Pylons/pyramid/issues/461 (which made + it possible for instance methods to be used as view callables) introduced a + backwards incompatibility when methods that declared only a request + argument were used. See https://github.com/Pylons/pyramid/issues/503 + +1.3b3 (2012-03-17) +================== + +Bug Fixes +--------- + +- ``config.add_view()`` 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__db`` instead of ``populate_``. + +Documentation +------------- + +- Wiki tutorials improved due to collaboration at PyCon US 2012 sprints. + +1.3b2 (2012-03-02) +================== + +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. + +1.3b1 (2012-02-26) +================== + +Bug Fixes +--------- + +- ``pyramid.config.Configurator.with_package`` didn't work if the + Configurator was an old-style ``pyramid.configuration.Configurator`` + instance. + +- Pyramid authorization policies did not show up in the introspector. + +Deprecations +------------ + +- All references to the ``tmpl_context`` request variable were removed from + the docs. Its existence in Pyramid is confusing for people who were never + Pylons users. It was added as a porting convenience for Pylons users in + Pyramid 1.0, but it never caught on because the Pyramid rendering system is + a lot different than Pylons' was, and alternate ways exist to do what it + was designed to offer in Pylons. It will continue to exist "forever" but + it will not be recommended or mentioned in the docs. + +1.3a9 (2012-02-22) +================== + +Features +-------- + +- Add an ``introspection`` boolean to the Configurator constructor. If this + is ``True``, actions registered using the Configurator will be registered + with the introspector. If it is ``False``, they won't. The default is + ``True``. Setting it to ``False`` during action processing will prevent + introspection for any following registration statements, and setting it to + ``True`` will start them up again. This addition is to service a + requirement that the debug toolbar's own views and methods not show up in + the introspector. + +- New API: ``pyramid.config.Configurator.add_notfound_view``. This is a + wrapper for ``pyramid.Config.configurator.add_view`` which provides easy + append_slash support and does the right thing about permissions. It should + be preferred over calling ``add_view`` directly with + ``context=HTTPNotFound`` as was previously recommended. + +- New API: ``pyramid.view.notfound_view_config``. This is a decorator + constructor like ``pyramid.view.view_config`` that calls + ``pyramid.config.Configurator.add_notfound_view`` when scanned. It should + be preferred over using ``pyramid.view.view_config`` with + ``context=HTTPNotFound`` as was previously recommended. + +- New API: ``pyramid.config.Configurator.add_forbidden_view``. This is a + wrapper for ``pyramid.Config.configurator.add_view`` which does the right + thing about permissions. It should be preferred over calling ``add_view`` + directly with ``context=HTTPForbidden`` as was previously recommended. + +- New API: ``pyramid.view.forbidden_view_config``. This is a decorator + constructor like ``pyramid.view.view_config`` that calls + ``pyramid.config.Configurator.add_forbidden_view`` when scanned. It should + be preferred over using ``pyramid.view.view_config`` with + ``context=HTTPForbidden`` as was previously recommended. + +- New APIs: ``pyramid.response.FileResponse`` and + ``pyramid.response.FileIter``, for usage in views that must serve files + "manually". + +Backwards Incompatibilities +--------------------------- + +- Remove ``pyramid.config.Configurator.with_context`` class method. It was + never an API, it is only used by ``pyramid_zcml`` and its functionality has + been moved to that package's latest release. This means that you'll need + to use the 0.9.2 or later release of ``pyramid_zcml`` with this release of + Pyramid. + +- The ``introspector`` argument to the ``pyramid.config.Configurator`` + constructor API has been removed. It has been replaced by the boolean + ``introspection`` flag. + +- The ``pyramid.registry.noop_introspector`` API object has been removed. + +- The older deprecated ``set_notfound_view`` Configurator method is now an + alias for the new ``add_notfound_view`` Configurator method. Likewise, the + older deprecated ``set_forbidden_view`` is now an alias for the new + ``add_forbidden_view``. This has the following impact: the ``context`` sent + to views with a ``(context, request)`` call signature registered via the + ``set_notfound_view`` or ``set_forbidden_view`` will now be an exception + object instead of the actual resource context found. Use + ``request.context`` to get the actual resource context. It's also + recommended to disuse ``set_notfound_view`` in favor of + ``add_notfound_view``, and disuse ``set_forbidden_view`` in favor of + ``add_forbidden_view`` despite the aliasing. + +Deprecations +------------ + +- The API documentation for ``pyramid.view.append_slash_notfound_view`` and + ``pyramid.view.AppendSlashNotFoundViewFactory`` was removed. These names + still exist and are still importable, but they are no longer APIs. Use + ``pyramid.config.Configurator.add_notfound_view(append_slash=True)`` or + ``pyramid.view.notfound_view_config(append_slash=True)`` to get the same + behavior. + +- The ``set_forbidden_view`` and ``set_notfound_view`` methods of the + Configurator were removed from the documentation. They have been + deprecated since Pyramid 1.1. + +Bug Fixes +--------- + +- The static file response object used by ``config.add_static_view`` opened + the static file twice, when it only needed to open it once. + +- The AppendSlashNotFoundViewFactory used request.path to match routes. This + was wrong because request.path contains the script name, and this would + cause it to fail in circumstances where the script name was not empty. It + should have used request.path_info, and now does. + +Documentation +------------- + +- Updated the "Creating a Not Found View" section of the "Hooks" chapter, + replacing explanations of registering a view using ``add_view`` or + ``view_config`` with ones using ``add_notfound_view`` or + ``notfound_view_config``. + +- Updated the "Creating a Not Forbidden View" section of the "Hooks" chapter, + replacing explanations of registering a view using ``add_view`` or + ``view_config`` with ones using ``add_forbidden_view`` or + ``forbidden_view_config``. + +- Updated the "Redirecting to Slash-Appended Routes" section of the "URL + Dispatch" chapter, replacing explanations of registering a view using + ``add_view`` or ``view_config`` with ones using ``add_notfound_view`` or + ``notfound_view_config`` + +- Updated all tutorials to use ``pyramid.view.forbidden_view_config`` rather + than ``pyramid.view.view_config`` with an HTTPForbidden context. + +1.3a8 (2012-02-19) +================== + +Features +-------- + +- The ``scan`` method of a ``Configurator`` can be passed an ``ignore`` + argument, which can be a string, a callable, or a list consisting of + strings and/or callables. This feature allows submodules, subpackages, and + global objects from being scanned. See + http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for + more information about how to use the ``ignore`` argument to ``scan``. + +- Better error messages when a view callable returns a value that cannot be + converted to a response (for example, when a view callable returns a + dictionary without a renderer defined, or doesn't return any value at all). + The error message now contains information about the view callable itself + as well as the result of calling it. + +- Better error message when a .pyc-only module is ``config.include`` -ed. + This is not permitted due to error reporting requirements, and a better + error message is shown when it is attempted. Previously it would fail with + something like "AttributeError: 'NoneType' object has no attribute + 'rfind'". + +- Add ``pyramid.config.Configurator.add_traverser`` API method. See the + Hooks narrative documentation section entitled "Changing the Traverser" for + more information. This is not a new feature, it just provides an API for + adding a traverser without needing to use the ZCA API. + +- Add ``pyramid.config.Configurator.add_resource_url_adapter`` API method. + See the Hooks narrative documentation section entitled "Changing How + pyramid.request.Request.resource_url Generates a URL" for more information. + This is not a new feature, it just provides an API for adding a resource + url adapter without needing to use the ZCA API. + +- The system value ``req`` is now supplied to renderers as an alias for + ``request``. This means that you can now, for example, in a template, do + ``req.route_url(...)`` instead of ``request.route_url(...)``. This is + purely a change to reduce the amount of typing required to use request + methods and attributes from within templates. The value ``request`` is + still available too, this is just an alternative. + +- A new interface was added: ``pyramid.interfaces.IResourceURL``. An adapter + implementing its interface can be used to override resource URL generation + when ``request.resource_url`` is called. This interface replaces the + now-deprecated ``pyramid.interfaces.IContextURL`` interface. + +- The dictionary passed to a resource's ``__resource_url__`` method (see + "Overriding Resource URL Generation" in the "Resources" chapter) now + contains an ``app_url`` key, representing the application URL generated + during ``request.resource_url``. It represents a potentially customized + URL prefix, containing potentially custom scheme, host and port information + passed by the user to ``request.resource_url``. It should be used instead + of ``request.application_url`` where necessary. + +- The ``request.resource_url`` API now accepts these arguments: ``app_url``, + ``scheme``, ``host``, and ``port``. The app_url argument can be used to + replace the URL prefix wholesale during url generation. The ``scheme``, + ``host``, and ``port`` arguments can be used to replace the respective + default values of ``request.application_url`` partially. + +- A new API named ``request.resource_path`` now exists. It works like + ``request.resource_url`` but produces a relative URL rather than an + absolute one. + +- The ``request.route_url`` API now accepts these arguments: ``_app_url``, + ``_scheme``, ``_host``, and ``_port``. The ``_app_url`` argument can be + used to replace the URL prefix wholesale during url generation. The + ``_scheme``, ``_host``, and ``_port`` arguments can be used to replace the + respective default values of ``request.application_url`` partially. + +Backwards Incompatibilities +--------------------------- + +- The ``pyramid.interfaces.IContextURL`` interface has been deprecated. + People have been instructed to use this to register a resource url adapter + in the "Hooks" chapter to use to influence ``request.resource_url`` URL + generation for resources found via custom traversers since Pyramid 1.0. + + The interface still exists and registering such an adapter still works, but + this interface will be removed from the software after a few major Pyramid + releases. You should replace it with an equivalent + ``pyramid.interfaces.IResourceURL`` adapter, registered using the new + ``pyramid.config.Configurator.add_resource_url_adapter`` API. A + deprecation warning is now emitted when a + ``pyramid.interfaces.IContextURL`` adapter is found when + ``request.resource_url`` is called. + +Documentation +------------- + +- Don't create a ``session`` instance in SQLA Wiki tutorial, use raw + ``DBSession`` instead (this is more common in real SQLA apps). + +Scaffolding +----------- + +- Put ``pyramid.includes`` targets within ini files in scaffolds on separate + lines in order to be able to tell people to comment out only the + ``pyramid_debugtoolbar`` line when they want to disable the toolbar. + +Dependencies +------------ + +- Depend on ``venusian`` >= 1.0a3 to provide scan ``ignore`` support. + +Internal +-------- + +- Create a "MakoRendererFactoryHelper" that provides customizable settings + key prefixes. Allows settings prefixes other than "mako." to be used to + create different factories that don't use the global mako settings. This + will be useful for the debug toolbar, which can currently be sabotaged by + someone using custom mako configuration settings. + +1.3a7 (2012-02-07) +================== + +Features +-------- + +- More informative error message when a ``config.include`` cannot find an + ``includeme``. See https://github.com/Pylons/pyramid/pull/392. + +- Internal: catch unhashable discriminators early (raise an error instead of + allowing them to find their way into resolveConflicts). + +- The `match_param` view predicate now accepts a string or a tuple. + This replaces the broken behavior of accepting a dict. See + https://github.com/Pylons/pyramid/issues/425 for more information. + +Bug Fixes +--------- + +- The process will now restart when ``pserve`` is used with the ``--reload`` + flag when the ``development.ini`` file (or any other .ini file in use) is + changed. See https://github.com/Pylons/pyramid/issues/377 and + https://github.com/Pylons/pyramid/pull/411 + +- The ``prequest`` script would fail when used against URLs which did not + return HTML or text. See https://github.com/Pylons/pyramid/issues/381 + +Backwards Incompatibilities +--------------------------- + +- The `match_param` view predicate no longer accepts a dict. This will + have no negative affect because the implementation was broken for + dict-based arguments. + +Documentation +------------- + +- Add a traversal hello world example to the narrative docs. + +1.3a6 (2012-01-20) +================== + +Features +-------- + +- New API: ``pyramid.config.Configurator.set_request_property``. Add lazy + property descriptors to a request without changing the request factory. + This method provides conflict detection and is the suggested way to add + properties to a request. + +- Responses generated by Pyramid's ``static_view`` now use + a ``wsgi.file_wrapper`` (see + http://www.python.org/dev/peps/pep-0333/#optional-platform-specific-file-handling) + when one is provided by the web server. + +Bug Fixes +--------- + +- Views registered with an ``accept`` could not be overridden correctly with + a different view that had the same predicate arguments. See + https://github.com/Pylons/pyramid/pull/404 for more information. + +- When using a dotted name for a ``view`` argument to + ``Configurator.add_view`` that pointed to a class with a ``view_defaults`` + decorator, the view defaults would not be applied. See + https://github.com/Pylons/pyramid/issues/396 . + +- Static URL paths were URL-quoted twice. See + https://github.com/Pylons/pyramid/issues/407 . + +1.3a5 (2012-01-09) +================== + +Bug Fixes +--------- + +- The ``pyramid.view.view_defaults`` decorator did not work properly when + more than one view relied on the defaults being different for configuration + conflict resolution. See https://github.com/Pylons/pyramid/issues/394. + +Backwards Incompatibilities +--------------------------- + +- The ``path_info`` route and view predicates now match against + ``request.upath_info`` (Unicode) rather than ``request.path_info`` + (indeterminate value based on Python 3 vs. Python 2). This has to be done + to normalize matching on Python 2 and Python 3. + +1.3a4 (2012-01-05) +================== + +Features +-------- + +- New API: ``pyramid.request.Request.set_property``. Add lazy property + descriptors to a request without changing the request factory. New + properties may be reified, effectively caching the value for the lifetime + of the instance. Common use-cases for this would be to get a database + connection for the request or identify the current user. + +- Use the ``waitress`` WSGI server instead of ``wsgiref`` in scaffolding. + +Bug Fixes +--------- + +- The documentation of ``pyramid.events.subscriber`` indicated that using it + as a decorator with no arguments like this:: + + @subscriber() + def somefunc(event): + pass + + Would register ``somefunc`` to receive all events sent via the registry, + but this was untrue. Instead, it would receive no events at all. This has + now been fixed and the code matches the documentation. See also + https://github.com/Pylons/pyramid/issues/386 + +- Literal portions of route patterns were not URL-quoted when ``route_url`` + or ``route_path`` was used to generate a URL or path. + +- The result of ``route_path`` or ``route_url`` might have been ``unicode`` + or ``str`` depending on the input. It is now guaranteed to always be + ``str``. + +- URL matching when the pattern contained non-ASCII characters in literal + parts was indeterminate. Now the pattern supplied to ``add_route`` is + assumed to be either: a ``unicode`` value, or a ``str`` value that contains + only ASCII characters. If you now want to match the path info from a URL + that contains high order characters, you can pass the Unicode + representation of the decoded path portion in the pattern. + +- When using a ``traverse=`` route predicate, traversal would fail with a + URLDecodeError if there were any high-order characters in the traversal + pattern or in the matched dynamic segments. + +- Using a dynamic segment named ``traverse`` in a route pattern like this:: + + config.add_route('trav_route', 'traversal/{traverse:.*}') + + Would cause a ``UnicodeDecodeError`` when the route was matched and the + matched portion of the URL contained any high-order characters. See + https://github.com/Pylons/pyramid/issues/385 . + +- When using a ``*traverse`` stararg in a route pattern, a URL that matched + that possessed a ``@@`` in its name (signifying a view name) would be + inappropriately quoted by the traversal machinery during traversal, + resulting in the view not being found properly. See + https://github.com/Pylons/pyramid/issues/382 and + https://github.com/Pylons/pyramid/issues/375 . + +Backwards Incompatibilities +--------------------------- + +- String values passed to ``route_url`` or ``route_path`` that are meant to + replace "remainder" matches will now be URL-quoted except for embedded + slashes. For example:: + + config.add_route('remain', '/foo*remainder') + request.route_path('remain', remainder='abc / def') + # -> '/foo/abc%20/%20def' + + Previously string values passed as remainder replacements were tacked on + untouched, without any URL-quoting. But this doesn't really work logically + if the value passed is Unicode (raw unicode cannot be placed in a URL or in + a path) and it is inconsistent with the rest of the URL generation + machinery if the value is a string (it won't be quoted unless by the + caller). + + Some folks will have been relying on the older behavior to tack on query + string elements and anchor portions of the URL; sorry, you'll need to + change your code to use the ``_query`` and/or ``_anchor`` arguments to + ``route_path`` or ``route_url`` to do this now. + +- If you pass a bytestring that contains non-ASCII characters to + ``add_route`` as a pattern, it will now fail at startup time. Use Unicode + instead. + +1.3a3 (2011-12-21) +================== + +Features +-------- + +- Added a ``prequest`` script (along the lines of ``paster request``). It is + documented in the "Command-Line Pyramid" chapter in the section entitled + "Invoking a Request". + +- Add undocumented ``__discriminator__`` API to derived view callables. + e.g. ``adapters.lookup(...).__discriminator__(context, request)``. It will + be used by superdynamic systems that require the discriminator to be used + for introspection after manual view lookup. + +Bug Fixes +--------- + +- Normalized exit values and ``-h`` output for all ``p*`` scripts + (``pviews``, ``proutes``, etc). + +Documentation +------------- + +- Added a section named "Making Your Script into a Console Script" in the + "Command-Line Pyramid" chapter. + +- Removed the "Running Pyramid on Google App Engine" tutorial from the main + docs. It survives on in the Cookbook + (http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gae.html). + Rationale: it provides the correct info for the Python 2.5 version of GAE + only, and this version of Pyramid does not support Python 2.5. + +1.3a2 (2011-12-14) +================== + +Features +-------- + +- New API: ``pyramid.view.view_defaults``. If you use a class as a view, you + can use the new ``view_defaults`` class decorator on the class to provide + defaults to the view configuration information used by every + ``@view_config`` decorator that decorates a method of that class. It also + works against view configurations involving a class made imperatively. + +- Added a backwards compatibility knob to ``pcreate`` to emulate ``paster + create`` handling for the ``--list-templates`` option. + +- Changed scaffolding machinery around a bit to make it easier for people who + want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X, + 1.2.X and 1.3.X. See the new "Creating Pyramid Scaffolds" chapter in the + narrative documentation for more info. + +Documentation +------------- + +- Added documentation to "View Configuration" narrative documentation chapter + about ``view_defaults`` class decorator. + +- Added API docs for ``view_defaults`` class decorator. + +- Added an API docs chapter for ``pyramid.scaffolds``. + +- Added a narrative docs chapter named "Creating Pyramid Scaffolds". + +Backwards Incompatibilities +--------------------------- + +- The ``template_renderer`` method of ``pyramid.scaffolds.PyramidScaffold`` + was renamed to ``render_template``. If you were overriding it, you're a + bad person, because it wasn't an API before now. But we're nice so we're + letting you know. + +1.3a1 (2011-12-09) +================== + +Features +-------- + +- Python 3.2 compatibility. + +- New ``pyramid.compat`` module and API documentation which provides Python + 2/3 straddling support for Pyramid add-ons and development environments. + +- A ``mako.directories`` setting is no longer required to use Mako templates + Rationale: Mako template renderers can be specified using an absolute asset + spec. An entire application can be written with such asset specs, + requiring no ordered lookup path. + +- ``bpython`` interpreter compatibility in ``pshell``. See the "Command-Line + Pyramid" narrative docs chapter for more information. + +- Added ``get_appsettings`` API function to the ``pyramid.paster`` module. + This function returns the settings defined within an ``[app:...]`` section + in a PasteDeploy ini file. + +- Added ``setup_logging`` API function to the ``pyramid.paster`` module. + This function sets up Python logging according to the logging configuration + in a PasteDeploy ini file. + +- Configuration conflict reporting is reported in a more understandable way + ("Line 11 in file..." vs. a repr of a tuple of similar info). + +- A configuration introspection system was added; see the narrative + documentation chapter entitled "Pyramid Configuration Introspection" for + more information. New APIs: ``pyramid.registry.Introspectable``, + ``pyramid.config.Configurator.introspector``, + ``pyramid.config.Configurator.introspectable``, + ``pyramid.registry.Registry.introspector``. + +- Allow extra keyword arguments to be passed to the + ``pyramid.config.Configurator.action`` method. + +- New APIs: ``pyramid.path.AssetResolver`` and + ``pyramid.path.DottedNameResolver``. The former can be used to resolve + asset specifications, the latter can be used to resolve dotted names to + modules or packages. + +Bug Fixes +--------- + +- Make test suite pass on 32-bit systems; closes #286. closes #306. + See also https://github.com/Pylons/pyramid/issues/286 + +- The ``pyramid.view.view_config`` decorator did not accept a ``match_params`` + predicate argument. See https://github.com/Pylons/pyramid/pull/308 + +- The AuthTktCookieHelper could potentially generate Unicode headers + inappropriately when the ``tokens`` argument to remember was used. See + https://github.com/Pylons/pyramid/pull/314. + +- The AuthTktAuthenticationPolicy did not use a timing-attack-aware string + comparator. See https://github.com/Pylons/pyramid/pull/320 for more info. + +- The DummySession in ``pyramid.testing`` now generates a new CSRF token if + one doesn't yet exist. + +- ``request.static_url`` now generates URL-quoted URLs when fed a ``path`` + argument which contains characters that are unsuitable for URLs. See + https://github.com/Pylons/pyramid/issues/349 for more info. + +- Prevent a scaffold rendering from being named ``site`` (conflicts with + Python internal site.py). + +- Support for using instances as targets of the ``pyramid.wsgi.wsgiapp`` and + ``pryramid.wsgi.wsgiapp2`` functions. + See https://github.com/Pylons/pyramid/pull/370 for more info. + +Backwards Incompatibilities +--------------------------- + +- Pyramid no longer runs on Python 2.5 (which includes the most recent + release of Jython and the Python 2.5 version of GAE as of this writing). + +- The ``paster`` command is no longer the documented way to create projects, + start the server, or run debugging commands. To create projects from + scaffolds, ``paster create`` is replaced by the ``pcreate`` console script. + To serve up a project, ``paster serve`` is replaced by the ``pserve`` + console script. New console scripts named ``pshell``, ``pviews``, + ``proutes``, and ``ptweens`` do what their ``paster `` + equivalents used to do. Rationale: the Paste and PasteScript packages do + not run under Python 3. + +- The default WSGI server run as the result of ``pserve`` from newly rendered + scaffolding is now the ``wsgiref`` WSGI server instead of the + ``paste.httpserver`` server. Rationale: Rationale: the Paste and + PasteScript packages do not run under Python 3. + +- The ``pshell`` command (see "paster pshell") no longer accepts a + ``--disable-ipython`` command-line argument. Instead, it accepts a ``-p`` + or ``--python-shell`` argument, which can be any of the values ``python``, + ``ipython`` or ``bpython``. + +- Removed the ``pyramid.renderers.renderer_from_name`` function. It has been + deprecated since Pyramid 1.0, and was never an API. + +- To use ZCML with versions of Pyramid >= 1.3, you will need ``pyramid_zcml`` + version >= 0.8 and ``zope.configuration`` version >= 3.8.0. The + ``pyramid_zcml`` package version 0.8 is backwards compatible all the way to + Pyramid 1.0, so you won't be warned if you have older versions installed + and upgrade Pyramid "in-place"; it may simply break instead. + +Dependencies +------------ + +- Pyramid no longer depends on the ``zope.component`` package, except as a + testing dependency. + +- Pyramid now depends on a zope.interface>=3.8.0, WebOb>=1.2dev, + repoze.lru>=0.4, zope.deprecation>=3.5.0, translationstring>=0.4 (for + Python 3 compatibility purposes). It also, as a testing dependency, + depends on WebTest>=1.3.1 for the same reason. + +- Pyramid no longer depends on the Paste or PasteScript packages. + +Documentation +------------- + +- The SQLAlchemy Wiki tutorial has been updated. It now uses + ``@view_config`` decorators and an explicit database population script. + +- Minor updates to the ZODB Wiki tutorial. + +- A narrative documentation chapter named "Extending Pyramid Configuration" + was added; it describes how to add a new directive, and how use the + ``pyramid.config.Configurator.action`` method within custom directives. It + also describes how to add introspectable objects. + +- A narrative documentation chapter named "Pyramid Configuration + Introspection" was added. It describes how to query the introspection + system. + +Scaffolds +--------- + +- Rendered scaffolds have now been changed to be more relocatable (fewer + mentions of the package name within files in the package). + +- The ``routesalchemy`` scaffold has been renamed ``alchemy``, replacing the + older (traversal-based) ``alchemy`` scaffold (which has been retired). + +- The ``starter`` scaffold now uses URL dispatch by default. + +1.2 (2011-09-12) +================ + +Features +-------- + +- Route pattern replacement marker names can now begin with an underscore. + See https://github.com/Pylons/pyramid/issues/276. + +1.2b3 (2011-09-11) +================== + +Bug Fixes +--------- + +- The route prefix was not taken into account when a static view was added in + an "include". See https://github.com/Pylons/pyramid/issues/266 . + +1.2b2 (2011-09-08) +================== + +Bug Fixes +--------- + +- The 1.2b1 tarball was a brownbag (particularly for Windows users) because + it contained filenames with stray quotation marks in inappropriate places. + We depend on ``setuptools-git`` to produce release tarballs, and when it + was run to produce the 1.2b1 tarball, it didn't yet cope well with files + present in git repositories with high-order characters in their filenames. + +Documentation +------------- + +- Minor tweaks to the "Introduction" narrative chapter example app and + wording. + +1.2b1 (2011-09-08) +================== + +Bug Fixes +--------- + +- Sometimes falling back from territory translations (``de_DE``) to language + translations (``de``) would not work properly when using a localizer. See + https://github.com/Pylons/pyramid/issues/263 + +- The static file serving machinery could not serve files that started with a + ``.`` (dot) character. + +- Static files with high-order (super-ASCII) characters in their names could + not be served by a static view. The static file serving machinery + inappropriately URL-quoted path segments in filenames when asking for files + from the filesystem. + +- Within ``pyramid.traversal.traversal_path`` , canonicalize URL segments + from UTF-8 to Unicode before checking whether a segment matches literally + one of ``.``, the empty string, or ``..`` in case there's some sneaky way + someone might tunnel those strings via UTF-8 that don't match the literals + before decoded. + +Documentation +------------- + +- Added a "What Makes Pyramid Unique" section to the Introduction narrative + chapter. + +1.2a6 (2011-09-06) +================== + +Bug Fixes +--------- + +- AuthTktAuthenticationPolicy with a ``reissue_time`` interfered with logout. + See https://github.com/Pylons/pyramid/issues/262. + +Internal +-------- + +- Internalize code previously depended upon as imports from the + ``paste.auth`` module (futureproof). + +- Replaced use of ``paste.urlparser.StaticURLParser`` with a derivative of + Chris Rossi's "happy" static file serving code (futureproof). + +- Fixed test suite; on some systems tests would fail due to indeterminate + test run ordering and a double-push-single-pop of a shared test variable. + +Behavior Differences +-------------------- + +- An ETag header is no longer set when serving a static file. A + Last-Modified header is set instead. + +- Static file serving no longer supports the ``wsgi.file_wrapper`` extension. + +- Instead of returning a ``403 Forbidden`` error when a static file is served + that cannot be accessed by the Pyramid process' user due to file + permissions, an IOError (or similar) will be raised. + +Scaffolds +--------- + +- All scaffolds now send the ``cache_max_age`` parameter to the + ``add_static_view`` method. + +1.2a5 (2011-09-04) +================== + +Bug Fixes +--------- + +- The ``route_prefix`` of a configurator was not properly taken into account + when registering routes in certain circumstances. See + https://github.com/Pylons/pyramid/issues/260 + +Dependencies +------------ + +- The ``zope.configuration`` package is no longer a dependency. + +1.2a4 (2011-09-02) +================== + +Features +-------- + +- Support an ``onerror`` keyword argument to + ``pyramid.config.Configurator.scan()``. This onerror keyword argument is + passed to ``venusian.Scanner.scan()`` to influence error behavior when + an exception is raised during scanning. + +- The ``request_method`` predicate argument to + ``pyramid.config.Configurator.add_view`` and + ``pyramid.config.Configurator.add_route`` is now permitted to be a tuple of + HTTP method names. Previously it was restricted to being a string + representing a single HTTP method name. + +- Undeprecated ``pyramid.traversal.find_model``, + ``pyramid.traversal.model_path``, ``pyramid.traversal.model_path_tuple``, + and ``pyramid.url.model_url``, which were all deprecated in Pyramid 1.0. + There's just not much cost to keeping them around forever as aliases to + their renamed ``resource_*`` prefixed functions. + +- Undeprecated ``pyramid.view.bfg_view``, which was deprecated in Pyramid + 1.0. This is a low-cost alias to ``pyramid.view.view_config`` which we'll + just keep around forever. + +Dependencies +------------ + +- Pyramid now requires Venusian 1.0a1 or better to support the ``onerror`` + keyword argument to ``pyramid.config.Configurator.scan``. + +1.2a3 (2011-08-29) +================== + +Bug Fixes +--------- + +- Pyramid did not properly generate static URLs using + ``pyramid.url.static_url`` when passed a caller-package relative path due + to a refactoring done in 1.2a1. + +- The ``settings`` object emitted a deprecation warning any time + ``__getattr__`` was called upon it. However, there are legitimate + situations in which ``__getattr__`` is called on arbitrary objects + (e.g. ``hasattr``). Now, the ``settings`` object only emits the warning + upon successful lookup. + +Internal +-------- + +- Use ``config.with_package`` in view_config decorator rather than + manufacturing a new renderer helper (cleanup). + +1.2a2 (2011-08-27) +================== + +Bug Fixes +--------- + +- When a ``renderers=`` argument is not specified to the Configurator + constructor, eagerly register and commit the default renderer set. This + permits the overriding of the default renderers, which was broken in 1.2a1 + without a commit directly after Configurator construction. + +- Mako rendering exceptions had the wrong value for an error message. + +- An include could not set a root factory successfully because the + Configurator constructor unconditionally registered one that would be + treated as if it were "the word of the user". + +Features +-------- + +- A session factory can now be passed in using the dotted name syntax. + +1.2a1 (2011-08-24) +================== + +Features +-------- + +- The ``[pshell]`` section in an ini configuration file now treats a + ``setup`` key as a dotted name that points to a callable that is passed the + bootstrap environment. It can mutate the environment as necessary for + great justice. + +- A new configuration setting named ``pyramid.includes`` is now available. + It is described in the "Environment Variables and ``.ini`` Files Settings" + narrative documentation chapter. + +- Added a ``route_prefix`` argument to the + ``pyramid.config.Configurator.include`` method. This argument allows you + to compose URL dispatch applications together. See the section entitled + "Using a Route Prefix to Compose Applications" in the "URL Dispatch" + narrative documentation chapter. + +- Added a ``pyramid.security.NO_PERMISSION_REQUIRED`` constant for use in + ``permission=`` statements to view configuration. This constant has a + value of the string ``__no_permission_required__``. This string value was + previously referred to in documentation; now the documentation uses the + constant. + +- Added a decorator-based way to configure a response adapter: + ``pyramid.response.response_adapter``. This decorator has the same use as + ``pyramid.config.Configurator.add_response_adapter`` but it's declarative. + +- The ``pyramid.events.BeforeRender`` event now has an attribute named + ``rendering_val``. This can be used to introspect the value returned by a + view in a BeforeRender subscriber. + +- New configurator directive: ``pyramid.config.Configurator.add_tween``. + This directive adds a "tween". A "tween" is used to wrap the Pyramid + router's primary request handling function. This is a feature may be used + by Pyramid framework extensions, to provide, for example, view timing + support and as a convenient place to hang bookkeeping code. + + Tweens are further described in the narrative docs section in the Hooks + chapter, named "Registering Tweens". + +- New paster command ``paster ptweens``, which prints the current "tween" + configuration for an application. See the section entitled "Displaying + Tweens" in the Command-Line Pyramid chapter of the narrative documentation + for more info. + +- The Pyramid debug logger now uses the standard logging configuration + (usually set up by Paste as part of startup). This means that output from + e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the + normal logging channels. The logger name of the debug logger will be the + package name of the *caller* of the Configurator's constructor. + +- A new attribute is available on request objects: ``exc_info``. Its value + will be ``None`` until an exception is caught by the Pyramid router, after + which it will be the result of ``sys.exc_info()``. + +- ``pyramid.testing.DummyRequest`` now implements the + ``add_finished_callback`` and ``add_response_callback`` methods. + +- New methods of the ``pyramid.config.Configurator`` class: + ``set_authentication_policy`` and ``set_authorization_policy``. These are + meant to be consumed mostly by add-on authors. + +- New Configurator method: ``set_root_factory``. + +- Pyramid no longer eagerly commits some default configuration statements at + Configurator construction time, which permits values passed in as + constructor arguments (e.g. ``authentication_policy`` and + ``authorization_policy``) to override the same settings obtained via an + "include". + +- Better Mako rendering exceptions via + ``pyramid.mako_templating.MakoRenderingException`` + +- New request methods: ``current_route_url``, ``current_route_path``, and + ``static_path``. + +- New functions in ``pyramid.url``: ``current_route_path`` and + ``static_path``. + +- The ``pyramid.request.Request.static_url`` API (and its brethren + ``pyramid.request.Request.static_path``, ``pyramid.url.static_url``, and + ``pyramid.url.static_path``) now accept an asbolute filename as a "path" + argument. This will generate a URL to an asset as long as the filename is + in a directory which was previously registered as a static view. + Previously, trying to generate a URL to an asset using an absolute file + path would raise a ValueError. + +- The ``RemoteUserAuthenticationPolicy ``, ``AuthTktAuthenticationPolicy``, + and ``SessionAuthenticationPolicy`` constructors now accept an additional + keyword argument named ``debug``. By default, this keyword argument is + ``False``. When it is ``True``, debug information will be sent to the + Pyramid debug logger (usually on stderr) when the ``authenticated_userid`` + or ``effective_principals`` method is called on any of these policies. The + output produced can be useful when trying to diagnose + authentication-related problems. + +- New view predicate: ``match_param``. Example: a view added via + ``config.add_view(aview, match_param='action=edit')`` will be called only + when the ``request.matchdict`` has a value inside it named ``action`` with + a value of ``edit``. + +Internal +-------- + +- The Pyramid "exception view" machinery is now implemented as a "tween" + (``pyramid.tweens.excview_tween_factory``). + +- WSGIHTTPException (HTTPFound, HTTPNotFound, etc) now has a new API named + "prepare" which renders the body and content type when it is provided with + a WSGI environ. Required for debug toolbar. + +- Once ``__call__`` or ``prepare`` is called on a WSGIHTTPException, the body + will be set, and subsequent calls to ``__call__`` will always return the + same body. Delete the body attribute to rerender the exception body. + +- Previously the ``pyramid.events.BeforeRender`` event *wrapped* a dictionary + (it addressed it as its ``_system`` attribute). Now it *is* a dictionary + (it inherits from ``dict``), and it's the value that is passed to templates + as a top-level dictionary. + +- The ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and + ``current_route_url`` functions in the ``pyramid.url`` package now delegate + to a method on the request they've been passed, instead of the other way + around. The pyramid.request.Request object now inherits from a mixin named + pyramid.url.URLMethodsMixin to make this possible, and all url/path + generation logic is embedded in this mixin. + +- Refactor ``pyramid.config`` into a package. + +- Removed the ``_set_security_policies`` method of the Configurator. + +- Moved the ``StaticURLInfo`` class from ``pyramid.static`` to + ``pyramid.config.views``. + +- Move the ``Settings`` class from ``pyramid.settings`` to + ``pyramid.config.settings``. + +- Move the ``OverrideProvider``, ``PackageOverrides``, ``DirectoryOverride``, + and ``FileOverride`` classes from ``pyramid.asset`` to + ``pyramid.config.assets``. + +Deprecations +------------ + +- All Pyramid-related deployment settings (e.g. ``debug_all``, + ``debug_notfound``) are now meant to be prefixed with the prefix + ``pyramid.``. For example: ``debug_all`` -> ``pyramid.debug_all``. The + old non-prefixed settings will continue to work indefinitely but supplying + them may eventually print a deprecation warning. All scaffolds and + tutorials have been changed to use prefixed settings. + +- The ``settings`` dictionary now raises a deprecation warning when you + attempt to access its values via ``__getattr__`` instead of + via ``__getitem__``. + +Backwards Incompatibilities +--------------------------- + +- If a string is passed as the ``debug_logger`` parameter to a Configurator, + that string is considered to be the name of a global Python logger rather + than a dotted name to an instance of a logger. + +- The ``pyramid.config.Configurator.include`` method now accepts only a + single ``callable`` argument (a sequence of callables used to be + permitted). If you are passing more than one ``callable`` to + ``pyramid.config.Configurator.include``, it will break. You now must now + instead make a separate call to the method for each callable. This change + was introduced to support the ``route_prefix`` feature of include. + +- It may be necessary to more strictly order configuration route and view + statements when using an "autocommitting" Configurator. In the past, it + was possible to add a view which named a route name before adding a route + with that name when you used an autocommitting configurator. For example:: + + config = Configurator(autocommit=True) + config.add_view('my.pkg.someview', route_name='foo') + config.add_route('foo', '/foo') + + The above will raise an exception when the view attempts to add itself. + Now you must add the route before adding the view:: + + config = Configurator(autocommit=True) + config.add_route('foo', '/foo') + config.add_view('my.pkg.someview', route_name='foo') + + This won't effect "normal" users, only people who have legacy BFG codebases + that used an autommitting configurator and possibly tests that use the + configurator API (the configurator returned by ``pyramid.testing.setUp`` is + an autocommitting configurator). The right way to get around this is to + use a non-autocommitting configurator (the default), which does not have + these directive ordering requirements. + +- The ``pyramid.config.Configurator.add_route`` directive no longer returns a + route object. This change was required to make route vs. view + configuration processing work properly. + +Documentation +------------- + +- Narrative and API documentation which used the ``route_url``, + ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` + functions in the ``pyramid.url`` package have now been changed to use + eponymous methods of the request instead. + +- Added a section entitled "Using a Route Prefix to Compose Applications" to + the "URL Dispatch" narrative documentation chapter. + +- Added a new module to the API docs: ``pyramid.tweens``. + +- Added a "Registering Tweens" section to the "Hooks" narrative chapter. + +- Added a "Displaying Tweens" section to the "Command-Line Pyramid" narrative + chapter. + +- Added documentation for the ``pyramid.tweens`` and ``pyramid.includes`` + configuration settings to the "Environment Variables and ``.ini`` Files + Settings" chapter. + +- Added a Logging chapter to the narrative docs (based on the Pylons logging + docs, thanks Phil). + +- Added a Paste chapter to the narrative docs (moved content from the Project + chapter). + +- Added the ``pyramid.interfaces.IDict`` interface representing the methods + of a dictionary, for documentation purposes only (IMultiDict and + IBeforeRender inherit from it). + +- All tutorials now use - The ``route_url``, ``route_path``, + ``resource_url``, ``static_url``, and ``current_route_url`` methods of the + request rather than the function variants imported from ``pyramid.url``. + +- The ZODB wiki tutorial now uses the ``pyramid_zodbconn`` package rather + than the ``repoze.zodbconn`` package to provide ZODB integration. + +Dependency Changes +------------------ + +- Pyramid now relies on PasteScript >= 1.7.4. This version contains a + feature important for allowing flexible logging configuration. + +Scaffolds +---------- + +- All scaffolds now use the ``pyramid_tm`` package rather than the + ``repoze.tm2`` middleware to manage transaction management. + +- The ZODB scaffold now uses the ``pyramid_zodbconn`` package rather than the + ``repoze.zodbconn`` package to provide ZODB integration. + +- All scaffolds now use the ``pyramid_debugtoolbar`` package rather than the + ``WebError`` package to provide interactive debugging features. + +- Projects created via a scaffold no longer depend on the ``WebError`` + package at all; configuration in the ``production.ini`` file which used to + require its ``error_catcher`` middleware has been removed. Configuring + error catching / email sending is now the domain of the ``pyramid_exclog`` + package (see http://docs.pylonsproject.org/projects/pyramid_exclog/en/latest/). + +Bug Fixes +--------- + +- Fixed an issue with the default renderer not working at certain times. See + https://github.com/Pylons/pyramid/issues/249 + + +1.1 (2011-07-22) +================ + +Features +-------- + +- Added the ``pyramid.renderers.null_renderer`` object as an API. The null + renderer is an object that can be used in advanced integration cases as + input to the view configuration ``renderer=`` argument. When the null + renderer is used as a view renderer argument, Pyramid avoids converting the + view callable result into a Response object. This is useful if you want to + reuse the view configuration and lookup machinery outside the context of + its use by the Pyramid router. This feature was added for consumption by + the ``pyramid_rpc`` package, which uses view configuration and lookup + outside the context of a router in exactly this way. ``pyramid_rpc`` has + been broken under 1.1 since 1.1b1; adding it allows us to make it work + again. + +- Change all scaffolding templates that point to docs.pylonsproject.org to + use ``/projects/pyramid/current`` rather than ``/projects/pyramid/dev``. + +Internals +--------- + +- Remove ``compat`` code that served only the purpose of providing backwards + compatibility with Python 2.4. + +- Add a deprecation warning for non-API function + ``pyramid.renderers.renderer_from_name`` which has seen use in the wild. + +- Add a ``clone`` method to ``pyramid.renderers.RendererHelper`` for use by + the ``pyramid.view.view_config`` decorator. + +Documentation +------------- + +- Fixed two typos in wiki2 (SQLA + URL Dispatch) tutorial. + +- Reordered chapters in narrative section for better new user friendliness. + +- Added more indexing markers to sections in documentation. + +1.1b4 (2011-07-18) +================== + +Documentation +------------- + +- Added a section entitled "Writing a Script" to the "Command-Line Pyramid" + chapter. + +Backwards Incompatibilities +--------------------------- + +- We added the ``pyramid.scripting.make_request`` API too hastily in 1.1b3. + It has been removed. Sorry for any inconvenience. Use the + ``pyramid.request.Request.blank`` API instead. + +Features +-------- + +- The ``paster pshell``, ``paster pviews``, and ``paster proutes`` commands + each now under the hood uses ``pyramid.paster.bootstrap``, which makes it + possible to supply an ``.ini`` file without naming the "right" section in + the file that points at the actual Pyramid application. Instead, you can + generally just run ``paster {pshell|proutes|pviews} development.ini`` and + it will do mostly the right thing. + +Bug Fixes +--------- + +- Omit custom environ variables when rendering a custom exception template in + ``pyramid.httpexceptions.WSGIHTTPException._set_default_attrs``; + stringifying thse may trigger code that should not be executed; see + https://github.com/Pylons/pyramid/issues/239 + +1.1b3 (2011-07-15) +================== + +Features +-------- + +- Fix corner case to ease semifunctional testing of views: create a new + rendererinfo to clear out old registry on a rescan. See + https://github.com/Pylons/pyramid/pull/234. + +- New API class: ``pyramid.static.static_view``. This supersedes the + deprecated ``pyramid.view.static`` class. ``pyramid.static.static_view`` + by default serves up documents as the result of the request's + ``path_info``, attribute rather than it's ``subpath`` attribute (the + inverse was true of ``pyramid.view.static``, and still is). + ``pyramid.static.static_view`` exposes a ``use_subpath`` flag for use when + you want the static view to behave like the older deprecated version. + +- A new API function ``pyramid.paster.bootstrap`` has been added to make + writing scripts that bootstrap a Pyramid environment easier, e.g.:: + + from pyramid.paster import bootstrap + info = bootstrap('/path/to/my/development.ini') + request = info['request'] + print request.route_url('myroute') + +- A new API function ``pyramid.scripting.prepare`` has been added. It is a + lower-level analogue of ``pyramid.paster.boostrap`` that accepts a request + and a registry instead of a config file argument, and is used for the same + purpose:: + + from pyramid.scripting import prepare + info = prepare(registry=myregistry) + request = info['request'] + print request.route_url('myroute') + +- A new API function ``pyramid.scripting.make_request`` has been added. The + resulting request will have a ``registry`` attribute. It is meant to be + used in conjunction with ``pyramid.scripting.prepare`` and/or + ``pyramid.paster.bootstrap`` (both of which accept a request as an + argument):: + + from pyramid.scripting import make_request + request = make_request('/') + +- New API attribute ``pyramid.config.global_registries`` is an iterable + object that contains references to every Pyramid registry loaded into the + current process via ``pyramid.config.Configurator.make_app``. It also has + a ``last`` attribute containing the last registry loaded. This is used by + the scripting machinery, and is available for introspection. + +Deprecations +------------ + +- The ``pyramid.view.static`` class has been deprecated in favor of the newer + ``pyramid.static.static_view`` class. A deprecation warning is raised when + it is used. You should replace it with a reference to + ``pyramid.static.static_view`` with the ``use_subpath=True`` argument. + +Bug Fixes +--------- + +- Without a mo-file loaded for the combination of domain/locale, + ``pyramid.i18n.Localizer.pluralize`` run using that domain/locale + combination raised an inscrutable "translations object has no attr + 'plural'" error. Now, instead it "works" (it uses a germanic pluralization + by default). It's nonsensical to try to pluralize something without + translations for that locale/domain available, but this behavior matches + the behavior of ``pyramid.i18n.Localizer.translate`` so it's at least + consistent; see https://github.com/Pylons/pyramid/issues/235. + +1.1b2 (2011-07-13) +================== + +Features +-------- + +- New environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and new + configuration file value ``prevent_http_cache``. These are synomymous and + allow you to prevent HTTP cache headers from being set by Pyramid's + ``http_cache`` machinery globally in a process. see the "Influencing HTTP + Caching" section of the "View Configuration" narrative chapter and the + detailed documentation for this setting in the "Environment Variables and + Configuration Settings" narrative chapter. + +Behavior Changes +---------------- + +- Previously, If a ``BeforeRender`` event subscriber added a value via the + ``__setitem__`` or ``update`` methods of the event object with a key that + already existed in the renderer globals dictionary, a ``KeyError`` was + raised. With the deprecation of the "add_renderer_globals" feature of the + configurator, there was no way to override an existing value in the + renderer globals dictionary that already existed. Now, the event object + will overwrite an older value that is already in the globals dictionary + when its ``__setitem__`` or ``update`` is called (as well as the new + ``setdefault`` method), just like a plain old dictionary. As a result, for + maximum interoperability with other third-party subscribers, if you write + an event subscriber meant to be used as a BeforeRender subscriber, your + subscriber code will now need to (using ``.get`` or ``__contains__`` of the + event object) ensure no value already exists in the renderer globals + dictionary before setting an overriding value. + +Bug Fixes +--------- + +- The ``Configurator.add_route`` method allowed two routes with the same + route to be added without an intermediate ``config.commit()``. If you now + receive a ``ConfigurationError`` at startup time that appears to be + ``add_route`` related, you'll need to either a) ensure that all of your + route names are unique or b) call ``config.commit()`` before adding a + second route with the name of a previously added name or c) use a + Configurator that works in ``autocommit`` mode. + +- The ``pyramid_routesalchemy`` and ``pyramid_alchemy`` scaffolds + inappropriately used ``DBSession.rollback()`` instead of + ``transaction.abort()`` in one place. + +- We now clear ``request.response`` before we invoke an exception view; an + exception view will be working with a request.response that has not been + touched by any code prior to the exception. + +- Views associated with routes with spaces in the route name may not have + been looked up correctly when using Pyramid with ``zope.interface`` 3.6.4 + and better. See https://github.com/Pylons/pyramid/issues/232. + +Documentation +------------- + +- Wiki2 (SQLAlchemy + URL Dispatch) tutorial ``models.initialize_sql`` didn't + match the ``pyramid_routesalchemy`` scaffold function of the same name; it + didn't get synchronized when it was changed in the scaffold. + +- New documentation section in View Configuration narrative chapter: + "Influencing HTTP Caching". + +1.1b1 (2011-07-10) +================== + +Features +-------- + +- It is now possible to invoke ``paster pshell`` even if the paste ini file + section name pointed to in its argument is not actually a Pyramid WSGI + application. The shell will work in a degraded mode, and will warn the + user. See "The Interactive Shell" in the "Creating a Pyramid Project" + narrative documentation section. + +- ``paster pshell`` now offers more built-in global variables by default + (including ``app`` and ``settings``). See "The Interactive Shell" in the + "Creating a Pyramid Project" narrative documentation section. + +- It is now possible to add a ``[pshell]`` section to your application's .ini + configuration file, which influences the global names available to a pshell + session. See "Extending the Shell" in the "Creating a Pyramid Project" + narrative documentation chapter. + +- The ``config.scan`` method has grown a ``**kw`` argument. ``kw`` argument + represents a set of keyword arguments to pass to the Venusian ``Scanner`` + object created by Pyramid. (See the Venusian documentation for more + information about ``Scanner``). + +- New request property: ``json_body``. This property will return the + JSON-decoded variant of the request body. If the request body is not + well-formed JSON, this property will raise an exception. + +- A new value ``http_cache`` can be used as a view configuration + parameter. + + When you supply an ``http_cache`` value to a view configuration, the + ``Expires`` and ``Cache-Control`` headers of a response generated by the + associated view callable are modified. The value for ``http_cache`` may be + one of the following: + + - A nonzero integer. If it's a nonzero integer, it's treated as a number + of seconds. This number of seconds will be used to compute the + ``Expires`` header and the ``Cache-Control: max-age`` parameter of + responses to requests which call this view. For example: + ``http_cache=3600`` instructs the requesting browser to 'cache this + response for an hour, please'. + + - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` + instance, it will be converted into a number of seconds, and that number + of seconds will be used to compute the ``Expires`` header and the + ``Cache-Control: max-age`` parameter of responses to requests which call + this view. For example: ``http_cache=datetime.timedelta(days=1)`` + instructs the requesting browser to 'cache this response for a day, + please'. + + - Zero (``0``). If the value is zero, the ``Cache-Control`` and + ``Expires`` headers present in all responses from this view will be + composed such that client browser cache (and any intermediate caches) are + instructed to never cache the response. + + - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, + {'public':True})``), the first value in the tuple may be a nonzero + integer or a ``datetime.timedelta`` instance; in either case this value + will be used as the number of seconds to cache the response. The second + value in the tuple must be a dictionary. The values present in the + dictionary will be used as input to the ``Cache-Control`` response + header. For example: ``http_cache=(3600, {'public':True})`` means 'cache + for an hour, and add ``public`` to the Cache-Control header of the + response'. All keys and values supported by the + ``webob.cachecontrol.CacheControl`` interface may be added to the + dictionary. Supplying ``{'public':True}`` is equivalent to calling + ``response.cache_control.public = True``. + + Providing a non-tuple value as ``http_cache`` is equivalent to calling + ``response.cache_expires(value)`` within your view's body. + + Providing a two-tuple value as ``http_cache`` is equivalent to calling + ``response.cache_expires(value[0], **value[1])`` within your view's body. + + If you wish to avoid influencing, the ``Expires`` header, and instead wish + to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` + with the first element of ``None``, e.g.: ``(None, {'public':True})``. + +Bug Fixes +--------- + +- Framework wrappers of the original view (such as http_cached and so on) + relied on being able to trust that the response they were receiving was an + IResponse. It wasn't always, because the response was resolved by the + router instead of early in the view wrapping process. This has been fixed. + +Documentation +------------- + +- Added a section in the "Webob" chapter named "Dealing With A JSON-Encoded + Request Body" (usage of ``request.json_body``). + +Behavior Changes +---------------- + +- The ``paster pshell``, ``paster proutes``, and ``paster pviews`` commands + now take a single argument in the form ``/path/to/config.ini#sectionname`` + rather than the previous 2-argument spelling ``/path/to/config.ini + sectionname``. ``#sectionname`` may be omitted, in which case ``#main`` is + assumed. + +1.1a4 (2011-07-01) +================== + +Bug Fixes +--------- + +- ``pyramid.testing.DummyRequest`` now raises deprecation warnings when + attributes deprecated for ``pyramid.request.Request`` are accessed (like + ``response_content_type``). This is for the benefit of folks running unit + tests which use DummyRequest instead of a "real" request, so they know + things are deprecated without necessarily needing a functional test suite. + +- The ``pyramid.events.subscriber`` directive behaved contrary to the + documentation when passed more than one interface object to its + constructor. For example, when the following listener was registered:: + + @subscriber(IFoo, IBar) + def expects_ifoo_events_and_ibar_events(event): + print event + + The Events chapter docs claimed that the listener would be registered and + listening for both ``IFoo`` and ``IBar`` events. Instead, it registered an + "object event" subscriber which would only be called if an IObjectEvent was + emitted where the object interface was ``IFoo`` and the event interface was + ``IBar``. + + The behavior now matches the documentation. If you were relying on the + buggy behavior of the 1.0 ``subscriber`` directive in order to register an + object event subscriber, you must now pass a sequence to indicate you'd + like to register a subscriber for an object event. e.g.:: + + @subscriber([IFoo, IBar]) + def expects_object_event(object, event): + print object, event + +Features +-------- + +- Add JSONP renderer (see "JSONP renderer" in the Renderers chapter of the + documentation). + +Deprecations +------------ + +- Deprecated the ``set_renderer_globals_factory`` method of the Configurator + and the ``renderer_globals`` Configurator constructor parameter. + +Documentation +------------- + +- The Wiki and Wiki2 tutorial "Tests" chapters each had two bugs: neither did + told the user to depend on WebTest, and 2 tests failed in each as the + result of changes to Pyramid itself. These issues have been fixed. + +- Move 1.0.X CHANGES.txt entries to HISTORY.txt. + +1.1a3 (2011-06-26) +================== + +Features +-------- + +- Added ``mako.preprocessor`` config file parameter; allows for a Mako + preprocessor to be specified as a Python callable or Python dotted name. + See https://github.com/Pylons/pyramid/pull/183 for rationale. + +Bug fixes +--------- + +- Pyramid would raise an AttributeError in the Configurator when attempting + to set a ``__text__`` attribute on a custom predicate that was actually a + classmethod. See https://github.com/Pylons/pyramid/pull/217 . + +- Accessing or setting deprecated response_* attrs on request + (e.g. ``response_content_type``) now issues a deprecation warning at access + time rather than at rendering time. + +1.1a2 (2011-06-22) +================== + +Bug Fixes +--------- + +- 1.1a1 broke Akhet by not providing a backwards compatibility import shim + for ``pyramid.paster.PyramidTemplate``. Now one has been added, although a + deprecation warning is emitted when Akhet imports it. + +- If multiple specs were provided in a single call to + ``config.add_translation_dirs``, the directories were inserted into the + beginning of the directory list in the wrong order: they were inserted in + the reverse of the order they were provided in the ``*specs`` list (items + later in the list were added before ones earlier in the list). This is now + fixed. + +Backwards Incompatibilities +--------------------------- + +- The pyramid Router attempted to set a value into the key + ``environ['repoze.bfg.message']`` when it caught a view-related exception + for backwards compatibility with applications written for ``repoze.bfg`` + during error handling. It did this by using code that looked like so:: + + # "why" is an exception object + try: + msg = why[0] + except: + msg = '' + + environ['repoze.bfg.message'] = msg + + Use of the value ``environ['repoze.bfg.message']`` was docs-deprecated in + Pyramid 1.0. Our standing policy is to not remove features after a + deprecation for two full major releases, so this code was originally slated + to be removed in Pyramid 1.2. However, computing the + ``repoze.bfg.message`` value was the source of at least one bug found in + the wild (https://github.com/Pylons/pyramid/issues/199), and there isn't a + foolproof way to both preserve backwards compatibility and to fix the bug. + Therefore, the code which sets the value has been removed in this release. + Code in exception views which relies on this value's presence in the + environment should now use the ``exception`` attribute of the request + (e.g. ``request.exception[0]``) to retrieve the message instead of relying + on ``request.environ['repoze.bfg.message']``. + +1.1a1 (2011-06-20) +================== + +Documentation +------------- + +- The term "template" used to refer to both "paster templates" and "rendered + templates" (templates created by a rendering engine. i.e. Mako, Chameleon, + Jinja, etc.). "Paster templates" will now be refered to as "scaffolds", + whereas the name for "rendered templates" will remain as "templates." + +- The ``wiki`` (ZODB+Traversal) tutorial was updated slightly. + +- The ``wiki2`` (SQLA+URL Dispatch) tutorial was updated slightly. + +- Make ``pyramid.interfaces.IAuthenticationPolicy`` and + ``pyramid.interfaces.IAuthorizationPolicy`` public interfaces, and refer to + them within the ``pyramid.authentication`` and ``pyramid.authorization`` + API docs. + +- Render the function definitions for each exposed interface in + ``pyramid.interfaces``. + +- Add missing docs reference to + ``pyramid.config.Configurator.set_view_mapper`` and refer to it within + Hooks chapter section named "Using a View Mapper". + +- Added section to the "Environment Variables and ``.ini`` File Settings" + chapter in the narrative documentation section entitled "Adding a Custom + Setting". + +- Added documentation for a "multidict" (e.g. the API of ``request.POST``) as + interface API documentation. + +- Added a section to the "URL Dispatch" narrative chapter regarding the new + "static" route feature. + +- Added "What's New in Pyramid 1.1" to HTML rendering of documentation. + +- Added API docs for ``pyramid.authentication.SessionAuthenticationPolicy``. + +- Added API docs for ``pyramid.httpexceptions.exception_response``. + +- Added "HTTP Exceptions" section to Views narrative chapter including a + description of ``pyramid.httpexceptions.exception_response``. + +Features +-------- + +- Add support for language fallbacks: when trying to translate for a + specific territory (such as ``en_GB``) fall back to translations + for the language (ie ``en``). This brings the translation behaviour in line + with GNU gettext and fixes partially translated texts when using C + extensions. + +- New authentication policy: + ``pyramid.authentication.SessionAuthenticationPolicy``, which uses a session + to store credentials. + +- Accessing the ``response`` attribute of a ``pyramid.request.Request`` + object (e.g. ``request.response`` within a view) now produces a new + ``pyramid.response.Response`` object. This feature is meant to be used + mainly when a view configured with a renderer needs to set response + attributes: all renderers will use the Response object implied by + ``request.response`` as the response object returned to the router. + + ``request.response`` can also be used by code in a view that does not use a + renderer, however the response object that is produced by + ``request.response`` must be returned when a renderer is not in play (it is + not a "global" response). + +- Integers and longs passed as ``elements`` to ``pyramid.url.resource_url`` + or ``pyramid.request.Request.resource_url`` e.g. ``resource_url(context, + request, 1, 2)`` (``1`` and ``2`` are the ``elements``) will now be + converted implicitly to strings in the result. Previously passing integers + or longs as elements would cause a TypeError. + +- ``pyramid_alchemy`` paster template now uses ``query.get`` rather than + ``query.filter_by`` to take better advantage of identity map caching. + +- ``pyramid_alchemy`` paster template now has unit tests. + +- Added ``pyramid.i18n.make_localizer`` API (broken out from + ``get_localizer`` guts). + +- An exception raised by a NewRequest event subscriber can now be caught by + an exception view. + +- It is now possible to get information about why Pyramid raised a Forbidden + exception from within an exception view. The ``ACLDenied`` object returned + by the ``permits`` method of each stock authorization policy + (``pyramid.interfaces.IAuthorizationPolicy.permits``) is now attached to + the Forbidden exception as its ``result`` attribute. Therefore, if you've + created a Forbidden exception view, you can see the ACE, ACL, permission, + and principals involved in the request as + eg. ``context.result.permission``, ``context.result.acl``, etc within the + logic of the Forbidden exception view. + +- Don't explicitly prevent the ``timeout`` from being lower than the + ``reissue_time`` when setting up an ``AuthTktAuthenticationPolicy`` + (previously such a configuration would raise a ``ValueError``, now it's + allowed, although typically nonsensical). Allowing the nonsensical + configuration made the code more understandable and required fewer tests. + +- A new paster command named ``paster pviews`` was added. This command + prints a summary of potentially matching views for a given path. See the + section entitled "Displaying Matching Views for a Given URL" in the "View + Configuration" chapter of the narrative documentation for more information. + +- The ``add_route`` method of the Configurator now accepts a ``static`` + argument. If this argument is ``True``, the added route will never be + considered for matching when a request is handled. Instead, it will only + be useful for URL generation via ``route_url`` and ``route_path``. See the + section entitled "Static Routes" in the URL Dispatch narrative chapter for + more information. + +- A default exception view for the context + ``pyramid.interfaces.IExceptionResponse`` is now registered by default. + This means that an instance of any exception response class imported from + ``pyramid.httpexceptions`` (such as ``HTTPFound``) can now be raised from + within view code; when raised, this exception view will render the + exception to a response. + +- A function named ``pyramid.httpexceptions.exception_response`` is a + shortcut that can be used to create HTTP exception response objects using + an HTTP integer status code. + +- The Configurator now accepts an additional keyword argument named + ``exceptionresponse_view``. By default, this argument is populated with a + default exception view function that will be used when a response is raised + as an exception. When ``None`` is passed for this value, an exception view + for responses will not be registered. Passing ``None`` returns the + behavior of raising an HTTP exception to that of Pyramid 1.0 (the exception + will propagate to middleware and to the WSGI server). + +- The ``pyramid.request.Request`` class now has a ``ResponseClass`` interface + which points at ``pyramid.response.Response``. + +- The ``pyramid.response.Response`` class now has a ``RequestClass`` + interface which points at ``pyramid.request.Request``. + +- It is now possible to return an arbitrary object from a Pyramid view + callable even if a renderer is not used, as long as a suitable adapter to + ``pyramid.interfaces.IResponse`` is registered for the type of the returned + object by using the new + ``pyramid.config.Configurator.add_response_adapter`` API. See the section + in the Hooks chapter of the documentation entitled "Changing How Pyramid + Treats View Responses". + +- The Pyramid router will now, by default, call the ``__call__`` method of + WebOb response objects when returning a WSGI response. This means that, + among other things, the ``conditional_response`` feature of WebOb response + objects will now behave properly. + +- New method named ``pyramid.request.Request.is_response``. This method + should be used instead of the ``pyramid.view.is_response`` function, which + has been deprecated. + +Bug Fixes +--------- + +- URL pattern markers used in URL dispatch are permitted to specify a custom + regex. For example, the pattern ``/{foo:\d+}`` means to match ``/12345`` + (foo==12345 in the match dictionary) but not ``/abc``. However, custom + regexes in a pattern marker which used squiggly brackets did not work. For + example, ``/{foo:\d{4}}`` would fail to match ``/1234`` and + ``/{foo:\d{1,2}}`` would fail to match ``/1`` or ``/11``. One level of + inner squiggly brackets is now recognized so that the prior two patterns + given as examples now work. See also + https://github.com/Pylons/pyramid/issues/#issue/123. + +- Don't send port numbers along with domain information in cookies set by + AuthTktCookieHelper (see https://github.com/Pylons/pyramid/issues/131). + +- ``pyramid.url.route_path`` (and the shortcut + ``pyramid.request.Request.route_url`` method) now include the WSGI + SCRIPT_NAME at the front of the path if it is not empty (see + https://github.com/Pylons/pyramid/issues/135). + +- ``pyramid.testing.DummyRequest`` now has a ``script_name`` attribute (the + empty string). + +- Don't quote ``:@&+$,`` symbols in ``*elements`` passed to + ``pyramid.url.route_url`` or ``pyramid.url.resource_url`` (see + https://github.com/Pylons/pyramid/issues#issue/141). + +- Include SCRIPT_NAME in redirects issued by + ``pyramid.view.append_slash_notfound_view`` (see + https://github.com/Pylons/pyramid/issues#issue/149). + +- Static views registered with ``config.add_static_view`` which also included + a ``permission`` keyword argument would not work as expected, because + ``add_static_view`` also registered a route factory internally. Because a + route factory was registered internally, the context checked by the Pyramid + permission machinery never had an ACL. ``add_static_view`` no longer + registers a route with a factory, so the default root factory will be used. + +- ``config.add_static_view`` now passes extra keyword arguments it receives + to ``config.add_route`` (calling add_static_view is mostly logically + equivalent to adding a view of the type ``pyramid.static.static_view`` + hooked up to a route with a subpath). This makes it possible to pass e.g., + ``factory=`` to ``add_static_view`` to protect a particular static view + with a custom ACL. + +- ``testing.DummyRequest`` used the wrong registry (the global registry) as + ``self.registry`` if a dummy request was created *before* ``testing.setUp`` + was executed (``testing.setUp`` pushes a local registry onto the + threadlocal stack). Fixed by implementing ``registry`` as a property for + DummyRequest instead of eagerly assigning an attribute. + See also https://github.com/Pylons/pyramid/issues/165 + +- When visiting a URL that represented a static view which resolved to a + subdirectory, the ``index.html`` of that subdirectory would not be served + properly. Instead, a redirect to ``/subdir`` would be issued. This has + been fixed, and now visiting a subdirectory that contains an ``index.html`` + within a static view returns the index.html properly. See also + https://github.com/Pylons/pyramid/issues/67. + +- Redirects issued by a static view did not take into account any existing + ``SCRIPT_NAME`` (such as one set by a url mapping composite). Now they do. + +- The ``pyramid.wsgi.wsgiapp2`` decorator did not take into account the + ``SCRIPT_NAME`` in the origin request. + +- The ``pyramid.wsgi.wsgiapp2`` decorator effectively only worked when it + decorated a view found via traversal; it ignored the ``PATH_INFO`` that was + part of a url-dispatch-matched view. + +Deprecations +------------ + +- Deprecated all assignments to ``request.response_*`` attributes (for + example ``request.response_content_type = 'foo'`` is now deprecated). + Assignments and mutations of assignable request attributes that were + considered by the framework for response influence are now deprecated: + ``response_content_type``, ``response_headerlist``, ``response_status``, + ``response_charset``, and ``response_cache_for``. Instead of assigning + these to the request object for later detection by the rendering machinery, + users should use the appropriate API of the Response object created by + accessing ``request.response`` (e.g. code which does + ``request.response_content_type = 'abc'`` should be changed to + ``request.response.content_type = 'abc'``). + +- Passing view-related parameters to + ``pyramid.config.Configurator.add_route`` is now deprecated. Previously, a + view was permitted to be connected to a route using a set of ``view*`` + parameters passed to the ``add_route`` method of the Configurator. This + was a shorthand which replaced the need to perform a subsequent call to + ``add_view``. For example, it was valid (and often recommended) to do:: + + config.add_route('home', '/', view='mypackage.views.myview', + view_renderer='some/renderer.pt') + + Passing ``view*`` arguments to ``add_route`` is now deprecated in favor of + connecting a view to a predefined route via ``Configurator.add_view`` using + the route's ``route_name`` parameter. As a result, the above example + should now be spelled:: + + config.add_route('home', '/') + config.add_view('mypackage.views.myview', route_name='home') + renderer='some/renderer.pt') + + This deprecation was done to reduce confusion observed in IRC, as well as + to (eventually) reduce documentation burden (see also + https://github.com/Pylons/pyramid/issues/164). A deprecation warning is + now issued when any view-related parameter is passed to + ``Configurator.add_route``. + +- Passing an ``environ`` dictionary to the ``__call__`` method of a + "traverser" (e.g. an object that implements + ``pyramid.interfaces.ITraverser`` such as an instance of + ``pyramid.traversal.ResourceTreeTraverser``) as its ``request`` argument + now causes a deprecation warning to be emitted. Consumer code should pass a + ``request`` object instead. The fact that passing an environ dict is + permitted has been documentation-deprecated since ``repoze.bfg`` 1.1, and + this capability will be removed entirely in a future version. + +- The following (undocumented, dictionary-like) methods of the + ``pyramid.request.Request`` object have been deprecated: ``__contains__``, + ``__delitem__``, ``__getitem__``, ``__iter__``, ``__setitem__``, ``get``, + ``has_key``, ``items``, ``iteritems``, ``itervalues``, ``keys``, ``pop``, + ``popitem``, ``setdefault``, ``update``, and ``values``. Usage of any of + these methods will cause a deprecation warning to be emitted. These + methods were added for internal compatibility in ``repoze.bfg`` 1.1 (code + that currently expects a request object expected an environ object in BFG + 1.0 and before). In a future version, these methods will be removed + entirely. + +- Deprecated ``pyramid.view.is_response`` function in favor of (newly-added) + ``pyramid.request.Request.is_response`` method. Determining if an object + is truly a valid response object now requires access to the registry, which + is only easily available as a request attribute. The + ``pyramid.view.is_response`` function will still work until it is removed, + but now may return an incorrect answer under some (very uncommon) + circumstances. + +Behavior Changes +---------------- + +- The default Mako renderer is now configured to escape all HTML in + expression tags. This is intended to help prevent XSS attacks caused by + rendering unsanitized input from users. To revert this behavior in user's + templates, they need to filter the expression through the 'n' filter. + For example, ${ myhtml | n }. + See https://github.com/Pylons/pyramid/issues/193. + +- A custom request factory is now required to return a request object that + has a ``response`` attribute (or "reified"/lazy property) if they the + request is meant to be used in a view that uses a renderer. This + ``response`` attribute should be an instance of the class + ``pyramid.response.Response``. + +- The JSON and string renderer factories now assign to + ``request.response.content_type`` rather than + ``request.response_content_type``. + +- Each built-in renderer factory now determines whether it should change the + content type of the response by comparing the response's content type + against the response's default content type; if the content type is the + default content type (usually ``text/html``), the renderer changes the + content type (to ``application/json`` or ``text/plain`` for JSON and string + renderers respectively). + +- The ``pyramid.wsgi.wsgiapp2`` now uses a slightly different method of + figuring out how to "fix" ``SCRIPT_NAME`` and ``PATH_INFO`` for the + downstream application. As a result, those values may differ slightly from + the perspective of the downstream application (for example, ``SCRIPT_NAME`` + will now never possess a trailing slash). + +- Previously, ``pyramid.request.Request`` inherited from + ``webob.request.Request`` and implemented ``__getattr__``, ``__setattr__`` + and ``__delattr__`` itself in order to overidde "adhoc attr" WebOb behavior + where attributes of the request are stored in the environ. Now, + ``pyramid.request.Request`` object inherits from (the more recent) + ``webob.request.BaseRequest`` instead of ``webob.request.Request``, which + provides the same behavior. ``pyramid.request.Request`` no longer + implements its own ``__getattr__``, ``__setattr__`` or ``__delattr__`` as a + result. + +- ``pyramid.response.Response`` is now a *subclass* of + ``webob.response.Response`` (in order to directly implement the + ``pyramid.interfaces.IResponse`` interface). + +- The "exception response" objects importable from ``pyramid.httpexceptions`` + (e.g. ``HTTPNotFound``) are no longer just import aliases for classes that + actually live in ``webob.exc``. Instead, we've defined our own exception + classes within the module that mirror and emulate the ``webob.exc`` + exception response objects almost entirely. See the "Design Defense" doc + section named "Pyramid Uses its Own HTTP Exception Classes" for more + information. + +Backwards Incompatibilities +--------------------------- + +- Pyramid no longer supports Python 2.4. Python 2.5 or better is required to + run Pyramid 1.1+. + +- The Pyramid router now, by default, expects response objects returned from + view callables to implement the ``pyramid.interfaces.IResponse`` interface. + Unlike the Pyramid 1.0 version of this interface, objects which implement + IResponse now must define a ``__call__`` method that accepts ``environ`` + and ``start_response``, and which returns an ``app_iter`` iterable, among + other things. Previously, it was possible to return any object which had + the three WebOb ``app_iter``, ``headerlist``, and ``status`` attributes as + a response, so this is a backwards incompatibility. It is possible to get + backwards compatibility back by registering an adapter to IResponse from + the type of object you're now returning from view callables. See the + section in the Hooks chapter of the documentation entitled "Changing How + Pyramid Treats View Responses". + +- The ``pyramid.interfaces.IResponse`` interface is now much more extensive. + Previously it defined only ``app_iter``, ``status`` and ``headerlist``; now + it is basically intended to directly mirror the ``webob.Response`` API, + which has many methods and attributes. + +- The ``pyramid.httpexceptions`` classes named ``HTTPFound``, + ``HTTPMultipleChoices``, ``HTTPMovedPermanently``, ``HTTPSeeOther``, + ``HTTPUseProxy``, and ``HTTPTemporaryRedirect`` now accept ``location`` as + their first positional argument rather than ``detail``. This means that + you can do, e.g. ``return pyramid.httpexceptions.HTTPFound('http://foo')`` + rather than ``return + pyramid.httpexceptions.HTTPFound(location='http//foo')`` (the latter will + of course continue to work). + +Dependencies +------------ + +- Pyramid now depends on WebOb >= 1.0.2 as tests depend on the bugfix in that + release: "Fix handling of WSGI environs with missing ``SCRIPT_NAME``". + (Note that in reality, everyone should probably be using 1.0.4 or better + though, as WebOb 1.0.2 and 1.0.3 were effectively brownbag releases.) + +1.0 (2011-01-30) +================ + +Documentation +------------- + +- Fixed bug in ZODB Wiki tutorial (missing dependency on ``docutils`` in + "models" step within ``setup.py``). + +- Removed API documentation for ``pyramid.testing`` APIs named + ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``, + ``registerEventListener``, ``registerTemplateRenderer``, + ``registerDummyRenderer``, ``registerView``, ``registerUtility``, + ``registerAdapter``, ``registerSubscriber``, ``registerRoute``, + and ``registerSettings``. + +- Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid" + tutorials out of core documentation and into the Pyramid Tutorials site + (http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/). + +- Changed "Cleaning up After a Request" section in the URL Dispatch chapter + to use ``request.add_finished_callback`` instead of jamming an object with + a ``__del__`` into the WSGI environment. + +- Remove duplication of ``add_route`` API documentation from URL Dispatch + narrative chapter. + +- Remove duplication of API and narrative documentation in + ``pyramid.view.view_config`` API docs by pointing to + ``pyramid.config.add_view`` documentation and narrative chapter + documentation. + +- Removed some API documentation duplicated in narrative portions of + documentation + +- Removed "Overall Flow of Authentication" from SQLAlchemy + URL Dispatch + wiki tutorial due to print space concerns (moved to Pyramid Tutorials + site). + +Bug Fixes +--------- + +- Deprecated-since-BFG-1.2 APIs from ``pyramid.testing`` now properly emit + deprecation warnings. + +- Added ``egg:repoze.retry#retry`` middleware to the WSGI pipeline in ZODB + templates (retry ZODB conflict errors which occur in normal operations). + +- Removed duplicate implementations of ``is_response``. Two competing + implementations existed: one in ``pyramid.config`` and one in + ``pyramid.view``. Now the one defined in ``pyramid.view`` is used + internally by ``pyramid.config`` and continues to be advertised as an API. + +1.0b3 (2011-01-28) +================== + +Bug Fixes +--------- + +- Use © instead of copyright symbol in paster templates / tutorial + templates for the benefit of folks who cutnpaste and save to a non-UTF8 + format. + +- ``pyramid.view.append_slash_notfound_view`` now preserves GET query + parameters across redirects. + +Documentation +------------- + +- Beef up documentation related to ``set_default_permission``: explicitly + mention that default permissions also protect exception views. + +- Paster templates and tutorials now use spaces instead of tabs in their HTML + templates. + +1.0b2 (2011-01-24) +================== + +Bug Fixes +--------- + +- The ``production.ini`` generated by all paster templates now have an + effective logging level of WARN, which prevents e.g. SQLAlchemy statement + logging and other inappropriate output. + +- The ``production.ini`` of the ``pyramid_routesalchemy`` and + ``pyramid_alchemy`` paster templates did not have a ``sqlalchemy`` logger + section, preventing ``paster serve production.ini`` from working. + +- The ``pyramid_routesalchemy`` and ``pyramid_alchemy`` paster templates used + the ``{{package}}`` variable in a place where it should have used the + ``{{project}}`` variable, causing applications created with uppercase + letters e.g. ``paster create -t pyramid_routesalchemy Dibbus`` to fail to + start when ``paster serve development.ini`` was used against the result. + See https://github.com/Pylons/pyramid/issues/#issue/107 + +- The ``render_view`` method of ``pyramid.renderers.RendererHelper`` passed + an incorrect value into the renderer for ``renderer_info``. It now passes + an instance of ``RendererHelper`` instead of a dictionary, which is + consistent with other usages. See + https://github.com/Pylons/pyramid/issues#issue/106 + +- A bug existed in the ``pyramid.authentication.AuthTktCookieHelper`` which + would break any usage of an AuthTktAuthenticationPolicy when one was + configured to reissue its tokens (``reissue_time`` < ``timeout`` / + ``max_age``). Symptom: ``ValueError: ('Invalid token %r', '')``. See + https://github.com/Pylons/pyramid/issues#issue/108. + +1.0b1 (2011-01-21) +================== + +Features +-------- + +- The AuthTktAuthenticationPolicy now accepts a ``tokens`` parameter via + ``pyramid.security.remember``. The value must be a sequence of strings. + Tokens are placed into the auth_tkt "tokens" field and returned in the + auth_tkt cookie. + +- Add ``wild_domain`` argument to AuthTktAuthenticationPolicy, which defaults + to ``True``. If it is set to ``False``, the feature of the policy which + sets a cookie with a wildcard domain will be turned off. + +- Add a ``MANIFEST.in`` file to each paster template. See + https://github.com/Pylons/pyramid/issues#issue/95 + +Bug Fixes +--------- + +- ``testing.setUp`` now adds a ``settings`` attribute to the registry (both + when it's passed a registry without any settings and when it creates one). + +- The ``testing.setUp`` function now takes a ``settings`` argument, which + should be a dictionary. Its values will subsequently be available on the + returned ``config`` object as ``config.registry.settings``. + +Documentation +------------- + +- Added "What's New in Pyramid 1.0" chapter to HTML rendering of + documentation. + +- Merged caseman-master narrative editing branch, many wording fixes and + extensions. + +- Fix deprecated example showing ``chameleon_zpt`` API call in testing + narrative chapter. + +- Added "Adding Methods to the Configurator via ``add_directive``" section to + Advanced Configuration narrative chapter. + +- Add docs for ``add_finished_callback``, ``add_response_callback``, + ``route_path``, ``route_url``, and ``static_url`` methods to + ``pyramid.request.Request`` API docs. + +- Add (minimal) documentation about using I18N within Mako templates to + "Internationalization and Localization" narrative chapter. + +- Move content of "Forms" chapter back to "Views" chapter; I can't think of a + better place to put it. + +- Slightly improved interface docs for ``IAuthorizationPolicy``. + +- Minimally explain usage of custom regular expressions in URL dispatch + replacement markers within URL Dispatch chapter. + +Deprecations +------------- + +- Using the ``pyramid.view.bfg_view`` alias for ``pyramid.view.view_config`` + (a backwards compatibility shim) now issues a deprecation warning. + +Backwards Incompatibilities +--------------------------- + +- Using ``testing.setUp`` now registers an ISettings utility as a side + effect. Some test code which queries for this utility after + ``testing.setUp`` via queryAdapter will expect a return value of ``None``. + This code will need to be changed. + +- When a ``pyramid.exceptions.Forbidden`` error is raised, its status code + now ``403 Forbidden``. It was previously ``401 Unauthorized``, for + backwards compatibility purposes with ``repoze.bfg``. This change will + cause problems for users of Pyramid with ``repoze.who``, which intercepts + ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to pass + through. Those deployments will need to configure ``repoze.who`` to also + react to ``403 Forbidden``. + +- The default value for the ``cookie_on_exception`` parameter to + ``pyramid.session.UnencyrptedCookieSessionFactory`` is now ``True``. This + means that when view code causes an exception to be raised, and the session + has been mutated, a cookie will be sent back in the response. Previously + its default value was ``False``. + +Paster Templates +---------------- + +- The ``pyramid_zodb``, ``pyramid_routesalchemy`` and ``pyramid_alchemy`` + paster templates now use a default "commit veto" hook when configuring the + ``repoze.tm2`` transaction manager in ``development.ini``. This prevents a + transaction from being committed when the response status code is within + the 400 or 500 ranges. See also + http://docs.repoze.org/tm2/#using-a-commit-veto. + +1.0a10 (2011-01-18) +=================== + +Bug Fixes +--------- + +- URL dispatch now properly handles a ``.*`` or ``*`` appearing in a regex + match when used inside brackets. Resolves issue #90. + +Backwards Incompatibilities +--------------------------- + +- The ``add_handler`` method of a Configurator has been removed from the + Pyramid core. Handlers are now a feature of the ``pyramid_handlers`` + package, which can be downloaded from PyPI. Documentation for the package + should be available via + http://docs.pylonsproject.org/projects/pyramid_handlers/en/latest/, + which describes how + to add a configuration statement to your ``main`` block to reobtain this + method. You will also need to add an ``install_requires`` dependency upon + ``pyramid_handlers`` to your ``setup.py`` file. + +- The ``load_zcml`` method of a Configurator has been removed from the + Pyramid core. Loading ZCML is now a feature of the ``pyramid_zcml`` + package, which can be downloaded from PyPI. Documentation for the package + should be available via + http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest/, + which describes how + to add a configuration statement to your ``main`` block to reobtain this + method. You will also need to add an ``install_requires`` dependency upon + ``pyramid_zcml`` to your ``setup.py`` file. + +- The ``pyramid.includes`` subpackage has been removed. ZCML files which use + include the package ``pyramid.includes`` (e.g. ````) now must include the ``pyramid_zcml`` + package instead (e.g. ````). + +- The ``pyramid.view.action`` decorator has been removed from the Pyramid + core. Handlers are now a feature of the ``pyramid_handlers`` package. It + should now be imported from ``pyramid_handlers`` e.g. ``from + pyramid_handlers import action``. + +- The ``handler`` ZCML directive has been removed. It is now a feature of + the ``pyramid_handlers`` package. + +- The ``pylons_minimal``, ``pylons_basic`` and ``pylons_sqla`` paster + templates were removed. Use ``pyramid_sqla`` (available from PyPI) as a + generic replacement for Pylons-esque development. + +- The ``make_app`` function has been removed from the ``pyramid.router`` + module. It continues life within the ``pyramid_zcml`` package. This + leaves the ``pyramid.router`` module without any API functions. + +- The ``configure_zcml`` setting within the deployment settings (within + ``**settings`` passed to a Pyramid ``main`` function) has ceased to have any + meaning. + +Features +-------- + +- ``pyramid.testing.setUp`` and ``pyramid.testing.tearDown`` have been + undeprecated. They are now the canonical setup and teardown APIs for test + configuration, replacing "direct" creation of a Configurator. This is a + change designed to provide a facade that will protect against any future + Configurator deprecations. + +- Add ``charset`` attribute to ``pyramid.testing.DummyRequest`` + (unconditionally ``UTF-8``). + +- Add ``add_directive`` method to configurator, which allows framework + extenders to add methods to the configurator (ala ZCML directives). + +- When ``Configurator.include`` is passed a *module* as an argument, it + defaults to attempting to find and use a callable named ``includeme`` + within that module. This makes it possible to use + ``config.include('some.module')`` rather than + ``config.include('some.module.somefunc')`` as long as the include function + within ``some.module`` is named ``includeme``. + +- The ``bfg2pyramid`` script now converts ZCML include tags that have + ``repoze.bfg.includes`` as a package attribute to the value + ``pyramid_zcml``. For example, ```` + will be converted to ````. + +Paster Templates +---------------- + +- All paster templates now use ``pyramid.testing.setUp`` and + ``pyramid.testing.tearDown`` rather than creating a Configurator "by hand" + within their ``tests.py`` module, as per decision in features above. + +- The ``starter_zcml`` paster template has been moved to the ``pyramid_zcml`` + package. + +Documentation +------------- + +- The wiki and wiki2 tutorials now use ``pyramid.testing.setUp`` and + ``pyramid.testing.tearDown`` rather than creating a Configurator "by hand", + as per decision in features above. + +- The "Testing" narrative chapter now explains ``pyramid.testing.setUp`` and + ``pyramid.testing.tearDown`` instead of Configurator creation and + ``Configurator.begin()`` and ``Configurator.end()``. + +- Document the ``request.override_renderer`` attribute within the narrative + "Renderers" chapter in a section named "Overriding A Renderer at Runtime". + +- The "Declarative Configuration" narrative chapter has been removed (it was + moved to the ``pyramid_zcml`` package). + +- Most references to ZCML in narrative chapters have been removed or + redirected to ``pyramid_zcml`` locations. + +Deprecations +------------ + +- Deprecation warnings related to import of the following API functions were + added: ``pyramid.traversal.find_model``, ``pyramid.traversal.model_path``, + ``pyramid.traversal.model_path_tuple``, ``pyramid.url.model_url``. The + instructions emitted by the deprecation warnings instruct the developer to + change these method spellings to their ``resource`` equivalents. This is a + consequence of the mass concept rename of "model" to "resource" performed + in 1.0a7. + +1.0a9 (2011-01-08) +================== + +Bug Fixes +--------- + +- The ``proutes`` command tried too hard to resolve the view for printing, + resulting in exceptions when an exceptional root factory was encountered. + Instead of trying to resolve the view, if it cannot, it will now just print + ````. + +- The `self` argument was included in new methods of the ``ISession`` interface + signature, causing ``pyramid_beaker`` tests to fail. + +- Readd ``pyramid.traversal.model_path_tuple`` as an alias for + ``pyramid.traversal.resource_path_tuple`` for backwards compatibility. + +Features +-------- + +- Add a new API ``pyramid.url.current_route_url``, which computes a URL based + on the "current" route (if any) and its matchdict values. + +- ``config.add_view`` now accepts a ``decorator`` keyword argument, a callable + which will decorate the view callable before it is added to the registry. + +- If a handler class provides an ``__action_decorator__`` attribute (usually + a classmethod or staticmethod), use that as the decorator for each view + registration for that handler. + +- The ``pyramid.interfaces.IAuthenticationPolicy`` interface now specifies an + ``unauthenticated_userid`` method. This method supports an important + optimization required by people who are using persistent storages which do + not support object caching and whom want to create a "user object" as a + request attribute. + +- A new API has been added to the ``pyramid.security`` module named + ``unauthenticated_userid``. This API function calls the + ``unauthenticated_userid`` method of the effective security policy. + +- An ``unauthenticated_userid`` method has been added to the dummy + authentication policy returned by + ``pyramid.config.Configurator.testing_securitypolicy``. It returns the + same thing as that the dummy authentication policy's + ``authenticated_userid`` method. + +- The class ``pyramid.authentication.AuthTktCookieHelper`` is now an API. + This class can be used by third-party authentication policy developers to + help in the mechanics of authentication cookie-setting. + +- New constructor argument to Configurator: ``default_view_mapper``. Useful + to create systems that have alternate view calling conventions. A view + mapper allows objects that are meant to be used as view callables to have + an arbitrary argument list and an arbitrary result. The object passed as + ``default_view_mapper`` should implement the + ``pyramid.interfaces.IViewMapperFactory`` interface. + +- add a ``set_view_mapper`` API to Configurator. Has + the same result as passing ``default_view_mapper`` to the Configurator + constructor. + +- ``config.add_view`` now accepts a ``mapper`` keyword argument, which should + either be ``None``, a string representing a Python dotted name, or an + object which is an ``IViewMapperFactory``. This feature is not useful for + "civilians", only for extension writers. + +- Allow static renderer provided during view registration to be overridden at + request time via a request attribute named ``override_renderer``, which + should be the name of a previously registered renderer. Useful to provide + "omnipresent" RPC using existing rendered views. + +- Instances of ``pyramid.testing.DummyRequest`` now have a ``session`` + object, which is mostly a dictionary, but also implements the other session + API methods for flash and CSRF. + +Backwards Incompatibilities +--------------------------- + +- Since the ``pyramid.interfaces.IAuthenticationPolicy`` interface now + specifies that a policy implementation must implement an + ``unauthenticated_userid`` method, all third-party custom authentication + policies now must implement this method. It, however, will only be called + when the global function named ``pyramid.security.unauthenticated_userid`` + is invoked, so if you're not invoking that, you will not notice any issues. + +- ``pyramid.interfaces.ISession.get_csrf_token`` now mandates that an + implementation should return a *new* token if one doesn't already exist in + the session (previously it would return None). The internal sessioning + implementation has been changed. + +Documentation +------------- + +- The (weak) "Converting a CMF Application to Pyramid" tutorial has been + removed from the tutorials section. It was moved to the + ``pyramid_tutorials`` Github repository. + +- The "Resource Location and View Lookup" chapter has been replaced with a + variant of Rob Miller's "Much Ado About Traversal" (originally published at + http://blog.nonsequitarian.org/2010/much-ado-about-traversal/). + +- Many minor wording tweaks and refactorings (merged Casey Duncan's docs + fork, in which he is working on general editing). + +- Added (weak) description of new view mapper feature to Hooks narrative + chapter. + +- Split views chapter into 2: View Callables and View Configuration. + +- Reorder Renderers and Templates chapters after View Callables but before + View Configuration. + +- Merge Session Objects, Cross-Site Request Forgery, and Flash Messaging + chapter into a single Sessions chapter. + +- The Wiki and Wiki2 tutorials now have much nicer CSS and graphics. + +Internals +--------- + +- The "view derivation" code is now factored into a set of classes rather + than a large number of standalone functions (a side effect of the + view mapper refactoring). + +- The ``pyramid.renderer.RendererHelper`` class has grown a ``render_view`` + method, which is used by the default view mapper (a side effect of the + view mapper refactoring). + +- The object passed as ``renderer`` to the "view deriver" is now an instance + of ``pyramid.renderers.RendererHelper`` rather than a dictionary (a side + effect of view mapper refactoring). + +- The class used as the "page template" in ``pyramid.chameleon_text`` was + removed, in preference to using a Chameleon-inbuilt version. + +- A view callable wrapper registered in the registry now contains an + ``__original_view__`` attribute which references the original view callable + (or class). + +- The (non-API) method of all internal authentication policy implementations + previously named ``_get_userid`` is now named ``unauthenticated_userid``, + promoted to an API method. If you were overriding this method, you'll now + need to override it as ``unauthenticated_userid`` instead. + +- Remove (non-API) function of config.py named _map_view. + +1.0a8 (2010-12-27) +================== + +Bug Fixes +--------- + +- The name ``registry`` was not available in the ``paster pshell`` + environment under IPython. + +Features +-------- + +- If a resource implements a ``__resource_url__`` method, it will be called + as the result of invoking the ``pyramid.url.resource_url`` function to + generate a URL, overriding the default logic. See the new "Generating The + URL Of A Resource" section within the Resources narrative chapter. + +- Added flash messaging, as described in the "Flash Messaging" narrative + documentation chapter. + +- Added CSRF token generation, as described in the narrative chapter entitled + "Preventing Cross-Site Request Forgery Attacks". + +- Prevent misunderstanding of how the ``view`` and ``view_permission`` + arguments to add_route work by raising an exception during configuration if + view-related arguments exist but no ``view`` argument is passed. + +- Add ``paster proute`` command which displays a summary of the routing + table. See the narrative documentation section within the "URL Dispatch" + chapter entitled "Displaying All Application Routes". + +Paster Templates +---------------- + +- The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead, it + is based on scanning. + +Documentation +------------- + +- Added "Generating The URL Of A Resource" section to the Resources narrative + chapter (includes information about overriding URL generation using + ``__resource_url__``). + +- Added "Generating the Path To a Resource" section to the Resources + narrative chapter. + +- Added "Finding a Resource by Path" section to the Resources narrative + chapter. + +- Added "Obtaining the Lineage of a Resource" to the Resources narrative + chapter. + +- Added "Determining if a Resource is In The Lineage of Another Resource" to + Resources narrative chapter. + +- Added "Finding the Root Resource" to Resources narrative chapter. + +- Added "Finding a Resource With a Class or Interface in Lineage" to + Resources narrative chapter. + +- Added a "Flash Messaging" narrative documentation chapter. + +- Added a narrative chapter entitled "Preventing Cross-Site Request Forgery + Attacks". + +- Changed the "ZODB + Traversal Wiki Tutorial" based on changes to + ``pyramid_zodb`` Paster template. + +- Added "Advanced Configuration" narrative chapter which documents how to + deal with configuration conflicts, two-phase configuration, ``include`` and + ``commit``. + +- Fix API documentation rendering for ``pyramid.view.static`` + +- Add "Pyramid Provides More Than One Way to Do It" to Design Defense + documentation. + +- Changed "Static Assets" narrative chapter: clarify that ``name`` represents + a prefix unless it's a URL, added an example of a root-relative static view + fallback for URL dispatch, added an example of creating a simple view that + returns the body of a file. + +- Move ZCML usage in Hooks chapter to Declarative Configuration chapter. + +- Merge "Static Assets" chapter into the "Assets" chapter. + +- Added narrative documentation section within the "URL Dispatch" chapter + entitled "Displaying All Application Routes" (for ``paster proutes`` + command). + +1.0a7 (2010-12-20) +================== + +Terminology Changes +------------------- + +- The Pyramid concept previously known as "model" is now known as "resource". + As a result: + + - The following API changes have been made:: + + pyramid.url.model_url -> + pyramid.url.resource_url + + pyramid.traversal.find_model -> + pyramid.url.find_resource + + pyramid.traversal.model_path -> + pyramid.traversal.resource_path + + pyramid.traversal.model_path_tuple -> + pyramid.traversal.resource_path_tuple + + pyramid.traversal.ModelGraphTraverser -> + pyramid.traversal.ResourceTreeTraverser + + pyramid.config.Configurator.testing_models -> + pyramid.config.Configurator.testing_resources + + pyramid.testing.registerModels -> + pyramid.testing.registerResources + + pyramid.testing.DummyModel -> + pyramid.testing.DummyResource + + - All documentation which previously referred to "model" now refers to + "resource". + + - The ``starter`` and ``starter_zcml`` paster templates now have a + ``resources.py`` module instead of a ``models.py`` module. + + - Positional argument names of various APIs have been changed from + ``model`` to ``resource``. + + Backwards compatibility shims have been left in place in all cases. They + will continue to work "forever". + +- The Pyramid concept previously known as "resource" is now known as "asset". + As a result: + + - The (non-API) module previously known as ``pyramid.resource`` is now + known as ``pyramid.asset``. + + - All docs that previously referred to "resource specification" now refer + to "asset specification". + + - The following API changes were made:: + + pyramid.config.Configurator.absolute_resource_spec -> + pyramid.config.Configurator.absolute_asset_spec + + pyramid.config.Configurator.override_resource -> + pyramid.config.Configurator.override_asset + + - The ZCML directive previously known as ``resource`` is now known as + ``asset``. + + - The setting previously known as ``BFG_RELOAD_RESOURCES`` (envvar) or + ``reload_resources`` (config file) is now known, respectively, as + ``PYRAMID_RELOAD_ASSETS`` and ``reload_assets``. + + Backwards compatibility shims have been left in place in all cases. They + will continue to work "forever". + +Bug Fixes +--------- + +- Make it possible to succesfully run all tests via ``nosetests`` command + directly (rather than indirectly via ``python setup.py nosetests``). + +- When a configuration conflict is encountered during scanning, the conflict + exception now shows the decorator information that caused the conflict. + +Features +-------- + +- Added ``debug_routematch`` configuration setting that logs matched routes + (including the matchdict and predicates). + +- The name ``registry`` is now available in a ``pshell`` environment by + default. It is the application registry object. + +Environment +----------- + +- All environment variables which used to be prefixed with ``BFG_`` are now + prefixed with ``PYRAMID_`` (e.g. ``BFG_DEBUG_NOTFOUND`` is now + ``PYRAMID_DEBUG_NOTFOUND``) + +Documentation +------------- + +- Added "Debugging Route Matching" section to the urldispatch narrative + documentation chapter. + +- Added reference to ``PYRAMID_DEBUG_ROUTEMATCH`` envvar and ``debug_routematch`` + config file setting to the Environment narrative docs chapter. + +- Changed "Project" chapter slightly to expand on use of ``paster pshell``. + +- Direct Jython users to Mako rather than Jinja2 in "Install" narrative + chapter. + +- Many changes to support terminological renaming of "model" to "resource" + and "resource" to "asset". + +- Added an example of ``WebTest`` functional testing to the testing narrative + chapter. + +- Rearranged chapter ordering by popular demand (URL dispatch first, then + traversal). Put hybrid chapter after views chapter. + +- Split off "Renderers" as its own chapter from "Views" chapter in narrative + documentation. + +Paster Templates +---------------- + +- Added ``debug_routematch = false`` to all paster templates. + +Dependencies +------------ + +- Depend on Venusian >= 0.5 (for scanning conflict exception decoration). + +1.0a6 (2010-12-15) +================== + +Bug Fixes +--------- + +- 1.0a5 introduced a bug when ``pyramid.config.Configurator.scan`` was used + without a ``package`` argument (e.g. ``config.scan()`` as opposed to + ``config.scan('packagename')``. The symptoms were: lots of deprecation + warnings printed to the console about imports of deprecated Pyramid + functions and classes and non-detection of view callables decorated with + ``view_config`` decorators. This has been fixed. + +- Tests now pass on Windows (no bugs found, but a few tests in the test suite + assumed UNIX path segments in filenames). + +Documentation +------------- + +- If you followed it to-the-letter, the ZODB+Traversal Wiki tutorial would + instruct you to run a test which would fail because the view callable + generated by the ``pyramid_zodb`` tutorial used a one-arg view callable, + but the test in the sample code used a two-arg call. + +- Updated ZODB+Traversal tutorial setup.py of all steps to match what's + generated by ``pyramid_zodb``. + +- Fix reference to ``repoze.bfg.traversalwrapper`` in "Models" chapter (point + at ``pyramid_traversalwrapper`` instead). + +1.0a5 (2010-12-14) +================== + +Features +-------- + +- Add a ``handler`` ZCML directive. This directive does the same thing as + ``pyramid.configuration.add_handler``. + +- A new module named ``pyramid.config`` was added. It subsumes the duties of + the older ``pyramid.configuration`` module. + +- The new ``pyramid.config.Configurator` class has API methods that the older + ``pyramid.configuration.Configurator`` class did not: ``with_context`` (a + classmethod), ``include``, ``action``, and ``commit``. These methods exist + for imperative application extensibility purposes. + +- The ``pyramid.testing.setUp`` function now accepts an ``autocommit`` + keyword argument, which defaults to ``True``. If it is passed ``False``, + the Config object returned by ``setUp`` will be a non-autocommiting Config + object. + +- Add logging configuration to all paster templates. + +- ``pyramid_alchemy``, ``pyramid_routesalchemy``, and ``pylons_sqla`` paster + templates now use idiomatic SQLAlchemy configuration in their respective + ``.ini`` files and Python code. + +- ``pyramid.testing.DummyRequest`` now has a class variable, + ``query_string``, which defaults to the empty string. + +- Add support for json on GAE by catching NotImplementedError and importing + simplejson from django.utils. + +- The Mako renderer now accepts a resource specification for + ``mako.module_directory``. + +- New boolean Mako settings variable ``mako.strict_undefined``. See `Mako + Context Variables + `_ for + its meaning. + +Dependencies +------------ + +- Depend on Mako 0.3.6+ (we now require the ``strict_undefined`` feature). + +Bug Fixes +--------- + +- When creating a Configurator from within a ``paster pshell`` session, you + were required to pass a ``package`` argument although ``package`` is not + actually required. If you didn't pass ``package``, you would receive an + error something like ``KeyError: '__name__'`` emanating from the + ``pyramid.path.caller_module`` function. This has now been fixed. + +- The ``pyramid_routesalchemy`` paster template's unit tests failed + (``AssertionError: 'SomeProject' != 'someproject'``). This is fixed. + +- Make default renderer work (renderer factory registered with no name, which + is active for every view unless the view names a specific renderer). + +- The Mako renderer did not properly turn the ``mako.imports``, + ``mako.default_filters``, and ``mako.imports`` settings into lists. + +- The Mako renderer did not properly convert the ``mako.error_handler`` + setting from a dotted name to a callable. + +Documentation +------------- + +- Merged many wording, readability, and correctness changes to narrative + documentation chapters from https://github.com/caseman/pyramid (up to and + including "Models" narrative chapter). + +- "Sample Applications" section of docs changed to note existence of Cluegun, + Shootout and Virginia sample applications, ported from their repoze.bfg + origin packages. + +- SQLAlchemy+URLDispatch tutorial updated to integrate changes to + ``pyramid_routesalchemy`` template. + +- Add ``pyramid.interfaces.ITemplateRenderer`` interface to Interfaces API + chapter (has ``implementation()`` method, required to be used when getting + at Chameleon macros). + +- Add a "Modifying Package Structure" section to the project narrative + documentation chapter (explain turning a module into a package). + +- Documentation was added for the new ``handler`` ZCML directive in the ZCML + section. + +Deprecations +------------ + +- ``pyramid.configuration.Configurator`` is now deprecated. Use + ``pyramid.config.Configurator``, passing its constructor + ``autocommit=True`` instead. The ``pyramid.configuration.Configurator`` + alias will live for a long time, as every application uses it, but its + import now issues a deprecation warning. The + ``pyramid.config.Configurator`` class has the same API as + ``pyramid.configuration.Configurator`` class, which it means to replace, + except by default it is a *non-autocommitting* configurator. The + now-deprecated ``pyramid.configuration.Configurator`` will autocommit every + time a configuration method is called. + + The ``pyramid.configuration`` module remains, but it is deprecated. Use + ``pyramid.config`` instead. + +1.0a4 (2010-11-21) +================== + +Features +-------- + +- URL Dispatch now allows for replacement markers to be located anywhere + in the pattern, instead of immediately following a ``/``. + +- URL Dispatch now uses the form ``{marker}`` to denote a replace marker in + the route pattern instead of ``:marker``. The old colon-style marker syntax + is still accepted for backwards compatibility. The new format allows a + regular expression for that marker location to be used instead of the + default ``[^/]+``, for example ``{marker:\d+}`` is now valid to require the + marker to be digits. + +- Add a ``pyramid.url.route_path`` API, allowing folks to generate relative + URLs. Calling ``route_path`` is the same as calling + ``pyramid.url.route_url`` with the argument ``_app_url`` equal to the empty + string. + +- Add a ``pyramid.request.Request.route_path`` API. This is a convenience + method of the request which calls ``pyramid.url.route_url``. + +- Make test suite pass on Jython (requires PasteScript trunk, presumably to + be 1.7.4). + +- Make test suite pass on PyPy (Chameleon doesn't work). + +- Surrounding application configuration with ``config.begin()`` and + ``config.end()`` is no longer necessary. All paster templates have been + changed to no longer call these functions. + +- Fix configurator to not convert ``ImportError`` to ``ConfigurationError`` + if the import that failed was unrelated to the import requested via a + dotted name when resolving dotted names (such as view dotted names). + +Documentation +------------- + +- SQLAlchemy+URLDispatch and ZODB+Traversal tutorials have been updated to + not call ``config.begin()`` or ``config.end()``. + +Bug Fixes +--------- + +- Add deprecation warnings to import of ``pyramid.chameleon_text`` and + ``pyramid.chameleon_zpt`` of ``get_renderer``, ``get_template``, + ``render_template``, and ``render_template_to_response``. + +- Add deprecation warning for import of ``pyramid.zcml.zcml_configure`` and + ``pyramid.zcml.file_configure``. + +- The ``pyramid_alchemy`` paster template had a typo, preventing an import + from working. + +- Fix apparent failures when calling ``pyramid.traversal.find_model(root, + path)`` or ``pyramid.traversal.traverse(path)`` when ``path`` is + (erroneously) a Unicode object. The user is meant to pass these APIs a + string object, never a Unicode object. In practice, however, users indeed + pass Unicode. Because the string that is passed must be ASCII encodeable, + now, if they pass a Unicode object, its data is eagerly converted to an + ASCII string rather than being passed along to downstream code as a + convenience to the user and to prevent puzzling second-order failures from + cropping up (all failures will occur within ``pyramid.traversal.traverse`` + rather than later down the line as the result of calling e.g. + ``traversal_path``). + +Backwards Incompatibilities +--------------------------- + +- The ``pyramid.testing.zcml_configure`` API has been removed. It had been + advertised as removed since repoze.bfg 1.2a1, but hadn't actually been. + +Deprecations +------------ + +- The ``pyramid.settings.get_settings`` API is now deprecated. Use + ``pyramid.threadlocals.get_current_registry().settings`` instead or use the + ``settings`` attribute of the registry available from the request + (``request.registry.settings``). + +Documentation +------------- + +- Removed ``zodbsessions`` tutorial chapter. It's still useful, but we now + have a SessionFactory abstraction which competes with it, and maintaining + documentation on both ways to do it is a distraction. + +Internal +-------- + +- Replace Twill with WebTest in internal integration tests (avoid deprecation + warnings generated by Twill). + +1.0a3 (2010-11-16) +================== + +Features +-------- + +- Added Mako TemplateLookup settings for ``mako.error_handler``, + ``mako.default_filters``, and ``mako.imports``. + +- Normalized all paster templates: each now uses the name ``main`` to + represent the function that returns a WSGI application, each now uses + WebError, each now has roughly the same shape of development.ini style. + +- Added class vars ``matchdict`` and ``matched_route`` to + ``pyramid.request.Request``. Each is set to ``None``. + +- New API method: ``pyramid.settings.asbool``. + +- New API methods for ``pyramid.request.Request``: ``model_url``, + ``route_url``, and ``static_url``. These are simple passthroughs for their + respective functions in ``pyramid.url``. + +- The ``settings`` object which used to be available only when + ``request.settings.get_settings`` was called is now available as + ``registry.settings`` (e.g. ``request.registry.settings`` in view code). + +Bug Fixes +--------- + +- The pylons_* paster templates erroneously used the ``{squiggly}`` routing + syntax as the pattern supplied to ``add_route``. This style of routing is + not supported. They were replaced with ``:colon`` style route patterns. + +- The pylons_* paster template used the same string + (``your_app_secret_string``) for the ``session.secret`` setting in the + generated ``development.ini``. This was a security risk if left unchanged + in a project that used one of the templates to produce production + applications. It now uses a randomly generated string. + +Documentation +------------- + +- ZODB+traversal wiki (``wiki``) tutorial updated due to changes to + ``pyramid_zodb`` paster template. + +- SQLAlchemy+urldispach wiki (``wiki2``) tutorial updated due to changes to + ``pyramid_routesalchemy`` paster template. + +- Documented the ``matchdict`` and ``matched_route`` attributes of the + request object in the Request API documentation. + +Deprecations +------------ + +- Obtaining the ``settings`` object via + ``registry.{get|query}Utility(ISettings)`` is now deprecated. Instead, + obtain the ``settings`` object via the ``registry.settings`` attribute. A + backwards compatibility shim was added to the registry object to register + the settings object as an ISettings utility when ``setattr(registry, + 'settings', foo)`` is called, but it will be removed in a later release. + +- Obtaining the ``settings`` object via ``pyramid.settings.get_settings`` is + now deprecated. Obtain it as the ``settings`` attribute of the registry + now (obtain the registry via ``pyramid.threadlocal.get_registry`` or as + ``request.registry``). + +Behavior Differences +-------------------- + +- Internal: ZCML directives no longer call get_current_registry() if there's + a ``registry`` attribute on the ZCML context (kill off use of + threadlocals). + +- Internal: Chameleon template renderers now accept two arguments: ``path`` + and ``lookup``. ``Lookup`` will be an instance of a lookup class which + supplies (late-bound) arguments for debug, reload, and translate. Any + third-party renderers which use (the non-API) function + ``pyramid.renderers.template_renderer_factory`` will need to adjust their + implementations to obey the new callback argument list. This change was to + kill off inappropriate use of threadlocals. + +1.0a2 (2010-11-09) +================== + +Documentation +------------- + +- All references to events by interface + (e.g. ``pyramid.interfaces.INewRequest``) have been changed to reference + their concrete classes (e.g. ``pyramid.events.NewRequest``) in + documentation about making subscriptions. + +- All references to Pyramid-the-application were changed from mod-`pyramid` + to app-`Pyramid`. A custom role setting was added to ``docs/conf.py`` to + allow for this. (internal) + +1.0a1 (2010-11-05) +================== + +Features (delta from BFG 1.3) +------------------------------- + +- Mako templating renderer supports resource specification format for + template lookups and within Mako templates. Absolute filenames must + be used in Pyramid to avoid this lookup process. + +- Add ``pyramid.httpexceptions`` module, which is a facade for the + ``webob.exc`` module. + +- Direct built-in support for the Mako templating language. + +- A new configurator method exists: ``add_handler``. This method adds + a Pylons-style "view handler" (such a thing used to be called a + "controller" in Pylons 1.0). + +- New argument to configurator: ``session_factory``. + +- New method on configurator: ``set_session_factory`` + +- Using ``request.session`` now returns a (dictionary-like) session + object if a session factory has been configured. + +- The request now has a new attribute: ``tmpl_context`` for benefit of + Pylons users. + +- The decorator previously known as ``pyramid.view.bfg_view`` is now + known most formally as ``pyramid.view.view_config`` in docs and + paster templates. An import of ``pyramid.view.bfg_view``, however, + will continue to work "forever". + +- New API methods in ``pyramid.session``: ``signed_serialize`` and + ``signed_deserialize``. + +- New interface: ``pyramid.interfaces.IRendererInfo``. An object of this type + is passed to renderer factory constructors (see "Backwards + Incompatibilities"). + +- New event type: ``pyramid.interfaces.IBeforeRender``. An object of this type + is sent as an event before a renderer is invoked (but after the + application-level renderer globals factory added via + ``pyramid.configurator.configuration.set_renderer_globals_factory``, if any, + has injected its own keys). Applications may now subscribe to the + ``IBeforeRender`` event type in order to introspect the and modify the set of + renderer globals before they are passed to a renderer. The event object + iself has a dictionary-like interface that can be used for this purpose. For + example:: + + from repoze.events import subscriber + from pyramid.interfaces import IRendererGlobalsEvent + + @subscriber(IRendererGlobalsEvent) + def add_global(event): + event['mykey'] = 'foo' + + If a subscriber attempts to add a key that already exist in the renderer + globals dictionary, a ``KeyError`` is raised. This limitation is due to the + fact that subscribers cannot be ordered relative to each other. The set of + keys added to the renderer globals dictionary by all subscribers and + app-level globals factories must be unique. + +- New class: ``pyramid.response.Response``. This is a pure facade for + ``webob.Response`` (old code need not change to use this facade, it's + existence is mostly for vanity and documentation-generation purposes). + +- All preexisting paster templates (except ``zodb``) now use "imperative" + configuration (``starter``, ``routesalchemy``, ``alchemy``). + +- A new paster template named ``pyramid_starter_zcml`` exists, which uses + declarative configuration. + +Documentation (delta from BFG 1.3) +----------------------------------- + +- Added a ``pyramid.httpexceptions`` API documentation chapter. + +- Added a ``pyramid.session`` API documentation chapter. + +- Added a ``Session Objects`` narrative documentation chapter. + +- Added an API chapter for the ``pyramid.personality`` module. + +- Added an API chapter for the ``pyramid.response`` module. + +- All documentation which previously referred to ``webob.Response`` now uses + ``pyramid.response.Response`` instead. + +- The documentation has been overhauled to use imperative configuration, + moving declarative configuration (ZCML) explanations to a separate + narrative chapter ``declarative.rst``. + +- The ZODB Wiki tutorial was updated to take into account changes to the + ``pyramid_zodb`` paster template. + +- The SQL Wiki tutorial was updated to take into account changes to the + ``pyramid_routesalchemy`` paster template. + +Backwards Incompatibilities (with BFG 1.3) +------------------------------------------ + +- There is no longer an ``IDebugLogger`` registered as a named utility + with the name ``repoze.bfg.debug``. + +- The logger which used to have the name of ``repoze.bfg.debug`` now + has the name ``pyramid.debug``. + +- The deprecated API ``pyramid.testing.registerViewPermission`` + has been removed. + +- The deprecated API named ``pyramid.testing.registerRoutesMapper`` + has been removed. + +- The deprecated API named ``pyramid.request.get_request`` was removed. + +- The deprecated API named ``pyramid.security.Unauthorized`` was + removed. + +- The deprecated API named ``pyramid.view.view_execution_permitted`` + was removed. + +- The deprecated API named ``pyramid.view.NotFound`` was removed. + +- The ``bfgshell`` paster command is now named ``pshell``. + +- The Venusian "category" for all built-in Venusian decorators + (e.g. ``subscriber`` and ``view_config``/``bfg_view``) is now + ``pyramid`` instead of ``bfg``. + +- ``pyramid.renderers.rendered_response`` function removed; use + ``render_pyramid.renderers.render_to_response`` instead. + +- Renderer factories now accept a *renderer info object* rather than an + absolute resource specification or an absolute path. The object has the + following attributes: ``name`` (the ``renderer=`` value), ``package`` (the + 'current package' when the renderer configuration statement was found), + ``type``: the renderer type, ``registry``: the current registry, and + ``settings``: the deployment settings dictionary. + + Third-party ``repoze.bfg`` renderer implementations that must be ported to + Pyramid will need to account for this. + + This change was made primarily to support more flexible Mako template + rendering. + +- The presence of the key ``repoze.bfg.message`` in the WSGI environment when + an exception occurs is now deprecated. Instead, code which relies on this + environ value should use the ``exception`` attribute of the request + (e.g. ``request.exception[0]``) to retrieve the message. + +- The values ``bfg_localizer`` and ``bfg_locale_name`` kept on the request + during internationalization for caching purposes were never APIs. These + however have changed to ``localizer`` and ``locale_name``, respectively. + +- The default ``cookie_name`` value of the ``authtktauthenticationpolicy`` ZCML + now defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). + +- The default ``cookie_name`` value of the + ``pyramid.authentication.AuthTktAuthenticationPolicy`` constructor now + defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). + +- The ``request_type`` argument to the ``view`` ZCML directive, the + ``pyramid.configuration.Configurator.add_view`` method, or the + ``pyramid.view.view_config`` decorator (nee ``bfg_view``) is no longer + permitted to be one of the strings ``GET``, ``HEAD``, ``PUT``, ``POST`` or + ``DELETE``, and now must always be an interface. Accepting the + method-strings as ``request_type`` was a backwards compatibility strategy + servicing repoze.bfg 1.0 applications. Use the ``request_method`` + parameter instead to specify that a view a string request-method predicate. + diff --git a/HISTORY.txt b/HISTORY.txt deleted file mode 100644 index 8a92eadcc..000000000 --- a/HISTORY.txt +++ /dev/null @@ -1,5773 +0,0 @@ -1.9 (2017-06-26) -================ - -- No major changes from 1.9b1. - -- Updated documentation links for ``docs.pylonsproject.org`` to use HTTPS. - -1.9b1 (2017-06-19) -================== - -- Add an informative error message when unknown predicates are supplied. The - new message suggests alternatives based on the list of known predicates. - See https://github.com/Pylons/pyramid/pull/3054 - -- Added integrity attributes for JavaScripts in cookiecutters, scaffolds, and - resulting source files in tutorials. - See https://github.com/Pylons/pyramid/issues/2548 - -- Update RELEASING.txt for updating cookiecutters. Change cookiecutter URLs to - use shortcut. - See https://github.com/Pylons/pyramid/issues/3042 - -- Ensure the correct threadlocals are pushed during view execution when - invoked from ``request.invoke_exception_view``. - See https://github.com/Pylons/pyramid/pull/3060 - -- Fix a bug in which ``pyramid.security.ALL_PERMISSIONS`` failed to return - a valid iterator in its ``__iter__`` implementation. - See https://github.com/Pylons/pyramid/pull/3074 - -- Normalize the permission results to a proper class hierarchy. - ``pyramid.security.ACLAllowed`` is now a subclass of - ``pyramid.security.Allowed`` and ``pyramid.security.ACLDenied`` is now a - subclass of ``pyramid.security.Denied``. - See https://github.com/Pylons/pyramid/pull/3084 - -- Add a ``quote_via`` argument to ``pyramid.encode.urlencode`` to follow - the stdlib's version and enable custom quoting functions. - See https://github.com/Pylons/pyramid/pull/3088 - -- Support `_query=None` and `_anchor=None` in ``request.route_url`` as well - as ``query=None`` and ``anchor=None`` in ``request.resource_url``. - Previously this would cause an `?` and a `#`, respectively, in the url - with nothing after it. Now the unnecessary parts are dropped from the - generated URL. See https://github.com/Pylons/pyramid/pull/3034 - -- Revamp the ``IRouter`` API used by ``IExecutionPolicy`` to force - pushing/popping the request threadlocals. The - ``IRouter.make_request(environ)`` API has been replaced by - ``IRouter.request_context(environ)`` which should be used as a context - manager. See https://github.com/Pylons/pyramid/pull/3086 - -1.9a2 (2017-05-09) -================== - -Backward Incompatibilities --------------------------- - -- ``request.exception`` and ``request.exc_info`` will only be set if the - response was generated by the EXCVIEW tween. This is to avoid any confusion - where a response was generated elsewhere in the pipeline and not in - direct relation to the original exception. If anyone upstream wants to - catch and render responses for exceptions they should set - ``request.exception`` and ``request.exc_info`` themselves to indicate - the exception that was squashed when generating the response. - - Similar behavior occurs with ``request.invoke_exception_view`` in which - the exception properties are set to reflect the exception if a response - is successfully generated by the method. - - This is a very minor incompatibility. Most tweens right now would give - priority to the raised exception and ignore ``request.exception``. This - change just improves and clarifies that bookkeeping by trying to be - more clear about the relationship between the response and its squashed - exception. See https://github.com/Pylons/pyramid/pull/3029 and - https://github.com/Pylons/pyramid/pull/3031 - -1.9a1 (2017-05-01) -================== - -Major Features --------------- - -- The file format used by all ``p*`` command line scripts such as ``pserve`` - and ``pshell``, as well as the ``pyramid.paster.bootstrap`` function - is now replaceable thanks to a new dependency on - `plaster `_. - - For now, Pyramid is still shipping with integrated support for the - PasteDeploy INI format by depending on the - `plaster_pastedeploy `_ - binding library. This may change in the future. - - See https://github.com/Pylons/pyramid/pull/2985 - -- Added an execution policy hook to the request pipeline. An execution - policy has the ability to control creation and execution of the request - objects before they enter the rest of the pipeline. This means for a single - request environ the policy may create more than one request object. - - The first library to use this feature is - `pyramid_retry - `_. - - See https://github.com/Pylons/pyramid/pull/2964 - -- CSRF support has been refactored out of sessions and into its own - independent API in the ``pyramid.csrf`` module. It supports a pluggable - ``pyramid.interfaces.ICSRFStoragePolicy`` which can be used to define your - own mechanism for generating and validating CSRF tokens. By default, - Pyramid continues to use the ``pyramid.csrf.LegacySessionCSRFStoragePolicy`` - that uses the ``request.session.get_csrf_token`` and - ``request.session.new_csrf_token`` APIs under the hood to preserve - compatibility. Two new policies are shipped as well, - ``pyramid.csrf.SessionCSRFStoragePolicy`` and - ``pyramid.csrf.CookieCSRFStoragePolicy`` which will store the CSRF tokens - in the session and in a standalone cookie, respectively. The storage policy - can be changed by using the new - ``pyramid.config.Configurator.set_csrf_storage_policy`` config directive. - - CSRF tokens should be used via the new ``pyramid.csrf.get_csrf_token``, - ``pyramid.csrf.new_csrf_token`` and ``pyramid.csrf.check_csrf_token`` APIs - in order to continue working if the storage policy is changed. Also, the - ``pyramid.csrf.get_csrf_token`` function is injected into templates to be - used conveniently in UI code. - - See https://github.com/Pylons/pyramid/pull/2854 and - https://github.com/Pylons/pyramid/pull/3019 - -Minor Features --------------- - -- Support an ``open_url`` config setting in the ``pserve`` section of the - config file. This url is used to open a web browser when ``pserve --browser`` - is invoked. When this setting is unavailable the ``pserve`` script will - attempt to guess the port the server is using from the - ``server:`` section of the config file but there is no - requirement that the server is being run in this format so it may fail. - See https://github.com/Pylons/pyramid/pull/2984 - -- The ``pyramid.config.Configurator`` can now be used as a context manager - which will automatically push/pop threadlocals (similar to - ``config.begin()`` and ``config.end()``). It will also automatically perform - a ``config.commit()`` and thus it is only recommended to be used at the - top-level of your app. See https://github.com/Pylons/pyramid/pull/2874 - -- The threadlocals are now available inside any function invoked via - ``config.include``. This means the only config-time code that cannot rely - on threadlocals is code executed from non-actions inside the main. This - can be alleviated by invoking ``config.begin()`` and ``config.end()`` - appropriately or using the new context manager feature of the configurator. - See https://github.com/Pylons/pyramid/pull/2989 - -Bug Fixes ---------- - -- HTTPException's accepts a detail kwarg that may be used to pass additional - details to the exception. You may now pass objects so long as they have a - valid __str__ method. See https://github.com/Pylons/pyramid/pull/2951 - -- Fix a reference cycle causing memory leaks in which the registry - would keep a ``Configurator`` instance alive even after the configurator - was discarded. Another fix was also added for the ``global_registries`` - object in which the registry was stored in a closure preventing it from - being deallocated. See https://github.com/Pylons/pyramid/pull/2967 - -- Fix a bug directly invoking ``pyramid.scripts.pserve.main`` with the - ``--reload`` option in which ``sys.argv`` is always used in the subprocess - instead of the supplied ``argv``. - See https://github.com/Pylons/pyramid/pull/2962 - -Deprecations ------------- - -- Pyramid currently depends on ``plaster_pastedeploy`` to simplify the - transition to ``plaster`` by maintaining integrated support for INI files. - This dependency on ``plaster_pastedeploy`` should be considered subject to - Pyramid's deprecation policy and may be removed in the future. - Applications should depend on the appropriate plaster binding to satisfy - their needs. - -- Retrieving CSRF token from the session has been deprecated in favor of - equivalent methods in the ``pyramid.csrf`` module. The CSRF methods - (``ISession.get_csrf_token`` and ``ISession.new_csrf_token``) are no longer - required on the ``ISession`` interface except when using the default - ``pyramid.csrf.LegacySessionCSRFStoragePolicy``. - - Also, ``pyramid.session.check_csrf_token`` is now located at - ``pyramid.csrf.check_csrf_token``. - - See https://github.com/Pylons/pyramid/pull/2854 and - https://github.com/Pylons/pyramid/pull/3019 - -Documentation Changes ---------------------- - -- Added the execution policy to the routing diagram in the Request Processing - chapter. See https://github.com/Pylons/pyramid/pull/2993 - -1.8 (2017-01-21) -================ - -- No major changes from 1.8b1. - -1.8b1 (2017-01-17) -================== - -Features --------- - -- Added an ``override`` option to ``config.add_translation_dirs`` to allow - later calls to place translation directories at a higher priority than - earlier calls. See https://github.com/Pylons/pyramid/pull/2902 - -Documentation Changes ---------------------- - -- Improve registry documentation to discuss uses as a component registry - and as a dictionary. See https://github.com/Pylons/pyramid/pull/2893 - -- Quick Tour, Quick Tutorial, and most other remaining documentation updated to - use cookiecutters instead of pcreate and scaffolds. - See https://github.com/Pylons/pyramid/pull/2888 and - https://github.com/Pylons/pyramid/pull/2889 - -- Fix unittests in wiki2 to work without different dependencies between - py2 and py3. See https://github.com/Pylons/pyramid/pull/2899 - -- Update Windows documentation to track newer Python 3 improvements to the - installer. See https://github.com/Pylons/pyramid/pull/2900 - -- Updated the ``mod_wsgi`` tutorial to use cookiecutters and Apache 2.4+. - See https://github.com/Pylons/pyramid/pull/2901 - -1.8a1 (2016-12-25) -================== - -Backward Incompatibilities --------------------------- - -- Support for the ``IContextURL`` interface that was deprecated in Pyramid 1.3 - has been removed. See https://github.com/Pylons/pyramid/pull/2822 - -- Following the Pyramid deprecation period (1.6 -> 1.8), - daemon support for pserve has been removed. This includes removing the - daemon commands (start, stop, restart, status) as well as the following - arguments: ``--daemon``, ``--pid-file``, ``--log-file``, - ``--monitor-restart``, ``--status``, ``--user``, ``--group``, - ``--stop-daemon`` - - To run your server as a daemon you should use a process manager instead of - pserve. - - See https://github.com/Pylons/pyramid/pull/2615 - -- ``pcreate`` is now interactive by default. You will be prompted if a file - already exists with different content. Previously if there were similar - files it would silently skip them unless you specified ``--interactive`` - or ``--overwrite``. - See https://github.com/Pylons/pyramid/pull/2775 - -- Removed undocumented argument ``cachebust_match`` from - ``pyramid.static.static_view``. This argument was shipped accidentally - in Pyramid 1.6. See https://github.com/Pylons/pyramid/pull/2681 - -- Change static view to avoid setting the ``Content-Encoding`` response header - to an encoding guessed using Python's ``mimetypes`` module. This was causing - clients to decode the content of gzipped files when downloading them. The - client would end up with a ``foo.txt.gz`` file on disk that was already - decoded, thus should really be ``foo.txt``. Also, the ``Content-Encoding`` - should only have been used if the client itself broadcast support for the - encoding via ``Accept-Encoding`` request headers. - See https://github.com/Pylons/pyramid/pull/2810 - -- Settings are no longer accessible as attributes on the settings object - (e.g. ``request.registry.settings.foo``). This was deprecated in Pyramid 1.2. - See https://github.com/Pylons/pyramid/pull/2823 - -Features --------- - -- Python 3.6 compatibility. - https://github.com/Pylons/pyramid/issues/2835 - -- ``pcreate`` learned about ``--package-name`` to allow you to create a new - project in an existing folder with a different package name than the project - name. See https://github.com/Pylons/pyramid/pull/2783 - -- The ``_get_credentials`` private method of ``BasicAuthAuthenticationPolicy`` - has been extracted into standalone function ``extract_http_basic_credentials`` - in ``pyramid.authentication`` module, this function extracts HTTP Basic - credentials from a ``request`` object, and returns them as a named tuple. - See https://github.com/Pylons/pyramid/pull/2662 - -- Pyramid 1.4 silently dropped a feature of the configurator that has been - restored. It's again possible for action discriminators to conflict across - different action orders. - See https://github.com/Pylons/pyramid/pull/2757 - -- ``pyramid.paster.bootstrap`` and its sibling ``pyramid.scripting.prepare`` - can now be used as context managers to automatically invoke the ``closer`` - and pop threadlocals off of the stack to prevent memory leaks. - See https://github.com/Pylons/pyramid/pull/2760 - -- Added ``pyramid.config.Configurator.add_exception_view`` and the - ``pyramid.view.exception_view_config`` decorator. It is now possible using - these methods or via the new ``exception_only=True`` option to ``add_view`` - to add a view which will only be matched when handling an exception. - Previously any exception views were also registered for a traversal - context that inherited from the exception class which prevented any - exception-only optimizations. - See https://github.com/Pylons/pyramid/pull/2660 - -- Added the ``exception_only`` boolean to - ``pyramid.interfaces.IViewDeriverInfo`` which can be used by view derivers - to determine if they are wrapping a view which only handles exceptions. - This means that it is no longer necessary to perform request-time checks - for ``request.exception`` to determine if the view is handling an exception - - the pipeline can be optimized at config-time. - See https://github.com/Pylons/pyramid/pull/2660 - -- ``pserve`` should now work with ``gevent`` and other workers that need - to monkeypatch the process, assuming the server and / or the app do so - as soon as possible before importing the rest of pyramid. - See https://github.com/Pylons/pyramid/pull/2797 - -- Pyramid no longer copies the settings object passed to the - ``pyramid.config.Configurator(settings=)``. The original ``dict`` is kept. - See https://github.com/Pylons/pyramid/pull/2823 - -- The csrf trusted origins setting may now be a whitespace-separated list of - domains. Previously only a python list was allowed. Also, it can now be set - using the ``PYRAMID_CSRF_TRUSTED_ORIGINS`` environment variable similar to - other settings. See https://github.com/Pylons/pyramid/pull/2823 - -- ``pserve --reload`` now uses the - `hupper ` - library to monitor file changes. This comes with many improvements: - - - If the `watchdog `_ package is - installed then monitoring will be done using inotify instead of - cpu and disk-intensive polling. - - - The monitor is now a separate process that will not crash and starts up - before any of your code. - - - The monitor will not restart the process after a crash until a file is - saved. - - - The monitor works on windows. - - - You can now trigger a reload manually from a pyramid view or any other - code via ``hupper.get_reloader().trigger_reload()``. Kind of neat. - - - You can trigger a reload by issuing a ``SIGHUP`` to the monitor process. - - See https://github.com/Pylons/pyramid/pull/2805 - -- A new ``[pserve]`` section is supported in your config files with a - ``watch_files`` key that can configure ``pserve --reload`` to monitor custom - file paths. See https://github.com/Pylons/pyramid/pull/2827 - -- Allow streaming responses to be made from subclasses of - ``pyramid.httpexceptions.HTTPException``. Previously the response would - be unrolled while testing for a body, making it impossible to stream - a response. - See https://github.com/Pylons/pyramid/pull/2863 - -- Update starter, alchemy and zodb scaffolds to support IPv6 by using the - new ``listen`` directives in waitress. - See https://github.com/Pylons/pyramid/pull/2853 - -- All p* scripts now use argparse instead of optparse. This improves their - ``--help`` output as well as enabling nicer documentation of their options. - See https://github.com/Pylons/pyramid/pull/2864 - -- Any deferred configuration action registered via ``config.action`` may now - depend on threadlocal state, such as asset overrides, being active when - the action is executed. - See https://github.com/Pylons/pyramid/pull/2873 - -- Asset specifications for directories passed to - ``config.add_translation_dirs`` now support overriding the entire asset - specification, including the folder name. Previously only the package name - was supported and the folder would always need to have the same name. - See https://github.com/Pylons/pyramid/pull/2873 - -- ``config.begin()`` will propagate the current threadlocal request through - as long as the registry is the same. For example: - - .. code-block:: python - - request = Request.blank(...) - config.begin(request) # pushes a request - config.begin() # propagates the previous request through unchanged - assert get_current_request() is request - - See https://github.com/Pylons/pyramid/pull/2873 - -- Added a new ``callback`` option to ``config.set_default_csrf_options`` which - can be used to determine per-request whether CSRF checking should be enabled - to allow for a mix authentication methods. Only cookie-based methods - generally require CSRF checking. - See https://github.com/Pylons/pyramid/pull/2778 - -Bug Fixes ---------- - -- Fixed bug in ``proutes`` such that it now shows the correct view when a - class and ``attr`` is involved. - See: https://github.com/Pylons/pyramid/pull/2687 - -- Fix a ``FutureWarning`` in Python 3.5 when using ``re.split`` on the - ``format`` setting to the ``proutes`` script. - See https://github.com/Pylons/pyramid/pull/2714 - -- Fix a ``RuntimeWarning`` emitted by WebOb when using arbitrary objects - as the ``userid`` in the ``AuthTktAuthenticationPolicy``. This is now caught - by the policy and the object is serialized as a base64 string to avoid - the cryptic warning. Since the userid will be read back as a string on - subsequent requests a more useful warning is emitted encouraging you to - use a primitive type instead. - See https://github.com/Pylons/pyramid/pull/2715 - -- Pyramid 1.6 introduced the ability for an action to invoke another action. - There was a bug in the way that ``config.add_view`` would interact with - custom view derivers introduced in Pyramid 1.7 because the view's - discriminator cannot be computed until view derivers and view predicates - have been created in earlier orders. Invoking an action from another action - would trigger an unrolling of the pipeline and would compute discriminators - before they were ready. The new behavior respects the ``order`` of the action - and ensures the discriminators are not computed until dependent actions - from previous orders have executed. - See https://github.com/Pylons/pyramid/pull/2757 - -- Fix bug in i18n where the default domain would always use the Germanic plural - style, even if a different plural function is defined in the relevant - messages file. See https://github.com/Pylons/pyramid/pull/2859 - -- The ``config.override_asset`` method now occurs during - ``pyramid.config.PHASE1_CONFIG`` such that it is ordered to execute before - any calls to ``config.add_translation_dirs``. - See https://github.com/Pylons/pyramid/pull/2873 - -Deprecations ------------- - -- The ``pcreate`` script and related scaffolds have been deprecated in favor - of the popular - `cookiecutter `_ project. - - All of Pyramid's official scaffolds as well as the tutorials have been - ported to cookiecutters: - - - `pyramid-cookiecutter-starter - `_ - - - `pyramid-cookiecutter-alchemy - `_ - - - `pyramid-cookiecutter-zodb - `_ - - See https://github.com/Pylons/pyramid/pull/2780 - -Documentation Changes ---------------------- - -- Update Typographical Conventions. - https://github.com/Pylons/pyramid/pull/2838 - -- Add `pyramid_nacl_session - `_ - to session factories. See https://github.com/Pylons/pyramid/issues/2791 - -- Update ``HACKING.txt`` from stale branch that was never merged to master. - See https://github.com/Pylons/pyramid/pull/2782 - -- Updated Windows installation instructions and related bits. - See https://github.com/Pylons/pyramid/issues/2661 - -- Fix an inconsistency in the documentation between view predicates and - route predicates and highlight the differences in their APIs. - See https://github.com/Pylons/pyramid/pull/2764 - -- Clarify a possible misuse of the ``headers`` kwarg to subclasses of - ``pyramid.httpexceptions.HTTPException`` in which more appropriate - kwargs from the parent class ``pyramid.response.Response`` should be - used instead. See https://github.com/Pylons/pyramid/pull/2750 - -- The SQLAlchemy + URL Dispatch + Jinja2 (``wiki2``) and - ZODB + Traversal + Chameleon (``wiki``) tutorials have been updated to - utilize the new cookiecutters and drop support for the ``pcreate`` - scaffolds. - - See https://github.com/Pylons/pyramid/pull/2881 and - https://github.com/Pylons/pyramid/pull/2883. - -- Improve output of p* script descriptions for help. - See https://github.com/Pylons/pyramid/pull/2886 - -- Quick Tour updated to use cookiecutters instead of pcreate and scaffolds. - See https://github.com/Pylons/pyramid/pull/2888 - -1.7 (2016-05-19) -================ - -- Fix a bug in the wiki2 tutorial where bcrypt is always expecting byte - strings. See https://github.com/Pylons/pyramid/pull/2576 - -- Simplify windows detection code and remove some duplicated data. - See https://github.com/Pylons/pyramid/pull/2585 and - https://github.com/Pylons/pyramid/pull/2586 - -1.7b4 (2016-05-12) -================== - -- Fixed the exception view tween to re-raise the original exception if - no exception view could be found to handle the exception. This better - allows tweens further up the chain to handle exceptions that were - left unhandled. Previously they would be converted into a - ``PredicateMismatch`` exception if predicates failed to allow the view to - handle the exception. - See https://github.com/Pylons/pyramid/pull/2567 - -- Exposed the ``pyramid.interfaces.IRequestFactory`` interface to mirror - the public ``pyramid.interfaces.IResponseFactory`` interface. - -1.7b3 (2016-05-10) -================== - -- Fix ``request.invoke_exception_view`` to raise an ``HTTPNotFound`` - exception if no view is matched. Previously ``None`` would be returned - if no views were matched and a ``PredicateMismatch`` would be raised if - a view "almost" matched (a view was found matching the context). - See https://github.com/Pylons/pyramid/pull/2564 - -- Add defaults for py.test configuration and coverage to all three scaffolds, - and update documentation accordingly. - See https://github.com/Pylons/pyramid/pull/2550 - -- Add ``linkcheck`` to ``Makefile`` for Sphinx. To check the documentation for - broken links, use the command ``make linkcheck - SPHINXBUILD=$VENV/bin/sphinx-build``. Also removed and fixed dozens of broken - external links. - -- Fix the internal runner for scaffold tests to ensure they work with pip - and py.test. - See https://github.com/Pylons/pyramid/pull/2565 - -1.7b2 (2016-05-01) -================== - -- Removed inclusion of pyramid_tm in development.ini for alchemy scaffold - See https://github.com/Pylons/pyramid/issues/2538 - -- A default permission set via ``config.set_default_permission`` will no - longer be enforced on an exception view. This has been the case for a while - with the default exception views (``config.add_notfound_view`` and - ``config.add_forbidden_view``), however for any other exception view a - developer had to remember to set ``permission=NO_PERMISSION_REQUIRED`` or - be surprised when things didn't work. It is still possible to force a - permission check on an exception view by setting the ``permission`` argument - manually to ``config.add_view``. This behavior is consistent with the new - CSRF features added in the 1.7 series. - See https://github.com/Pylons/pyramid/pull/2534 - -1.7b1 (2016-04-25) -================== - -- This release announces the beta period for 1.7. - -- Fix an issue where some files were being included in the alchemy scafffold - which had been removed from the 1.7 series. - See https://github.com/Pylons/pyramid/issues/2525 - -1.7a2 (2016-04-19) -================== - -Features --------- - -- Automatic CSRF checks are now disabled by default on exception views. They - can be turned back on by setting the appropriate `require_csrf` option on - the view. - See https://github.com/Pylons/pyramid/pull/2517 - -- The automatic CSRF API was reworked to use a config directive for - setting the options. The ``pyramid.require_default_csrf`` setting is - no longer supported. Instead, a new ``config.set_default_csrf_options`` - directive has been introduced that allows the developer to specify - the default value for ``require_csrf`` as well as change the CSRF token, - header and safe request methods. The ``pyramid.csrf_trusted_origins`` - setting is still supported. - See https://github.com/Pylons/pyramid/pull/2518 - -Bug fixes ---------- - -- CSRF origin checks had a bug causing the checks to always fail. - See https://github.com/Pylons/pyramid/pull/2512 - -- Fix the test suite to pass on windows. - See https://github.com/Pylons/pyramid/pull/2520 - -1.7a1 (2016-04-16) -================== - -Backward Incompatibilities --------------------------- - -- Following the Pyramid deprecation period (1.4 -> 1.6), - AuthTktAuthenticationPolicy's default hashing algorithm is changing from md5 - to sha512. If you are using the authentication policy and need to continue - using md5, please explicitly set hashalg to 'md5'. - - This change does mean that any existing auth tickets (and associated cookies) - will no longer be valid, and users will no longer be logged in, and have to - login to their accounts again. - - See https://github.com/Pylons/pyramid/pull/2496 - -- The ``check_csrf_token`` function no longer validates a csrf token in the - query string of a request. Only headers and request bodies are supported. - See https://github.com/Pylons/pyramid/pull/2500 - -Features --------- - -- Added a new setting, ``pyramid.require_default_csrf`` which may be used - to turn on CSRF checks globally for every POST request in the application. - This should be considered a good default for websites built on Pyramid. - It is possible to opt-out of CSRF checks on a per-view basis by setting - ``require_csrf=False`` on those views. - See https://github.com/Pylons/pyramid/pull/2413 - -- Added a ``require_csrf`` view option which will enforce CSRF checks on any - request with an unsafe method as defined by RFC2616. If the CSRF check fails - a ``BadCSRFToken`` exception will be raised and may be caught by exception - views (the default response is a ``400 Bad Request``). This option should be - used in place of the deprecated ``check_csrf`` view predicate which would - normally result in unexpected ``404 Not Found`` response to the client - instead of a catchable exception. See - https://github.com/Pylons/pyramid/pull/2413 and - https://github.com/Pylons/pyramid/pull/2500 - -- Added an additional CSRF validation that checks the origin/referrer of a - request and makes sure it matches the current ``request.domain``. This - particular check is only active when accessing a site over HTTPS as otherwise - browsers don't always send the required information. If this additional CSRF - validation fails a ``BadCSRFOrigin`` exception will be raised and may be - caught by exception views (the default response is ``400 Bad Request``). - Additional allowed origins may be configured by setting - ``pyramid.csrf_trusted_origins`` to a list of domain names (with ports if on - a non standard port) to allow. Subdomains are not allowed unless the domain - name has been prefixed with a ``.``. See - https://github.com/Pylons/pyramid/pull/2501 - -- Added a new ``pyramid.session.check_csrf_origin`` API for validating the - origin or referrer headers against the request's domain. - See https://github.com/Pylons/pyramid/pull/2501 - -- Pyramid HTTPExceptions will now take into account the best match for the - clients Accept header, and depending on what is requested will return - text/html, application/json or text/plain. The default for */* is still - text/html, but if application/json is explicitly mentioned it will now - receive a valid JSON response. See - https://github.com/Pylons/pyramid/pull/2489 - -- A new event and interface (BeforeTraversal) has been introduced that will - notify listeners before traversal starts in the router. See - https://github.com/Pylons/pyramid/pull/2469 and - https://github.com/Pylons/pyramid/pull/1876 - -- Add a new "view deriver" concept to Pyramid to allow framework authors to - inject elements into the standard Pyramid view pipeline and affect all - views in an application. This is similar to a decorator except that it - has access to options passed to ``config.add_view`` and can affect other - stages of the pipeline such as the raw response from a view or prior to - security checks. See https://github.com/Pylons/pyramid/pull/2021 - -- Allow a leading ``=`` on the key of the request param predicate. - For example, '=abc=1' is equivalent down to - ``request.params['=abc'] == '1'``. - See https://github.com/Pylons/pyramid/pull/1370 - -- A new ``request.invoke_exception_view(...)`` method which can be used to - invoke an exception view and get back a response. This is useful for - rendering an exception view outside of the context of the excview tween - where you may need more control over the request. - See https://github.com/Pylons/pyramid/pull/2393 - -- Allow using variable substitutions like ``%(LOGGING_LOGGER_ROOT_LEVEL)s`` - for logging sections of the .ini file and populate these variables from - the ``pserve`` command line -- e.g.: - ``pserve development.ini LOGGING_LOGGER_ROOT_LEVEL=DEBUG`` - See https://github.com/Pylons/pyramid/pull/2399 - -Documentation Changes ---------------------- - -- A complete overhaul of the docs: - - - Use pip instead of easy_install. - - Become opinionated by preferring Python 3.4 or greater to simplify - installation of Python and its required packaging tools. - - Use venv for the tool, and virtual environment for the thing created, - instead of virtualenv. - - Use py.test and pytest-cov instead of nose and coverage. - - Further updates to the scaffolds as well as tutorials and their src files. - - See https://github.com/Pylons/pyramid/pull/2468 - -- A complete overhaul of the ``alchemy`` scaffold as well as the - Wiki2 SQLAlchemy + URLDispatch tutorial to introduce more modern features - into the usage of SQLAlchemy with Pyramid and provide a better starting - point for new projects. - See https://github.com/Pylons/pyramid/pull/2024 - -Bug Fixes ---------- - -- Fix ``pserve --browser`` to use the ``--server-name`` instead of the - app name when selecting a section to use. This was only working for people - who had server and app sections with the same name, for example - ``[app:main]`` and ``[server:main]``. - See https://github.com/Pylons/pyramid/pull/2292 - -Deprecations ------------- - -- The ``check_csrf`` view predicate has been deprecated. Use the - new ``require_csrf`` option or the ``pyramid.require_default_csrf`` setting - to ensure that the ``BadCSRFToken`` exception is raised. - See https://github.com/Pylons/pyramid/pull/2413 - -- Support for Python 3.3 will be removed in Pyramid 1.8. - https://github.com/Pylons/pyramid/issues/2477 - -- Python 2.6 is no longer supported by Pyramid. See - https://github.com/Pylons/pyramid/issues/2368 - -- Dropped Python 3.2 support. - See https://github.com/Pylons/pyramid/pull/2256 - -1.6 (2016-01-03) -================ - -Deprecations ------------- - -- Continue removal of ``pserve`` daemon/process management features - by deprecating ``--user`` and ``--group`` options. - See https://github.com/Pylons/pyramid/pull/2190 - -1.6b3 (2015-12-17) -================== - -Backward Incompatibilities --------------------------- - -- Remove the ``cachebust`` option from ``config.add_static_view``. See - ``config.add_cache_buster`` for the new way to attach cache busters to - static assets. - See https://github.com/Pylons/pyramid/pull/2186 - -- Modify the ``pyramid.interfaces.ICacheBuster`` API to be a simple callable - instead of an object with ``match`` and ``pregenerate`` methods. Cache - busters are now focused solely on generation. Matching has been dropped. - - Note this affects usage of ``pyramid.static.QueryStringCacheBuster`` and - ``pyramid.static.ManifestCacheBuster``. - - See https://github.com/Pylons/pyramid/pull/2186 - -Features --------- - -- Add a new ``config.add_cache_buster`` API for attaching cache busters to - static assets. See https://github.com/Pylons/pyramid/pull/2186 - -Bug Fixes ---------- - -- Ensure that ``IAssetDescriptor.abspath`` always returns an absolute path. - There were cases depending on the process CWD that a relative path would - be returned. See https://github.com/Pylons/pyramid/issues/2188 - -1.6b2 (2015-10-15) -================== - -Features --------- - -- Allow asset specifications to be supplied to - ``pyramid.static.ManifestCacheBuster`` instead of requiring a - filesystem path. - -1.6b1 (2015-10-15) -================== - -Backward Incompatibilities --------------------------- - -- IPython and BPython support have been removed from pshell in the core. - To continue using them on Pyramid 1.6+ you must install the binding - packages explicitly:: - - $ pip install pyramid_ipython - - or - - $ pip install pyramid_bpython - -- Remove default cache busters introduced in 1.6a1 including - ``PathSegmentCacheBuster``, ``PathSegmentMd5CacheBuster``, and - ``QueryStringMd5CacheBuster``. - See https://github.com/Pylons/pyramid/pull/2116 - -Features --------- - -- Additional shells for ``pshell`` can now be registered as entrypoints. See - https://github.com/Pylons/pyramid/pull/1891 and - https://github.com/Pylons/pyramid/pull/2012 - -- The variables injected into ``pshell`` are now displayed with their - docstrings instead of the default ``str(obj)`` when possible. - See https://github.com/Pylons/pyramid/pull/1929 - -- Add new ``pyramid.static.ManifestCacheBuster`` for use with external - asset pipelines as well as examples of common usages in the narrative. - See https://github.com/Pylons/pyramid/pull/2116 - -- Fix ``pserve --reload`` to not crash on syntax errors!!! - See https://github.com/Pylons/pyramid/pull/2125 - -- Fix an issue when user passes unparsed strings to ``pyramid.session.CookieSession`` - and ``pyramid.authentication.AuthTktCookieHelper`` for time related parameters - ``timeout``, ``reissue_time``, ``max_age`` that expect an integer value. - See https://github.com/Pylons/pyramid/pull/2050 - -Bug Fixes ---------- - -- ``pyramid.httpexceptions.HTTPException`` now defaults to - ``520 Unknown Error`` instead of ``None None`` to conform with changes in - WebOb 1.5. - See https://github.com/Pylons/pyramid/pull/1865 - -- ``pshell`` will now preserve the capitalization of variables in the - ``[pshell]`` section of the INI file. This makes exposing classes to the - shell a little more straightfoward. - See https://github.com/Pylons/pyramid/pull/1883 - -- Fixed usage of ``pserve --monitor-restart --daemon`` which would fail in - horrible ways. See https://github.com/Pylons/pyramid/pull/2118 - -- Explicitly prevent ``pserve --reload --daemon`` from being used. It's never - been supported but would work and fail in weird ways. - See https://github.com/Pylons/pyramid/pull/2119 - -- Fix an issue on Windows when running ``pserve --reload`` in which the - process failed to fork because it could not find the pserve script to - run. See https://github.com/Pylons/pyramid/pull/2138 - -Deprecations ------------- - -- Deprecate ``pserve --monitor-restart`` in favor of user's using a real - process manager such as Systemd or Upstart as well as Python-based - solutions like Circus and Supervisor. - See https://github.com/Pylons/pyramid/pull/2120 - -1.6a2 (2015-06-30) -================== - -Bug Fixes ---------- - -- Ensure that ``pyramid.httpexceptions.exception_response`` returns the - appropriate "concrete" class for ``400`` and ``500`` status codes. - See https://github.com/Pylons/pyramid/issues/1832 - -- Fix an infinite recursion bug introduced in 1.6a1 when - ``pyramid.view.render_view_to_response`` was called directly or indirectly. - See https://github.com/Pylons/pyramid/issues/1643 - -- Further fix the JSONP renderer by prefixing the returned content with - a comment. This should mitigate attacks from Flash (See CVE-2014-4671). - See https://github.com/Pylons/pyramid/pull/1649 - -- Allow periods and brackets (``[]``) in the JSONP callback. The original - fix was overly-restrictive and broke Angular. - See https://github.com/Pylons/pyramid/pull/1649 - -1.6a1 (2015-04-15) -================== - -Features --------- - -- pcreate will now ask for confirmation if invoked with - an argument for a project name that already exists or - is importable in the current environment. - See https://github.com/Pylons/pyramid/issues/1357 and - https://github.com/Pylons/pyramid/pull/1837 - -- Make it possible to subclass ``pyramid.request.Request`` and also use - ``pyramid.request.Request.add_request.method``. See - https://github.com/Pylons/pyramid/issues/1529 - -- The ``pyramid.config.Configurator`` has grown the ability to allow - actions to call other actions during a commit-cycle. This enables much more - logic to be placed into actions, such as the ability to invoke other actions - or group them for improved conflict detection. We have also exposed and - documented the config phases that Pyramid uses in order to further assist - in building conforming addons. - See https://github.com/Pylons/pyramid/pull/1513 - -- Add ``pyramid.request.apply_request_extensions`` function which can be - used in testing to apply any request extensions configured via - ``config.add_request_method``. Previously it was only possible to test - the extensions by going through Pyramid's router. - See https://github.com/Pylons/pyramid/pull/1581 - -- pcreate when run without a scaffold argument will now print information on - the missing flag, as well as a list of available scaffolds. - See https://github.com/Pylons/pyramid/pull/1566 and - https://github.com/Pylons/pyramid/issues/1297 - -- Added support / testing for 'pypy3' under Tox and Travis. - See https://github.com/Pylons/pyramid/pull/1469 - -- Automate code coverage metrics across py2 and py3 instead of just py2. - See https://github.com/Pylons/pyramid/pull/1471 - -- Cache busting for static resources has been added and is available via a new - argument to ``pyramid.config.Configurator.add_static_view``: ``cachebust``. - Core APIs are shipped for both cache busting via query strings and - path segments and may be extended to fit into custom asset pipelines. - See https://github.com/Pylons/pyramid/pull/1380 and - https://github.com/Pylons/pyramid/pull/1583 - -- Add ``pyramid.config.Configurator.root_package`` attribute and init - parameter to assist with includeable packages that wish to resolve - resources relative to the package in which the ``Configurator`` was created. - This is especially useful for addons that need to load asset specs from - settings, in which case it is may be natural for a developer to define - imports or assets relative to the top-level package. - See https://github.com/Pylons/pyramid/pull/1337 - -- Added line numbers to the log formatters in the scaffolds to assist with - debugging. See https://github.com/Pylons/pyramid/pull/1326 - -- Add new HTTP exception objects for status codes - ``428 Precondition Required``, ``429 Too Many Requests`` and - ``431 Request Header Fields Too Large`` in ``pyramid.httpexceptions``. - See https://github.com/Pylons/pyramid/pull/1372/files - -- The ``pshell`` script will now load a ``PYTHONSTARTUP`` file if one is - defined in the environment prior to launching the interpreter. - See https://github.com/Pylons/pyramid/pull/1448 - -- Make it simple to define notfound and forbidden views that wish to use - the default exception-response view but with altered predicates and other - configuration options. The ``view`` argument is now optional in - ``config.add_notfound_view`` and ``config.add_forbidden_view``.. - See https://github.com/Pylons/pyramid/issues/494 - -- Greatly improve the readability of the ``pcreate`` shell script output. - See https://github.com/Pylons/pyramid/pull/1453 - -- Improve robustness to timing attacks in the ``AuthTktCookieHelper`` and - the ``SignedCookieSessionFactory`` classes by using the stdlib's - ``hmac.compare_digest`` if it is available (such as Python 2.7.7+ and 3.3+). - See https://github.com/Pylons/pyramid/pull/1457 - -- Assets can now be overidden by an absolute path on the filesystem when using - the ``config.override_asset`` API. This makes it possible to fully support - serving up static content from a mutable directory while still being able - to use the ``request.static_url`` API and ``config.add_static_view``. - Previously it was not possible to use ``config.add_static_view`` with an - absolute path **and** generate urls to the content. This change replaces - the call, ``config.add_static_view('/abs/path', 'static')``, with - ``config.add_static_view('myapp:static', 'static')`` and - ``config.override_asset(to_override='myapp:static/', - override_with='/abs/path/')``. The ``myapp:static`` asset spec is completely - made up and does not need to exist - it is used for generating urls - via ``request.static_url('myapp:static/foo.png')``. - See https://github.com/Pylons/pyramid/issues/1252 - -- Added ``pyramid.config.Configurator.set_response_factory`` and the - ``response_factory`` keyword argument to the ``Configurator`` for defining - a factory that will return a custom ``Response`` class. - See https://github.com/Pylons/pyramid/pull/1499 - -- Allow an iterator to be returned from a renderer. Previously it was only - possible to return bytes or unicode. - See https://github.com/Pylons/pyramid/pull/1417 - -- ``pserve`` can now take a ``-b`` or ``--browser`` option to open the server - URL in a web browser. See https://github.com/Pylons/pyramid/pull/1533 - -- Overall improvments for the ``proutes`` command. Added ``--format`` and - ``--glob`` arguments to the command, introduced the ``method`` - column for displaying available request methods, and improved the ``view`` - output by showing the module instead of just ``__repr__``. - See https://github.com/Pylons/pyramid/pull/1488 - -- Support keyword-only arguments and function annotations in views in - Python 3. See https://github.com/Pylons/pyramid/pull/1556 - -- ``request.response`` will no longer be mutated when using the - ``pyramid.renderers.render_to_response()`` API. It is now necessary to - pass in a ``response=`` argument to ``render_to_response`` if you wish to - supply the renderer with a custom response object for it to use. If you - do not pass one then a response object will be created using the - application's ``IResponseFactory``. Almost all renderers - mutate the ``request.response`` response object (for example, the JSON - renderer sets ``request.response.content_type`` to ``application/json``). - However, when invoking ``render_to_response`` it is not expected that the - response object being returned would be the same one used later in the - request. The response object returned from ``render_to_response`` is now - explicitly different from ``request.response``. This does not change the - API of a renderer. See https://github.com/Pylons/pyramid/pull/1563 - -- The ``append_slash`` argument of ```Configurator().add_notfound_view()`` will - now accept anything that implements the ``IResponse`` interface and will use - that as the response class instead of the default ``HTTPFound``. See - https://github.com/Pylons/pyramid/pull/1610 - -Bug Fixes ---------- - -- The JSONP renderer created JavaScript code in such a way that a callback - variable could be used to arbitrarily inject javascript into the response - object. https://github.com/Pylons/pyramid/pull/1627 - -- Work around an issue where ``pserve --reload`` would leave terminal echo - disabled if it reloaded during a pdb session. - See https://github.com/Pylons/pyramid/pull/1577, - https://github.com/Pylons/pyramid/pull/1592 - -- ``pyramid.wsgi.wsgiapp`` and ``pyramid.wsgi.wsgiapp2`` now raise - ``ValueError`` when accidentally passed ``None``. - See https://github.com/Pylons/pyramid/pull/1320 - -- Fix an issue whereby predicates would be resolved as maybe_dotted in the - introspectable but not when passed for registration. This would mean that - ``add_route_predicate`` for example can not take a string and turn it into - the actual callable function. - See https://github.com/Pylons/pyramid/pull/1306 - -- Fix ``pyramid.testing.setUp`` to return a ``Configurator`` with a proper - package. Previously it was not possible to do package-relative includes - using the returned ``Configurator`` during testing. There is now a - ``package`` argument that can override this behavior as well. - See https://github.com/Pylons/pyramid/pull/1322 - -- Fix an issue where a ``pyramid.response.FileResponse`` may apply a charset - where it does not belong. See https://github.com/Pylons/pyramid/pull/1251 - -- Work around a bug introduced in Python 2.7.7 on Windows where - ``mimetypes.guess_type`` returns Unicode rather than str for the content - type, unlike any previous version of Python. See - https://github.com/Pylons/pyramid/issues/1360 for more information. - -- ``pcreate`` now normalizes the package name by converting hyphens to - underscores. See https://github.com/Pylons/pyramid/pull/1376 - -- Fix an issue with the final response/finished callback being unable to - add another callback to the list. See - https://github.com/Pylons/pyramid/pull/1373 - -- Fix a failing unittest caused by differing mimetypes across various OSs. - See https://github.com/Pylons/pyramid/issues/1405 - -- Fix route generation for static view asset specifications having no path. - See https://github.com/Pylons/pyramid/pull/1377 - -- Allow the ``pyramid.renderers.JSONP`` renderer to work even if there is no - valid request object. In this case it will not wrap the object in a - callback and thus behave just like the ``pyramid.renderers.JSON`` renderer. - See https://github.com/Pylons/pyramid/pull/1561 - -- Prevent "parameters to load are deprecated" ``DeprecationWarning`` - from setuptools>=11.3. See https://github.com/Pylons/pyramid/pull/1541 - -- Avoiding sharing the ``IRenderer`` objects across threads when attached to - a view using the `renderer=` argument. These renderers were instantiated - at time of first render and shared between requests, causing potentially - subtle effects like `pyramid.reload_templates = true` failing to work - in `pyramid_mako`. See https://github.com/Pylons/pyramid/pull/1575 - and https://github.com/Pylons/pyramid/issues/1268 - -- Avoiding timing attacks against CSRF tokens. - See https://github.com/Pylons/pyramid/pull/1574 - -- ``request.finished_callbacks`` and ``request.response_callbacks`` now - default to an iterable instead of ``None``. It may be checked for a length - of 0. This was the behavior in 1.5. - -Deprecations ------------- - -- The ``pserve`` command's daemonization features have been deprecated. This - includes the ``[start,stop,restart,status]`` subcommands as well as the - ``--daemon``, ``--stop-server``, ``--pid-file``, and ``--status`` flags. - - Please use a real process manager in the future instead of relying on the - ``pserve`` to daemonize itself. Many options exist including your Operating - System's services such as Systemd or Upstart, as well as Python-based - solutions like Circus and Supervisor. - - See https://github.com/Pylons/pyramid/pull/1641 - -- Renamed the ``principal`` argument to ``pyramid.security.remember()`` to - ``userid`` in order to clarify its intended purpose. - See https://github.com/Pylons/pyramid/pull/1399 - -Docs ----- - -- Moved the documentation for ``accept`` on ``Configurator.add_view`` to no - longer be part of the predicate list. See - https://github.com/Pylons/pyramid/issues/1391 for a bug report stating - ``not_`` was failing on ``accept``. Discussion with @mcdonc led to the - conclusion that it should not be documented as a predicate. - See https://github.com/Pylons/pyramid/pull/1487 for this PR - -- Removed logging configuration from Quick Tutorial ini files except for - scaffolding- and logging-related chapters to avoid needing to explain it too - early. - -- Clarify a previously-implied detail of the ``ISession.invalidate`` API - documentation. - -- Improve and clarify the documentation on what Pyramid defines as a - ``principal`` and a ``userid`` in its security APIs. - See https://github.com/Pylons/pyramid/pull/1399 - -- Add documentation of command line programs (``p*`` scripts). See - https://github.com/Pylons/pyramid/pull/2191 - -Scaffolds ---------- - -- Update scaffold generating machinery to return the version of pyramid and - pyramid docs for use in scaffolds. Updated starter, alchemy and zodb - templates to have links to correctly versioned documentation and reflect - which pyramid was used to generate the scaffold. - -- Removed non-ascii copyright symbol from templates, as this was - causing the scaffolds to fail for project generation. - -- You can now run the scaffolding func tests via ``tox py2-scaffolds`` and - ``tox py3-scaffolds``. - - -1.5 (2014-04-08) -================ - -- Python 3.4 compatibility. - -- Avoid crash in ``pserve --reload`` under Py3k, when iterating over possibly - mutated ``sys.modules``. - -- ``UnencryptedCookieSessionFactoryConfig`` failed if the secret contained - higher order characters. See https://github.com/Pylons/pyramid/issues/1246 - -- Fixed a bug in ``UnencryptedCookieSessionFactoryConfig`` and - ``SignedCookieSessionFactory`` where ``timeout=None`` would cause a new - session to always be created. Also in ``SignedCookieSessionFactory`` a - ``reissue_time=None`` would cause an exception when modifying the session. - See https://github.com/Pylons/pyramid/issues/1247 - -- Updated docs and scaffolds to keep in step with new 2.0 release of - ``Lingua``. This included removing all ``setup.cfg`` files from scaffolds - and documentation environments. - -1.5b1 (2014-02-08) -================== - -Features --------- - -- We no longer eagerly clear ``request.exception`` and ``request.exc_info`` in - the exception view tween. This makes it possible to inspect exception - information within a finished callback. See - https://github.com/Pylons/pyramid/issues/1223. - -1.5a4 (2014-01-28) -================== - -Features --------- - -- Updated scaffolds with new theme, fixed documentation and sample project. - -Bug Fixes ---------- - -- Depend on a newer version of WebOb so that we pull in some crucial bug-fixes - that were showstoppers for functionality in Pyramid. - -- Add a trailing semicolon to the JSONP response. This fixes JavaScript syntax - errors for old IE versions. See https://github.com/Pylons/pyramid/pull/1205 - -- Fix a memory leak when the configurator's ``set_request_property`` method was - used or when the configurator's ``add_request_method`` method was used with - the ``property=True`` attribute. See - https://github.com/Pylons/pyramid/issues/1212 . - -1.5a3 (2013-12-10) -================== - -Features --------- - -- An authorization API has been added as a method of the - request: ``request.has_permission``. - - ``request.has_permission`` is a method-based alternative to the - ``pyramid.security.has_permission`` API and works exactly the same. The - older API is now deprecated. - -- Property API attributes have been added to the request for easier access to - authentication data: ``request.authenticated_userid``, - ``request.unauthenticated_userid``, and ``request.effective_principals``. - - These are analogues, respectively, of - ``pyramid.security.authenticated_userid``, - ``pyramid.security.unauthenticated_userid``, and - ``pyramid.security.effective_principals``. They operate exactly the same, - except they are attributes of the request instead of functions accepting a - request. They are properties, so they cannot be assigned to. The older - function-based APIs are now deprecated. - -- Pyramid's console scripts (``pserve``, ``pviews``, etc) can now be run - directly, allowing custom arguments to be sent to the python interpreter - at runtime. For example:: - - python -3 -m pyramid.scripts.pserve development.ini - -- Added a specific subclass of ``HTTPBadRequest`` named - ``pyramid.exceptions.BadCSRFToken`` which will now be raised in response - to failures in ``check_csrf_token``. - See https://github.com/Pylons/pyramid/pull/1149 - -- Added a new ``SignedCookieSessionFactory`` which is very similar to the - ``UnencryptedCookieSessionFactoryConfig`` but with a clearer focus on signing - content. The custom serializer arguments to this function should only focus - on serializing, unlike its predecessor which required the serializer to also - perform signing. See https://github.com/Pylons/pyramid/pull/1142 . Note - that cookies generated using ``SignedCookieSessionFactory`` are not - compatible with cookies generated using ``UnencryptedCookieSessionFactory``, - so existing user session data will be destroyed if you switch to it. - -- Added a new ``BaseCookieSessionFactory`` which acts as a generic cookie - factory that can be used by framework implementors to create their own - session implementations. It provides a reusable API which focuses strictly - on providing a dictionary-like object that properly handles renewals, - timeouts, and conformance with the ``ISession`` API. - See https://github.com/Pylons/pyramid/pull/1142 - -- The anchor argument to ``pyramid.request.Request.route_url`` and - ``pyramid.request.Request.resource_url`` and their derivatives will now be - escaped via URL quoting to ensure minimal conformance. See - https://github.com/Pylons/pyramid/pull/1183 - -- Allow sending of ``_query`` and ``_anchor`` options to - ``pyramid.request.Request.static_url`` when an external URL is being - generated. - See https://github.com/Pylons/pyramid/pull/1183 - -- You can now send a string as the ``_query`` argument to - ``pyramid.request.Request.route_url`` and - ``pyramid.request.Request.resource_url`` and their derivatives. When a - string is sent instead of a list or dictionary. it is URL-quoted however it - does not need to be in ``k=v`` form. This is useful if you want to be able - to use a different query string format than ``x-www-form-urlencoded``. See - https://github.com/Pylons/pyramid/pull/1183 - -- ``pyramid.testing.DummyRequest`` now has a ``domain`` attribute to match the - new WebOb 1.3 API. Its value is ``example.com``. - -Bug Fixes ---------- - -- Fix the ``pcreate`` script so that when the target directory name ends with a - slash it does not produce a non-working project directory structure. - Previously saying ``pcreate -s starter /foo/bar/`` produced different output - than saying ``pcreate -s starter /foo/bar``. The former did not work - properly. - -- Fix the ``principals_allowed_by_permission`` method of - ``ACLAuthorizationPolicy`` so it anticipates a callable ``__acl__`` - on resources. Previously it did not try to call the ``__acl__`` - if it was callable. - -- The ``pviews`` script did not work when a url required custom request - methods in order to perform traversal. Custom methods and descriptors added - via ``pyramid.config.Configurator.add_request_method`` will now be present, - allowing traversal to continue. - See https://github.com/Pylons/pyramid/issues/1104 - -- Remove unused ``renderer`` argument from ``Configurator.add_route``. - -- Allow the ``BasicAuthenticationPolicy`` to work with non-ascii usernames - and passwords. The charset is not passed as part of the header and different - browsers alternate between UTF-8 and Latin-1, so the policy now attempts - to decode with UTF-8 first, and will fallback to Latin-1. - See https://github.com/Pylons/pyramid/pull/1170 - -- The ``@view_defaults`` now apply to notfound and forbidden views - that are defined as methods of a decorated class. - See https://github.com/Pylons/pyramid/issues/1173 - -Documentation -------------- - -- Added a "Quick Tutorial" to go with the Quick Tour - -- Removed mention of ``pyramid_beaker`` from docs. Beaker is no longer - maintained. Point people at ``pyramid_redis_sessions`` instead. - -- Add documentation for ``pyramid.interfaces.IRendererFactory`` and - ``pyramid.interfaces.IRenderer``. - -Backwards Incompatibilities ---------------------------- - -- The key/values in the ``_query`` parameter of ``request.route_url`` and the - ``query`` parameter of ``request.resource_url`` (and their variants), used - to encode a value of ``None`` as the string ``'None'``, leaving the resulting - query string to be ``a=b&key=None``. The value is now dropped in this - situation, leaving a query string of ``a=b&key=``. - See https://github.com/Pylons/pyramid/issues/1119 - -Deprecations ------------- - -- Deprecate the ``pyramid.interfaces.ITemplateRenderer`` interface. It was - ill-defined and became unused when Mako and Chameleon template bindings were - split into their own packages. - -- The ``pyramid.session.UnencryptedCookieSessionFactoryConfig`` API has been - deprecated and is superseded by the - ``pyramid.session.SignedCookieSessionFactory``. Note that while the cookies - generated by the ``UnencryptedCookieSessionFactoryConfig`` - are compatible with cookies generated by old releases, cookies generated by - the SignedCookieSessionFactory are not. See - https://github.com/Pylons/pyramid/pull/1142 - -- The ``pyramid.security.has_permission`` API is now deprecated. Instead, use - the newly-added ``has_permission`` method of the request object. - -- The ``pyramid.security.effective_principals`` API is now deprecated. - Instead, use the newly-added ``effective_principals`` attribute of the - request object. - -- The ``pyramid.security.authenticated_userid`` API is now deprecated. - Instead, use the newly-added ``authenticated_userid`` attribute of the - request object. - -- The ``pyramid.security.unauthenticated_userid`` API is now deprecated. - Instead, use the newly-added ``unauthenticated_userid`` attribute of the - request object. - -Dependencies ------------- - -- Pyramid now depends on WebOb>=1.3 (it uses ``webob.cookies.CookieProfile`` - from 1.3+). - -1.5a2 (2013-09-22) -================== - -Features --------- - -- Users can now provide dotted Python names to as the ``factory`` argument - the Configurator methods named ``add_{view,route,subscriber}_predicate`` - (instead of passing the predicate factory directly, you can pass a - dotted name which refers to the factory). - -Bug Fixes ---------- - -- Fix an exception in ``pyramid.path.package_name`` when resolving the package - name for namespace packages that had no ``__file__`` attribute. - -Backwards Incompatibilities ---------------------------- - -- Pyramid no longer depends on or configures the Mako and Chameleon templating - system renderers by default. Disincluding these templating systems by - default means that the Pyramid core has fewer dependencies and can run on - future platforms without immediate concern for the compatibility of its - templating add-ons. It also makes maintenance slightly more effective, as - different people can maintain the templating system add-ons that they - understand and care about without needing commit access to the Pyramid core, - and it allows users who just don't want to see any packages they don't use - come along for the ride when they install Pyramid. - - This means that upon upgrading to Pyramid 1.5a2+, projects that use either - of these templating systems will see a traceback that ends something like - this when their application attempts to render a Chameleon or Mako template:: - - ValueError: No such renderer factory .pt - - Or:: - - ValueError: No such renderer factory .mako - - Or:: - - ValueError: No such renderer factory .mak - - Support for Mako templating has been moved into an add-on package named - ``pyramid_mako``, and support for Chameleon templating has been moved into - an add-on package named ``pyramid_chameleon``. These packages are drop-in - replacements for the old built-in support for these templating langauges. - All you have to do is install them and make them active in your configuration - to register renderer factories for ``.pt`` and/or ``.mako`` (or ``.mak``) to - make your application work again. - - To re-add support for Chameleon and/or Mako template renderers into your - existing projects, follow the below steps. - - If you depend on Mako templates: - - * Make sure the ``pyramid_mako`` package is installed. One way to do this - is by adding ``pyramid_mako`` to the ``install_requires`` section of your - package's ``setup.py`` file and afterwards rerunning ``setup.py develop``:: - - setup( - #... - install_requires=[ - 'pyramid_mako', # new dependency - 'pyramid', - #... - ], - ) - - * Within the portion of your application which instantiates a Pyramid - ``pyramid.config.Configurator`` (often the ``main()`` function in - your project's ``__init__.py`` file), tell Pyramid to include the - ``pyramid_mako`` includeme:: - - config = Configurator(.....) - config.include('pyramid_mako') - - If you depend on Chameleon templates: - - * Make sure the ``pyramid_chameleon`` package is installed. One way to do - this is by adding ``pyramid_chameleon`` to the ``install_requires`` section - of your package's ``setup.py`` file and afterwards rerunning - ``setup.py develop``:: - - setup( - #... - install_requires=[ - 'pyramid_chameleon', # new dependency - 'pyramid', - #... - ], - ) - - * Within the portion of your application which instantiates a Pyramid - ``~pyramid.config.Configurator`` (often the ``main()`` function in - your project's ``__init__.py`` file), tell Pyramid to include the - ``pyramid_chameleon`` includeme:: - - config = Configurator(.....) - config.include('pyramid_chameleon') - - Note that it's also fine to install these packages into *older* Pyramids for - forward compatibility purposes. Even if you don't upgrade to Pyramid 1.5 - immediately, performing the above steps in a Pyramid 1.4 installation is - perfectly fine, won't cause any difference, and will give you forward - compatibility when you eventually do upgrade to Pyramid 1.5. - - With the removal of Mako and Chameleon support from the core, some - unit tests that use the ``pyramid.renderers.render*`` methods may begin to - fail. If any of your unit tests are invoking either - ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response()`` - with either Mako or Chameleon templates then the - ``pyramid.config.Configurator`` instance in effect during - the unit test should be also be updated to include the addons, as shown - above. For example:: - - class ATest(unittest.TestCase): - def setUp(self): - self.config = pyramid.testing.setUp() - self.config.include('pyramid_mako') - - def test_it(self): - result = pyramid.renderers.render('mypkg:templates/home.mako', {}) - - Or:: - - class ATest(unittest.TestCase): - def setUp(self): - self.config = pyramid.testing.setUp() - self.config.include('pyramid_chameleon') - - def test_it(self): - result = pyramid.renderers.render('mypkg:templates/home.pt', {}) - -- If you're using the Pyramid debug toolbar, when you upgrade Pyramid to - 1.5a2+, you'll also need to upgrade the ``pyramid_debugtoolbar`` package to - at least version 1.0.8, as older toolbar versions are not compatible with - Pyramid 1.5a2+ due to the removal of Mako support from the core. It's - fine to use this newer version of the toolbar code with older Pyramids too. - -- Removed the ``request.response_*`` varying attributes. These attributes - have been deprecated since Pyramid 1.1, and as per the deprecation policy, - have now been removed. - -- ``request.response`` will no longer be mutated when using the - ``pyramid.renderers.render()`` API. Almost all renderers mutate the - ``request.response`` response object (for example, the JSON renderer sets - ``request.response.content_type`` to ``application/json``), but this is - only necessary when the renderer is generating a response; it was a bug - when it was done as a side effect of calling ``pyramid.renderers.render()``. - -- Removed the ``bfg2pyramid`` fixer script. - -- The ``pyramid.events.NewResponse`` event is now sent **after** response - callbacks are executed. It previously executed before response callbacks - were executed. Rationale: it's more useful to be able to inspect the response - after response callbacks have done their jobs instead of before. - -- Removed the class named ``pyramid.view.static`` that had been deprecated - since Pyramid 1.1. Instead use ``pyramid.static.static_view`` with - ``use_subpath=True`` argument. - -- Removed the ``pyramid.view.is_response`` function that had been deprecated - since Pyramid 1.1. Use the ``pyramid.request.Request.is_response`` method - instead. - -- Removed the ability to pass the following arguments to - ``pyramid.config.Configurator.add_route``: ``view``, ``view_context``. - ``view_for``, ``view_permission``, ``view_renderer``, and ``view_attr``. - Using these arguments had been deprecated since Pyramid 1.1. Instead of - passing view-related arguments to ``add_route``, use a separate call to - ``pyramid.config.Configurator.add_view`` to associate a view with a route - using its ``route_name`` argument. Note that this impacts the - ``pyramid.config.Configurator.add_static_view`` function too, because it - delegates to ``add_route``. - -- Removed the ability to influence and query a ``pyramid.request.Request`` - object as if it were a dictionary. Previously it was possible to use methods - like ``__getitem__``, ``get``, ``items``, and other dictlike methods to - access values in the WSGI environment. This behavior had been deprecated - since Pyramid 1.1. Use methods of ``request.environ`` (a real dictionary) - instead. - -- Removed ancient backwards compatibily hack in - ``pyramid.traversal.DefaultRootFactory`` which populated the ``__dict__`` of - the factory with the matchdict values for compatibility with BFG 0.9. - -- The ``renderer_globals_factory`` argument to the - ``pyramid.config.Configurator` constructor and its ``setup_registry`` method - has been removed. The ``set_renderer_globals_factory`` method of - ``pyramid.config.Configurator`` has also been removed. The (internal) - ``pyramid.interfaces.IRendererGlobals`` interface was also removed. These - arguments, methods and interfaces had been deprecated since 1.1. Use a - ``BeforeRender`` event subscriber as documented in the "Hooks" chapter of the - Pyramid narrative documentation instead of providing renderer globals values - to the configurator. - -Deprecations ------------- - -- The ``pyramid.config.Configurator.set_request_property`` method now issues - a deprecation warning when used. It had been docs-deprecated in 1.4 - but did not issue a deprecation warning when used. - -1.5a1 (2013-08-30) -================== - -Features --------- - -- A new http exception subclass named ``pyramid.httpexceptions.HTTPSuccessful`` - was added. You can use this class as the ``context`` of an exception - view to catch all 200-series "exceptions" (e.g. "raise HTTPOk"). This - also allows you to catch *only* the ``HTTPOk`` exception itself; previously - this was impossible because a number of other exceptions - (such as ``HTTPNoContent``) inherited from ``HTTPOk``, but now they do not. - -- You can now generate "hybrid" urldispatch/traversal URLs more easily - by using the new ``route_name``, ``route_kw`` and ``route_remainder_name`` - arguments to ``request.resource_url`` and ``request.resource_path``. See - the new section of the "Combining Traversal and URL Dispatch" documentation - chapter entitled "Hybrid URL Generation". - -- It is now possible to escape double braces in Pyramid scaffolds (unescaped, - these represent replacement values). You can use ``\{\{a\}\}`` to - represent a "bare" ``{{a}}``. See - https://github.com/Pylons/pyramid/pull/862 - -- Add ``localizer`` and ``locale_name`` properties (reified) to the request. - See https://github.com/Pylons/pyramid/issues/508. Note that the - ``pyramid.i18n.get_localizer`` and ``pyramid.i18n.get_locale_name`` functions - now simply look up these properties on the request. - -- Add ``pdistreport`` script, which prints the Python version in use, the - Pyramid version in use, and the version number and location of all Python - distributions currently installed. - -- Add the ability to invert the result of any view, route, or subscriber - predicate using the ``not_`` class. For example:: - - from pyramid.config import not_ - - @view_config(route_name='myroute', request_method=not_('POST')) - def myview(request): ... - - The above example will ensure that the view is called if the request method - is not POST (at least if no other view is more specific). - - The ``pyramid.config.not_`` class can be used against any value that is - a predicate value passed in any of these contexts: - - - ``pyramid.config.Configurator.add_view`` - - - ``pyramid.config.Configurator.add_route`` - - - ``pyramid.config.Configurator.add_subscriber`` - - - ``pyramid.view.view_config`` - - - ``pyramid.events.subscriber`` - -- ``scripts/prequest.py``: add support for submitting ``PUT`` and ``PATCH`` - requests. See https://github.com/Pylons/pyramid/pull/1033. add support for - submitting ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify - basic authentication credentials in the request via a ``--login`` argument to - the script. See https://github.com/Pylons/pyramid/pull/1039. - -- ``ACLAuthorizationPolicy`` supports ``__acl__`` as a callable. This - removes the ambiguity between the potential ``AttributeError`` that would - be raised on the ``context`` when the property was not defined and the - ``AttributeError`` that could be raised from any user-defined code within - a dynamic property. It is recommended to define a dynamic ACL as a callable - to avoid this ambiguity. See https://github.com/Pylons/pyramid/issues/735. - -- Allow a protocol-relative URL (e.g. ``//example.com/images``) to be passed to - ``pyramid.config.Configurator.add_static_view``. This allows - externally-hosted static URLs to be generated based on the current protocol. - -- The ``AuthTktAuthenticationPolicy`` has two new options to configure its - domain usage: - - * ``parent_domain``: if set the authentication cookie is set on - the parent domain. This is useful if you have multiple sites sharing the - same domain. - * ``domain``: if provided the cookie is always set for this domain, bypassing - all usual logic. - - See https://github.com/Pylons/pyramid/pull/1028, - https://github.com/Pylons/pyramid/pull/1072 and - https://github.com/Pylons/pyramid/pull/1078. - -- The ``AuthTktAuthenticationPolicy`` now supports IPv6 addresses when using - the ``include_ip=True`` option. This is possibly incompatible with - alternative ``auth_tkt`` implementations, as the specification does not - define how to properly handle IPv6. See - https://github.com/Pylons/pyramid/issues/831. - -- Make it possible to use variable arguments via - ``pyramid.paster.get_appsettings``. This also allowed the generated - ``initialize_db`` script from the ``alchemy`` scaffold to grow support - for options in the form ``a=1 b=2`` so you can fill in - values in a parameterized ``.ini`` file, e.g. - ``initialize_myapp_db etc/development.ini a=1 b=2``. - See https://github.com/Pylons/pyramid/pull/911 - -- The ``request.session.check_csrf_token()`` method and the ``check_csrf`` view - predicate now take into account the value of the HTTP header named - ``X-CSRF-Token`` (as well as the ``csrf_token`` form parameter, which they - always did). The header is tried when the form parameter does not exist. - -- View lookup will now search for valid views based on the inheritance - hierarchy of the context. It tries to find views based on the most - specific context first, and upon predicate failure, will move up the - inheritance chain to test views found by the super-type of the context. - In the past, only the most specific type containing views would be checked - and if no matching view could be found then a PredicateMismatch would be - raised. Now predicate mismatches don't hide valid views registered on - super-types. Here's an example that now works:: - - class IResource(Interface): - - ... - - @view_config(context=IResource) - def get(context, request): - - ... - - @view_config(context=IResource, request_method='POST') - def post(context, request): - - ... - - @view_config(context=IResource, request_method='DELETE') - def delete(context, request): - - ... - - @implementer(IResource) - class MyResource: - - ... - - @view_config(context=MyResource, request_method='POST') - def override_post(context, request): - - ... - - Previously the override_post view registration would hide the get - and delete views in the context of MyResource -- leading to a - predicate mismatch error when trying to use GET or DELETE - methods. Now the views are found and no predicate mismatch is - raised. - See https://github.com/Pylons/pyramid/pull/786 and - https://github.com/Pylons/pyramid/pull/1004 and - https://github.com/Pylons/pyramid/pull/1046 - -- The ``pserve`` command now takes a ``-v`` (or ``--verbose``) flag and a - ``-q`` (or ``--quiet``) flag. Output from running ``pserve`` can be - controlled using these flags. ``-v`` can be specified multiple times to - increase verbosity. ``-q`` sets verbosity to ``0`` unconditionally. The - default verbosity level is ``1``. - -- The ``alchemy`` scaffold tests now provide better coverage. See - https://github.com/Pylons/pyramid/pull/1029 - -- The ``pyramid.config.Configurator.add_route`` method now supports being - called with an external URL as pattern. See - https://github.com/Pylons/pyramid/issues/611 and the documentation section - in the "URL Dispatch" chapter entitled "External Routes" for more information. - -Bug Fixes ---------- - -- It was not possible to use ``pyramid.httpexceptions.HTTPException`` as - the ``context`` of an exception view as very general catchall for - http-related exceptions when you wanted that exception view to override the - default exception view. See https://github.com/Pylons/pyramid/issues/985 - -- When the ``pyramid.reload_templates`` setting was true, and a Chameleon - template was reloaded, and the renderer specification named a macro - (e.g. ``foo#macroname.pt``), renderings of the template after the template - was reloaded due to a file change would produce the entire template body - instead of just a rendering of the macro. See - https://github.com/Pylons/pyramid/issues/1013. - -- Fix an obscure problem when combining a virtual root with a route with a - ``*traverse`` in its pattern. Now the traversal path generated in - such a configuration will be correct, instead of an element missing - a leading slash. - -- Fixed a Mako renderer bug returning a tuple with a previous defname value - in some circumstances. See https://github.com/Pylons/pyramid/issues/1037 - for more information. - -- Make the ``pyramid.config.assets.PackageOverrides`` object implement the API - for ``__loader__`` objects specified in PEP 302. Proxies to the - ``__loader__`` set by the importer, if present; otherwise, raises - ``NotImplementedError``. This makes Pyramid static view overrides work - properly under Python 3.3 (previously they would not). See - https://github.com/Pylons/pyramid/pull/1015 for more information. - -- ``mako_templating``: added defensive workaround for non-importability of - ``mako`` due to upstream ``markupsafe`` dropping Python 3.2 support. Mako - templating will no longer work under the combination of MarkupSafe 0.17 and - Python 3.2 (although the combination of MarkupSafe 0.17 and Python 3.3 or any - supported Python 2 version will work OK). - -- Spaces and dots may now be in mako renderer template paths. This was - broken when support for the new makodef syntax was added in 1.4a1. - See https://github.com/Pylons/pyramid/issues/950 - -- ``pyramid.debug_authorization=true`` will now correctly print out - ``Allowed`` for views registered with ``NO_PERMISSION_REQUIRED`` instead - of invoking the ``permits`` method of the authorization policy. - See https://github.com/Pylons/pyramid/issues/954 - -- Pyramid failed to install on some systems due to being packaged with - some test files containing higher order characters in their names. These - files have now been removed. See - https://github.com/Pylons/pyramid/issues/981 - -- ``pyramid.testing.DummyResource`` didn't define ``__bool__``, so code under - Python 3 would use ``__len__`` to find truthiness; this usually caused an - instance of DummyResource to be "falsy" instead of "truthy". See - https://github.com/Pylons/pyramid/pull/1032 - -- The ``alchemy`` scaffold would break when the database was MySQL during - tables creation. See https://github.com/Pylons/pyramid/pull/1049 - -- The ``current_route_url`` method now attaches the query string to the URL by - default. See - https://github.com/Pylons/pyramid/issues/1040 - -- Make ``pserve.cherrypy_server_runner`` Python 3 compatible. See - https://github.com/Pylons/pyramid/issues/718 - -Backwards Incompatibilities ---------------------------- - -- Modified the ``current_route_url`` method in pyramid.Request. The method - previously returned the URL without the query string by default, it now does - attach the query string unless it is overriden. - -- The ``route_url`` and ``route_path`` APIs no longer quote ``/`` - to ``%2F`` when a replacement value contains a ``/``. This was pointless, - as WSGI servers always unquote the slash anyway, and Pyramid never sees the - quoted value. - -- It is no longer possible to set a ``locale_name`` attribute of the request, - nor is it possible to set a ``localizer`` attribute of the request. These - are now "reified" properties that look up a locale name and localizer - respectively using the machinery described in the "Internationalization" - chapter of the documentation. - -- If you send an ``X-Vhm-Root`` header with a value that ends with a slash (or - any number of slashes), the trailing slash(es) will be removed before a URL - is generated when you use use ``request.resource_url`` or - ``request.resource_path``. Previously the virtual root path would not have - trailing slashes stripped, which would influence URL generation. - -- The ``pyramid.interfaces.IResourceURL`` interface has now grown two new - attributes: ``virtual_path_tuple`` and ``physical_path_tuple``. These should - be the tuple form of the resource's path (physical and virtual). - -1.4 (2012-12-18) -================ - -Docs ----- - -- Fix functional tests in the ZODB tutorial - -1.4b3 (2012-12-10) -================== - -- Packaging release only, no code changes. 1.4b2 was a brownbag release due to - missing directories in the tarball. - -1.4b2 (2012-12-10) -================== - -Docs ----- - -- Scaffolding is now PEP-8 compliant (at least for a brief shining moment). - -- Tutorial improvements. - -Backwards Incompatibilities ---------------------------- - -- Modified the ``_depth`` argument to ``pyramid.view.view_config`` to accept - a value relative to the invocation of ``view_config`` itself. Thus, when it - was previously expecting a value of ``1`` or greater, to reflect that - the caller of ``view_config`` is 1 stack frame away from ``venusian.attach``, - this implementation detail is now hidden. - -- Modified the ``_backframes`` argument to ``pyramid.util.action_method`` in a - similar way to the changes described to ``_depth`` above. This argument - remains undocumented, but might be used in the wild by some insane person. - -1.4b1 (2012-11-21) -================== - -Features --------- - -- Small microspeed enhancement which anticipates that a - ``pyramid.response.Response`` object is likely to be returned from a view. - Some code is shortcut if the class of the object returned by a view is this - class. A similar microoptimization was done to - ``pyramid.request.Request.is_response``. - -- Make it possible to use variable arguments on ``p*`` commands (``pserve``, - ``pshell``, ``pviews``, etc) in the form ``a=1 b=2`` so you can fill in - values in parameterized ``.ini`` file, e.g. ``pshell etc/development.ini - http_port=8080``. See https://github.com/Pylons/pyramid/pull/714 - -- A somewhat advanced and obscure feature of Pyramid event handlers is their - ability to handle "multi-interface" notifications. These notifications have - traditionally presented multiple objects to the subscriber callable. For - instance, if an event was sent by code like this:: - - registry.notify(event, context) - - In the past, in order to catch such an event, you were obligated to write and - register an event subscriber that mentioned both the event and the context in - its argument list:: - - @subscriber([SomeEvent, SomeContextType]) - def asubscriber(event, context): - pass - - In many subscriber callables registered this way, it was common for the logic - in the subscriber callable to completely ignore the second and following - arguments (e.g. ``context`` in the above example might be ignored), because - they usually existed as attributes of the event anyway. You could usually - get the same value by doing ``event.context`` or similar. - - The fact that you needed to put an extra argument which you usually ignored - in the subscriber callable body was only a minor annoyance until we added - "subscriber predicates", used to narrow the set of circumstances under which - a subscriber will be executed, in a prior 1.4 alpha release. Once those were - added, the annoyance was escalated, because subscriber predicates needed to - accept the same argument list and arity as the subscriber callables that they - were configured against. So, for example, if you had these two subscriber - registrations in your code:: - - @subscriber([SomeEvent, SomeContextType]) - def asubscriber(event, context): - pass - - @subscriber(SomeOtherEvent) - def asubscriber(event): - pass - - And you wanted to use a subscriber predicate:: - - @subscriber([SomeEvent, SomeContextType], mypredicate=True) - def asubscriber1(event, context): - pass - - @subscriber(SomeOtherEvent, mypredicate=True) - def asubscriber2(event): - pass - - If an existing ``mypredicate`` subscriber predicate had been written in such - a way that it accepted only one argument in its ``__call__``, you could not - use it against a subscription which named more than one interface in its - subscriber interface list. Similarly, if you had written a subscriber - predicate that accepted two arguments, you couldn't use it against a - registration that named only a single interface type. - - For example, if you created this predicate:: - - class MyPredicate(object): - # portions elided... - def __call__(self, event): - return self.val == event.context.foo - - It would not work against a multi-interface-registered subscription, so in - the above example, when you attempted to use it against ``asubscriber1``, it - would fail at runtime with a TypeError, claiming something was attempting to - call it with too many arguments. - - To hack around this limitation, you were obligated to design the - ``mypredicate`` predicate to expect to receive in its ``__call__`` either a - single ``event`` argument (a SomeOtherEvent object) *or* a pair of arguments - (a SomeEvent object and a SomeContextType object), presumably by doing - something like this:: - - class MyPredicate(object): - # portions elided... - def __call__(self, event, context=None): - return self.val == event.context.foo - - This was confusing and bad. - - In order to allow people to ignore unused arguments to subscriber callables - and to normalize the relationship between event subscribers and subscriber - predicates, we now allow both subscribers and subscriber predicates to accept - only a single ``event`` argument even if they've been subscribed for - notifications that involve multiple interfaces. Subscribers and subscriber - predicates that accept only one argument will receive the first object passed - to ``notify``; this is typically (but not always) the event object. The - other objects involved in the subscription lookup will be discarded. You can - now write an event subscriber that accepts only ``event`` even if it - subscribes to multiple interfaces:: - - @subscriber([SomeEvent, SomeContextType]) - def asubscriber(event): - # this will work! - - This prevents you from needing to match the subscriber callable parameters to - the subscription type unnecessarily, especially when you don't make use of - any argument in your subscribers except for the event object itself. - - Note, however, that if the event object is not the first - object in the call to ``notify``, you'll run into trouble. For example, if - notify is called with the context argument first:: - - registry.notify(context, event) - - You won't be able to take advantage of the event-only feature. It will - "work", but the object received by your event handler won't be the event - object, it will be the context object, which won't be very useful:: - - @subscriber([SomeContextType, SomeEvent]) - def asubscriber(event): - # bzzt! you'll be getting the context here as ``event``, and it'll - # be useless - - Existing multiple-argument subscribers continue to work without issue, so you - should continue use those if your system notifies using multiple interfaces - and the first interface is not the event interface. For example:: - - @subscriber([SomeContextType, SomeEvent]) - def asubscriber(context, event): - # this will still work! - - The event-only feature makes it possible to use a subscriber predicate that - accepts only a request argument within both multiple-interface subscriber - registrations and single-interface subscriber registrations. You needn't - make slightly different variations of predicates depending on the - subscription type arguments. Instead, just write all your subscriber - predicates so they only accept ``event`` in their ``__call__`` and they'll be - useful across all registrations for subscriptions that use an event as their - first argument, even ones which accept more than just ``event``. - - However, the same caveat applies to predicates as to subscriber callables: if - you're subscribing to a multi-interface event, and the first interface is not - the event interface, the predicate won't work properly. In such a case, - you'll need to match the predicate ``__call__`` argument ordering and - composition to the ordering of the interfaces. For example, if the - registration for the subscription uses ``[SomeContext, SomeEvent]``, you'll - need to reflect that in the ordering of the parameters of the predicate's - ``__call__`` method:: - - def __call__(self, context, event): - return event.request.path.startswith(self.val) - - tl;dr: 1) When using multi-interface subscriptions, always use the event type - as the first subscription registration argument and 2) When 1 is true, use - only ``event`` in your subscriber and subscriber predicate parameter lists, - no matter how many interfaces the subscriber is notified with. This - combination will result in the maximum amount of reusability of subscriber - predicates and the least amount of thought on your part. Drink responsibly. - -Bug Fixes ---------- - -- A failure when trying to locate the attribute ``__text__`` on route and view - predicates existed when the ``debug_routematch`` setting was true or when the - ``pviews`` command was used. See https://github.com/Pylons/pyramid/pull/727 - -Documentation -------------- - -- Sync up tutorial source files with the files that are rendered by the - scaffold that each uses. - -1.4a4 (2012-11-14) -================== - -Features --------- - -- ``pyramid.authentication.AuthTktAuthenticationPolicy`` has been updated to - support newer hashing algorithms such as ``sha512``. Existing applications - should consider updating if possible for improved security over the default - md5 hashing. - -- Added an ``effective_principals`` route and view predicate. - -- Do not allow the userid returned from the ``authenticated_userid`` or the - userid that is one of the list of principals returned by - ``effective_principals`` to be either of the strings ``system.Everyone`` or - ``system.Authenticated`` when any of the built-in authorization policies that - live in ``pyramid.authentication`` are in use. These two strings are - reserved for internal usage by Pyramid and they will not be accepted as valid - userids. - -- Slightly better debug logging from - ``pyramid.authentication.RepozeWho1AuthenticationPolicy``. - -- ``pyramid.security.view_execution_permitted`` used to return ``True`` if no - view could be found. It now raises a ``TypeError`` exception in that case, as - it doesn't make sense to assert that a nonexistent view is - execution-permitted. See https://github.com/Pylons/pyramid/issues/299. - -- Allow a ``_depth`` argument to ``pyramid.view.view_config``, which will - permit limited composition reuse of the decorator by other software that - wants to provide custom decorators that are much like view_config. - -- Allow an iterable of decorators to be passed to - ``pyramid.config.Configurator.add_view``. This allows views to be wrapped - by more than one decorator without requiring combining the decorators - yourself. - -Bug Fixes ---------- - -- In the past if a renderer returned ``None``, the body of the resulting - response would be set explicitly to the empty string. Instead, now, the body - is left unchanged, which allows the renderer to set a body itself by using - e.g. ``request.response.body = b'foo'``. The body set by the renderer will - be unmolested on the way out. See - https://github.com/Pylons/pyramid/issues/709 - -- In uncommon cases, the ``pyramid_excview_tween_factory`` might have - inadvertently raised a ``KeyError`` looking for ``request_iface`` as an - attribute of the request. It no longer fails in this case. See - https://github.com/Pylons/pyramid/issues/700 - -- Be more tolerant of potential error conditions in ``match_param`` and - ``physical_path`` predicate implementations; instead of raising an exception, - return False. - -- ``pyramid.view.render_view`` was not functioning properly under Python 3.x - due to a byte/unicode discrepancy. See - https://github.com/Pylons/pyramid/issues/721 - -Deprecations ------------- - -- ``pyramid.authentication.AuthTktAuthenticationPolicy`` will emit a warning if - an application is using the policy without explicitly passing a ``hashalg`` - argument. This is because the default is "md5" which is considered - theoretically subject to collision attacks. If you really want "md5" then you - must specify it explicitly to get rid of the warning. - -Documentation -------------- - -- All of the tutorials that use - ``pyramid.authentication.AuthTktAuthenticationPolicy`` now explicitly pass - ``sha512`` as a ``hashalg`` argument. - - -Internals ---------- - -- Move ``TopologicalSorter`` from ``pyramid.config.util`` to ``pyramid.util``, - move ``CyclicDependencyError`` from ``pyramid.config.util`` to - ``pyramid.exceptions``, rename ``Singleton`` to ``Sentinel`` and move from - ``pyramid.config.util`` to ``pyramid.util``; this is in an effort to - move that stuff that may be an API one day out of ``pyramid.config.util``, - because that package should never be imported from non-Pyramid code. - TopologicalSorter is still not an API, but may become one. - -- Get rid of shady monkeypatching of ``pyramid.request.Request`` and - ``pyramid.response.Response`` done within the ``__init__.py`` of Pyramid. - Webob no longer relies on this being done. Instead, the ResponseClass - attribute of the Pyramid Request class is assigned to the Pyramid response - class; that's enough to satisfy WebOb and behave as it did before with the - monkeypatching. - -1.4a3 (2012-10-26) -================== - -Bug Fixes ---------- - -- The match_param predicate's text method was fixed to sort its values. - Part of https://github.com/Pylons/pyramid/pull/705 - -- 1.4a ``pyramid.scripting.prepare`` behaved differently than 1.3 series - function of same name. In particular, if passed a request, it would not - set the ``registry`` attribute of the request like 1.3 did. A symptom - would be that passing a request to ``pyramid.paster.bootstrap`` (which uses - the function) that did not have a ``registry`` attribute could assume that - the registry would be attached to the request by Pyramid. This assumption - could be made in 1.3, but not in 1.4. The assumption can now be made in - 1.4 too (a registry is attached to a request passed to bootstrap or - prepare). - -- When registering a view configuration that named a Chameleon ZPT renderer - with a macro name in it (e.g. ``renderer='some/template#somemacro.pt``) as - well as a view configuration without a macro name in it that pointed to the - same template (e.g. ``renderer='some/template.pt'``), internal caching could - confuse the two, and your code might have rendered one instead of the - other. - -Features --------- - -- Allow multiple values to be specified to the ``request_param`` view/route - predicate as a sequence. Previously only a single string value was allowed. - See https://github.com/Pylons/pyramid/pull/705 - -- Comments with references to documentation sections placed in scaffold - ``.ini`` files. - -- Added an HTTP Basic authentication policy - at ``pyramid.authentication.BasicAuthAuthenticationPolicy``. - -- The Configurator ``testing_securitypolicy`` method now returns the policy - object it creates. - -- The Configurator ``testing_securitypolicy`` method accepts two new - arguments: ``remember_result`` and ``forget_result``. If supplied, these - values influence the result of the policy's ``remember`` and ``forget`` - methods, respectively. - -- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a - ``forgotten`` value on the policy (the value ``True``) when its ``forget`` - method is called. - -- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a - ``remembered`` value on the policy, which is the value of the ``principal`` - argument it's called with when its ``remember`` method is called. - -- New ``physical_path`` view predicate. If specified, this value should be a - string or a tuple representing the physical traversal path of the context - found via traversal for this predicate to match as true. For example: - ``physical_path='/'`` or ``physical_path='/a/b/c'`` or ``physical_path=('', - 'a', 'b', 'c')``. This is not a path prefix match or a regex, it's a - whole-path match. It's useful when you want to always potentially show a - view when some object is traversed to, but you can't be sure about what kind - of object it will be, so you can't use the ``context`` predicate. The - individual path elements inbetween slash characters or in tuple elements - should be the Unicode representation of the name of the resource and should - not be encoded in any way. - -1.4a2 (2012-09-27) -================== - -Bug Fixes ---------- - -- When trying to determine Mako defnames and Chameleon macro names in asset - specifications, take into account that the filename may have a hyphen in - it. See https://github.com/Pylons/pyramid/pull/692 - -Features --------- - -- A new ``pyramid.session.check_csrf_token`` convenience function was added. - -- A ``check_csrf`` view predicate was added. For example, you can now do - ``config.add_view(someview, check_csrf=True)``. When the predicate is - checked, if the ``csrf_token`` value in ``request.params`` matches the CSRF - token in the request's session, the view will be permitted to execute. - Otherwise, it will not be permitted to execute. - -- Add ``Base.metadata.bind = engine`` to alchemy template, so that tables - defined imperatively will work. - -Documentation -------------- - -- update wiki2 SQLA tutorial with the changes required after inserting - ``Base.metadata.bind = engine`` into the alchemy scaffold. - -1.4a1 (2012-09-16) -================== - -Bug Fixes ---------- - -- Forward port from 1.3 branch: When no authentication policy was configured, - a call to ``pyramid.security.effective_principals`` would unconditionally - return the empty list. This was incorrect, it should have unconditionally - returned ``[Everyone]``, and now does. - -- Explicit url dispatch regexes can now contain colons. - https://github.com/Pylons/pyramid/issues/629 - -- On at least one 64-bit Ubuntu system under Python 3.2, using the - ``view_config`` decorator caused a ``RuntimeError: dictionary changed size - during iteration`` exception. It no longer does. See - https://github.com/Pylons/pyramid/issues/635 for more information. - -- In Mako Templates lookup, check if the uri is already adjusted and bring - it back to an asset spec. Normally occurs with inherited templates or - included components. - https://github.com/Pylons/pyramid/issues/606 - https://github.com/Pylons/pyramid/issues/607 - -- In Mako Templates lookup, check for absolute uri (using mako directories) - when mixing up inheritance with asset specs. - https://github.com/Pylons/pyramid/issues/662 - -- HTTP Accept headers were not being normalized causing potentially - conflicting view registrations to go unnoticed. Two views that only - differ in the case ('text/html' vs. 'text/HTML') will now raise an error. - https://github.com/Pylons/pyramid/pull/620 - -- Forward-port from 1.3 branch: when registering multiple views with an - ``accept`` predicate in a Pyramid application runing under Python 3, you - might have received a ``TypeError: unorderable types: function() < - function()`` exception. - -Features --------- - -- Python 3.3 compatibility. - -- Configurator.add_directive now accepts arbitrary callables like partials or - objects implementing ``__call__`` which dont have ``__name__`` and - ``__doc__`` attributes. See https://github.com/Pylons/pyramid/issues/621 - and https://github.com/Pylons/pyramid/pull/647. - -- Third-party custom view, route, and subscriber predicates can now be added - for use by view authors via - ``pyramid.config.Configurator.add_view_predicate``, - ``pyramid.config.Configurator.add_route_predicate`` and - ``pyramid.config.Configurator.add_subscriber_predicate``. So, for example, - doing this:: - - config.add_view_predicate('abc', my.package.ABCPredicate) - - Might allow a view author to do this in an application that configured that - predicate:: - - @view_config(abc=1) - - Similar features exist for ``add_route``, and ``add_subscriber``. See - "Adding A Third Party View, Route, or Subscriber Predicate" in the Hooks - chapter for more information. - - Note that changes made to support the above feature now means that only - actions registered using the same "order" can conflict with one another. - It used to be the case that actions registered at different orders could - potentially conflict, but to my knowledge nothing ever depended on this - behavior (it was a bit silly). - -- Custom objects can be made easily JSON-serializable in Pyramid by defining - a ``__json__`` method on the object's class. This method should return - values natively serializable by ``json.dumps`` (such as ints, lists, - dictionaries, strings, and so forth). - -- The JSON renderer now allows for the definition of custom type adapters to - convert unknown objects to JSON serializations. - -- As of this release, the ``request_method`` predicate, when used, will also - imply that ``HEAD`` is implied when you use ``GET``. For example, using - ``@view_config(request_method='GET')`` is equivalent to using - ``@view_config(request_method=('GET', 'HEAD'))``. Using - ``@view_config(request_method=('GET', 'POST')`` is equivalent to using - ``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because - HEAD is a variant of GET that omits the body, and WebOb has special support - to return an empty body when a HEAD is used. - -- ``config.add_request_method`` has been introduced to support extending - request objects with arbitrary callables. This method expands on the - previous ``config.set_request_property`` by supporting methods as well as - properties. This method now causes less code to be executed at - request construction time than ``config.set_request_property`` in - version 1.3. - -- Don't add a ``?`` to URLs generated by ``request.resource_url`` if the - ``query`` argument is provided but empty. - -- Don't add a ``?`` to URLs generated by ``request.route_url`` if the - ``_query`` argument is provided but empty. - -- The static view machinery now raises (rather than returns) ``HTTPNotFound`` - and ``HTTPMovedPermanently`` exceptions, so these can be caught by the - Not Found View (and other exception views). - -- The Mako renderer now supports a def name in an asset spec. When the def - name is present in the asset spec, the system will render the template def - within the template and will return the result. An example asset spec is - ``package:path/to/template#defname.mako``. This will render the def named - ``defname`` inside the ``template.mako`` template instead of rendering the - entire template. The old way of returning a tuple in the form - ``('defname', {})`` from the view is supported for backward compatibility, - -- The Chameleon ZPT renderer now accepts a macro name in an asset spec. When - the macro name is present in the asset spec, the system will render the - macro listed as a ``define-macro`` and return the result instead of - rendering the entire template. An example asset spec: - ``package:path/to/template#macroname.pt``. This will render the macro - defined as ``macroname`` within the ``template.pt`` template instead of the - entire templae. - -- When there is a predicate mismatch exception (seen when no view matches for - a given request due to predicates not working), the exception now contains - a textual description of the predicate which didn't match. - -- An ``add_permission`` directive method was added to the Configurator. This - directive registers a free-standing permission introspectable into the - Pyramid introspection system. Frameworks built atop Pyramid can thus use - the ``permissions`` introspectable category data to build a - comprehensive list of permissions supported by a running system. Before - this method was added, permissions were already registered in this - introspectable category as a side effect of naming them in an ``add_view`` - call, this method just makes it possible to arrange for a permission to be - put into the ``permissions`` introspectable category without naming it - along with an associated view. Here's an example of usage of - ``add_permission``:: - - config = Configurator() - config.add_permission('view') - -- The ``UnencryptedCookieSessionFactoryConfig`` now accepts - ``signed_serialize`` and ``signed_deserialize`` hooks which may be used - to influence how the sessions are marshalled (by default this is done - with HMAC+pickle). - -- ``pyramid.testing.DummyRequest`` now supports methods supplied by the - ``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. - -- Request properties and methods added via ``config.set_request_property`` or - ``config.add_request_method`` are now available to tweens. - -- Request properties and methods added via ``config.set_request_property`` or - ``config.add_request_method`` are now available in the request object - returned from ``pyramid.paster.bootstrap``. - -- ``request.context`` of environment request during ``bootstrap`` is now the - root object if a context isn't already set on a provided request. - -- The ``pyramid.decorator.reify`` function is now an API, and was added to - the API documentation. - -- Added the ``pyramid.testing.testConfig`` context manager, which can be used - to generate a configurator in a test, e.g. ``with testing.testConfig(...):``. - -- Users can now invoke a subrequest from within view code using a new - ``request.invoke_subrequest`` API. - -Deprecations ------------- - -- The ``pyramid.config.Configurator.set_request_property`` has been - documentation-deprecated. The method remains usable but the more - featureful ``pyramid.config.Configurator.add_request_method`` should be - used in its place (it has all of the same capabilities but can also extend - the request object with methods). - -Backwards Incompatibilities ---------------------------- - -- The Pyramid router no longer adds the values ``bfg.routes.route`` or - ``bfg.routes.matchdict`` to the request's WSGI environment dictionary. - These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven - minor releases ago). If your code depended on these values, use - request.matched_route and request.matchdict instead. - -- It is no longer possible to pass an environ dictionary directly to - ``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka - ``ModelGraphTraverser.__call__``). Instead, you must pass a request - object. Passing an environment instead of a request has generated a - deprecation warning since Pyramid 1.1. - -- Pyramid will no longer work properly if you use the - ``webob.request.LegacyRequest`` as a request factory. Instances of the - LegacyRequest class have a ``request.path_info`` which return a string. - This Pyramid release assumes that ``request.path_info`` will - unconditionally be Unicode. - -- The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text`` - named ``get_renderer``, ``get_template``, ``render_template``, and - ``render_template_to_response`` have been removed. These have issued a - deprecation warning upon import since Pyramid 1.0. Use - ``pyramid.renderers.get_renderer()``, - ``pyramid.renderers.get_renderer().implementation()``, - ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response`` - respectively instead of these functions. - -- The ``pyramid.configuration`` module was removed. It had been deprecated - since Pyramid 1.0 and printed a deprecation warning upon its use. Use - ``pyramid.config`` instead. - -- The ``pyramid.paster.PyramidTemplate`` API was removed. It had been - deprecated since Pyramid 1.1 and issued a warning on import. If your code - depended on this, adjust your code to import - ``pyramid.scaffolds.PyramidTemplate`` instead. - -- The ``pyramid.settings.get_settings()`` API was removed. It had been - printing a deprecation warning since Pyramid 1.0. If your code depended on - this API, use ``pyramid.threadlocal.get_current_registry().settings`` - instead or use the ``settings`` attribute of the registry available from - the request (``request.registry.settings``). - -- These APIs from the ``pyramid.testing`` module were removed. They have - been printing deprecation warnings since Pyramid 1.0: - - * ``registerDummySecurityPolicy``, use - ``pyramid.config.Configurator.testing_securitypolicy`` instead. - - * ``registerResources`` (aka ``registerModels``, use - ``pyramid.config.Configurator.testing_resources`` instead. - - * ``registerEventListener``, use - ``pyramid.config.Configurator.testing_add_subscriber`` instead. - - * ``registerTemplateRenderer`` (aka `registerDummyRenderer``), use - ``pyramid.config.Configurator.testing_add_template`` instead. - - * ``registerView``, use ``pyramid.config.Configurator.add_view`` instead. - - * ``registerUtility``, use - ``pyramid.config.Configurator.registry.registerUtility`` instead. - - * ``registerAdapter``, use - ``pyramid.config.Configurator.registry.registerAdapter`` instead. - - * ``registerSubscriber``, use - ``pyramid.config.Configurator.add_subscriber`` instead. - - * ``registerRoute``, use - ``pyramid.config.Configurator.add_route`` instead. - - * ``registerSettings``, use - ``pyramid.config.Configurator.add_settings`` instead. - -- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object - was invoked before any finished callbacks were executed. As of this - release, the ``__call__`` method of a Response object is invoked *after* - finished callbacks are executed. This is in support of the - ``request.invoke_subrequest`` feature. - -- The 200-series exception responses named ``HTTPCreated``, ``HTTPAccepted``, - ``HTTPNonAuthoritativeInformation``, ``HTTPNoContent``, ``HTTPResetContent``, - and ``HTTPPartialContent`` in ``pyramid.httpexceptions`` no longer inherit - from ``HTTPOk``. Instead they inherit from a new base class named - ``HTTPSuccessful``. This will have no effect on you unless you've registered - an exception view for ``HTTPOk`` and expect that exception view to - catch all the aforementioned exceptions. - -Documentation -------------- - -- Added an "Upgrading Pyramid" chapter to the narrative documentation. It - describes how to cope with deprecations and removals of Pyramid APIs and - how to show Pyramid-generated deprecation warnings while running tests and - while running a server. - -- Added a "Invoking a Subrequest" chapter to the documentation. It describes - how to use the new ``request.invoke_subrequest`` API. - -Dependencies ------------- - -- Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on - 1.2dev+). This is to ensure that we obtain a version of WebOb that returns - ``request.path_info`` as text. - -1.3 (2012-03-21) -================ - -Bug Fixes ---------- - -- When ``pyramid.wsgi.wsgiapp2`` calls the downstream WSGI app, the app's - environ will no longer have (deprecated and potentially misleading) - ``bfg.routes.matchdict`` or ``bfg.routes.route`` keys in it. A symptom of - this bug would be a ``wsgiapp2``-wrapped Pyramid app finding the wrong view - because it mistakenly detects that a route was matched when, in fact, it - was not. - -- The fix for issue https://github.com/Pylons/pyramid/issues/461 (which made - it possible for instance methods to be used as view callables) introduced a - backwards incompatibility when methods that declared only a request - argument were used. See https://github.com/Pylons/pyramid/issues/503 - -1.3b3 (2012-03-17) -================== - -Bug Fixes ---------- - -- ``config.add_view()`` 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__db`` instead of ``populate_``. - -Documentation -------------- - -- Wiki tutorials improved due to collaboration at PyCon US 2012 sprints. - -1.3b2 (2012-03-02) -================== - -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. - -1.3b1 (2012-02-26) -================== - -Bug Fixes ---------- - -- ``pyramid.config.Configurator.with_package`` didn't work if the - Configurator was an old-style ``pyramid.configuration.Configurator`` - instance. - -- Pyramid authorization policies did not show up in the introspector. - -Deprecations ------------- - -- All references to the ``tmpl_context`` request variable were removed from - the docs. Its existence in Pyramid is confusing for people who were never - Pylons users. It was added as a porting convenience for Pylons users in - Pyramid 1.0, but it never caught on because the Pyramid rendering system is - a lot different than Pylons' was, and alternate ways exist to do what it - was designed to offer in Pylons. It will continue to exist "forever" but - it will not be recommended or mentioned in the docs. - -1.3a9 (2012-02-22) -================== - -Features --------- - -- Add an ``introspection`` boolean to the Configurator constructor. If this - is ``True``, actions registered using the Configurator will be registered - with the introspector. If it is ``False``, they won't. The default is - ``True``. Setting it to ``False`` during action processing will prevent - introspection for any following registration statements, and setting it to - ``True`` will start them up again. This addition is to service a - requirement that the debug toolbar's own views and methods not show up in - the introspector. - -- New API: ``pyramid.config.Configurator.add_notfound_view``. This is a - wrapper for ``pyramid.Config.configurator.add_view`` which provides easy - append_slash support and does the right thing about permissions. It should - be preferred over calling ``add_view`` directly with - ``context=HTTPNotFound`` as was previously recommended. - -- New API: ``pyramid.view.notfound_view_config``. This is a decorator - constructor like ``pyramid.view.view_config`` that calls - ``pyramid.config.Configurator.add_notfound_view`` when scanned. It should - be preferred over using ``pyramid.view.view_config`` with - ``context=HTTPNotFound`` as was previously recommended. - -- New API: ``pyramid.config.Configurator.add_forbidden_view``. This is a - wrapper for ``pyramid.Config.configurator.add_view`` which does the right - thing about permissions. It should be preferred over calling ``add_view`` - directly with ``context=HTTPForbidden`` as was previously recommended. - -- New API: ``pyramid.view.forbidden_view_config``. This is a decorator - constructor like ``pyramid.view.view_config`` that calls - ``pyramid.config.Configurator.add_forbidden_view`` when scanned. It should - be preferred over using ``pyramid.view.view_config`` with - ``context=HTTPForbidden`` as was previously recommended. - -- New APIs: ``pyramid.response.FileResponse`` and - ``pyramid.response.FileIter``, for usage in views that must serve files - "manually". - -Backwards Incompatibilities ---------------------------- - -- Remove ``pyramid.config.Configurator.with_context`` class method. It was - never an API, it is only used by ``pyramid_zcml`` and its functionality has - been moved to that package's latest release. This means that you'll need - to use the 0.9.2 or later release of ``pyramid_zcml`` with this release of - Pyramid. - -- The ``introspector`` argument to the ``pyramid.config.Configurator`` - constructor API has been removed. It has been replaced by the boolean - ``introspection`` flag. - -- The ``pyramid.registry.noop_introspector`` API object has been removed. - -- The older deprecated ``set_notfound_view`` Configurator method is now an - alias for the new ``add_notfound_view`` Configurator method. Likewise, the - older deprecated ``set_forbidden_view`` is now an alias for the new - ``add_forbidden_view``. This has the following impact: the ``context`` sent - to views with a ``(context, request)`` call signature registered via the - ``set_notfound_view`` or ``set_forbidden_view`` will now be an exception - object instead of the actual resource context found. Use - ``request.context`` to get the actual resource context. It's also - recommended to disuse ``set_notfound_view`` in favor of - ``add_notfound_view``, and disuse ``set_forbidden_view`` in favor of - ``add_forbidden_view`` despite the aliasing. - -Deprecations ------------- - -- The API documentation for ``pyramid.view.append_slash_notfound_view`` and - ``pyramid.view.AppendSlashNotFoundViewFactory`` was removed. These names - still exist and are still importable, but they are no longer APIs. Use - ``pyramid.config.Configurator.add_notfound_view(append_slash=True)`` or - ``pyramid.view.notfound_view_config(append_slash=True)`` to get the same - behavior. - -- The ``set_forbidden_view`` and ``set_notfound_view`` methods of the - Configurator were removed from the documentation. They have been - deprecated since Pyramid 1.1. - -Bug Fixes ---------- - -- The static file response object used by ``config.add_static_view`` opened - the static file twice, when it only needed to open it once. - -- The AppendSlashNotFoundViewFactory used request.path to match routes. This - was wrong because request.path contains the script name, and this would - cause it to fail in circumstances where the script name was not empty. It - should have used request.path_info, and now does. - -Documentation -------------- - -- Updated the "Creating a Not Found View" section of the "Hooks" chapter, - replacing explanations of registering a view using ``add_view`` or - ``view_config`` with ones using ``add_notfound_view`` or - ``notfound_view_config``. - -- Updated the "Creating a Not Forbidden View" section of the "Hooks" chapter, - replacing explanations of registering a view using ``add_view`` or - ``view_config`` with ones using ``add_forbidden_view`` or - ``forbidden_view_config``. - -- Updated the "Redirecting to Slash-Appended Routes" section of the "URL - Dispatch" chapter, replacing explanations of registering a view using - ``add_view`` or ``view_config`` with ones using ``add_notfound_view`` or - ``notfound_view_config`` - -- Updated all tutorials to use ``pyramid.view.forbidden_view_config`` rather - than ``pyramid.view.view_config`` with an HTTPForbidden context. - -1.3a8 (2012-02-19) -================== - -Features --------- - -- The ``scan`` method of a ``Configurator`` can be passed an ``ignore`` - argument, which can be a string, a callable, or a list consisting of - strings and/or callables. This feature allows submodules, subpackages, and - global objects from being scanned. See - http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for - more information about how to use the ``ignore`` argument to ``scan``. - -- Better error messages when a view callable returns a value that cannot be - converted to a response (for example, when a view callable returns a - dictionary without a renderer defined, or doesn't return any value at all). - The error message now contains information about the view callable itself - as well as the result of calling it. - -- Better error message when a .pyc-only module is ``config.include`` -ed. - This is not permitted due to error reporting requirements, and a better - error message is shown when it is attempted. Previously it would fail with - something like "AttributeError: 'NoneType' object has no attribute - 'rfind'". - -- Add ``pyramid.config.Configurator.add_traverser`` API method. See the - Hooks narrative documentation section entitled "Changing the Traverser" for - more information. This is not a new feature, it just provides an API for - adding a traverser without needing to use the ZCA API. - -- Add ``pyramid.config.Configurator.add_resource_url_adapter`` API method. - See the Hooks narrative documentation section entitled "Changing How - pyramid.request.Request.resource_url Generates a URL" for more information. - This is not a new feature, it just provides an API for adding a resource - url adapter without needing to use the ZCA API. - -- The system value ``req`` is now supplied to renderers as an alias for - ``request``. This means that you can now, for example, in a template, do - ``req.route_url(...)`` instead of ``request.route_url(...)``. This is - purely a change to reduce the amount of typing required to use request - methods and attributes from within templates. The value ``request`` is - still available too, this is just an alternative. - -- A new interface was added: ``pyramid.interfaces.IResourceURL``. An adapter - implementing its interface can be used to override resource URL generation - when ``request.resource_url`` is called. This interface replaces the - now-deprecated ``pyramid.interfaces.IContextURL`` interface. - -- The dictionary passed to a resource's ``__resource_url__`` method (see - "Overriding Resource URL Generation" in the "Resources" chapter) now - contains an ``app_url`` key, representing the application URL generated - during ``request.resource_url``. It represents a potentially customized - URL prefix, containing potentially custom scheme, host and port information - passed by the user to ``request.resource_url``. It should be used instead - of ``request.application_url`` where necessary. - -- The ``request.resource_url`` API now accepts these arguments: ``app_url``, - ``scheme``, ``host``, and ``port``. The app_url argument can be used to - replace the URL prefix wholesale during url generation. The ``scheme``, - ``host``, and ``port`` arguments can be used to replace the respective - default values of ``request.application_url`` partially. - -- A new API named ``request.resource_path`` now exists. It works like - ``request.resource_url`` but produces a relative URL rather than an - absolute one. - -- The ``request.route_url`` API now accepts these arguments: ``_app_url``, - ``_scheme``, ``_host``, and ``_port``. The ``_app_url`` argument can be - used to replace the URL prefix wholesale during url generation. The - ``_scheme``, ``_host``, and ``_port`` arguments can be used to replace the - respective default values of ``request.application_url`` partially. - -Backwards Incompatibilities ---------------------------- - -- The ``pyramid.interfaces.IContextURL`` interface has been deprecated. - People have been instructed to use this to register a resource url adapter - in the "Hooks" chapter to use to influence ``request.resource_url`` URL - generation for resources found via custom traversers since Pyramid 1.0. - - The interface still exists and registering such an adapter still works, but - this interface will be removed from the software after a few major Pyramid - releases. You should replace it with an equivalent - ``pyramid.interfaces.IResourceURL`` adapter, registered using the new - ``pyramid.config.Configurator.add_resource_url_adapter`` API. A - deprecation warning is now emitted when a - ``pyramid.interfaces.IContextURL`` adapter is found when - ``request.resource_url`` is called. - -Documentation -------------- - -- Don't create a ``session`` instance in SQLA Wiki tutorial, use raw - ``DBSession`` instead (this is more common in real SQLA apps). - -Scaffolding ------------ - -- Put ``pyramid.includes`` targets within ini files in scaffolds on separate - lines in order to be able to tell people to comment out only the - ``pyramid_debugtoolbar`` line when they want to disable the toolbar. - -Dependencies ------------- - -- Depend on ``venusian`` >= 1.0a3 to provide scan ``ignore`` support. - -Internal --------- - -- Create a "MakoRendererFactoryHelper" that provides customizable settings - key prefixes. Allows settings prefixes other than "mako." to be used to - create different factories that don't use the global mako settings. This - will be useful for the debug toolbar, which can currently be sabotaged by - someone using custom mako configuration settings. - -1.3a7 (2012-02-07) -================== - -Features --------- - -- More informative error message when a ``config.include`` cannot find an - ``includeme``. See https://github.com/Pylons/pyramid/pull/392. - -- Internal: catch unhashable discriminators early (raise an error instead of - allowing them to find their way into resolveConflicts). - -- The `match_param` view predicate now accepts a string or a tuple. - This replaces the broken behavior of accepting a dict. See - https://github.com/Pylons/pyramid/issues/425 for more information. - -Bug Fixes ---------- - -- The process will now restart when ``pserve`` is used with the ``--reload`` - flag when the ``development.ini`` file (or any other .ini file in use) is - changed. See https://github.com/Pylons/pyramid/issues/377 and - https://github.com/Pylons/pyramid/pull/411 - -- The ``prequest`` script would fail when used against URLs which did not - return HTML or text. See https://github.com/Pylons/pyramid/issues/381 - -Backwards Incompatibilities ---------------------------- - -- The `match_param` view predicate no longer accepts a dict. This will - have no negative affect because the implementation was broken for - dict-based arguments. - -Documentation -------------- - -- Add a traversal hello world example to the narrative docs. - -1.3a6 (2012-01-20) -================== - -Features --------- - -- New API: ``pyramid.config.Configurator.set_request_property``. Add lazy - property descriptors to a request without changing the request factory. - This method provides conflict detection and is the suggested way to add - properties to a request. - -- Responses generated by Pyramid's ``static_view`` now use - a ``wsgi.file_wrapper`` (see - http://www.python.org/dev/peps/pep-0333/#optional-platform-specific-file-handling) - when one is provided by the web server. - -Bug Fixes ---------- - -- Views registered with an ``accept`` could not be overridden correctly with - a different view that had the same predicate arguments. See - https://github.com/Pylons/pyramid/pull/404 for more information. - -- When using a dotted name for a ``view`` argument to - ``Configurator.add_view`` that pointed to a class with a ``view_defaults`` - decorator, the view defaults would not be applied. See - https://github.com/Pylons/pyramid/issues/396 . - -- Static URL paths were URL-quoted twice. See - https://github.com/Pylons/pyramid/issues/407 . - -1.3a5 (2012-01-09) -================== - -Bug Fixes ---------- - -- The ``pyramid.view.view_defaults`` decorator did not work properly when - more than one view relied on the defaults being different for configuration - conflict resolution. See https://github.com/Pylons/pyramid/issues/394. - -Backwards Incompatibilities ---------------------------- - -- The ``path_info`` route and view predicates now match against - ``request.upath_info`` (Unicode) rather than ``request.path_info`` - (indeterminate value based on Python 3 vs. Python 2). This has to be done - to normalize matching on Python 2 and Python 3. - -1.3a4 (2012-01-05) -================== - -Features --------- - -- New API: ``pyramid.request.Request.set_property``. Add lazy property - descriptors to a request without changing the request factory. New - properties may be reified, effectively caching the value for the lifetime - of the instance. Common use-cases for this would be to get a database - connection for the request or identify the current user. - -- Use the ``waitress`` WSGI server instead of ``wsgiref`` in scaffolding. - -Bug Fixes ---------- - -- The documentation of ``pyramid.events.subscriber`` indicated that using it - as a decorator with no arguments like this:: - - @subscriber() - def somefunc(event): - pass - - Would register ``somefunc`` to receive all events sent via the registry, - but this was untrue. Instead, it would receive no events at all. This has - now been fixed and the code matches the documentation. See also - https://github.com/Pylons/pyramid/issues/386 - -- Literal portions of route patterns were not URL-quoted when ``route_url`` - or ``route_path`` was used to generate a URL or path. - -- The result of ``route_path`` or ``route_url`` might have been ``unicode`` - or ``str`` depending on the input. It is now guaranteed to always be - ``str``. - -- URL matching when the pattern contained non-ASCII characters in literal - parts was indeterminate. Now the pattern supplied to ``add_route`` is - assumed to be either: a ``unicode`` value, or a ``str`` value that contains - only ASCII characters. If you now want to match the path info from a URL - that contains high order characters, you can pass the Unicode - representation of the decoded path portion in the pattern. - -- When using a ``traverse=`` route predicate, traversal would fail with a - URLDecodeError if there were any high-order characters in the traversal - pattern or in the matched dynamic segments. - -- Using a dynamic segment named ``traverse`` in a route pattern like this:: - - config.add_route('trav_route', 'traversal/{traverse:.*}') - - Would cause a ``UnicodeDecodeError`` when the route was matched and the - matched portion of the URL contained any high-order characters. See - https://github.com/Pylons/pyramid/issues/385 . - -- When using a ``*traverse`` stararg in a route pattern, a URL that matched - that possessed a ``@@`` in its name (signifying a view name) would be - inappropriately quoted by the traversal machinery during traversal, - resulting in the view not being found properly. See - https://github.com/Pylons/pyramid/issues/382 and - https://github.com/Pylons/pyramid/issues/375 . - -Backwards Incompatibilities ---------------------------- - -- String values passed to ``route_url`` or ``route_path`` that are meant to - replace "remainder" matches will now be URL-quoted except for embedded - slashes. For example:: - - config.add_route('remain', '/foo*remainder') - request.route_path('remain', remainder='abc / def') - # -> '/foo/abc%20/%20def' - - Previously string values passed as remainder replacements were tacked on - untouched, without any URL-quoting. But this doesn't really work logically - if the value passed is Unicode (raw unicode cannot be placed in a URL or in - a path) and it is inconsistent with the rest of the URL generation - machinery if the value is a string (it won't be quoted unless by the - caller). - - Some folks will have been relying on the older behavior to tack on query - string elements and anchor portions of the URL; sorry, you'll need to - change your code to use the ``_query`` and/or ``_anchor`` arguments to - ``route_path`` or ``route_url`` to do this now. - -- If you pass a bytestring that contains non-ASCII characters to - ``add_route`` as a pattern, it will now fail at startup time. Use Unicode - instead. - -1.3a3 (2011-12-21) -================== - -Features --------- - -- Added a ``prequest`` script (along the lines of ``paster request``). It is - documented in the "Command-Line Pyramid" chapter in the section entitled - "Invoking a Request". - -- Add undocumented ``__discriminator__`` API to derived view callables. - e.g. ``adapters.lookup(...).__discriminator__(context, request)``. It will - be used by superdynamic systems that require the discriminator to be used - for introspection after manual view lookup. - -Bug Fixes ---------- - -- Normalized exit values and ``-h`` output for all ``p*`` scripts - (``pviews``, ``proutes``, etc). - -Documentation -------------- - -- Added a section named "Making Your Script into a Console Script" in the - "Command-Line Pyramid" chapter. - -- Removed the "Running Pyramid on Google App Engine" tutorial from the main - docs. It survives on in the Cookbook - (http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gae.html). - Rationale: it provides the correct info for the Python 2.5 version of GAE - only, and this version of Pyramid does not support Python 2.5. - -1.3a2 (2011-12-14) -================== - -Features --------- - -- New API: ``pyramid.view.view_defaults``. If you use a class as a view, you - can use the new ``view_defaults`` class decorator on the class to provide - defaults to the view configuration information used by every - ``@view_config`` decorator that decorates a method of that class. It also - works against view configurations involving a class made imperatively. - -- Added a backwards compatibility knob to ``pcreate`` to emulate ``paster - create`` handling for the ``--list-templates`` option. - -- Changed scaffolding machinery around a bit to make it easier for people who - want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X, - 1.2.X and 1.3.X. See the new "Creating Pyramid Scaffolds" chapter in the - narrative documentation for more info. - -Documentation -------------- - -- Added documentation to "View Configuration" narrative documentation chapter - about ``view_defaults`` class decorator. - -- Added API docs for ``view_defaults`` class decorator. - -- Added an API docs chapter for ``pyramid.scaffolds``. - -- Added a narrative docs chapter named "Creating Pyramid Scaffolds". - -Backwards Incompatibilities ---------------------------- - -- The ``template_renderer`` method of ``pyramid.scaffolds.PyramidScaffold`` - was renamed to ``render_template``. If you were overriding it, you're a - bad person, because it wasn't an API before now. But we're nice so we're - letting you know. - -1.3a1 (2011-12-09) -================== - -Features --------- - -- Python 3.2 compatibility. - -- New ``pyramid.compat`` module and API documentation which provides Python - 2/3 straddling support for Pyramid add-ons and development environments. - -- A ``mako.directories`` setting is no longer required to use Mako templates - Rationale: Mako template renderers can be specified using an absolute asset - spec. An entire application can be written with such asset specs, - requiring no ordered lookup path. - -- ``bpython`` interpreter compatibility in ``pshell``. See the "Command-Line - Pyramid" narrative docs chapter for more information. - -- Added ``get_appsettings`` API function to the ``pyramid.paster`` module. - This function returns the settings defined within an ``[app:...]`` section - in a PasteDeploy ini file. - -- Added ``setup_logging`` API function to the ``pyramid.paster`` module. - This function sets up Python logging according to the logging configuration - in a PasteDeploy ini file. - -- Configuration conflict reporting is reported in a more understandable way - ("Line 11 in file..." vs. a repr of a tuple of similar info). - -- A configuration introspection system was added; see the narrative - documentation chapter entitled "Pyramid Configuration Introspection" for - more information. New APIs: ``pyramid.registry.Introspectable``, - ``pyramid.config.Configurator.introspector``, - ``pyramid.config.Configurator.introspectable``, - ``pyramid.registry.Registry.introspector``. - -- Allow extra keyword arguments to be passed to the - ``pyramid.config.Configurator.action`` method. - -- New APIs: ``pyramid.path.AssetResolver`` and - ``pyramid.path.DottedNameResolver``. The former can be used to resolve - asset specifications, the latter can be used to resolve dotted names to - modules or packages. - -Bug Fixes ---------- - -- Make test suite pass on 32-bit systems; closes #286. closes #306. - See also https://github.com/Pylons/pyramid/issues/286 - -- The ``pyramid.view.view_config`` decorator did not accept a ``match_params`` - predicate argument. See https://github.com/Pylons/pyramid/pull/308 - -- The AuthTktCookieHelper could potentially generate Unicode headers - inappropriately when the ``tokens`` argument to remember was used. See - https://github.com/Pylons/pyramid/pull/314. - -- The AuthTktAuthenticationPolicy did not use a timing-attack-aware string - comparator. See https://github.com/Pylons/pyramid/pull/320 for more info. - -- The DummySession in ``pyramid.testing`` now generates a new CSRF token if - one doesn't yet exist. - -- ``request.static_url`` now generates URL-quoted URLs when fed a ``path`` - argument which contains characters that are unsuitable for URLs. See - https://github.com/Pylons/pyramid/issues/349 for more info. - -- Prevent a scaffold rendering from being named ``site`` (conflicts with - Python internal site.py). - -- Support for using instances as targets of the ``pyramid.wsgi.wsgiapp`` and - ``pryramid.wsgi.wsgiapp2`` functions. - See https://github.com/Pylons/pyramid/pull/370 for more info. - -Backwards Incompatibilities ---------------------------- - -- Pyramid no longer runs on Python 2.5 (which includes the most recent - release of Jython and the Python 2.5 version of GAE as of this writing). - -- The ``paster`` command is no longer the documented way to create projects, - start the server, or run debugging commands. To create projects from - scaffolds, ``paster create`` is replaced by the ``pcreate`` console script. - To serve up a project, ``paster serve`` is replaced by the ``pserve`` - console script. New console scripts named ``pshell``, ``pviews``, - ``proutes``, and ``ptweens`` do what their ``paster `` - equivalents used to do. Rationale: the Paste and PasteScript packages do - not run under Python 3. - -- The default WSGI server run as the result of ``pserve`` from newly rendered - scaffolding is now the ``wsgiref`` WSGI server instead of the - ``paste.httpserver`` server. Rationale: Rationale: the Paste and - PasteScript packages do not run under Python 3. - -- The ``pshell`` command (see "paster pshell") no longer accepts a - ``--disable-ipython`` command-line argument. Instead, it accepts a ``-p`` - or ``--python-shell`` argument, which can be any of the values ``python``, - ``ipython`` or ``bpython``. - -- Removed the ``pyramid.renderers.renderer_from_name`` function. It has been - deprecated since Pyramid 1.0, and was never an API. - -- To use ZCML with versions of Pyramid >= 1.3, you will need ``pyramid_zcml`` - version >= 0.8 and ``zope.configuration`` version >= 3.8.0. The - ``pyramid_zcml`` package version 0.8 is backwards compatible all the way to - Pyramid 1.0, so you won't be warned if you have older versions installed - and upgrade Pyramid "in-place"; it may simply break instead. - -Dependencies ------------- - -- Pyramid no longer depends on the ``zope.component`` package, except as a - testing dependency. - -- Pyramid now depends on a zope.interface>=3.8.0, WebOb>=1.2dev, - repoze.lru>=0.4, zope.deprecation>=3.5.0, translationstring>=0.4 (for - Python 3 compatibility purposes). It also, as a testing dependency, - depends on WebTest>=1.3.1 for the same reason. - -- Pyramid no longer depends on the Paste or PasteScript packages. - -Documentation -------------- - -- The SQLAlchemy Wiki tutorial has been updated. It now uses - ``@view_config`` decorators and an explicit database population script. - -- Minor updates to the ZODB Wiki tutorial. - -- A narrative documentation chapter named "Extending Pyramid Configuration" - was added; it describes how to add a new directive, and how use the - ``pyramid.config.Configurator.action`` method within custom directives. It - also describes how to add introspectable objects. - -- A narrative documentation chapter named "Pyramid Configuration - Introspection" was added. It describes how to query the introspection - system. - -Scaffolds ---------- - -- Rendered scaffolds have now been changed to be more relocatable (fewer - mentions of the package name within files in the package). - -- The ``routesalchemy`` scaffold has been renamed ``alchemy``, replacing the - older (traversal-based) ``alchemy`` scaffold (which has been retired). - -- The ``starter`` scaffold now uses URL dispatch by default. - -1.2 (2011-09-12) -================ - -Features --------- - -- Route pattern replacement marker names can now begin with an underscore. - See https://github.com/Pylons/pyramid/issues/276. - -1.2b3 (2011-09-11) -================== - -Bug Fixes ---------- - -- The route prefix was not taken into account when a static view was added in - an "include". See https://github.com/Pylons/pyramid/issues/266 . - -1.2b2 (2011-09-08) -================== - -Bug Fixes ---------- - -- The 1.2b1 tarball was a brownbag (particularly for Windows users) because - it contained filenames with stray quotation marks in inappropriate places. - We depend on ``setuptools-git`` to produce release tarballs, and when it - was run to produce the 1.2b1 tarball, it didn't yet cope well with files - present in git repositories with high-order characters in their filenames. - -Documentation -------------- - -- Minor tweaks to the "Introduction" narrative chapter example app and - wording. - -1.2b1 (2011-09-08) -================== - -Bug Fixes ---------- - -- Sometimes falling back from territory translations (``de_DE``) to language - translations (``de``) would not work properly when using a localizer. See - https://github.com/Pylons/pyramid/issues/263 - -- The static file serving machinery could not serve files that started with a - ``.`` (dot) character. - -- Static files with high-order (super-ASCII) characters in their names could - not be served by a static view. The static file serving machinery - inappropriately URL-quoted path segments in filenames when asking for files - from the filesystem. - -- Within ``pyramid.traversal.traversal_path`` , canonicalize URL segments - from UTF-8 to Unicode before checking whether a segment matches literally - one of ``.``, the empty string, or ``..`` in case there's some sneaky way - someone might tunnel those strings via UTF-8 that don't match the literals - before decoded. - -Documentation -------------- - -- Added a "What Makes Pyramid Unique" section to the Introduction narrative - chapter. - -1.2a6 (2011-09-06) -================== - -Bug Fixes ---------- - -- AuthTktAuthenticationPolicy with a ``reissue_time`` interfered with logout. - See https://github.com/Pylons/pyramid/issues/262. - -Internal --------- - -- Internalize code previously depended upon as imports from the - ``paste.auth`` module (futureproof). - -- Replaced use of ``paste.urlparser.StaticURLParser`` with a derivative of - Chris Rossi's "happy" static file serving code (futureproof). - -- Fixed test suite; on some systems tests would fail due to indeterminate - test run ordering and a double-push-single-pop of a shared test variable. - -Behavior Differences --------------------- - -- An ETag header is no longer set when serving a static file. A - Last-Modified header is set instead. - -- Static file serving no longer supports the ``wsgi.file_wrapper`` extension. - -- Instead of returning a ``403 Forbidden`` error when a static file is served - that cannot be accessed by the Pyramid process' user due to file - permissions, an IOError (or similar) will be raised. - -Scaffolds ---------- - -- All scaffolds now send the ``cache_max_age`` parameter to the - ``add_static_view`` method. - -1.2a5 (2011-09-04) -================== - -Bug Fixes ---------- - -- The ``route_prefix`` of a configurator was not properly taken into account - when registering routes in certain circumstances. See - https://github.com/Pylons/pyramid/issues/260 - -Dependencies ------------- - -- The ``zope.configuration`` package is no longer a dependency. - -1.2a4 (2011-09-02) -================== - -Features --------- - -- Support an ``onerror`` keyword argument to - ``pyramid.config.Configurator.scan()``. This onerror keyword argument is - passed to ``venusian.Scanner.scan()`` to influence error behavior when - an exception is raised during scanning. - -- The ``request_method`` predicate argument to - ``pyramid.config.Configurator.add_view`` and - ``pyramid.config.Configurator.add_route`` is now permitted to be a tuple of - HTTP method names. Previously it was restricted to being a string - representing a single HTTP method name. - -- Undeprecated ``pyramid.traversal.find_model``, - ``pyramid.traversal.model_path``, ``pyramid.traversal.model_path_tuple``, - and ``pyramid.url.model_url``, which were all deprecated in Pyramid 1.0. - There's just not much cost to keeping them around forever as aliases to - their renamed ``resource_*`` prefixed functions. - -- Undeprecated ``pyramid.view.bfg_view``, which was deprecated in Pyramid - 1.0. This is a low-cost alias to ``pyramid.view.view_config`` which we'll - just keep around forever. - -Dependencies ------------- - -- Pyramid now requires Venusian 1.0a1 or better to support the ``onerror`` - keyword argument to ``pyramid.config.Configurator.scan``. - -1.2a3 (2011-08-29) -================== - -Bug Fixes ---------- - -- Pyramid did not properly generate static URLs using - ``pyramid.url.static_url`` when passed a caller-package relative path due - to a refactoring done in 1.2a1. - -- The ``settings`` object emitted a deprecation warning any time - ``__getattr__`` was called upon it. However, there are legitimate - situations in which ``__getattr__`` is called on arbitrary objects - (e.g. ``hasattr``). Now, the ``settings`` object only emits the warning - upon successful lookup. - -Internal --------- - -- Use ``config.with_package`` in view_config decorator rather than - manufacturing a new renderer helper (cleanup). - -1.2a2 (2011-08-27) -================== - -Bug Fixes ---------- - -- When a ``renderers=`` argument is not specified to the Configurator - constructor, eagerly register and commit the default renderer set. This - permits the overriding of the default renderers, which was broken in 1.2a1 - without a commit directly after Configurator construction. - -- Mako rendering exceptions had the wrong value for an error message. - -- An include could not set a root factory successfully because the - Configurator constructor unconditionally registered one that would be - treated as if it were "the word of the user". - -Features --------- - -- A session factory can now be passed in using the dotted name syntax. - -1.2a1 (2011-08-24) -================== - -Features --------- - -- The ``[pshell]`` section in an ini configuration file now treats a - ``setup`` key as a dotted name that points to a callable that is passed the - bootstrap environment. It can mutate the environment as necessary for - great justice. - -- A new configuration setting named ``pyramid.includes`` is now available. - It is described in the "Environment Variables and ``.ini`` Files Settings" - narrative documentation chapter. - -- Added a ``route_prefix`` argument to the - ``pyramid.config.Configurator.include`` method. This argument allows you - to compose URL dispatch applications together. See the section entitled - "Using a Route Prefix to Compose Applications" in the "URL Dispatch" - narrative documentation chapter. - -- Added a ``pyramid.security.NO_PERMISSION_REQUIRED`` constant for use in - ``permission=`` statements to view configuration. This constant has a - value of the string ``__no_permission_required__``. This string value was - previously referred to in documentation; now the documentation uses the - constant. - -- Added a decorator-based way to configure a response adapter: - ``pyramid.response.response_adapter``. This decorator has the same use as - ``pyramid.config.Configurator.add_response_adapter`` but it's declarative. - -- The ``pyramid.events.BeforeRender`` event now has an attribute named - ``rendering_val``. This can be used to introspect the value returned by a - view in a BeforeRender subscriber. - -- New configurator directive: ``pyramid.config.Configurator.add_tween``. - This directive adds a "tween". A "tween" is used to wrap the Pyramid - router's primary request handling function. This is a feature may be used - by Pyramid framework extensions, to provide, for example, view timing - support and as a convenient place to hang bookkeeping code. - - Tweens are further described in the narrative docs section in the Hooks - chapter, named "Registering Tweens". - -- New paster command ``paster ptweens``, which prints the current "tween" - configuration for an application. See the section entitled "Displaying - Tweens" in the Command-Line Pyramid chapter of the narrative documentation - for more info. - -- The Pyramid debug logger now uses the standard logging configuration - (usually set up by Paste as part of startup). This means that output from - e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the - normal logging channels. The logger name of the debug logger will be the - package name of the *caller* of the Configurator's constructor. - -- A new attribute is available on request objects: ``exc_info``. Its value - will be ``None`` until an exception is caught by the Pyramid router, after - which it will be the result of ``sys.exc_info()``. - -- ``pyramid.testing.DummyRequest`` now implements the - ``add_finished_callback`` and ``add_response_callback`` methods. - -- New methods of the ``pyramid.config.Configurator`` class: - ``set_authentication_policy`` and ``set_authorization_policy``. These are - meant to be consumed mostly by add-on authors. - -- New Configurator method: ``set_root_factory``. - -- Pyramid no longer eagerly commits some default configuration statements at - Configurator construction time, which permits values passed in as - constructor arguments (e.g. ``authentication_policy`` and - ``authorization_policy``) to override the same settings obtained via an - "include". - -- Better Mako rendering exceptions via - ``pyramid.mako_templating.MakoRenderingException`` - -- New request methods: ``current_route_url``, ``current_route_path``, and - ``static_path``. - -- New functions in ``pyramid.url``: ``current_route_path`` and - ``static_path``. - -- The ``pyramid.request.Request.static_url`` API (and its brethren - ``pyramid.request.Request.static_path``, ``pyramid.url.static_url``, and - ``pyramid.url.static_path``) now accept an asbolute filename as a "path" - argument. This will generate a URL to an asset as long as the filename is - in a directory which was previously registered as a static view. - Previously, trying to generate a URL to an asset using an absolute file - path would raise a ValueError. - -- The ``RemoteUserAuthenticationPolicy ``, ``AuthTktAuthenticationPolicy``, - and ``SessionAuthenticationPolicy`` constructors now accept an additional - keyword argument named ``debug``. By default, this keyword argument is - ``False``. When it is ``True``, debug information will be sent to the - Pyramid debug logger (usually on stderr) when the ``authenticated_userid`` - or ``effective_principals`` method is called on any of these policies. The - output produced can be useful when trying to diagnose - authentication-related problems. - -- New view predicate: ``match_param``. Example: a view added via - ``config.add_view(aview, match_param='action=edit')`` will be called only - when the ``request.matchdict`` has a value inside it named ``action`` with - a value of ``edit``. - -Internal --------- - -- The Pyramid "exception view" machinery is now implemented as a "tween" - (``pyramid.tweens.excview_tween_factory``). - -- WSGIHTTPException (HTTPFound, HTTPNotFound, etc) now has a new API named - "prepare" which renders the body and content type when it is provided with - a WSGI environ. Required for debug toolbar. - -- Once ``__call__`` or ``prepare`` is called on a WSGIHTTPException, the body - will be set, and subsequent calls to ``__call__`` will always return the - same body. Delete the body attribute to rerender the exception body. - -- Previously the ``pyramid.events.BeforeRender`` event *wrapped* a dictionary - (it addressed it as its ``_system`` attribute). Now it *is* a dictionary - (it inherits from ``dict``), and it's the value that is passed to templates - as a top-level dictionary. - -- The ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and - ``current_route_url`` functions in the ``pyramid.url`` package now delegate - to a method on the request they've been passed, instead of the other way - around. The pyramid.request.Request object now inherits from a mixin named - pyramid.url.URLMethodsMixin to make this possible, and all url/path - generation logic is embedded in this mixin. - -- Refactor ``pyramid.config`` into a package. - -- Removed the ``_set_security_policies`` method of the Configurator. - -- Moved the ``StaticURLInfo`` class from ``pyramid.static`` to - ``pyramid.config.views``. - -- Move the ``Settings`` class from ``pyramid.settings`` to - ``pyramid.config.settings``. - -- Move the ``OverrideProvider``, ``PackageOverrides``, ``DirectoryOverride``, - and ``FileOverride`` classes from ``pyramid.asset`` to - ``pyramid.config.assets``. - -Deprecations ------------- - -- All Pyramid-related deployment settings (e.g. ``debug_all``, - ``debug_notfound``) are now meant to be prefixed with the prefix - ``pyramid.``. For example: ``debug_all`` -> ``pyramid.debug_all``. The - old non-prefixed settings will continue to work indefinitely but supplying - them may eventually print a deprecation warning. All scaffolds and - tutorials have been changed to use prefixed settings. - -- The ``settings`` dictionary now raises a deprecation warning when you - attempt to access its values via ``__getattr__`` instead of - via ``__getitem__``. - -Backwards Incompatibilities ---------------------------- - -- If a string is passed as the ``debug_logger`` parameter to a Configurator, - that string is considered to be the name of a global Python logger rather - than a dotted name to an instance of a logger. - -- The ``pyramid.config.Configurator.include`` method now accepts only a - single ``callable`` argument (a sequence of callables used to be - permitted). If you are passing more than one ``callable`` to - ``pyramid.config.Configurator.include``, it will break. You now must now - instead make a separate call to the method for each callable. This change - was introduced to support the ``route_prefix`` feature of include. - -- It may be necessary to more strictly order configuration route and view - statements when using an "autocommitting" Configurator. In the past, it - was possible to add a view which named a route name before adding a route - with that name when you used an autocommitting configurator. For example:: - - config = Configurator(autocommit=True) - config.add_view('my.pkg.someview', route_name='foo') - config.add_route('foo', '/foo') - - The above will raise an exception when the view attempts to add itself. - Now you must add the route before adding the view:: - - config = Configurator(autocommit=True) - config.add_route('foo', '/foo') - config.add_view('my.pkg.someview', route_name='foo') - - This won't effect "normal" users, only people who have legacy BFG codebases - that used an autommitting configurator and possibly tests that use the - configurator API (the configurator returned by ``pyramid.testing.setUp`` is - an autocommitting configurator). The right way to get around this is to - use a non-autocommitting configurator (the default), which does not have - these directive ordering requirements. - -- The ``pyramid.config.Configurator.add_route`` directive no longer returns a - route object. This change was required to make route vs. view - configuration processing work properly. - -Documentation -------------- - -- Narrative and API documentation which used the ``route_url``, - ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` - functions in the ``pyramid.url`` package have now been changed to use - eponymous methods of the request instead. - -- Added a section entitled "Using a Route Prefix to Compose Applications" to - the "URL Dispatch" narrative documentation chapter. - -- Added a new module to the API docs: ``pyramid.tweens``. - -- Added a "Registering Tweens" section to the "Hooks" narrative chapter. - -- Added a "Displaying Tweens" section to the "Command-Line Pyramid" narrative - chapter. - -- Added documentation for the ``pyramid.tweens`` and ``pyramid.includes`` - configuration settings to the "Environment Variables and ``.ini`` Files - Settings" chapter. - -- Added a Logging chapter to the narrative docs (based on the Pylons logging - docs, thanks Phil). - -- Added a Paste chapter to the narrative docs (moved content from the Project - chapter). - -- Added the ``pyramid.interfaces.IDict`` interface representing the methods - of a dictionary, for documentation purposes only (IMultiDict and - IBeforeRender inherit from it). - -- All tutorials now use - The ``route_url``, ``route_path``, - ``resource_url``, ``static_url``, and ``current_route_url`` methods of the - request rather than the function variants imported from ``pyramid.url``. - -- The ZODB wiki tutorial now uses the ``pyramid_zodbconn`` package rather - than the ``repoze.zodbconn`` package to provide ZODB integration. - -Dependency Changes ------------------- - -- Pyramid now relies on PasteScript >= 1.7.4. This version contains a - feature important for allowing flexible logging configuration. - -Scaffolds ----------- - -- All scaffolds now use the ``pyramid_tm`` package rather than the - ``repoze.tm2`` middleware to manage transaction management. - -- The ZODB scaffold now uses the ``pyramid_zodbconn`` package rather than the - ``repoze.zodbconn`` package to provide ZODB integration. - -- All scaffolds now use the ``pyramid_debugtoolbar`` package rather than the - ``WebError`` package to provide interactive debugging features. - -- Projects created via a scaffold no longer depend on the ``WebError`` - package at all; configuration in the ``production.ini`` file which used to - require its ``error_catcher`` middleware has been removed. Configuring - error catching / email sending is now the domain of the ``pyramid_exclog`` - package (see http://docs.pylonsproject.org/projects/pyramid_exclog/en/latest/). - -Bug Fixes ---------- - -- Fixed an issue with the default renderer not working at certain times. See - https://github.com/Pylons/pyramid/issues/249 - - -1.1 (2011-07-22) -================ - -Features --------- - -- Added the ``pyramid.renderers.null_renderer`` object as an API. The null - renderer is an object that can be used in advanced integration cases as - input to the view configuration ``renderer=`` argument. When the null - renderer is used as a view renderer argument, Pyramid avoids converting the - view callable result into a Response object. This is useful if you want to - reuse the view configuration and lookup machinery outside the context of - its use by the Pyramid router. This feature was added for consumption by - the ``pyramid_rpc`` package, which uses view configuration and lookup - outside the context of a router in exactly this way. ``pyramid_rpc`` has - been broken under 1.1 since 1.1b1; adding it allows us to make it work - again. - -- Change all scaffolding templates that point to docs.pylonsproject.org to - use ``/projects/pyramid/current`` rather than ``/projects/pyramid/dev``. - -Internals ---------- - -- Remove ``compat`` code that served only the purpose of providing backwards - compatibility with Python 2.4. - -- Add a deprecation warning for non-API function - ``pyramid.renderers.renderer_from_name`` which has seen use in the wild. - -- Add a ``clone`` method to ``pyramid.renderers.RendererHelper`` for use by - the ``pyramid.view.view_config`` decorator. - -Documentation -------------- - -- Fixed two typos in wiki2 (SQLA + URL Dispatch) tutorial. - -- Reordered chapters in narrative section for better new user friendliness. - -- Added more indexing markers to sections in documentation. - -1.1b4 (2011-07-18) -================== - -Documentation -------------- - -- Added a section entitled "Writing a Script" to the "Command-Line Pyramid" - chapter. - -Backwards Incompatibilities ---------------------------- - -- We added the ``pyramid.scripting.make_request`` API too hastily in 1.1b3. - It has been removed. Sorry for any inconvenience. Use the - ``pyramid.request.Request.blank`` API instead. - -Features --------- - -- The ``paster pshell``, ``paster pviews``, and ``paster proutes`` commands - each now under the hood uses ``pyramid.paster.bootstrap``, which makes it - possible to supply an ``.ini`` file without naming the "right" section in - the file that points at the actual Pyramid application. Instead, you can - generally just run ``paster {pshell|proutes|pviews} development.ini`` and - it will do mostly the right thing. - -Bug Fixes ---------- - -- Omit custom environ variables when rendering a custom exception template in - ``pyramid.httpexceptions.WSGIHTTPException._set_default_attrs``; - stringifying thse may trigger code that should not be executed; see - https://github.com/Pylons/pyramid/issues/239 - -1.1b3 (2011-07-15) -================== - -Features --------- - -- Fix corner case to ease semifunctional testing of views: create a new - rendererinfo to clear out old registry on a rescan. See - https://github.com/Pylons/pyramid/pull/234. - -- New API class: ``pyramid.static.static_view``. This supersedes the - deprecated ``pyramid.view.static`` class. ``pyramid.static.static_view`` - by default serves up documents as the result of the request's - ``path_info``, attribute rather than it's ``subpath`` attribute (the - inverse was true of ``pyramid.view.static``, and still is). - ``pyramid.static.static_view`` exposes a ``use_subpath`` flag for use when - you want the static view to behave like the older deprecated version. - -- A new API function ``pyramid.paster.bootstrap`` has been added to make - writing scripts that bootstrap a Pyramid environment easier, e.g.:: - - from pyramid.paster import bootstrap - info = bootstrap('/path/to/my/development.ini') - request = info['request'] - print request.route_url('myroute') - -- A new API function ``pyramid.scripting.prepare`` has been added. It is a - lower-level analogue of ``pyramid.paster.boostrap`` that accepts a request - and a registry instead of a config file argument, and is used for the same - purpose:: - - from pyramid.scripting import prepare - info = prepare(registry=myregistry) - request = info['request'] - print request.route_url('myroute') - -- A new API function ``pyramid.scripting.make_request`` has been added. The - resulting request will have a ``registry`` attribute. It is meant to be - used in conjunction with ``pyramid.scripting.prepare`` and/or - ``pyramid.paster.bootstrap`` (both of which accept a request as an - argument):: - - from pyramid.scripting import make_request - request = make_request('/') - -- New API attribute ``pyramid.config.global_registries`` is an iterable - object that contains references to every Pyramid registry loaded into the - current process via ``pyramid.config.Configurator.make_app``. It also has - a ``last`` attribute containing the last registry loaded. This is used by - the scripting machinery, and is available for introspection. - -Deprecations ------------- - -- The ``pyramid.view.static`` class has been deprecated in favor of the newer - ``pyramid.static.static_view`` class. A deprecation warning is raised when - it is used. You should replace it with a reference to - ``pyramid.static.static_view`` with the ``use_subpath=True`` argument. - -Bug Fixes ---------- - -- Without a mo-file loaded for the combination of domain/locale, - ``pyramid.i18n.Localizer.pluralize`` run using that domain/locale - combination raised an inscrutable "translations object has no attr - 'plural'" error. Now, instead it "works" (it uses a germanic pluralization - by default). It's nonsensical to try to pluralize something without - translations for that locale/domain available, but this behavior matches - the behavior of ``pyramid.i18n.Localizer.translate`` so it's at least - consistent; see https://github.com/Pylons/pyramid/issues/235. - -1.1b2 (2011-07-13) -================== - -Features --------- - -- New environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and new - configuration file value ``prevent_http_cache``. These are synomymous and - allow you to prevent HTTP cache headers from being set by Pyramid's - ``http_cache`` machinery globally in a process. see the "Influencing HTTP - Caching" section of the "View Configuration" narrative chapter and the - detailed documentation for this setting in the "Environment Variables and - Configuration Settings" narrative chapter. - -Behavior Changes ----------------- - -- Previously, If a ``BeforeRender`` event subscriber added a value via the - ``__setitem__`` or ``update`` methods of the event object with a key that - already existed in the renderer globals dictionary, a ``KeyError`` was - raised. With the deprecation of the "add_renderer_globals" feature of the - configurator, there was no way to override an existing value in the - renderer globals dictionary that already existed. Now, the event object - will overwrite an older value that is already in the globals dictionary - when its ``__setitem__`` or ``update`` is called (as well as the new - ``setdefault`` method), just like a plain old dictionary. As a result, for - maximum interoperability with other third-party subscribers, if you write - an event subscriber meant to be used as a BeforeRender subscriber, your - subscriber code will now need to (using ``.get`` or ``__contains__`` of the - event object) ensure no value already exists in the renderer globals - dictionary before setting an overriding value. - -Bug Fixes ---------- - -- The ``Configurator.add_route`` method allowed two routes with the same - route to be added without an intermediate ``config.commit()``. If you now - receive a ``ConfigurationError`` at startup time that appears to be - ``add_route`` related, you'll need to either a) ensure that all of your - route names are unique or b) call ``config.commit()`` before adding a - second route with the name of a previously added name or c) use a - Configurator that works in ``autocommit`` mode. - -- The ``pyramid_routesalchemy`` and ``pyramid_alchemy`` scaffolds - inappropriately used ``DBSession.rollback()`` instead of - ``transaction.abort()`` in one place. - -- We now clear ``request.response`` before we invoke an exception view; an - exception view will be working with a request.response that has not been - touched by any code prior to the exception. - -- Views associated with routes with spaces in the route name may not have - been looked up correctly when using Pyramid with ``zope.interface`` 3.6.4 - and better. See https://github.com/Pylons/pyramid/issues/232. - -Documentation -------------- - -- Wiki2 (SQLAlchemy + URL Dispatch) tutorial ``models.initialize_sql`` didn't - match the ``pyramid_routesalchemy`` scaffold function of the same name; it - didn't get synchronized when it was changed in the scaffold. - -- New documentation section in View Configuration narrative chapter: - "Influencing HTTP Caching". - -1.1b1 (2011-07-10) -================== - -Features --------- - -- It is now possible to invoke ``paster pshell`` even if the paste ini file - section name pointed to in its argument is not actually a Pyramid WSGI - application. The shell will work in a degraded mode, and will warn the - user. See "The Interactive Shell" in the "Creating a Pyramid Project" - narrative documentation section. - -- ``paster pshell`` now offers more built-in global variables by default - (including ``app`` and ``settings``). See "The Interactive Shell" in the - "Creating a Pyramid Project" narrative documentation section. - -- It is now possible to add a ``[pshell]`` section to your application's .ini - configuration file, which influences the global names available to a pshell - session. See "Extending the Shell" in the "Creating a Pyramid Project" - narrative documentation chapter. - -- The ``config.scan`` method has grown a ``**kw`` argument. ``kw`` argument - represents a set of keyword arguments to pass to the Venusian ``Scanner`` - object created by Pyramid. (See the Venusian documentation for more - information about ``Scanner``). - -- New request property: ``json_body``. This property will return the - JSON-decoded variant of the request body. If the request body is not - well-formed JSON, this property will raise an exception. - -- A new value ``http_cache`` can be used as a view configuration - parameter. - - When you supply an ``http_cache`` value to a view configuration, the - ``Expires`` and ``Cache-Control`` headers of a response generated by the - associated view callable are modified. The value for ``http_cache`` may be - one of the following: - - - A nonzero integer. If it's a nonzero integer, it's treated as a number - of seconds. This number of seconds will be used to compute the - ``Expires`` header and the ``Cache-Control: max-age`` parameter of - responses to requests which call this view. For example: - ``http_cache=3600`` instructs the requesting browser to 'cache this - response for an hour, please'. - - - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` - instance, it will be converted into a number of seconds, and that number - of seconds will be used to compute the ``Expires`` header and the - ``Cache-Control: max-age`` parameter of responses to requests which call - this view. For example: ``http_cache=datetime.timedelta(days=1)`` - instructs the requesting browser to 'cache this response for a day, - please'. - - - Zero (``0``). If the value is zero, the ``Cache-Control`` and - ``Expires`` headers present in all responses from this view will be - composed such that client browser cache (and any intermediate caches) are - instructed to never cache the response. - - - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, - {'public':True})``), the first value in the tuple may be a nonzero - integer or a ``datetime.timedelta`` instance; in either case this value - will be used as the number of seconds to cache the response. The second - value in the tuple must be a dictionary. The values present in the - dictionary will be used as input to the ``Cache-Control`` response - header. For example: ``http_cache=(3600, {'public':True})`` means 'cache - for an hour, and add ``public`` to the Cache-Control header of the - response'. All keys and values supported by the - ``webob.cachecontrol.CacheControl`` interface may be added to the - dictionary. Supplying ``{'public':True}`` is equivalent to calling - ``response.cache_control.public = True``. - - Providing a non-tuple value as ``http_cache`` is equivalent to calling - ``response.cache_expires(value)`` within your view's body. - - Providing a two-tuple value as ``http_cache`` is equivalent to calling - ``response.cache_expires(value[0], **value[1])`` within your view's body. - - If you wish to avoid influencing, the ``Expires`` header, and instead wish - to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` - with the first element of ``None``, e.g.: ``(None, {'public':True})``. - -Bug Fixes ---------- - -- Framework wrappers of the original view (such as http_cached and so on) - relied on being able to trust that the response they were receiving was an - IResponse. It wasn't always, because the response was resolved by the - router instead of early in the view wrapping process. This has been fixed. - -Documentation -------------- - -- Added a section in the "Webob" chapter named "Dealing With A JSON-Encoded - Request Body" (usage of ``request.json_body``). - -Behavior Changes ----------------- - -- The ``paster pshell``, ``paster proutes``, and ``paster pviews`` commands - now take a single argument in the form ``/path/to/config.ini#sectionname`` - rather than the previous 2-argument spelling ``/path/to/config.ini - sectionname``. ``#sectionname`` may be omitted, in which case ``#main`` is - assumed. - -1.1a4 (2011-07-01) -================== - -Bug Fixes ---------- - -- ``pyramid.testing.DummyRequest`` now raises deprecation warnings when - attributes deprecated for ``pyramid.request.Request`` are accessed (like - ``response_content_type``). This is for the benefit of folks running unit - tests which use DummyRequest instead of a "real" request, so they know - things are deprecated without necessarily needing a functional test suite. - -- The ``pyramid.events.subscriber`` directive behaved contrary to the - documentation when passed more than one interface object to its - constructor. For example, when the following listener was registered:: - - @subscriber(IFoo, IBar) - def expects_ifoo_events_and_ibar_events(event): - print event - - The Events chapter docs claimed that the listener would be registered and - listening for both ``IFoo`` and ``IBar`` events. Instead, it registered an - "object event" subscriber which would only be called if an IObjectEvent was - emitted where the object interface was ``IFoo`` and the event interface was - ``IBar``. - - The behavior now matches the documentation. If you were relying on the - buggy behavior of the 1.0 ``subscriber`` directive in order to register an - object event subscriber, you must now pass a sequence to indicate you'd - like to register a subscriber for an object event. e.g.:: - - @subscriber([IFoo, IBar]) - def expects_object_event(object, event): - print object, event - -Features --------- - -- Add JSONP renderer (see "JSONP renderer" in the Renderers chapter of the - documentation). - -Deprecations ------------- - -- Deprecated the ``set_renderer_globals_factory`` method of the Configurator - and the ``renderer_globals`` Configurator constructor parameter. - -Documentation -------------- - -- The Wiki and Wiki2 tutorial "Tests" chapters each had two bugs: neither did - told the user to depend on WebTest, and 2 tests failed in each as the - result of changes to Pyramid itself. These issues have been fixed. - -- Move 1.0.X CHANGES.txt entries to HISTORY.txt. - -1.1a3 (2011-06-26) -================== - -Features --------- - -- Added ``mako.preprocessor`` config file parameter; allows for a Mako - preprocessor to be specified as a Python callable or Python dotted name. - See https://github.com/Pylons/pyramid/pull/183 for rationale. - -Bug fixes ---------- - -- Pyramid would raise an AttributeError in the Configurator when attempting - to set a ``__text__`` attribute on a custom predicate that was actually a - classmethod. See https://github.com/Pylons/pyramid/pull/217 . - -- Accessing or setting deprecated response_* attrs on request - (e.g. ``response_content_type``) now issues a deprecation warning at access - time rather than at rendering time. - -1.1a2 (2011-06-22) -================== - -Bug Fixes ---------- - -- 1.1a1 broke Akhet by not providing a backwards compatibility import shim - for ``pyramid.paster.PyramidTemplate``. Now one has been added, although a - deprecation warning is emitted when Akhet imports it. - -- If multiple specs were provided in a single call to - ``config.add_translation_dirs``, the directories were inserted into the - beginning of the directory list in the wrong order: they were inserted in - the reverse of the order they were provided in the ``*specs`` list (items - later in the list were added before ones earlier in the list). This is now - fixed. - -Backwards Incompatibilities ---------------------------- - -- The pyramid Router attempted to set a value into the key - ``environ['repoze.bfg.message']`` when it caught a view-related exception - for backwards compatibility with applications written for ``repoze.bfg`` - during error handling. It did this by using code that looked like so:: - - # "why" is an exception object - try: - msg = why[0] - except: - msg = '' - - environ['repoze.bfg.message'] = msg - - Use of the value ``environ['repoze.bfg.message']`` was docs-deprecated in - Pyramid 1.0. Our standing policy is to not remove features after a - deprecation for two full major releases, so this code was originally slated - to be removed in Pyramid 1.2. However, computing the - ``repoze.bfg.message`` value was the source of at least one bug found in - the wild (https://github.com/Pylons/pyramid/issues/199), and there isn't a - foolproof way to both preserve backwards compatibility and to fix the bug. - Therefore, the code which sets the value has been removed in this release. - Code in exception views which relies on this value's presence in the - environment should now use the ``exception`` attribute of the request - (e.g. ``request.exception[0]``) to retrieve the message instead of relying - on ``request.environ['repoze.bfg.message']``. - -1.1a1 (2011-06-20) -================== - -Documentation -------------- - -- The term "template" used to refer to both "paster templates" and "rendered - templates" (templates created by a rendering engine. i.e. Mako, Chameleon, - Jinja, etc.). "Paster templates" will now be refered to as "scaffolds", - whereas the name for "rendered templates" will remain as "templates." - -- The ``wiki`` (ZODB+Traversal) tutorial was updated slightly. - -- The ``wiki2`` (SQLA+URL Dispatch) tutorial was updated slightly. - -- Make ``pyramid.interfaces.IAuthenticationPolicy`` and - ``pyramid.interfaces.IAuthorizationPolicy`` public interfaces, and refer to - them within the ``pyramid.authentication`` and ``pyramid.authorization`` - API docs. - -- Render the function definitions for each exposed interface in - ``pyramid.interfaces``. - -- Add missing docs reference to - ``pyramid.config.Configurator.set_view_mapper`` and refer to it within - Hooks chapter section named "Using a View Mapper". - -- Added section to the "Environment Variables and ``.ini`` File Settings" - chapter in the narrative documentation section entitled "Adding a Custom - Setting". - -- Added documentation for a "multidict" (e.g. the API of ``request.POST``) as - interface API documentation. - -- Added a section to the "URL Dispatch" narrative chapter regarding the new - "static" route feature. - -- Added "What's New in Pyramid 1.1" to HTML rendering of documentation. - -- Added API docs for ``pyramid.authentication.SessionAuthenticationPolicy``. - -- Added API docs for ``pyramid.httpexceptions.exception_response``. - -- Added "HTTP Exceptions" section to Views narrative chapter including a - description of ``pyramid.httpexceptions.exception_response``. - -Features --------- - -- Add support for language fallbacks: when trying to translate for a - specific territory (such as ``en_GB``) fall back to translations - for the language (ie ``en``). This brings the translation behaviour in line - with GNU gettext and fixes partially translated texts when using C - extensions. - -- New authentication policy: - ``pyramid.authentication.SessionAuthenticationPolicy``, which uses a session - to store credentials. - -- Accessing the ``response`` attribute of a ``pyramid.request.Request`` - object (e.g. ``request.response`` within a view) now produces a new - ``pyramid.response.Response`` object. This feature is meant to be used - mainly when a view configured with a renderer needs to set response - attributes: all renderers will use the Response object implied by - ``request.response`` as the response object returned to the router. - - ``request.response`` can also be used by code in a view that does not use a - renderer, however the response object that is produced by - ``request.response`` must be returned when a renderer is not in play (it is - not a "global" response). - -- Integers and longs passed as ``elements`` to ``pyramid.url.resource_url`` - or ``pyramid.request.Request.resource_url`` e.g. ``resource_url(context, - request, 1, 2)`` (``1`` and ``2`` are the ``elements``) will now be - converted implicitly to strings in the result. Previously passing integers - or longs as elements would cause a TypeError. - -- ``pyramid_alchemy`` paster template now uses ``query.get`` rather than - ``query.filter_by`` to take better advantage of identity map caching. - -- ``pyramid_alchemy`` paster template now has unit tests. - -- Added ``pyramid.i18n.make_localizer`` API (broken out from - ``get_localizer`` guts). - -- An exception raised by a NewRequest event subscriber can now be caught by - an exception view. - -- It is now possible to get information about why Pyramid raised a Forbidden - exception from within an exception view. The ``ACLDenied`` object returned - by the ``permits`` method of each stock authorization policy - (``pyramid.interfaces.IAuthorizationPolicy.permits``) is now attached to - the Forbidden exception as its ``result`` attribute. Therefore, if you've - created a Forbidden exception view, you can see the ACE, ACL, permission, - and principals involved in the request as - eg. ``context.result.permission``, ``context.result.acl``, etc within the - logic of the Forbidden exception view. - -- Don't explicitly prevent the ``timeout`` from being lower than the - ``reissue_time`` when setting up an ``AuthTktAuthenticationPolicy`` - (previously such a configuration would raise a ``ValueError``, now it's - allowed, although typically nonsensical). Allowing the nonsensical - configuration made the code more understandable and required fewer tests. - -- A new paster command named ``paster pviews`` was added. This command - prints a summary of potentially matching views for a given path. See the - section entitled "Displaying Matching Views for a Given URL" in the "View - Configuration" chapter of the narrative documentation for more information. - -- The ``add_route`` method of the Configurator now accepts a ``static`` - argument. If this argument is ``True``, the added route will never be - considered for matching when a request is handled. Instead, it will only - be useful for URL generation via ``route_url`` and ``route_path``. See the - section entitled "Static Routes" in the URL Dispatch narrative chapter for - more information. - -- A default exception view for the context - ``pyramid.interfaces.IExceptionResponse`` is now registered by default. - This means that an instance of any exception response class imported from - ``pyramid.httpexceptions`` (such as ``HTTPFound``) can now be raised from - within view code; when raised, this exception view will render the - exception to a response. - -- A function named ``pyramid.httpexceptions.exception_response`` is a - shortcut that can be used to create HTTP exception response objects using - an HTTP integer status code. - -- The Configurator now accepts an additional keyword argument named - ``exceptionresponse_view``. By default, this argument is populated with a - default exception view function that will be used when a response is raised - as an exception. When ``None`` is passed for this value, an exception view - for responses will not be registered. Passing ``None`` returns the - behavior of raising an HTTP exception to that of Pyramid 1.0 (the exception - will propagate to middleware and to the WSGI server). - -- The ``pyramid.request.Request`` class now has a ``ResponseClass`` interface - which points at ``pyramid.response.Response``. - -- The ``pyramid.response.Response`` class now has a ``RequestClass`` - interface which points at ``pyramid.request.Request``. - -- It is now possible to return an arbitrary object from a Pyramid view - callable even if a renderer is not used, as long as a suitable adapter to - ``pyramid.interfaces.IResponse`` is registered for the type of the returned - object by using the new - ``pyramid.config.Configurator.add_response_adapter`` API. See the section - in the Hooks chapter of the documentation entitled "Changing How Pyramid - Treats View Responses". - -- The Pyramid router will now, by default, call the ``__call__`` method of - WebOb response objects when returning a WSGI response. This means that, - among other things, the ``conditional_response`` feature of WebOb response - objects will now behave properly. - -- New method named ``pyramid.request.Request.is_response``. This method - should be used instead of the ``pyramid.view.is_response`` function, which - has been deprecated. - -Bug Fixes ---------- - -- URL pattern markers used in URL dispatch are permitted to specify a custom - regex. For example, the pattern ``/{foo:\d+}`` means to match ``/12345`` - (foo==12345 in the match dictionary) but not ``/abc``. However, custom - regexes in a pattern marker which used squiggly brackets did not work. For - example, ``/{foo:\d{4}}`` would fail to match ``/1234`` and - ``/{foo:\d{1,2}}`` would fail to match ``/1`` or ``/11``. One level of - inner squiggly brackets is now recognized so that the prior two patterns - given as examples now work. See also - https://github.com/Pylons/pyramid/issues/#issue/123. - -- Don't send port numbers along with domain information in cookies set by - AuthTktCookieHelper (see https://github.com/Pylons/pyramid/issues/131). - -- ``pyramid.url.route_path`` (and the shortcut - ``pyramid.request.Request.route_url`` method) now include the WSGI - SCRIPT_NAME at the front of the path if it is not empty (see - https://github.com/Pylons/pyramid/issues/135). - -- ``pyramid.testing.DummyRequest`` now has a ``script_name`` attribute (the - empty string). - -- Don't quote ``:@&+$,`` symbols in ``*elements`` passed to - ``pyramid.url.route_url`` or ``pyramid.url.resource_url`` (see - https://github.com/Pylons/pyramid/issues#issue/141). - -- Include SCRIPT_NAME in redirects issued by - ``pyramid.view.append_slash_notfound_view`` (see - https://github.com/Pylons/pyramid/issues#issue/149). - -- Static views registered with ``config.add_static_view`` which also included - a ``permission`` keyword argument would not work as expected, because - ``add_static_view`` also registered a route factory internally. Because a - route factory was registered internally, the context checked by the Pyramid - permission machinery never had an ACL. ``add_static_view`` no longer - registers a route with a factory, so the default root factory will be used. - -- ``config.add_static_view`` now passes extra keyword arguments it receives - to ``config.add_route`` (calling add_static_view is mostly logically - equivalent to adding a view of the type ``pyramid.static.static_view`` - hooked up to a route with a subpath). This makes it possible to pass e.g., - ``factory=`` to ``add_static_view`` to protect a particular static view - with a custom ACL. - -- ``testing.DummyRequest`` used the wrong registry (the global registry) as - ``self.registry`` if a dummy request was created *before* ``testing.setUp`` - was executed (``testing.setUp`` pushes a local registry onto the - threadlocal stack). Fixed by implementing ``registry`` as a property for - DummyRequest instead of eagerly assigning an attribute. - See also https://github.com/Pylons/pyramid/issues/165 - -- When visiting a URL that represented a static view which resolved to a - subdirectory, the ``index.html`` of that subdirectory would not be served - properly. Instead, a redirect to ``/subdir`` would be issued. This has - been fixed, and now visiting a subdirectory that contains an ``index.html`` - within a static view returns the index.html properly. See also - https://github.com/Pylons/pyramid/issues/67. - -- Redirects issued by a static view did not take into account any existing - ``SCRIPT_NAME`` (such as one set by a url mapping composite). Now they do. - -- The ``pyramid.wsgi.wsgiapp2`` decorator did not take into account the - ``SCRIPT_NAME`` in the origin request. - -- The ``pyramid.wsgi.wsgiapp2`` decorator effectively only worked when it - decorated a view found via traversal; it ignored the ``PATH_INFO`` that was - part of a url-dispatch-matched view. - -Deprecations ------------- - -- Deprecated all assignments to ``request.response_*`` attributes (for - example ``request.response_content_type = 'foo'`` is now deprecated). - Assignments and mutations of assignable request attributes that were - considered by the framework for response influence are now deprecated: - ``response_content_type``, ``response_headerlist``, ``response_status``, - ``response_charset``, and ``response_cache_for``. Instead of assigning - these to the request object for later detection by the rendering machinery, - users should use the appropriate API of the Response object created by - accessing ``request.response`` (e.g. code which does - ``request.response_content_type = 'abc'`` should be changed to - ``request.response.content_type = 'abc'``). - -- Passing view-related parameters to - ``pyramid.config.Configurator.add_route`` is now deprecated. Previously, a - view was permitted to be connected to a route using a set of ``view*`` - parameters passed to the ``add_route`` method of the Configurator. This - was a shorthand which replaced the need to perform a subsequent call to - ``add_view``. For example, it was valid (and often recommended) to do:: - - config.add_route('home', '/', view='mypackage.views.myview', - view_renderer='some/renderer.pt') - - Passing ``view*`` arguments to ``add_route`` is now deprecated in favor of - connecting a view to a predefined route via ``Configurator.add_view`` using - the route's ``route_name`` parameter. As a result, the above example - should now be spelled:: - - config.add_route('home', '/') - config.add_view('mypackage.views.myview', route_name='home') - renderer='some/renderer.pt') - - This deprecation was done to reduce confusion observed in IRC, as well as - to (eventually) reduce documentation burden (see also - https://github.com/Pylons/pyramid/issues/164). A deprecation warning is - now issued when any view-related parameter is passed to - ``Configurator.add_route``. - -- Passing an ``environ`` dictionary to the ``__call__`` method of a - "traverser" (e.g. an object that implements - ``pyramid.interfaces.ITraverser`` such as an instance of - ``pyramid.traversal.ResourceTreeTraverser``) as its ``request`` argument - now causes a deprecation warning to be emitted. Consumer code should pass a - ``request`` object instead. The fact that passing an environ dict is - permitted has been documentation-deprecated since ``repoze.bfg`` 1.1, and - this capability will be removed entirely in a future version. - -- The following (undocumented, dictionary-like) methods of the - ``pyramid.request.Request`` object have been deprecated: ``__contains__``, - ``__delitem__``, ``__getitem__``, ``__iter__``, ``__setitem__``, ``get``, - ``has_key``, ``items``, ``iteritems``, ``itervalues``, ``keys``, ``pop``, - ``popitem``, ``setdefault``, ``update``, and ``values``. Usage of any of - these methods will cause a deprecation warning to be emitted. These - methods were added for internal compatibility in ``repoze.bfg`` 1.1 (code - that currently expects a request object expected an environ object in BFG - 1.0 and before). In a future version, these methods will be removed - entirely. - -- Deprecated ``pyramid.view.is_response`` function in favor of (newly-added) - ``pyramid.request.Request.is_response`` method. Determining if an object - is truly a valid response object now requires access to the registry, which - is only easily available as a request attribute. The - ``pyramid.view.is_response`` function will still work until it is removed, - but now may return an incorrect answer under some (very uncommon) - circumstances. - -Behavior Changes ----------------- - -- The default Mako renderer is now configured to escape all HTML in - expression tags. This is intended to help prevent XSS attacks caused by - rendering unsanitized input from users. To revert this behavior in user's - templates, they need to filter the expression through the 'n' filter. - For example, ${ myhtml | n }. - See https://github.com/Pylons/pyramid/issues/193. - -- A custom request factory is now required to return a request object that - has a ``response`` attribute (or "reified"/lazy property) if they the - request is meant to be used in a view that uses a renderer. This - ``response`` attribute should be an instance of the class - ``pyramid.response.Response``. - -- The JSON and string renderer factories now assign to - ``request.response.content_type`` rather than - ``request.response_content_type``. - -- Each built-in renderer factory now determines whether it should change the - content type of the response by comparing the response's content type - against the response's default content type; if the content type is the - default content type (usually ``text/html``), the renderer changes the - content type (to ``application/json`` or ``text/plain`` for JSON and string - renderers respectively). - -- The ``pyramid.wsgi.wsgiapp2`` now uses a slightly different method of - figuring out how to "fix" ``SCRIPT_NAME`` and ``PATH_INFO`` for the - downstream application. As a result, those values may differ slightly from - the perspective of the downstream application (for example, ``SCRIPT_NAME`` - will now never possess a trailing slash). - -- Previously, ``pyramid.request.Request`` inherited from - ``webob.request.Request`` and implemented ``__getattr__``, ``__setattr__`` - and ``__delattr__`` itself in order to overidde "adhoc attr" WebOb behavior - where attributes of the request are stored in the environ. Now, - ``pyramid.request.Request`` object inherits from (the more recent) - ``webob.request.BaseRequest`` instead of ``webob.request.Request``, which - provides the same behavior. ``pyramid.request.Request`` no longer - implements its own ``__getattr__``, ``__setattr__`` or ``__delattr__`` as a - result. - -- ``pyramid.response.Response`` is now a *subclass* of - ``webob.response.Response`` (in order to directly implement the - ``pyramid.interfaces.IResponse`` interface). - -- The "exception response" objects importable from ``pyramid.httpexceptions`` - (e.g. ``HTTPNotFound``) are no longer just import aliases for classes that - actually live in ``webob.exc``. Instead, we've defined our own exception - classes within the module that mirror and emulate the ``webob.exc`` - exception response objects almost entirely. See the "Design Defense" doc - section named "Pyramid Uses its Own HTTP Exception Classes" for more - information. - -Backwards Incompatibilities ---------------------------- - -- Pyramid no longer supports Python 2.4. Python 2.5 or better is required to - run Pyramid 1.1+. - -- The Pyramid router now, by default, expects response objects returned from - view callables to implement the ``pyramid.interfaces.IResponse`` interface. - Unlike the Pyramid 1.0 version of this interface, objects which implement - IResponse now must define a ``__call__`` method that accepts ``environ`` - and ``start_response``, and which returns an ``app_iter`` iterable, among - other things. Previously, it was possible to return any object which had - the three WebOb ``app_iter``, ``headerlist``, and ``status`` attributes as - a response, so this is a backwards incompatibility. It is possible to get - backwards compatibility back by registering an adapter to IResponse from - the type of object you're now returning from view callables. See the - section in the Hooks chapter of the documentation entitled "Changing How - Pyramid Treats View Responses". - -- The ``pyramid.interfaces.IResponse`` interface is now much more extensive. - Previously it defined only ``app_iter``, ``status`` and ``headerlist``; now - it is basically intended to directly mirror the ``webob.Response`` API, - which has many methods and attributes. - -- The ``pyramid.httpexceptions`` classes named ``HTTPFound``, - ``HTTPMultipleChoices``, ``HTTPMovedPermanently``, ``HTTPSeeOther``, - ``HTTPUseProxy``, and ``HTTPTemporaryRedirect`` now accept ``location`` as - their first positional argument rather than ``detail``. This means that - you can do, e.g. ``return pyramid.httpexceptions.HTTPFound('http://foo')`` - rather than ``return - pyramid.httpexceptions.HTTPFound(location='http//foo')`` (the latter will - of course continue to work). - -Dependencies ------------- - -- Pyramid now depends on WebOb >= 1.0.2 as tests depend on the bugfix in that - release: "Fix handling of WSGI environs with missing ``SCRIPT_NAME``". - (Note that in reality, everyone should probably be using 1.0.4 or better - though, as WebOb 1.0.2 and 1.0.3 were effectively brownbag releases.) - -1.0 (2011-01-30) -================ - -Documentation -------------- - -- Fixed bug in ZODB Wiki tutorial (missing dependency on ``docutils`` in - "models" step within ``setup.py``). - -- Removed API documentation for ``pyramid.testing`` APIs named - ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``, - ``registerEventListener``, ``registerTemplateRenderer``, - ``registerDummyRenderer``, ``registerView``, ``registerUtility``, - ``registerAdapter``, ``registerSubscriber``, ``registerRoute``, - and ``registerSettings``. - -- Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid" - tutorials out of core documentation and into the Pyramid Tutorials site - (http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/). - -- Changed "Cleaning up After a Request" section in the URL Dispatch chapter - to use ``request.add_finished_callback`` instead of jamming an object with - a ``__del__`` into the WSGI environment. - -- Remove duplication of ``add_route`` API documentation from URL Dispatch - narrative chapter. - -- Remove duplication of API and narrative documentation in - ``pyramid.view.view_config`` API docs by pointing to - ``pyramid.config.add_view`` documentation and narrative chapter - documentation. - -- Removed some API documentation duplicated in narrative portions of - documentation - -- Removed "Overall Flow of Authentication" from SQLAlchemy + URL Dispatch - wiki tutorial due to print space concerns (moved to Pyramid Tutorials - site). - -Bug Fixes ---------- - -- Deprecated-since-BFG-1.2 APIs from ``pyramid.testing`` now properly emit - deprecation warnings. - -- Added ``egg:repoze.retry#retry`` middleware to the WSGI pipeline in ZODB - templates (retry ZODB conflict errors which occur in normal operations). - -- Removed duplicate implementations of ``is_response``. Two competing - implementations existed: one in ``pyramid.config`` and one in - ``pyramid.view``. Now the one defined in ``pyramid.view`` is used - internally by ``pyramid.config`` and continues to be advertised as an API. - -1.0b3 (2011-01-28) -================== - -Bug Fixes ---------- - -- Use © instead of copyright symbol in paster templates / tutorial - templates for the benefit of folks who cutnpaste and save to a non-UTF8 - format. - -- ``pyramid.view.append_slash_notfound_view`` now preserves GET query - parameters across redirects. - -Documentation -------------- - -- Beef up documentation related to ``set_default_permission``: explicitly - mention that default permissions also protect exception views. - -- Paster templates and tutorials now use spaces instead of tabs in their HTML - templates. - -1.0b2 (2011-01-24) -================== - -Bug Fixes ---------- - -- The ``production.ini`` generated by all paster templates now have an - effective logging level of WARN, which prevents e.g. SQLAlchemy statement - logging and other inappropriate output. - -- The ``production.ini`` of the ``pyramid_routesalchemy`` and - ``pyramid_alchemy`` paster templates did not have a ``sqlalchemy`` logger - section, preventing ``paster serve production.ini`` from working. - -- The ``pyramid_routesalchemy`` and ``pyramid_alchemy`` paster templates used - the ``{{package}}`` variable in a place where it should have used the - ``{{project}}`` variable, causing applications created with uppercase - letters e.g. ``paster create -t pyramid_routesalchemy Dibbus`` to fail to - start when ``paster serve development.ini`` was used against the result. - See https://github.com/Pylons/pyramid/issues/#issue/107 - -- The ``render_view`` method of ``pyramid.renderers.RendererHelper`` passed - an incorrect value into the renderer for ``renderer_info``. It now passes - an instance of ``RendererHelper`` instead of a dictionary, which is - consistent with other usages. See - https://github.com/Pylons/pyramid/issues#issue/106 - -- A bug existed in the ``pyramid.authentication.AuthTktCookieHelper`` which - would break any usage of an AuthTktAuthenticationPolicy when one was - configured to reissue its tokens (``reissue_time`` < ``timeout`` / - ``max_age``). Symptom: ``ValueError: ('Invalid token %r', '')``. See - https://github.com/Pylons/pyramid/issues#issue/108. - -1.0b1 (2011-01-21) -================== - -Features --------- - -- The AuthTktAuthenticationPolicy now accepts a ``tokens`` parameter via - ``pyramid.security.remember``. The value must be a sequence of strings. - Tokens are placed into the auth_tkt "tokens" field and returned in the - auth_tkt cookie. - -- Add ``wild_domain`` argument to AuthTktAuthenticationPolicy, which defaults - to ``True``. If it is set to ``False``, the feature of the policy which - sets a cookie with a wildcard domain will be turned off. - -- Add a ``MANIFEST.in`` file to each paster template. See - https://github.com/Pylons/pyramid/issues#issue/95 - -Bug Fixes ---------- - -- ``testing.setUp`` now adds a ``settings`` attribute to the registry (both - when it's passed a registry without any settings and when it creates one). - -- The ``testing.setUp`` function now takes a ``settings`` argument, which - should be a dictionary. Its values will subsequently be available on the - returned ``config`` object as ``config.registry.settings``. - -Documentation -------------- - -- Added "What's New in Pyramid 1.0" chapter to HTML rendering of - documentation. - -- Merged caseman-master narrative editing branch, many wording fixes and - extensions. - -- Fix deprecated example showing ``chameleon_zpt`` API call in testing - narrative chapter. - -- Added "Adding Methods to the Configurator via ``add_directive``" section to - Advanced Configuration narrative chapter. - -- Add docs for ``add_finished_callback``, ``add_response_callback``, - ``route_path``, ``route_url``, and ``static_url`` methods to - ``pyramid.request.Request`` API docs. - -- Add (minimal) documentation about using I18N within Mako templates to - "Internationalization and Localization" narrative chapter. - -- Move content of "Forms" chapter back to "Views" chapter; I can't think of a - better place to put it. - -- Slightly improved interface docs for ``IAuthorizationPolicy``. - -- Minimally explain usage of custom regular expressions in URL dispatch - replacement markers within URL Dispatch chapter. - -Deprecations -------------- - -- Using the ``pyramid.view.bfg_view`` alias for ``pyramid.view.view_config`` - (a backwards compatibility shim) now issues a deprecation warning. - -Backwards Incompatibilities ---------------------------- - -- Using ``testing.setUp`` now registers an ISettings utility as a side - effect. Some test code which queries for this utility after - ``testing.setUp`` via queryAdapter will expect a return value of ``None``. - This code will need to be changed. - -- When a ``pyramid.exceptions.Forbidden`` error is raised, its status code - now ``403 Forbidden``. It was previously ``401 Unauthorized``, for - backwards compatibility purposes with ``repoze.bfg``. This change will - cause problems for users of Pyramid with ``repoze.who``, which intercepts - ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to pass - through. Those deployments will need to configure ``repoze.who`` to also - react to ``403 Forbidden``. - -- The default value for the ``cookie_on_exception`` parameter to - ``pyramid.session.UnencyrptedCookieSessionFactory`` is now ``True``. This - means that when view code causes an exception to be raised, and the session - has been mutated, a cookie will be sent back in the response. Previously - its default value was ``False``. - -Paster Templates ----------------- - -- The ``pyramid_zodb``, ``pyramid_routesalchemy`` and ``pyramid_alchemy`` - paster templates now use a default "commit veto" hook when configuring the - ``repoze.tm2`` transaction manager in ``development.ini``. This prevents a - transaction from being committed when the response status code is within - the 400 or 500 ranges. See also - http://docs.repoze.org/tm2/#using-a-commit-veto. - -1.0a10 (2011-01-18) -=================== - -Bug Fixes ---------- - -- URL dispatch now properly handles a ``.*`` or ``*`` appearing in a regex - match when used inside brackets. Resolves issue #90. - -Backwards Incompatibilities ---------------------------- - -- The ``add_handler`` method of a Configurator has been removed from the - Pyramid core. Handlers are now a feature of the ``pyramid_handlers`` - package, which can be downloaded from PyPI. Documentation for the package - should be available via - http://docs.pylonsproject.org/projects/pyramid_handlers/en/latest/, - which describes how - to add a configuration statement to your ``main`` block to reobtain this - method. You will also need to add an ``install_requires`` dependency upon - ``pyramid_handlers`` to your ``setup.py`` file. - -- The ``load_zcml`` method of a Configurator has been removed from the - Pyramid core. Loading ZCML is now a feature of the ``pyramid_zcml`` - package, which can be downloaded from PyPI. Documentation for the package - should be available via - http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest/, - which describes how - to add a configuration statement to your ``main`` block to reobtain this - method. You will also need to add an ``install_requires`` dependency upon - ``pyramid_zcml`` to your ``setup.py`` file. - -- The ``pyramid.includes`` subpackage has been removed. ZCML files which use - include the package ``pyramid.includes`` (e.g. ````) now must include the ``pyramid_zcml`` - package instead (e.g. ````). - -- The ``pyramid.view.action`` decorator has been removed from the Pyramid - core. Handlers are now a feature of the ``pyramid_handlers`` package. It - should now be imported from ``pyramid_handlers`` e.g. ``from - pyramid_handlers import action``. - -- The ``handler`` ZCML directive has been removed. It is now a feature of - the ``pyramid_handlers`` package. - -- The ``pylons_minimal``, ``pylons_basic`` and ``pylons_sqla`` paster - templates were removed. Use ``pyramid_sqla`` (available from PyPI) as a - generic replacement for Pylons-esque development. - -- The ``make_app`` function has been removed from the ``pyramid.router`` - module. It continues life within the ``pyramid_zcml`` package. This - leaves the ``pyramid.router`` module without any API functions. - -- The ``configure_zcml`` setting within the deployment settings (within - ``**settings`` passed to a Pyramid ``main`` function) has ceased to have any - meaning. - -Features --------- - -- ``pyramid.testing.setUp`` and ``pyramid.testing.tearDown`` have been - undeprecated. They are now the canonical setup and teardown APIs for test - configuration, replacing "direct" creation of a Configurator. This is a - change designed to provide a facade that will protect against any future - Configurator deprecations. - -- Add ``charset`` attribute to ``pyramid.testing.DummyRequest`` - (unconditionally ``UTF-8``). - -- Add ``add_directive`` method to configurator, which allows framework - extenders to add methods to the configurator (ala ZCML directives). - -- When ``Configurator.include`` is passed a *module* as an argument, it - defaults to attempting to find and use a callable named ``includeme`` - within that module. This makes it possible to use - ``config.include('some.module')`` rather than - ``config.include('some.module.somefunc')`` as long as the include function - within ``some.module`` is named ``includeme``. - -- The ``bfg2pyramid`` script now converts ZCML include tags that have - ``repoze.bfg.includes`` as a package attribute to the value - ``pyramid_zcml``. For example, ```` - will be converted to ````. - -Paster Templates ----------------- - -- All paster templates now use ``pyramid.testing.setUp`` and - ``pyramid.testing.tearDown`` rather than creating a Configurator "by hand" - within their ``tests.py`` module, as per decision in features above. - -- The ``starter_zcml`` paster template has been moved to the ``pyramid_zcml`` - package. - -Documentation -------------- - -- The wiki and wiki2 tutorials now use ``pyramid.testing.setUp`` and - ``pyramid.testing.tearDown`` rather than creating a Configurator "by hand", - as per decision in features above. - -- The "Testing" narrative chapter now explains ``pyramid.testing.setUp`` and - ``pyramid.testing.tearDown`` instead of Configurator creation and - ``Configurator.begin()`` and ``Configurator.end()``. - -- Document the ``request.override_renderer`` attribute within the narrative - "Renderers" chapter in a section named "Overriding A Renderer at Runtime". - -- The "Declarative Configuration" narrative chapter has been removed (it was - moved to the ``pyramid_zcml`` package). - -- Most references to ZCML in narrative chapters have been removed or - redirected to ``pyramid_zcml`` locations. - -Deprecations ------------- - -- Deprecation warnings related to import of the following API functions were - added: ``pyramid.traversal.find_model``, ``pyramid.traversal.model_path``, - ``pyramid.traversal.model_path_tuple``, ``pyramid.url.model_url``. The - instructions emitted by the deprecation warnings instruct the developer to - change these method spellings to their ``resource`` equivalents. This is a - consequence of the mass concept rename of "model" to "resource" performed - in 1.0a7. - -1.0a9 (2011-01-08) -================== - -Bug Fixes ---------- - -- The ``proutes`` command tried too hard to resolve the view for printing, - resulting in exceptions when an exceptional root factory was encountered. - Instead of trying to resolve the view, if it cannot, it will now just print - ````. - -- The `self` argument was included in new methods of the ``ISession`` interface - signature, causing ``pyramid_beaker`` tests to fail. - -- Readd ``pyramid.traversal.model_path_tuple`` as an alias for - ``pyramid.traversal.resource_path_tuple`` for backwards compatibility. - -Features --------- - -- Add a new API ``pyramid.url.current_route_url``, which computes a URL based - on the "current" route (if any) and its matchdict values. - -- ``config.add_view`` now accepts a ``decorator`` keyword argument, a callable - which will decorate the view callable before it is added to the registry. - -- If a handler class provides an ``__action_decorator__`` attribute (usually - a classmethod or staticmethod), use that as the decorator for each view - registration for that handler. - -- The ``pyramid.interfaces.IAuthenticationPolicy`` interface now specifies an - ``unauthenticated_userid`` method. This method supports an important - optimization required by people who are using persistent storages which do - not support object caching and whom want to create a "user object" as a - request attribute. - -- A new API has been added to the ``pyramid.security`` module named - ``unauthenticated_userid``. This API function calls the - ``unauthenticated_userid`` method of the effective security policy. - -- An ``unauthenticated_userid`` method has been added to the dummy - authentication policy returned by - ``pyramid.config.Configurator.testing_securitypolicy``. It returns the - same thing as that the dummy authentication policy's - ``authenticated_userid`` method. - -- The class ``pyramid.authentication.AuthTktCookieHelper`` is now an API. - This class can be used by third-party authentication policy developers to - help in the mechanics of authentication cookie-setting. - -- New constructor argument to Configurator: ``default_view_mapper``. Useful - to create systems that have alternate view calling conventions. A view - mapper allows objects that are meant to be used as view callables to have - an arbitrary argument list and an arbitrary result. The object passed as - ``default_view_mapper`` should implement the - ``pyramid.interfaces.IViewMapperFactory`` interface. - -- add a ``set_view_mapper`` API to Configurator. Has - the same result as passing ``default_view_mapper`` to the Configurator - constructor. - -- ``config.add_view`` now accepts a ``mapper`` keyword argument, which should - either be ``None``, a string representing a Python dotted name, or an - object which is an ``IViewMapperFactory``. This feature is not useful for - "civilians", only for extension writers. - -- Allow static renderer provided during view registration to be overridden at - request time via a request attribute named ``override_renderer``, which - should be the name of a previously registered renderer. Useful to provide - "omnipresent" RPC using existing rendered views. - -- Instances of ``pyramid.testing.DummyRequest`` now have a ``session`` - object, which is mostly a dictionary, but also implements the other session - API methods for flash and CSRF. - -Backwards Incompatibilities ---------------------------- - -- Since the ``pyramid.interfaces.IAuthenticationPolicy`` interface now - specifies that a policy implementation must implement an - ``unauthenticated_userid`` method, all third-party custom authentication - policies now must implement this method. It, however, will only be called - when the global function named ``pyramid.security.unauthenticated_userid`` - is invoked, so if you're not invoking that, you will not notice any issues. - -- ``pyramid.interfaces.ISession.get_csrf_token`` now mandates that an - implementation should return a *new* token if one doesn't already exist in - the session (previously it would return None). The internal sessioning - implementation has been changed. - -Documentation -------------- - -- The (weak) "Converting a CMF Application to Pyramid" tutorial has been - removed from the tutorials section. It was moved to the - ``pyramid_tutorials`` Github repository. - -- The "Resource Location and View Lookup" chapter has been replaced with a - variant of Rob Miller's "Much Ado About Traversal" (originally published at - http://blog.nonsequitarian.org/2010/much-ado-about-traversal/). - -- Many minor wording tweaks and refactorings (merged Casey Duncan's docs - fork, in which he is working on general editing). - -- Added (weak) description of new view mapper feature to Hooks narrative - chapter. - -- Split views chapter into 2: View Callables and View Configuration. - -- Reorder Renderers and Templates chapters after View Callables but before - View Configuration. - -- Merge Session Objects, Cross-Site Request Forgery, and Flash Messaging - chapter into a single Sessions chapter. - -- The Wiki and Wiki2 tutorials now have much nicer CSS and graphics. - -Internals ---------- - -- The "view derivation" code is now factored into a set of classes rather - than a large number of standalone functions (a side effect of the - view mapper refactoring). - -- The ``pyramid.renderer.RendererHelper`` class has grown a ``render_view`` - method, which is used by the default view mapper (a side effect of the - view mapper refactoring). - -- The object passed as ``renderer`` to the "view deriver" is now an instance - of ``pyramid.renderers.RendererHelper`` rather than a dictionary (a side - effect of view mapper refactoring). - -- The class used as the "page template" in ``pyramid.chameleon_text`` was - removed, in preference to using a Chameleon-inbuilt version. - -- A view callable wrapper registered in the registry now contains an - ``__original_view__`` attribute which references the original view callable - (or class). - -- The (non-API) method of all internal authentication policy implementations - previously named ``_get_userid`` is now named ``unauthenticated_userid``, - promoted to an API method. If you were overriding this method, you'll now - need to override it as ``unauthenticated_userid`` instead. - -- Remove (non-API) function of config.py named _map_view. - -1.0a8 (2010-12-27) -================== - -Bug Fixes ---------- - -- The name ``registry`` was not available in the ``paster pshell`` - environment under IPython. - -Features --------- - -- If a resource implements a ``__resource_url__`` method, it will be called - as the result of invoking the ``pyramid.url.resource_url`` function to - generate a URL, overriding the default logic. See the new "Generating The - URL Of A Resource" section within the Resources narrative chapter. - -- Added flash messaging, as described in the "Flash Messaging" narrative - documentation chapter. - -- Added CSRF token generation, as described in the narrative chapter entitled - "Preventing Cross-Site Request Forgery Attacks". - -- Prevent misunderstanding of how the ``view`` and ``view_permission`` - arguments to add_route work by raising an exception during configuration if - view-related arguments exist but no ``view`` argument is passed. - -- Add ``paster proute`` command which displays a summary of the routing - table. See the narrative documentation section within the "URL Dispatch" - chapter entitled "Displaying All Application Routes". - -Paster Templates ----------------- - -- The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead, it - is based on scanning. - -Documentation -------------- - -- Added "Generating The URL Of A Resource" section to the Resources narrative - chapter (includes information about overriding URL generation using - ``__resource_url__``). - -- Added "Generating the Path To a Resource" section to the Resources - narrative chapter. - -- Added "Finding a Resource by Path" section to the Resources narrative - chapter. - -- Added "Obtaining the Lineage of a Resource" to the Resources narrative - chapter. - -- Added "Determining if a Resource is In The Lineage of Another Resource" to - Resources narrative chapter. - -- Added "Finding the Root Resource" to Resources narrative chapter. - -- Added "Finding a Resource With a Class or Interface in Lineage" to - Resources narrative chapter. - -- Added a "Flash Messaging" narrative documentation chapter. - -- Added a narrative chapter entitled "Preventing Cross-Site Request Forgery - Attacks". - -- Changed the "ZODB + Traversal Wiki Tutorial" based on changes to - ``pyramid_zodb`` Paster template. - -- Added "Advanced Configuration" narrative chapter which documents how to - deal with configuration conflicts, two-phase configuration, ``include`` and - ``commit``. - -- Fix API documentation rendering for ``pyramid.view.static`` - -- Add "Pyramid Provides More Than One Way to Do It" to Design Defense - documentation. - -- Changed "Static Assets" narrative chapter: clarify that ``name`` represents - a prefix unless it's a URL, added an example of a root-relative static view - fallback for URL dispatch, added an example of creating a simple view that - returns the body of a file. - -- Move ZCML usage in Hooks chapter to Declarative Configuration chapter. - -- Merge "Static Assets" chapter into the "Assets" chapter. - -- Added narrative documentation section within the "URL Dispatch" chapter - entitled "Displaying All Application Routes" (for ``paster proutes`` - command). - -1.0a7 (2010-12-20) -================== - -Terminology Changes -------------------- - -- The Pyramid concept previously known as "model" is now known as "resource". - As a result: - - - The following API changes have been made:: - - pyramid.url.model_url -> - pyramid.url.resource_url - - pyramid.traversal.find_model -> - pyramid.url.find_resource - - pyramid.traversal.model_path -> - pyramid.traversal.resource_path - - pyramid.traversal.model_path_tuple -> - pyramid.traversal.resource_path_tuple - - pyramid.traversal.ModelGraphTraverser -> - pyramid.traversal.ResourceTreeTraverser - - pyramid.config.Configurator.testing_models -> - pyramid.config.Configurator.testing_resources - - pyramid.testing.registerModels -> - pyramid.testing.registerResources - - pyramid.testing.DummyModel -> - pyramid.testing.DummyResource - - - All documentation which previously referred to "model" now refers to - "resource". - - - The ``starter`` and ``starter_zcml`` paster templates now have a - ``resources.py`` module instead of a ``models.py`` module. - - - Positional argument names of various APIs have been changed from - ``model`` to ``resource``. - - Backwards compatibility shims have been left in place in all cases. They - will continue to work "forever". - -- The Pyramid concept previously known as "resource" is now known as "asset". - As a result: - - - The (non-API) module previously known as ``pyramid.resource`` is now - known as ``pyramid.asset``. - - - All docs that previously referred to "resource specification" now refer - to "asset specification". - - - The following API changes were made:: - - pyramid.config.Configurator.absolute_resource_spec -> - pyramid.config.Configurator.absolute_asset_spec - - pyramid.config.Configurator.override_resource -> - pyramid.config.Configurator.override_asset - - - The ZCML directive previously known as ``resource`` is now known as - ``asset``. - - - The setting previously known as ``BFG_RELOAD_RESOURCES`` (envvar) or - ``reload_resources`` (config file) is now known, respectively, as - ``PYRAMID_RELOAD_ASSETS`` and ``reload_assets``. - - Backwards compatibility shims have been left in place in all cases. They - will continue to work "forever". - -Bug Fixes ---------- - -- Make it possible to succesfully run all tests via ``nosetests`` command - directly (rather than indirectly via ``python setup.py nosetests``). - -- When a configuration conflict is encountered during scanning, the conflict - exception now shows the decorator information that caused the conflict. - -Features --------- - -- Added ``debug_routematch`` configuration setting that logs matched routes - (including the matchdict and predicates). - -- The name ``registry`` is now available in a ``pshell`` environment by - default. It is the application registry object. - -Environment ------------ - -- All environment variables which used to be prefixed with ``BFG_`` are now - prefixed with ``PYRAMID_`` (e.g. ``BFG_DEBUG_NOTFOUND`` is now - ``PYRAMID_DEBUG_NOTFOUND``) - -Documentation -------------- - -- Added "Debugging Route Matching" section to the urldispatch narrative - documentation chapter. - -- Added reference to ``PYRAMID_DEBUG_ROUTEMATCH`` envvar and ``debug_routematch`` - config file setting to the Environment narrative docs chapter. - -- Changed "Project" chapter slightly to expand on use of ``paster pshell``. - -- Direct Jython users to Mako rather than Jinja2 in "Install" narrative - chapter. - -- Many changes to support terminological renaming of "model" to "resource" - and "resource" to "asset". - -- Added an example of ``WebTest`` functional testing to the testing narrative - chapter. - -- Rearranged chapter ordering by popular demand (URL dispatch first, then - traversal). Put hybrid chapter after views chapter. - -- Split off "Renderers" as its own chapter from "Views" chapter in narrative - documentation. - -Paster Templates ----------------- - -- Added ``debug_routematch = false`` to all paster templates. - -Dependencies ------------- - -- Depend on Venusian >= 0.5 (for scanning conflict exception decoration). - -1.0a6 (2010-12-15) -================== - -Bug Fixes ---------- - -- 1.0a5 introduced a bug when ``pyramid.config.Configurator.scan`` was used - without a ``package`` argument (e.g. ``config.scan()`` as opposed to - ``config.scan('packagename')``. The symptoms were: lots of deprecation - warnings printed to the console about imports of deprecated Pyramid - functions and classes and non-detection of view callables decorated with - ``view_config`` decorators. This has been fixed. - -- Tests now pass on Windows (no bugs found, but a few tests in the test suite - assumed UNIX path segments in filenames). - -Documentation -------------- - -- If you followed it to-the-letter, the ZODB+Traversal Wiki tutorial would - instruct you to run a test which would fail because the view callable - generated by the ``pyramid_zodb`` tutorial used a one-arg view callable, - but the test in the sample code used a two-arg call. - -- Updated ZODB+Traversal tutorial setup.py of all steps to match what's - generated by ``pyramid_zodb``. - -- Fix reference to ``repoze.bfg.traversalwrapper`` in "Models" chapter (point - at ``pyramid_traversalwrapper`` instead). - -1.0a5 (2010-12-14) -================== - -Features --------- - -- Add a ``handler`` ZCML directive. This directive does the same thing as - ``pyramid.configuration.add_handler``. - -- A new module named ``pyramid.config`` was added. It subsumes the duties of - the older ``pyramid.configuration`` module. - -- The new ``pyramid.config.Configurator` class has API methods that the older - ``pyramid.configuration.Configurator`` class did not: ``with_context`` (a - classmethod), ``include``, ``action``, and ``commit``. These methods exist - for imperative application extensibility purposes. - -- The ``pyramid.testing.setUp`` function now accepts an ``autocommit`` - keyword argument, which defaults to ``True``. If it is passed ``False``, - the Config object returned by ``setUp`` will be a non-autocommiting Config - object. - -- Add logging configuration to all paster templates. - -- ``pyramid_alchemy``, ``pyramid_routesalchemy``, and ``pylons_sqla`` paster - templates now use idiomatic SQLAlchemy configuration in their respective - ``.ini`` files and Python code. - -- ``pyramid.testing.DummyRequest`` now has a class variable, - ``query_string``, which defaults to the empty string. - -- Add support for json on GAE by catching NotImplementedError and importing - simplejson from django.utils. - -- The Mako renderer now accepts a resource specification for - ``mako.module_directory``. - -- New boolean Mako settings variable ``mako.strict_undefined``. See `Mako - Context Variables - `_ for - its meaning. - -Dependencies ------------- - -- Depend on Mako 0.3.6+ (we now require the ``strict_undefined`` feature). - -Bug Fixes ---------- - -- When creating a Configurator from within a ``paster pshell`` session, you - were required to pass a ``package`` argument although ``package`` is not - actually required. If you didn't pass ``package``, you would receive an - error something like ``KeyError: '__name__'`` emanating from the - ``pyramid.path.caller_module`` function. This has now been fixed. - -- The ``pyramid_routesalchemy`` paster template's unit tests failed - (``AssertionError: 'SomeProject' != 'someproject'``). This is fixed. - -- Make default renderer work (renderer factory registered with no name, which - is active for every view unless the view names a specific renderer). - -- The Mako renderer did not properly turn the ``mako.imports``, - ``mako.default_filters``, and ``mako.imports`` settings into lists. - -- The Mako renderer did not properly convert the ``mako.error_handler`` - setting from a dotted name to a callable. - -Documentation -------------- - -- Merged many wording, readability, and correctness changes to narrative - documentation chapters from https://github.com/caseman/pyramid (up to and - including "Models" narrative chapter). - -- "Sample Applications" section of docs changed to note existence of Cluegun, - Shootout and Virginia sample applications, ported from their repoze.bfg - origin packages. - -- SQLAlchemy+URLDispatch tutorial updated to integrate changes to - ``pyramid_routesalchemy`` template. - -- Add ``pyramid.interfaces.ITemplateRenderer`` interface to Interfaces API - chapter (has ``implementation()`` method, required to be used when getting - at Chameleon macros). - -- Add a "Modifying Package Structure" section to the project narrative - documentation chapter (explain turning a module into a package). - -- Documentation was added for the new ``handler`` ZCML directive in the ZCML - section. - -Deprecations ------------- - -- ``pyramid.configuration.Configurator`` is now deprecated. Use - ``pyramid.config.Configurator``, passing its constructor - ``autocommit=True`` instead. The ``pyramid.configuration.Configurator`` - alias will live for a long time, as every application uses it, but its - import now issues a deprecation warning. The - ``pyramid.config.Configurator`` class has the same API as - ``pyramid.configuration.Configurator`` class, which it means to replace, - except by default it is a *non-autocommitting* configurator. The - now-deprecated ``pyramid.configuration.Configurator`` will autocommit every - time a configuration method is called. - - The ``pyramid.configuration`` module remains, but it is deprecated. Use - ``pyramid.config`` instead. - -1.0a4 (2010-11-21) -================== - -Features --------- - -- URL Dispatch now allows for replacement markers to be located anywhere - in the pattern, instead of immediately following a ``/``. - -- URL Dispatch now uses the form ``{marker}`` to denote a replace marker in - the route pattern instead of ``:marker``. The old colon-style marker syntax - is still accepted for backwards compatibility. The new format allows a - regular expression for that marker location to be used instead of the - default ``[^/]+``, for example ``{marker:\d+}`` is now valid to require the - marker to be digits. - -- Add a ``pyramid.url.route_path`` API, allowing folks to generate relative - URLs. Calling ``route_path`` is the same as calling - ``pyramid.url.route_url`` with the argument ``_app_url`` equal to the empty - string. - -- Add a ``pyramid.request.Request.route_path`` API. This is a convenience - method of the request which calls ``pyramid.url.route_url``. - -- Make test suite pass on Jython (requires PasteScript trunk, presumably to - be 1.7.4). - -- Make test suite pass on PyPy (Chameleon doesn't work). - -- Surrounding application configuration with ``config.begin()`` and - ``config.end()`` is no longer necessary. All paster templates have been - changed to no longer call these functions. - -- Fix configurator to not convert ``ImportError`` to ``ConfigurationError`` - if the import that failed was unrelated to the import requested via a - dotted name when resolving dotted names (such as view dotted names). - -Documentation -------------- - -- SQLAlchemy+URLDispatch and ZODB+Traversal tutorials have been updated to - not call ``config.begin()`` or ``config.end()``. - -Bug Fixes ---------- - -- Add deprecation warnings to import of ``pyramid.chameleon_text`` and - ``pyramid.chameleon_zpt`` of ``get_renderer``, ``get_template``, - ``render_template``, and ``render_template_to_response``. - -- Add deprecation warning for import of ``pyramid.zcml.zcml_configure`` and - ``pyramid.zcml.file_configure``. - -- The ``pyramid_alchemy`` paster template had a typo, preventing an import - from working. - -- Fix apparent failures when calling ``pyramid.traversal.find_model(root, - path)`` or ``pyramid.traversal.traverse(path)`` when ``path`` is - (erroneously) a Unicode object. The user is meant to pass these APIs a - string object, never a Unicode object. In practice, however, users indeed - pass Unicode. Because the string that is passed must be ASCII encodeable, - now, if they pass a Unicode object, its data is eagerly converted to an - ASCII string rather than being passed along to downstream code as a - convenience to the user and to prevent puzzling second-order failures from - cropping up (all failures will occur within ``pyramid.traversal.traverse`` - rather than later down the line as the result of calling e.g. - ``traversal_path``). - -Backwards Incompatibilities ---------------------------- - -- The ``pyramid.testing.zcml_configure`` API has been removed. It had been - advertised as removed since repoze.bfg 1.2a1, but hadn't actually been. - -Deprecations ------------- - -- The ``pyramid.settings.get_settings`` API is now deprecated. Use - ``pyramid.threadlocals.get_current_registry().settings`` instead or use the - ``settings`` attribute of the registry available from the request - (``request.registry.settings``). - -Documentation -------------- - -- Removed ``zodbsessions`` tutorial chapter. It's still useful, but we now - have a SessionFactory abstraction which competes with it, and maintaining - documentation on both ways to do it is a distraction. - -Internal --------- - -- Replace Twill with WebTest in internal integration tests (avoid deprecation - warnings generated by Twill). - -1.0a3 (2010-11-16) -================== - -Features --------- - -- Added Mako TemplateLookup settings for ``mako.error_handler``, - ``mako.default_filters``, and ``mako.imports``. - -- Normalized all paster templates: each now uses the name ``main`` to - represent the function that returns a WSGI application, each now uses - WebError, each now has roughly the same shape of development.ini style. - -- Added class vars ``matchdict`` and ``matched_route`` to - ``pyramid.request.Request``. Each is set to ``None``. - -- New API method: ``pyramid.settings.asbool``. - -- New API methods for ``pyramid.request.Request``: ``model_url``, - ``route_url``, and ``static_url``. These are simple passthroughs for their - respective functions in ``pyramid.url``. - -- The ``settings`` object which used to be available only when - ``request.settings.get_settings`` was called is now available as - ``registry.settings`` (e.g. ``request.registry.settings`` in view code). - -Bug Fixes ---------- - -- The pylons_* paster templates erroneously used the ``{squiggly}`` routing - syntax as the pattern supplied to ``add_route``. This style of routing is - not supported. They were replaced with ``:colon`` style route patterns. - -- The pylons_* paster template used the same string - (``your_app_secret_string``) for the ``session.secret`` setting in the - generated ``development.ini``. This was a security risk if left unchanged - in a project that used one of the templates to produce production - applications. It now uses a randomly generated string. - -Documentation -------------- - -- ZODB+traversal wiki (``wiki``) tutorial updated due to changes to - ``pyramid_zodb`` paster template. - -- SQLAlchemy+urldispach wiki (``wiki2``) tutorial updated due to changes to - ``pyramid_routesalchemy`` paster template. - -- Documented the ``matchdict`` and ``matched_route`` attributes of the - request object in the Request API documentation. - -Deprecations ------------- - -- Obtaining the ``settings`` object via - ``registry.{get|query}Utility(ISettings)`` is now deprecated. Instead, - obtain the ``settings`` object via the ``registry.settings`` attribute. A - backwards compatibility shim was added to the registry object to register - the settings object as an ISettings utility when ``setattr(registry, - 'settings', foo)`` is called, but it will be removed in a later release. - -- Obtaining the ``settings`` object via ``pyramid.settings.get_settings`` is - now deprecated. Obtain it as the ``settings`` attribute of the registry - now (obtain the registry via ``pyramid.threadlocal.get_registry`` or as - ``request.registry``). - -Behavior Differences --------------------- - -- Internal: ZCML directives no longer call get_current_registry() if there's - a ``registry`` attribute on the ZCML context (kill off use of - threadlocals). - -- Internal: Chameleon template renderers now accept two arguments: ``path`` - and ``lookup``. ``Lookup`` will be an instance of a lookup class which - supplies (late-bound) arguments for debug, reload, and translate. Any - third-party renderers which use (the non-API) function - ``pyramid.renderers.template_renderer_factory`` will need to adjust their - implementations to obey the new callback argument list. This change was to - kill off inappropriate use of threadlocals. - -1.0a2 (2010-11-09) -================== - -Documentation -------------- - -- All references to events by interface - (e.g. ``pyramid.interfaces.INewRequest``) have been changed to reference - their concrete classes (e.g. ``pyramid.events.NewRequest``) in - documentation about making subscriptions. - -- All references to Pyramid-the-application were changed from mod-`pyramid` - to app-`Pyramid`. A custom role setting was added to ``docs/conf.py`` to - allow for this. (internal) - -1.0a1 (2010-11-05) -================== - -Features (delta from BFG 1.3) -------------------------------- - -- Mako templating renderer supports resource specification format for - template lookups and within Mako templates. Absolute filenames must - be used in Pyramid to avoid this lookup process. - -- Add ``pyramid.httpexceptions`` module, which is a facade for the - ``webob.exc`` module. - -- Direct built-in support for the Mako templating language. - -- A new configurator method exists: ``add_handler``. This method adds - a Pylons-style "view handler" (such a thing used to be called a - "controller" in Pylons 1.0). - -- New argument to configurator: ``session_factory``. - -- New method on configurator: ``set_session_factory`` - -- Using ``request.session`` now returns a (dictionary-like) session - object if a session factory has been configured. - -- The request now has a new attribute: ``tmpl_context`` for benefit of - Pylons users. - -- The decorator previously known as ``pyramid.view.bfg_view`` is now - known most formally as ``pyramid.view.view_config`` in docs and - paster templates. An import of ``pyramid.view.bfg_view``, however, - will continue to work "forever". - -- New API methods in ``pyramid.session``: ``signed_serialize`` and - ``signed_deserialize``. - -- New interface: ``pyramid.interfaces.IRendererInfo``. An object of this type - is passed to renderer factory constructors (see "Backwards - Incompatibilities"). - -- New event type: ``pyramid.interfaces.IBeforeRender``. An object of this type - is sent as an event before a renderer is invoked (but after the - application-level renderer globals factory added via - ``pyramid.configurator.configuration.set_renderer_globals_factory``, if any, - has injected its own keys). Applications may now subscribe to the - ``IBeforeRender`` event type in order to introspect the and modify the set of - renderer globals before they are passed to a renderer. The event object - iself has a dictionary-like interface that can be used for this purpose. For - example:: - - from repoze.events import subscriber - from pyramid.interfaces import IRendererGlobalsEvent - - @subscriber(IRendererGlobalsEvent) - def add_global(event): - event['mykey'] = 'foo' - - If a subscriber attempts to add a key that already exist in the renderer - globals dictionary, a ``KeyError`` is raised. This limitation is due to the - fact that subscribers cannot be ordered relative to each other. The set of - keys added to the renderer globals dictionary by all subscribers and - app-level globals factories must be unique. - -- New class: ``pyramid.response.Response``. This is a pure facade for - ``webob.Response`` (old code need not change to use this facade, it's - existence is mostly for vanity and documentation-generation purposes). - -- All preexisting paster templates (except ``zodb``) now use "imperative" - configuration (``starter``, ``routesalchemy``, ``alchemy``). - -- A new paster template named ``pyramid_starter_zcml`` exists, which uses - declarative configuration. - -Documentation (delta from BFG 1.3) ------------------------------------ - -- Added a ``pyramid.httpexceptions`` API documentation chapter. - -- Added a ``pyramid.session`` API documentation chapter. - -- Added a ``Session Objects`` narrative documentation chapter. - -- Added an API chapter for the ``pyramid.personality`` module. - -- Added an API chapter for the ``pyramid.response`` module. - -- All documentation which previously referred to ``webob.Response`` now uses - ``pyramid.response.Response`` instead. - -- The documentation has been overhauled to use imperative configuration, - moving declarative configuration (ZCML) explanations to a separate - narrative chapter ``declarative.rst``. - -- The ZODB Wiki tutorial was updated to take into account changes to the - ``pyramid_zodb`` paster template. - -- The SQL Wiki tutorial was updated to take into account changes to the - ``pyramid_routesalchemy`` paster template. - -Backwards Incompatibilities (with BFG 1.3) ------------------------------------------- - -- There is no longer an ``IDebugLogger`` registered as a named utility - with the name ``repoze.bfg.debug``. - -- The logger which used to have the name of ``repoze.bfg.debug`` now - has the name ``pyramid.debug``. - -- The deprecated API ``pyramid.testing.registerViewPermission`` - has been removed. - -- The deprecated API named ``pyramid.testing.registerRoutesMapper`` - has been removed. - -- The deprecated API named ``pyramid.request.get_request`` was removed. - -- The deprecated API named ``pyramid.security.Unauthorized`` was - removed. - -- The deprecated API named ``pyramid.view.view_execution_permitted`` - was removed. - -- The deprecated API named ``pyramid.view.NotFound`` was removed. - -- The ``bfgshell`` paster command is now named ``pshell``. - -- The Venusian "category" for all built-in Venusian decorators - (e.g. ``subscriber`` and ``view_config``/``bfg_view``) is now - ``pyramid`` instead of ``bfg``. - -- ``pyramid.renderers.rendered_response`` function removed; use - ``render_pyramid.renderers.render_to_response`` instead. - -- Renderer factories now accept a *renderer info object* rather than an - absolute resource specification or an absolute path. The object has the - following attributes: ``name`` (the ``renderer=`` value), ``package`` (the - 'current package' when the renderer configuration statement was found), - ``type``: the renderer type, ``registry``: the current registry, and - ``settings``: the deployment settings dictionary. - - Third-party ``repoze.bfg`` renderer implementations that must be ported to - Pyramid will need to account for this. - - This change was made primarily to support more flexible Mako template - rendering. - -- The presence of the key ``repoze.bfg.message`` in the WSGI environment when - an exception occurs is now deprecated. Instead, code which relies on this - environ value should use the ``exception`` attribute of the request - (e.g. ``request.exception[0]``) to retrieve the message. - -- The values ``bfg_localizer`` and ``bfg_locale_name`` kept on the request - during internationalization for caching purposes were never APIs. These - however have changed to ``localizer`` and ``locale_name``, respectively. - -- The default ``cookie_name`` value of the ``authtktauthenticationpolicy`` ZCML - now defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). - -- The default ``cookie_name`` value of the - ``pyramid.authentication.AuthTktAuthenticationPolicy`` constructor now - defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). - -- The ``request_type`` argument to the ``view`` ZCML directive, the - ``pyramid.configuration.Configurator.add_view`` method, or the - ``pyramid.view.view_config`` decorator (nee ``bfg_view``) is no longer - permitted to be one of the strings ``GET``, ``HEAD``, ``PUT``, ``POST`` or - ``DELETE``, and now must always be an interface. Accepting the - method-strings as ``request_type`` was a backwards compatibility strategy - servicing repoze.bfg 1.0 applications. Use the ``request_method`` - parameter instead to specify that a view a string request-method predicate. - diff --git a/MANIFEST.in b/MANIFEST.in index 8dac939f8..2e18ad5fe 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -3,7 +3,7 @@ graft docs prune docs/_build include README.rst -include CHANGES.txt HISTORY.txt BFG_HISTORY.txt +include CHANGES.rst HISTORY.rst BFG_HISTORY.rst include CONTRIBUTORS.txt LICENSE.txt COPYRIGHT.txt include contributing.md RELEASING.txt diff --git a/docs/changes.rst b/docs/changes.rst index fdeaf1e99..61d639a16 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -3,11 +3,11 @@ :app:`Pyramid` Change History ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. include:: ../CHANGES.txt +.. include:: ../CHANGES.rst -.. include:: ../HISTORY.txt +.. include:: ../HISTORY.rst :mod:`repoze.bfg` Change History (previous name for Pyramid) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. include:: ../BFG_HISTORY.txt +.. include:: ../BFG_HISTORY.rst diff --git a/setup.py b/setup.py index 14c0ab770..6fa833737 100644 --- a/setup.py +++ b/setup.py @@ -18,7 +18,7 @@ def readfile(name): return f.read() README = readfile('README.rst') -CHANGES = readfile('CHANGES.txt') +CHANGES = readfile('CHANGES.rst') install_requires = [ 'setuptools', -- cgit v1.2.3