Merge branch '1.3-branch'

4 files changed, 87 insertions, 98 deletions

diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index f9f72270f..044655c1f 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -16,6 +16,8 @@ how to send log messages to loggers that you've configured.
    a third-party scaffold which does not create these files, the
    configuration information in this chapter will not be applicable.
 
+.. _logging_config:
+
 Logging Configuration
 ---------------------
 
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index d08261b17..b78362066 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -9,74 +9,67 @@
 Request Processing
 ==================
 
-Once a :app:`Pyramid` application is up and running, it is ready to
-accept requests and return responses.
+Once a :app:`Pyramid` application is up and running, it is ready to accept
+requests and return responses.  What happens from the time a :term:`WSGI`
+request enters a :app:`Pyramid` application through to the point that
+:app:`Pyramid` hands off a response back to WSGI for upstream processing?
 
-What happens from the time a :term:`WSGI` request enters a
-:app:`Pyramid` application through to the point that
-:app:`Pyramid` hands off a response back to WSGI for upstream
-processing?
+#. A user initiates a request from his browser to the hostname and port
+   number of the WSGI server used by the :app:`Pyramid` application.
 
-#. A user initiates a request from his browser to the hostname and
-   port number of the WSGI server used by the :app:`Pyramid`
-   application.
-
-#. The WSGI server used by the :app:`Pyramid` application passes
-   the WSGI environment to the ``__call__`` method of the
-   :app:`Pyramid` :term:`router` object.
+#. The WSGI server used by the :app:`Pyramid` application passes the WSGI
+   environment to the ``__call__`` method of the :app:`Pyramid`
+   :term:`router` object.
 
 #. A :term:`request` object is created based on the WSGI environment.
 
-#. The :term:`application registry` and the :term:`request` object
-   created in the last step are pushed on to the :term:`thread local`
-   stack that :app:`Pyramid` uses to allow the functions named
+#. The :term:`application registry` and the :term:`request` object created in
+   the last step are pushed on to the :term:`thread local` stack that
+   :app:`Pyramid` uses to allow the functions named
    :func:`~pyramid.threadlocal.get_current_request` and
    :func:`~pyramid.threadlocal.get_current_registry` to work.
 
 #. A :class:`~pyramid.events.NewRequest` :term:`event` is sent to any
    subscribers.
 
-#. If any :term:`route` has been defined within application
-   configuration, the :app:`Pyramid` :term:`router` calls a
-   :term:`URL dispatch` "route mapper."  The job of the mapper is to
-   examine the request to determine whether any user-defined
-   :term:`route` matches the current WSGI environment.  The
-   :term:`router` passes the request as an argument to the mapper.
-
-#. If any route matches, the request is mutated; a ``matchdict`` and
-   ``matched_route`` attributes are added to the request object; the
-   former contains a dictionary representing the matched dynamic
-   elements of the request's ``PATH_INFO`` value, the latter contains
-   the :class:`~pyramid.interfaces.IRoute` object representing the
-   route which matched.  The root object associated with the route
-   found is also generated: if the :term:`route configuration` which
-   matched has an associated a ``factory`` argument, this factory is
-   used to generate the root object, otherwise a default :term:`root
-   factory` is used.
-
-#. If a route match was *not* found, and a ``root_factory`` argument
-   was passed to the :term:`Configurator` constructor, that callable
-   is used to generate the root object.  If the ``root_factory``
-   argument passed to the Configurator constructor was ``None``, a
-   default root factory is used to generate a root object.
-
-#. The :app:`Pyramid` router calls a "traverser" function with the
-   root object and the request.  The traverser function attempts to
-   traverse the root object (using any existing ``__getitem__`` on the
-   root object and subobjects) to find a :term:`context`.  If the root
-   object has no ``__getitem__`` method, the root itself is assumed to
-   be the context.  The exact traversal algorithm is described in
-   :ref:`traversal_chapter`. The traverser function returns a
-   dictionary, which contains a :term:`context` and a :term:`view
-   name` as well as other ancillary information.
-
-#. The request is decorated with various names returned from the
-   traverser (such as ``context``, ``view_name``, and so forth), so
-   they can be accessed via e.g. ``request.context`` within
-   :term:`view` code.
-
-#. A :class:`~pyramid.events.ContextFound` :term:`event` is
-   sent to any subscribers.
+#. If any :term:`route` has been defined within application configuration,
+   the :app:`Pyramid` :term:`router` calls a :term:`URL dispatch` "route
+   mapper."  The job of the mapper is to examine the request to determine
+   whether any user-defined :term:`route` matches the current WSGI
+   environment.  The :term:`router` passes the request as an argument to the
+   mapper.
+
+#. If any route matches, the route mapper adds attributes to the request:
+   ``matchdict`` and ``matched_route`` attributes are added to the request
+   object.  The former contains a dictionary representing the matched dynamic
+   elements of the request's ``PATH_INFO`` value, the latter contains the
+   :class:`~pyramid.interfaces.IRoute` object representing the route which
+   matched.  The root object associated with the route found is also
+   generated: if the :term:`route configuration` which matched has an
+   associated a ``factory`` argument, this factory is used to generate the
+   root object, otherwise a default :term:`root factory` is used.
+
+#. If a route match was *not* found, and a ``root_factory`` argument was
+   passed to the :term:`Configurator` constructor, that callable is used to
+   generate the root object.  If the ``root_factory`` argument passed to the
+   Configurator constructor was ``None``, a default root factory is used to
+   generate a root object.
+
+#. The :app:`Pyramid` router calls a "traverser" function with the root
+   object and the request.  The traverser function attempts to traverse the
+   root object (using any existing ``__getitem__`` on the root object and
+   subobjects) to find a :term:`context`.  If the root object has no
+   ``__getitem__`` method, the root itself is assumed to be the context.  The
+   exact traversal algorithm is described in :ref:`traversal_chapter`. The
+   traverser function returns a dictionary, which contains a :term:`context`
+   and a :term:`view name` as well as other ancillary information.
+
+#. The request is decorated with various names returned from the traverser
+   (such as ``context``, ``view_name``, and so forth), so they can be
+   accessed via e.g. ``request.context`` within :term:`view` code.
+
+#. A :class:`~pyramid.events.ContextFound` :term:`event` is sent to any
+   subscribers.
 
 #. :app:`Pyramid` looks up a :term:`view` callable using the context, the
    request, and the view name.  If a view callable doesn't exist for this
