Merge pull request #2435 from mmerickel/feature/separate-viewderiver-module

separate viewderiver module

2 files changed, 46 insertions, 14 deletions

diff --git a/docs/api/viewderivers.rst b/docs/api/viewderivers.rst
new file mode 100644
index 000000000..2a141501e
--- /dev/null
+++ b/docs/api/viewderivers.rst
@@ -0,0 +1,17 @@
+.. _viewderivers_module:
+
+:mod:`pyramid.viewderivers`
+---------------------------
+
+.. automodule:: pyramid.viewderivers
+
+   .. attribute:: INGRESS
+
+      Constant representing the request ingress, for use in ``under``
+      arguments to :meth:`pyramid.config.Configurator.add_view_deriver`.
+
+   .. attribute:: VIEW
+
+      Constant representing the :term:`view callable` at the end of the view
+      pipeline, for use in ``over`` arguments to
+      :meth:`pyramid.config.Configurator.add_view_deriver`.
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index a32e94d1a..2c3782387 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -1580,12 +1580,6 @@ There are several built-in view derivers that :app:`Pyramid` will automatically
 apply to any view. Below they are defined in order from furthest to closest to
 the user-defined :term:`view callable`:
 
-``authdebug_view``
-
-  Used to output useful debugging information when
-  ``pyramid.debug_authorization`` is enabled. This element is a no-op
-  otherwise.
-
 ``secured_view``
 
   Enforce the ``permission`` defined on the view. This element is a no-op if no
@@ -1593,6 +1587,9 @@ the user-defined :term:`view callable`:
   default permission was assigned via
   :meth:`pyramid.config.Configurator.set_default_permission`.
 
+  This element will also output useful debugging information when
+  ``pyramid.debug_authorization`` is enabled.
+
 ``owrapped_view``
 
   Invokes the wrapped view defined by the ``wrapper`` option.
@@ -1620,6 +1617,14 @@ the user-defined :term:`view callable`:
   view pipeline interface to accept ``(context, request)`` from all previous
   view derivers.
 
+.. warning::
+
+   Any view derivers defined ``under`` the ``rendered_view`` are not
+   guaranteed to receive a valid response object. Rather they will receive the
+   result from the :term:`view mapper` which is likely the original response
+   returned from the view. This is possibly a dictionary for a renderer but it
+   may be any Python object that may be adapted into a response.
+
 Custom View Derivers
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -1645,7 +1650,7 @@ view pipeline:
            response.headers['X-View-Performance'] = '%.3f' % (end - start,)
        return wrapper_view
 
-   config.add_view_deriver(timing_view, 'timing view')
+   config.add_view_deriver(timing_view)
 
 View derivers are unique in that they have access to most of the options
 passed to :meth:`pyramid.config.Configurator.add_view` in order to decide what
@@ -1671,7 +1676,7 @@ token unless ``disable_csrf=True`` is passed to the view:
 
    require_csrf_view.options = ('disable_csrf',)
 
-   config.add_view_deriver(require_csrf_view, 'require_csrf_view')
+   config.add_view_deriver(require_csrf_view)
 
    def protected_view(request):
        return Response('protected')
@@ -1694,13 +1699,19 @@ By default, every new view deriver is added between the ``decorated_view`` and
 ``rendered_view`` built-in derivers. It is possible to customize this ordering
 using the ``over`` and ``under`` options. Each option can use the names of
 other view derivers in order to specify an ordering. There should rarely be a
-reason to worry about the ordering of the derivers.
+reason to worry about the ordering of the derivers except when the deriver
+depends on other operations in the view pipeline.
 
 Both ``over`` and ``under`` may also be iterables of constraints. For either
 option, if one or more constraints was defined, at least one must be satisfied,
 else a :class:`pyramid.exceptions.ConfigurationError` will be raised. This may
 be used to define fallback constraints if another deriver is missing.
 
+Two sentinel values exist, :attr:`pyramid.viewderivers.INGRESS` and
+:attr:`pyramid.viewderivers.VIEW`, which may be used when specifying
+constraints at the edges of the view pipeline. For example, to add a deriver
+at the start of the pipeline you may use ``under=INGRESS``.
+
 It is not possible to add a view deriver under the ``mapped_view`` as the
 :term:`view mapper` is intimately tied to the signature of the user-defined
 :term:`view callable`. If you simply need to know what the original view
@@ -1710,8 +1721,12 @@ deriver.
 
 .. warning::
 
-   Any view derivers defined ``under`` the ``rendered_view`` are not
-   guaranteed to receive a valid response object. Rather they will receive the
-   result from the :term:`view mapper` which is likely the original response
-   returned from the view. This is possibly a dictionary for a renderer but it
-   may be any Python object that may be adapted into a response.
+   The default constraints for any view deriver are ``over='rendered_view'``
+   and ``under='decorated_view'``. When escaping these constraints you must
+   take care to avoid cyclic dependencies between derivers. For example, if
+   you want to add a new view deriver before ``secured_view`` then
+   simply specifying ``over='secured_view'`` is not enough, because the
+   default is also under ``decorated view`` there will be an unsatisfiable
+   cycle. You must specify a valid ``under`` constraint as well, such as
+   ``under=INGRESS`` to fall between INGRESS and ``secured_view`` at the
+   beginning of the view pipeline.