convert remainder of docs to use pyramid instead of repoze.bfg

1 files changed, 4 insertions, 1252 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 6d97062f7..242e4bfe8 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,1260 +1,12 @@
 Next release
 ============
 
-Features
---------
-
-- The ``paster`` template named ``bfg_routesalchemy`` has been updated
-  to use SQLAlchemy declarative syntax.  Thanks to Ergo^.
-
-- 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.
-
-Bug Fixes
----------
-
-- When a renderer factory could not be found, a misleading error
-  message was raised if the renderer name was not a string.
-
-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 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 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
-  <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 ``pyramid.testing.registerRoutesMapper`` API (deprecated in BFG
+  1.2) has been removed.
 
-- The Edgewall (BSD) license was added to the LICENSES.txt file, as
-  some code in the ``repoze.bfg.i18n`` derives from Babel source.
+- The ``pyramid.testing.registerViewPermission`` API (deprecated in
+  BFG 1.1) has been removed.