- Added a route_prefix argument to the

  ``pyramid.config.Configurator.include`` method.  This argument allows you
  to compose URL dispatch applications together.  See the section entitled
  "Using a Route Prefix to Compose Applications" in the "URL Dispatch"
  narrative documentation chapter.

- Added a section entitled "Using a Route Prefix to Compose Applications" to
  the "URL Dispatch" narrative documentation chapter.

CHANGES.txt

@@ -4,6 +4,12 @@ Next release
 Features
 --------
 
+- Added a ``route_prefix`` argument to the
+  ``pyramid.config.Configurator.include`` method.  This argument allows you
+  to compose URL dispatch applications together.  See the section entitled
+  "Using a Route Prefix to Compose Applications" in the "URL Dispatch"
+  narrative documentation chapter.
+
 - Added a ``pyramid.security.NO_PERMISSION_REQUIRED`` constant for use in
   ``permission=`` statements to view configuration.  This constant has a
   value of the string ``__no_permission_required__``.  This string value was
@@ -65,9 +71,18 @@ Backwards Incompatibilities
   that string is considered to be the name of a global Python logger rather
   than a dotted name to an instance of a logger.
 
+- The ``pyramid.config.Configurator.include`` method now accepts only a
+  single ``callable`` argument (a sequence of callables used to be
+  permitted).  If you are passing more than one ``callable`` to
+  ``pyramid.config.Configurator.include``, it will break.  You now must now
+  instead make a separate call to the method for each callable.
+
 Documentation
 -------------
 
+- Added a section entitled "Using a Route Prefix to Compose Applications" to
+  the "URL Dispatch" narrative documentation chapter.
+
 - Added a new module to the API docs: ``pyramid.tweens``.
 
 - Added a "Registering Tweens" section to the "Hooks" narrative chapter.

docs/narr/extending.rst

@@ -62,6 +62,8 @@ Pyramid applications are *extensible*.
 .. index::
    single: extensible application
 
+.. _building_an_extensible_app:
+
 Rules for Building An Extensible Application
 --------------------------------------------
 

docs/narr/urldispatch.rst

@@ -1082,6 +1082,96 @@ either of them in detail.
 If no route is matched using :term:`URL dispatch`, :app:`Pyramid` falls back
 to :term:`traversal` to handle the :term:`request`.
 
+.. _route_prefix:
+
+Using a Route Prefix to Compose Applications
+--------------------------------------------
+
+.. note:: This feature is new as of :app:`Pyramid` 1.2.
+
+The :meth:`pyramid.config.Configurator.include` method allows configuration
+statements to be included from separate files.  See
+:ref:`building_an_extensible_app` for information about this method.  Using
+:meth:`pyramid.config.Configurator.include` allows you to build your
+application from small and potentially reusable components.
+
+The :meth:`pyramid.config.Configurator.include` method accepts an argument
+named ``route_prefix`` which can be useful to authors of URL-dispatch-based
+applications.  If ``route_prefix`` is supplied to the include method, it must
+be a string.  This string represents a route prefix that will be prepended to
+all route patterns added by the *included* configuration.  Any calls to
+:meth:`pyramid.config.Configurator.add_route` within the included callable
+will have their pattern prefixed with the value of ``route_prefix``. This can
+be used to help mount a set of routes at a different location than the
+included callable's author intended while still maintaining the same route
+names.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+
+   def users_include(config):
+       config.add_route('show_users', '/show')
+       
+   def main(global_config, **settings):
+       config = Configurator()
+       config.include(users_include, route_prefix='/users')
+
+In the above configuration, the ``show_users`` route will have an effective
+route pattern of ``/users/show``, instead of ``/show`` because the
+``route_prefix`` argument will be prepended to the pattern.  The route will
+then only match if the URL path is ``/users/show``, and when the
+:func:`pyramid.url.route_url` function is called with the route name
+``show_users``, it will generate a URL with that same path.
+
+Route prefixes are recursive, so if a callable executed via an include itself
+turns around and includes another callable, the second-level route prefix
+will be prepended with the first:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+
+   def timing_include(config):
+       config.add_route('show_times', /times')
+       
+   def users_include(config):
+       config.add_route('show_users', '/show')
+       config.include(timing_include, route_prefix='/timing')
+
+   def main(global_config, **settings):
+       config = Configurator()
+       config.include(users_include, route_prefix='/users')
+
+In the above configuration, the ``show_users`` route will still have an
+effective route pattern of ``/users/show``.  The ``show_times`` route
+however, will have an effective pattern of ``/users/timing/show_times``.
+
+Route prefixes have no impact on the requirement that the set of route
+*names* in any given Pyramid configuration must be entirely unique.  If you
+compose your URL dispatch application out of many small subapplications using
+:meth:`pyramid.config.Configurator.include`, it's wise to use a dotted name
+for your route names, so they'll be unlikely to conflict with other packages
+that may be added in the future.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+
+   def timing_include(config):
+       config.add_route('timing.show_times', /times')
+       
+   def users_include(config):
+       config.add_route('users.show_users', '/show')
+       config.include(timing_include, route_prefix='/timing')
+
+   def main(global_config, **settings):
+       config = Configurator()
+       config.include(users_include, route_prefix='/users')
+
 References
 ----------
 

pyramid/config.py

@@ -536,7 +536,7 @@ def include(self, callable, route_prefix=None):
         """Include a configuration callables, to support imperative
         application extensibility.
 
-        .. warning:: In versions of :app:`Pyramid` prior to 1.x, this
+        .. warning:: In versions of :app:`Pyramid` prior to 1.2, this
             function accepted ``*callables``, but this has been changed
             to support only a single callable.
 
@@ -599,12 +599,32 @@ def main(global_config, **settings):
         configuration conflict by registering something with the same
         configuration parameters.
 
-        If the ``route_prefix`` is supplied, any calls to
-        :meth:`pyramid.config.Configurator.add_route` within the ``callable``
-        will have their pattern prefixed with ``route_prefix``. This can
-        be used to help mount a set of routes at a different location than
-        the ``callable``-author intended while still maintaining the same
-        route names. This parameter is new as of Pyramid 1.2."""
+        If the ``route_prefix`` is supplied, it must be a string.  Any calls
+        to :meth:`pyramid.config.Configurator.add_route` within the included
+        callable will have their pattern prefixed with the value of
+        ``route_prefix``. This can be used to help mount a set of routes at a
+        different location than the included callable's author intended while
+        still maintaining the same route names.  For example:
+            
+        .. code-block:: python
+           :linenos:
+
+           from pyramid.config import Configurator
+
+           def included(config):
+               config.add_route('show_users', '/show')
+               
+           def main(global_config, **settings):
+               config = Configurator()
+               config.include(included, route_prefix='/users')
+
+        In the above configuration, the ``show_users`` route will have an
+        effective route pattern of ``/users/show``, instead of ``/show``
+        because the ``route_prefix`` argument will be prepended to the
+        pattern.
+
+        The ``route_prefix`` parameter is new as of Pyramid 1.2.
+        """
 
         _context = self._ctx
         if _context is None: