document under and over params

4 files changed, 238 insertions, 75 deletions

diff --git a/docs/api/tweens.rst b/docs/api/tweens.rst
index 5fc15cb00..ddacd2cde 100644
--- a/docs/api/tweens.rst
+++ b/docs/api/tweens.rst
@@ -6,3 +6,20 @@
 .. automodule:: pyramid.tweens
 
    .. autofunction:: excview_tween_factory
+
+   .. attribute:: MAIN
+
+      Constant representing the main Pyramid handling function, for use in
+      ``under`` and ``over`` arguments to
+      :meth:`pyramid.config.Configurator.add_tween`.
+
+   .. attribute:: INGRESS
+
+      Constant representing the request ingress, for use in ``under`` and
+      ``over`` arguments to :meth:`pyramid.config.Configurator.add_tween`.
+
+   .. attribute:: EXCVIEW
+
+      Constant representing the exception view tween, for use in ``under``
+      and ``over`` arguments to
+      :meth:`pyramid.config.Configurator.add_tween`.
diff --git a/docs/glossary.rst b/docs/glossary.rst
index ccb62bbc8..f0ad81ded 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -920,11 +920,13 @@ Glossary
    tween
      A bit of code that sits between the Pyramid router's main request
      handling function and the upstream WSGI component that uses
-     :app:`Pyramid` as its 'app'.  A tween may be used by Pyramid framework
-     extensions, to provide, for example, Pyramid-specific view timing
-     support bookkeeping code that examines exceptions before they are
-     returned to the upstream WSGI application.  Tweens behave a bit like
-     :mod:`WSGI` 'middleware' but they have the benefit of running in a
+     :app:`Pyramid` as its 'app'.  The word "tween" is a contraction of
+     "between".  A tween may be used by Pyramid framework extensions, to
+     provide, for example, Pyramid-specific view timing support, bookkeeping
+     code that examines exceptions before they are returned to the upstream
+     WSGI application, or a variety of other features.  Tweens behave a bit
+     like :mod:`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.
+     registry` as well as the Pyramid rendering machinery.  See
+     :ref:`registering_tweens`.
 
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 6f969196f..0f23c153c 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -306,15 +306,16 @@ is executed.
 Displaying "Tweens"
 -------------------
 
-A user can get a representation of both the implicit :term:`tween` ordering
-(the ordering specified by calls to
-:meth:`pyramid.config.Configurator.add_tween`) and the explicit tween
-ordering (specified by the ``pyramid.tweens`` configuration setting)
-orderings using the ``paster ptweens`` command.  Handler factories which are
-functions or classes will show up as a standard Python dotted name in the
-``paster ptweens`` output.  Tween factories which are *instances* will show
-their module and class name; the Python object id of the instance will be
-appended.
+A :term:`tween` is a bit of code that sits between the main Pyramid
+application request handler and the WSGI application which calls it.  A user
+can get a representation of both the implicit tween ordering (the ordering
+specified by calls to :meth:`pyramid.config.Configurator.add_tween`) and the
+explicit tween ordering (specified by the ``pyramid.tweens`` configuration
+setting) orderings using the ``paster ptweens`` command.  Handler factories
+which are functions or classes will show up as a standard Python dotted name
+in the ``paster ptweens`` output.  Tween factories which are *instances* will
+show their module and class name; the Python object id of the instance will
+be appended.
 
 For example, here's the ``paster pwteens`` command run against a system
 configured without any explicit tweens:
@@ -322,12 +323,17 @@ configured without any explicit tweens:
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko starter]$ ../bin/paster ptweens development.ini 
+   [chrism@thinko pyramid]$ paster ptweens development.ini 
    "pyramid.tweens" config value NOT set (implicitly ordered tweens used)
 
-   Position Name                          
-   -------- ----                          
-   0        pyramid.router.excview_tween_factory
+   Implicit Tween Chain
+
+   Position    Name                                                Alias 
+   --------    ----                                                -----
+   -           -                                                   INGRESS
+   0           pyramid_debugtoolbar.toolbar.toolbar_tween_factory  pdbt
+   1           pyramid.tweens.excview_tween_factory                excview
+   -           -                                                   MAIN
 
 Here's the ``paster pwteens`` command run against a system configured *with*
 explicit tweens defined in its ``development.ini`` file:
