Merge branch '1.3-branch'

Chris McDonough

2011-12-12 ec507ade5541e1e3949fd6020062e78d113e0ed8

Merge branch '1.3-branch'

 docs/narr/logging.rst

@@ -16,6 +16,8 @@
   a third-party scaffold which does not create these files, the
   configuration information in this chapter will not be applicable.

.. _logging_config:

Logging Configuration
---------------------


 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 :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 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.
#. 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 :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.
#. 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.
#. 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 @@
   :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 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 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 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 @@

.. 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`.


 docs/narr/startup.rst

@@ -24,11 +24,11 @@
-------------------

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 @@

#. 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 @@
   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,17 +98,14 @@
   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
   factory (constructor) to it as its ``root_factory`` argument, and
   ``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

 docs/whatsnew-1.3.rst

@@ -178,8 +178,8 @@
  ``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``