Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 6 insertions, 1474 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 0254ac2b0..c0681053d 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,1485 +1,17 @@
-Next release
-============
+unreleased
+==========
 
-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``.
-
-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.
-
-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.
-
-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 response 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 renderer factory 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 not 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.
-
-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/dev/).
-
-- 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)
-==================
+Backward Incompatibilities
+--------------------------
 
 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 wilcard 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
----------------------------
-
-- 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://pylonsproject.org/projects/pyramid_handlers/dev/, 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://pylonsproject.org/projects/pyramid_zcml/dev/, 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. ``<include
-  package="pyramid.includes"/>``) now must include the ``pyramid_zcml``
-  package instead (e.g. ``<include package="pyramid_zcml"/>``).
-
-- 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, ``<include package="repoze.bfg.includes">``
-  will be converted to ``<include package="pyramid_zcml">``.
-
-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
-  ``<unknown>``.
-
-- 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
-  <http://www.makotemplates.org/docs/runtime.html#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.
+Documentation Changes
+---------------------