@@ -335,22 +341,27 @@ explicit tweens defined in its ``development.ini`` file:
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko starter]$ ../bin/paster ptweens development.ini 
+   [chrism@thinko pyramid]$ paster ptweens development.ini  
    "pyramid.tweens" config value set (explicitly ordered tweens used)
 
    Explicit Tween Chain (used)
 
-   Position Name                          
-   -------- ----                          
-   0        pyramid.tweens.excview_tween_factory
-   1        starter.tween_factory1        
-   2        starter.tween_factory2        
+   Position    Name                                                             
+   --------    ----                                                             
+   -           INGRESS                                                          
+   0           starter.tween_factory2                                           
+   1           starter.tween_factory1                                           
+   2           pyramid.tweens.excview_tween_factory                             
+   -           MAIN                                                             
 
    Implicit Tween Chain (not used)
 
-   Position Name                          
-   -------- ----                          
-   0        pyramid.tweens.excview_tween_factory
+   Position    Name                                                Alias
+   --------    ----                                                -----
+   -           -                                                   INGRESS
+   0           pyramid_debugtoolbar.toolbar.toolbar_tween_factory  pdbt
+   1           pyramid.tweens.excview_tween_factory                excview
+   -           -                                                   MAIN
 
 Here's the application configuration section of the ``development.ini`` used
 by the above ``paster ptweens`` command which reprorts that the explicit
@@ -361,15 +372,18 @@ tween chain is used:
 
    [app:starter]
    use = egg:starter
-   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.tweens = pyramid.tweens.excview_tween_factory
+   reload_templates = true
+   debug_authorization = false
+   debug_notfound = false
+   debug_routematch = false
+   debug_templates = true
+   default_locale_name = en
+   pyramid.include = pyramid_debugtoolbar
+   pyramid.tweens = starter.tween_factory2
                     starter.tween_factory1
-                    starter.tween_factory2
+                    pyramid.tweens.excview_tween_factory
+
+See :ref:`registering_tweens` for more information about tweens.
 
 .. _writing_a_script:
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 889e8d6d8..f7ee82821 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -836,11 +836,11 @@ Registering "Tweens"
 .. note:: Tweens are a feature which were added in Pyramid 1.1.1.  They are
    not available in any previous version.
 
-A :term:`tween` (think: "between") is a bit of code that sits between the
-Pyramid router's main request handling function and the upstream WSGI
-component that uses :app:`Pyramid` as its "app".  This is a feature that may
-be used by Pyramid framework extensions, to provide, for example,
-Pyramid-specific view timing support bookkeeping code that examines
+A :term:`tween` (a contraction of the word "between") is a bit of code that
+sits between the Pyramid router's main request handling function and the
+upstream WSGI component that uses :app:`Pyramid` as its "app".  This is a
+feature that may be used by Pyramid framework extensions, to provide, for
+example, Pyramid-specific view timing support bookkeeping code that examines
 exceptions before they are returned to the upstream WSGI application.  Tweens
 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
@@ -857,8 +857,8 @@ 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 using the
-:meth:`pyramid.config.Configurator.add_tween` method.
+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:
 
@@ -897,30 +897,145 @@ The ``request`` argument to a tween will be the request created by Pyramid's
 router when it receives a WSGI request.
 
 If more than one call to :meth:`pyramid.config.Configurator.add_tween` is