@@ -86,20 +79,17 @@ processing?
    :class:`~pyramid.httpexceptions.HTTPNotFound` exception, which is meant to
    be caught by a surrounding :term:`exception view`.
 
-#. If a view callable was found, :app:`Pyramid` attempts to call
-   the view function.
-
-#. If an :term:`authorization policy` is in use, and the view was protected
-   by a :term:`permission`, :app:`Pyramid` passes the context, the request,
-   and the view_name to a function which determines whether the view being
-   asked for can be executed by the requesting user, based on credential
-   information in the request and security information attached to the
-   context.  If it returns ``True``, :app:`Pyramid` calls the view callable
-   to obtain a response.  If it returns ``False``, it raises a
-   :class:`~pyramid.httpexceptions.HTTPForbidden` exception, which is meant
-   to be called by a surrounding :term:`exception view`.
-
-#. If any exception was raised within a :term:`root factory`, by
+#. If a view callable was found, :app:`Pyramid` attempts to call it.  If an
+   :term:`authorization policy` is in use, and the view configuration is
+   protected by a :term:`permission`, :app:`Pyramid` determines whether the
+   view callable being asked for can be executed by the requesting user based
+   on credential information in the request and security information attached
+   to the context.  If the view execution is allowed, :app:`Pyramid` calls
+   the view callable to obtain a response.  If view execution is forbidden,
+   :app:`Pyramid` raises a :class:`~pyramid.httpexceptions.HTTPForbidden`
+   exception.
+
+#. If any exception is raised within a :term:`root factory`, by
    :term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself
    (such as when it raises :class:`~pyramid.httpexceptions.HTTPNotFound` or
    :class:`~pyramid.httpexceptions.HTTPForbidden`), the router catches the
@@ -128,9 +118,8 @@ processing?
 
 .. image:: router.png
 
-This is a very high-level overview that leaves out various details.
-For more detail about subsystems invoked by the :app:`Pyramid` router
-such as traversal, URL dispatch, views, and event processing, see
-:ref:`urldispatch_chapter`, :ref:`views_chapter`, and
-:ref:`events_chapter`.
+This is a very high-level overview that leaves out various details.  For more
+detail about subsystems invoked by the :app:`Pyramid` router such as
+traversal, URL dispatch, views, and event processing, see
+:ref:`urldispatch_chapter`, :ref:`views_chapter`, and :ref:`events_chapter`.
 
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 971d12b45..a7fc5d33c 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -24,11 +24,11 @@ The Startup Process
 -------------------
 
 The easiest and best-documented way to start and serve a :app:`Pyramid`
