'Include a configuration callable, to support imperative
application extensibility.
.. 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.
A configuration callable should be a callable that accepts a single
argument named ``config``, which will be an instance of a
:term:`Configurator`.  However, be warned that it will not be the same
configurator instance on which you call this method.  The
code which runs as a result of calling the callable should invoke
methods on the configurator passed to it which add configuration
state.  The return value of a callable will be ignored.
Values allowed to be presented via the ``callable`` argument to
this method: any callable Python object or any :term:`dotted Python
name` which resolves to a callable Python object.  It may also be a
Python :term:`module`, in which case, the module will be searched for
a callable named ``includeme``, which will be treated as the
configuration callable.
For example, if the ``includeme`` function below lives in a module
named ``myapp.myconfig``:
.. code-block:: python
:linenos:
# myapp.myconfig module
def my_view(request):
from pyramid.response import Response
return Response(\'OK\')
def includeme(config):
config.add_view(my_view)
You might cause it to be included within your Pyramid application like
so:
.. code-block:: python
:linenos:
from pyramid.config import Configurator
def main(global_config, **settings):
config = Configurator()
config.include(\'myapp.myconfig.includeme\')
Because the function is named ``includeme``, the function name can
also be omitted from the dotted name reference:
.. code-block:: python
:linenos:
from pyramid.config import Configurator
def main(global_config, **settings):
config = Configurator()
config.include(\'myapp.myconfig\')
Included configuration statements will be overridden by local
configuration statements if an included callable causes a
configuration conflict by registering something with the same
configuration parameters.
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.
.. versionadded:: 1.2
The ``route_prefix`` parameter.
.. versionchanged:: 1.9
The included function is wrapped with a call to
:meth:`pyramid.config.Configurator.begin` and
:meth:`pyramid.config.Configurator.end` while it is executed.'

def include(self, callable, route_prefix=None):

    action_state = self.action_state
    if (route_prefix is None):
        route_prefix = ''
    old_route_prefix = self.route_prefix
    if (old_route_prefix is None):
        old_route_prefix = ''
    route_prefix = ('%s/%s' % (old_route_prefix.rstrip('/'), route_prefix.lstrip('/')))
    route_prefix = route_prefix.strip('/')
    if (not route_prefix):
        route_prefix = None
    c = self.maybe_dotted(callable)
    module = self.inspect.getmodule(c)
    if (module is c):
        try:
            c = getattr(module, 'includeme')
        except AttributeError:
            raise ConfigurationError(("module    %r    has    no    attribute    'includeme'" % module.__name__))
    spec = ((module.__name__ + ':') + c.__name__)
    sourcefile = self.inspect.getsourcefile(c)
    if (sourcefile is None):
        raise ConfigurationError(('No    source    file    for    module    %r    (.py    file    must    exist,    refusing    to    use    orphan    .pyc    or    .pyo    file).' % module.__name__))
    if action_state.processSpec(spec):
        configurator = self.__class__(registry=self.registry, package=package_of(module), root_package=self.root_package, autocommit=self.autocommit, route_prefix=route_prefix)
        configurator.basepath = os.path.dirname(sourcefile)
        configurator.includepath = (self.includepath + (spec,))
        self.begin()
        try:
            c(configurator)
        finally:
            self.end()
