Require that tween_factory argument to add_tween be a dotted name.

1 files changed, 64 insertions, 15 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 97bee479b..50758f327 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -846,25 +846,26 @@ behave a bit like :term:`WSGI` middleware but they have the benefit of
 running in a context in which they have access to the Pyramid
 :term:`application registry` as well as the Pyramid rendering machinery.
 
+Creating a Tween Factory
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 To make use of tweens, you must construct a "tween factory".  A tween factory
-must be a globally importable callable (or a :term:`dotted Python name` to
-such a callable) which accepts two arguments: ``handler`` and ``registry``.
-``handler`` will be the either the main Pyramid request handling function or
-another tween.  ``registry`` will be the Pyramid :term:`application registry`
-represented by this Configurator.  A tween factory must return a tween when
-it is called.
+must be a globally importable callable which accepts two arguments:
+``handler`` and ``registry``.  ``handler`` will be the either the main
+Pyramid request handling function or another tween.  ``registry`` will be the
+Pyramid :term:`application registry` represented by this Configurator.  A
+tween factory must return a tween when it is called.
 
 A tween is a callable which accepts a :term:`request` object and returns a
 two-tuple a :term:`response` object.
 
-Once you've created a tween factory, you can register it into the implicit
-tween chain using the :meth:`pyramid.config.Configurator.add_tween` method.
-
-Here's an example creating a tween factory and registering it:
+Here's an example of a tween factory:
 
 .. code-block:: python
    :linenos:
 
+    # in a module named myapp.tweens
+
     import time
     from pyramid.settings import asbool
     import logging
@@ -888,13 +889,58 @@ Here's an example creating a tween factory and registering it:
         # handler
         return handler
 
-    from pyramid.config import Configurator
+If you remember, a tween is an object which accepts a :term:`request` object
+and which returns a :term:`response` argument.  The ``request`` argument to a
+tween will be the request created by Pyramid's router when it receives a WSGI
+request.  The response object will be generated by the downstream Pyramid
+application and it should be returned by the tween.
+
+In the above example, the tween factory defines a ``timing_tween`` tween and
+returns it if ``asbool(registry.settings.get('do_timing'))`` is true.  It
+otherwise simply returns the handler it was given.  The ``registry.settings``
+attribute is a handle to the deployment settings provided by the user
+(usually in an ``.ini`` file).  In this case, if the user has defined a
+``do_timing`` setting, and that setting is ``True``, the user has said she
+wants to do timing, so the tween factory returns the timing tween; it
+otherwise just returns the handler it has been provided, preventing any
+timing.
+
+The example timing tween simply records the start time, calls the downstream
+handler, logs the number of seconds consumed by the downstream handler, and
+returns the response.
+
+Registering an Implicit Tween Factory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    config = Configurator()
-    config.add_tween(timing_tween_factory)
+Once you've created a tween factory, you can register it into the implicit
+tween chain using the :meth:`pyramid.config.Configurator.add_tween` method
+using its :term:`dotted Python name`.
 
-The ``request`` argument to a tween will be the request created by Pyramid's
-router when it receives a WSGI request.
+Here's an example of registering the a tween factory as an "implicit"
+tween in a Pyramid application:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.config import Configurator
+    config = Configurator()
+    config.add_tween('myapp.tweens.timing_tween_factory')
+
+Note that you must use a :term:`dotted Python name` as the first argument to
+:meth:`pyramid.config.Configurator.add_tween`; this must point at a tween
+factory.  You cannot pass the tween factory object itself to the method: it
+must be a globally importable object.  In the above example, we assume that a
+``timing_tween_factory`` tween factory was defined in a module named
+``myapp.tweens``, so the tween factory is importable as
+``myapp.tweens.timing_tween_factory``.
+
+When you use :meth:`pyramid.config.Configurator.add_tween`, you're
+instructing the system to use your tween factory at startup time unless the
+user has provided an explicit tween list in his configuration.  This is
+what's meant by an "implicit" tween.  A user can always elect to supply an
+explicit tween list, reordering or disincluding implicitly added tweens.  See
+:ref:`explicit_tween_ordering` for more information about explicit tween
+ordering.
 
 If more than one call to :meth:`pyramid.config.Configurator.add_tween` is
 made within a single application configuration, the tweens will be chained
@@ -925,6 +971,9 @@ this::
     pyramid.tweens.excview_tween_factory (implicit)
     MAIN (implicit)
 
+Suggesting Implicit Tween Ordering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 By default, as described above, the ordering of the chain is controlled
 entirely by the relative ordering of calls to
 :meth:`pyramid.config.Configurator.add_tween`.  However, the caller of