-made within a single application configuration, the added tweens will be
-chained together.  The first tween factory added will be called with the
-default Pyramid request handler as its ``handler`` argument, the second tween
-factory added will be called with the result of the first tween factory as
-its ``handler`` argument, and so on, ad infinitum. The Pyramid router will
-use the outermost tween produced by this chain (the tween generated by the
-very last tween factory added) as its request handler function.
-
-Pyramid will prevent the same tween factory from being added to the implicit
-tween chain more than once using configuration conflict detection.  If you
-wish to add the same tween factory more than once in a configuration, you
-should either: a) use a tween factory that is an instance rather than a
-function or class, b) use a function or class as a tween factory with the
-same logic as the other tween factory it conflicts with but with a different
-``__name__`` attribute or c) call :meth:`pyramid.config.Configurator.commit`
-between calls to :meth:`pyramid.config.Configurator.add_tween`.
-
-By default, the ordering of the chain is controlled entirely by the relative
-ordering of calls to :meth:`pyramid.config.Configurator.add_tween`.  However,
-the deploying user can override tween inclusion and ordering entirely in his
-Pyramid configuration using the ``pyramid.tweens`` settings value.  When
-used, this settings value will be a list of Python dotted names which imply
-the ordering (and inclusion) of tween factories in the tween chain.  For
-example:
+made within a single application configuration, the tweens will be chained
+together at application startup time.  The *first* tween factory added via
+``add_tween`` will be called with the Pyramid exception view tween factory as
+its ``handler`` argument, then the tween factory added directly after that
+one will be called with the result of the first tween factory as its
+``handler`` argument, and so on, ad infinitum until all tween factories have
+been called. The Pyramid router will use the outermost tween produced by this
+chain (the tween generated by the very last tween factory added) as its
+request handler function.  For example:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.config import Configurator
+
+    config = Configurator()
+    config.add_tween('myapp.tween_factory1')
+    config.add_tween('myapp.tween_factory2')
+
+The above example will generate an implicit tween chain that looks like
+this::
+
+    INGRESS (implicit)
+    myapp.tween_factory2
+    myapp.tween_factory1
+    pyramid.tweens.excview_tween_factory (implicit)
+    MAIN (implicit)
+
+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
+add_tween can provide an optional hint that can influence the implicit tween
+chain ordering by supplying ``under`` or ``over`` (or both) arguments to
+:meth:`~pyramid.config.Configurator.add_tween`.  These hints are only used
+used when an explicit tween chain is not used (when the ``pyramid.tweens``
+configuration value is not set).
+
+Allowable values for ``under`` or ``over`` (or both) are:
+
+- ``None`` (the default).
+
+- A :term:`dotted Python name` to a tween factory: a string representing the
+  predicted dotted name of a tween factory added in a call to ``add_tween``
+  in the same configuration session.
+
+- A "tween alias": a string representing the predicted value of ``alias`` in
+  a separate call to ``add_tween`` in the same configuration session
+
+- One of the constants :attr:`pyramid.tweens.MAIN`,
+  :attr:`pyramid.tweens.INGRESS`, or :attr:`pyramid.tweens.EXCVIEW`.
+
+Effectively, ``under`` means "closer to the main Pyramid application than",
+``over`` means "closer to the request ingress than".
+
+For example, the following call to
+:meth:`~pyramid.config.Configurator.add_tween` will attempt to place the
+tween factory represented by ``myapp.tween_factory`` directly 'above' (in
+``paster ptweens`` order) the main Pyramid request handler.
+
+.. code-block:: python
+   :linenos:
+
+   import pyramid.tweens
+
+   config.add_tween('myapp.tween_factory', over=pyramid.tweens.MAIN)
+
+The above example will generate an implicit tween chain that looks like
+this::
+
+    INGRESS (implicit)
+    pyramid.tweens.excview_tween_factory (implicit)
+    myapp.tween_factory
+    MAIN (implicit)
+
+Likewise, calling the following call to
+:meth:`~pyramid.config.Configurator.add_tween` will attempt to place this
+tween factory 'above' the main handler but 'below' a separately added tween
+factory:
+
+.. code-block:: python
+   :linenos:
+
+   import pyramid.tweens
+
+   config.add_tween('myapp.tween_factory1',
+                    over=pyramid.tweens.MAIN)
+   config.add_tween('myapp.tween_factory2',
+                    over=pyramid.tweens.MAIN,
+                    under='myapp.tween_factory1')
+
+The above example will generate an implicit tween chain that looks like
+this::
+
+    INGRESS (implicit)
+    pyramid.tweens.excview_tween_factory (implicit)
+    myapp.tween_factory1
+    myapp.tween_factory2
+    MAIN (implicit)
+
+Specifying neither ``over`` nor ``under`` is equivalent to specifying
+``under=INGRESS``.
+
+If an ``under`` or ``over`` value is provided that does not match a tween
+factory dotted name or alias in the current configuration, that value will be
+ignored.  It is not an error to provide an ``under`` or ``over`` value that
+matches an unused tween factory.
+
+:meth:`~pyramid.config.Configurator.add_tween` also accepts an ``alias``
+argument.  If ``alias`` is not ``None``, should be a string.  The string will
+represent a value that other callers of ``add_tween`` may pass as an
+``under`` and ``over`` argument instead of a dotted name to a tween factory.
+For example:
+
+.. code-block:: python
+   :linenos:
+
+   import pyramid.tweens
+
+   config.add_tween('myapp.tween_factory1',
+                    alias='one'
+                    over=pyramid.tweens.MAIN)
+   config.add_tween('myapp.tween_factory2',
+                    alias='two'
+                    over=pyramid.tweens.MAIN,
+                    under='one')
+
+Alias names are only useful in relation to ``under`` and ``over`` values.
+They cannot be used in explicit tween chain configuration, or anywhere else.
+
+Implicit tween ordering is obviously only best-effort.  Pyramid will attempt
+to provide an implicit order of tweens as best it can using hints provided by
+calls to :meth:`~pyramid.config.Configurator.add_tween`, but because it's
+only best-effort, if very precise tween ordering is required, the only
+surefire way to get it is to use an explicit tween order.  The deploying user
+can override the implicit tween inclusion and ordering implied by calls to
+:meth:`~pyramid.config.Configurator.add_tween` entirely by using the
+``pyramid.tweens`` settings value.  When used, this settings value must be a
+list of Python dotted names which will override the ordering (and inclusion)
+of tween factories in the implicit tween chain.  For example:
 
 .. code-block:: ini
    :linenos:
