expose public config phases in pyramid.config

5 files changed, 36 insertions, 16 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 1c82e5f27..f2bedbcc9 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -7,7 +7,9 @@ Features
 - The ``pyramid.config.Configurator`` has grown the ability to allow
   actions to call other actions during a commit-cycle. This enables much more
   logic to be placed into actions, such as the ability to invoke other actions
-  or group them for improved conflict detection.
+  or group them for improved conflict detection. We have also exposed and
+  documented the config phases that Pyramid uses in order to further assist
+  in building conforming addons.
   See https://github.com/Pylons/pyramid/pull/1513
 
 - Add ``pyramid.request.apply_request_extensions`` function which can be
diff --git a/docs/api/config.rst b/docs/api/config.rst
index 48dd2f0b9..ae913d32c 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -132,3 +132,8 @@
    are being used.
 
 .. autoclass:: not_
+
+.. attribute:: PHASE0_CONFIG
+.. attribute:: PHASE1_CONFIG
+.. attribute:: PHASE2_CONFIG
+.. attribute:: PHASE3_CONFIG
diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index c4d3e0250..c805f1572 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -243,12 +243,17 @@ This means that if an action must be reliably executed before or after another
 action, the ``order`` must be defined explicitly to make this work. For
 example, views are dependent on routes being defined. Thus the action created
 by :meth:`pyramid.config.Configurator.add_route` has an ``order`` of
-:const:`pyramid.interfaces.PHASE2_CONFIG`.
+:const:`pyramid.config.PHASE2_CONFIG`.
 
 Pre-defined Phases
 ~~~~~~~~~~~~~~~~~~
 
-:const:`pyramid.interfaces.PHASE1_CONFIG`
+:const:`pyramid.config.PHASE0_CONFIG`
+
+- This phase is reserved for developers who want to execute actions prior
+  to Pyramid's core directives.
+
+:const:`pyramid.config.PHASE1_CONFIG`
 
 - :meth:`pyramid.config.Configurator.add_renderer`
 - :meth:`pyramid.config.Configurator.add_route_predicate`
@@ -258,12 +263,12 @@ Pre-defined Phases
 - :meth:`pyramid.config.Configurator.set_default_permission`
 - :meth:`pyramid.config.Configurator.set_view_mapper`
 
-:const:`pyramid.interfaces.PHASE2_CONFIG`
+:const:`pyramid.config.PHASE2_CONFIG`
 
 - :meth:`pyramid.config.Configurator.add_route`
 - :meth:`pyramid.config.Configurator.set_authentication_policy`
 
-``0``
+:const:`pyramid.config.PHASE3_CONFIG`
 
 - The default for all builtin or custom directives unless otherwise specified.
 
@@ -285,9 +290,7 @@ but we want it to conflict with any other call to our addon:
 .. code-block:: python
    :linenos:
 
-   from pyramid.interfaces import PHASE1_CONFIG
-
-   PHASE0_CONFIG = PHASE1_CONFIG - 10
+   from pyramid.config import PHASE0_CONFIG
 
    def includeme(config):
        config.add_directive(add_auto_route, 'add_auto_route')
diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py
index b5b5e841d..ea84aa1dc 100644
--- a/pyramid/config/__init__.py
+++ b/pyramid/config/__init__.py
@@ -12,7 +12,10 @@ from pyramid.interfaces import (
     IDebugLogger,
     IExceptionResponse,
     IPredicateList,
+    PHASE0_CONFIG,
     PHASE1_CONFIG,
+    PHASE2_CONFIG,
+    PHASE3_CONFIG,
     )
 
 from pyramid.asset import resolve_asset_spec
@@ -55,7 +58,9 @@ from pyramid.settings import aslist
 from pyramid.threadlocal import manager
 
 from pyramid.util import (
+    ActionInfo,
     WeakOrderedSet,
+    action_method,
     object_description,
     )
 
@@ -69,17 +74,18 @@ from pyramid.config.security import SecurityConfiguratorMixin
 from pyramid.config.settings import SettingsConfiguratorMixin
 from pyramid.config.testing import TestingConfiguratorMixin
 from pyramid.config.tweens import TweensConfiguratorMixin
-from pyramid.config.util import PredicateList, not_
+from pyramid.config.util import (
+    PredicateList,
+    not_,
+    PHASE1_CONFIG,
+    PHASE2_CONFIG,
+    PHASE3_CONFIG,
+)
 from pyramid.config.views import ViewsConfiguratorMixin
 from pyramid.config.zca import ZCAConfiguratorMixin
 
 from pyramid.path import DottedNameResolver
 
-from pyramid.util import (
-    action_method,
-    ActionInfo,
-    )
-
 empty = text_('')
 _marker = object()
 
@@ -87,6 +93,10 @@ ConfigurationError = ConfigurationError # pyflakes
 
 not_ = not_ # pyflakes, this is an API
 
+PHASE0_CONFIG = PHASE0_CONFIG  # api
+PHASE1_CONFIG = PHASE1_CONFIG  # api
+PHASE2_CONFIG = PHASE2_CONFIG  # api
+PHASE3_CONFIG = PHASE3_CONFIG  # api
 
 class Configurator(
     TestingConfiguratorMixin,
@@ -1301,4 +1311,3 @@ def expand_action(discriminator, callable=None, args=(), kw=None,
         )
 
 global_registries = WeakOrderedSet()
-
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 1508f282e..4c171f9cc 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -1228,6 +1228,7 @@ class ICacheBuster(Interface):
 # with this phase will be executed earlier than those with later phase
 # numbers.  The default phase number is 0, FTR.
 
+PHASE0_CONFIG = -30
 PHASE1_CONFIG = -20
 PHASE2_CONFIG = -10
-
+PHASE3_CONFIG = 0