-application is to use the ``pserve`` command against a
-:term:`PasteDeploy` ``.ini`` file.  This uses the ``.ini`` file to infer
-settings and starts a server listening on a port.  For the purposes of this
-discussion, we'll assume that you are using this command to run your
-:app:`Pyramid` application.
+application is to use the ``pserve`` command against a :term:`PasteDeploy`
+``.ini`` file.  This uses the ``.ini`` file to infer settings and starts a
+server listening on a port.  For the purposes of this discussion, we'll
+assume that you are using this command to run your :app:`Pyramid`
+application.
 
 Here's a high-level time-ordered overview of what happens when you press
 ``return`` after running ``pserve development.ini``.
@@ -56,11 +56,12 @@ Here's a high-level time-ordered overview of what happens when you press
 
 #. The framework finds all :mod:`logging` related configuration in the
    ``.ini`` file and uses it to configure the Python standard library logging
-   system for this application.
+   system for this application.  See :ref:`logging_config` for more
+   information.
 
-#. The application's *constructor* (named by the entry point reference or
+#. The application's *constructor* named by the entry point reference or
    dotted Python name on the ``use=`` line of the section representing your
-   :app:`Pyramid` application) is passed the key/value parameters mentioned
+   :app:`Pyramid` application is passed the key/value parameters mentioned
    within the section in which it's defined.  The constructor is meant to
    return a :term:`router` instance, which is a :term:`WSGI` application.
 
@@ -77,13 +78,13 @@ Here's a high-level time-ordered overview of what happens when you press
    Note that the constructor function accepts a ``global_config`` argument,
    which is a dictionary of key/value pairs mentioned in the ``[DEFAULT]``
    section of an ``.ini`` file (if `[DEFAULT]
-   <http://docs.pylonsproject.org/projects/pyramid/dev/narr/paste.html
-   #defaults-section-of-a-pastedeploy-ini-file>`__ is present).  It also
-   accepts a ``**settings`` argument, which collects another set of arbitrary
-   key/value pairs.  The arbitrary key/value pairs received by this function
-   in ``**settings`` will be composed of all the key/value pairs that are
-   present in the ``[app:main]`` section (except for the ``use=`` setting)
-   when this function is called by when you run ``pserve``.
+   <http://docs.pylonsproject.org/projects/pyramid/dev/narr/paste.html#defaults-section-of-a-pastedeploy-ini-file>`__
+   is present).  It also accepts a ``**settings`` argument, which collects
+   another set of arbitrary key/value pairs.  The arbitrary key/value pairs
+   received by this function in ``**settings`` will be composed of all the
+   key/value pairs that are present in the ``[app:main]`` section (except for
+   the ``use=`` setting) when this function is called by when you run
+   ``pserve``.
 
    Our generated ``development.ini`` file looks like so:
 
@@ -97,7 +98,8 @@ Here's a high-level time-ordered overview of what happens when you press
    will receive the key/value pairs ``{'pyramid.reload_templates':'true',
    'pyramid.debug_authorization':'false', 'pyramid.debug_notfound':'false',
    'pyramid.debug_routematch':'false', 'pyramid.debug_templates':'true',
-   'pyramid.default_locale_name':'en'}``.
+   'pyramid.default_locale_name':'en'}``.  See :ref:`environment_chapter` for
+   the meanings of these keys.
 
 #. The ``main`` function first constructs a
    :class:`~pyramid.config.Configurator` instance, passing a root resource
@@ -105,10 +107,6 @@ Here's a high-level time-ordered overview of what happens when you press
    ``settings`` dictionary captured via the ``**settings`` kwarg as its
    ``settings`` argument.
 
-   The root resource factory is invoked on every request to retrieve the
-   application's root resource.  It is not called during startup, only when a
-   request is handled.
-
    The ``settings`` dictionary contains all the options in the ``[app:main]``
    section of our .ini file except the ``use`` option (which is internal to
    PasteDeploy) such as ``pyramid.reload_templates``,
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index d19935c97..f51c7977a 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -178,8 +178,8 @@ Backwards Incompatibilities
   ``paste.httpserver`` server.  ``wsgiref``, unlike the server it replaced
   (``paste.httpserver``) is not a production quality server.  See
   :ref:`alternate_wsgi_server` for information about how to use another WSGI
-  server in production. Rationale: Rationale: the Paste and PasteScript
-  packages do not run under Python 3.
+  server in production. Rationale: the Paste and PasteScript packages do not
+  run under Python 3.
 
 - The ``pshell`` command (see "paster pshell") no longer accepts a
   ``--disable-ipython`` command-line argument.  Instead, it accepts a ``-p``