@@ -932,17 +1047,19 @@ example:
    pyramid.debug_notfound = false
    pyramid.debug_routematch = false
    pyramid.debug_templates = true
-   pyramid.tweens = pyramid.tweens.excview_tween_factory
-                    myapp.my_cool_tween_factory
+   pyramid.tweens = myapp.my_cool_tween_factory
+                    pyramid.tweens.excview_tween_factory
 
 In the above configuration, calls made during configuration to
 :meth:`pyramid.config.Configurator.add_tween` are ignored, and the user is
 telling the system to use the tween factories he has listed in the
-``pyramid.tweens`` configuration setting (each is a:term:`Python dotted name`
-which points to a tween factory).  The *last* tween factory in the
-``pyramid.tweens`` list will be used as the producer of the effective
+``pyramid.tweens`` configuration setting (each is a :term:`dotted Python
+name` which points to a tween factory) instead of any tween factories added
+via :meth:`pyramid.config.Configurator.add_tween`.  The *first* tween factory
+in the ``pyramid.tweens`` list will be used as the producer of the effective
 :app:`Pyramid` request handling function; it will wrap the tween factory
-declared directly "above" it, ad infinitum.
+declared directly "below" it, ad infinitum.  The "main" Pyramid request
+handler is implicit, and always "at the bottom".
 
 .. note:: Pyramid's own :term:`exception view` handling logic is implemented
    as a tween factory function: :func:`pyramid.tweens.excview_tween_factory`.
@@ -952,6 +1069,19 @@ declared directly "above" it, ad infinitum.
    ``pyramid.tweens`` configuration setting list explicitly.  If it is not
    present, Pyramid will not perform exception view handling.
 
-The ``paster ptweens`` command-line utility can be used to report the current
-tween chain used by an application.  See :ref:`displaying_tweens`.
+Pyramid will prevent the same tween factory from being added to the tween
+chain more than once using configuration conflict detection.  If you wish to
+add the same tween factory more than once in a configuration, you should
+either: a) use a tween factory that is an instance rather than a function or
+class, b) use a function or class as a tween factory with the same logic as
+the other tween factory it conflicts with but with a different ``__name__``
+attribute or c) call :meth:`pyramid.config.Configurator.commit` between calls
+to :meth:`pyramid.config.Configurator.add_tween`.
 
+If a cycle is detected in implicit tween ordering when ``over`` and ``under``
+are used in any call to "add_tween", an exception will be raised at startup
+time.
+
+The ``paster ptweens`` command-line utility can be used to report the current
+implict and explicit tween chains used by an application.  See
+:ref:`displaying_tweens`.