add config.root_package attribute

3 files changed, 34 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 63987d980..d66534752 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -7,6 +7,11 @@ Features
 - Cache busting for static resources has been added and is available via a new
   argument to ``pyramid.config.Configurator.add_static_view``: ``cachebust``.
 
+- Add ``pyramid.config.Configurator.root_package`` attribute and init
+  parameter to assist with includeable packages that wish to resolve
+  resources relative to the package in which the ``Configurator`` was created.
+  See https://github.com/Pylons/pyramid/pull/1337
+
 Bug Fixes
 ---------
 
diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py
index ebaae38a9..cfa35ec6c 100644
--- a/pyramid/config/__init__.py
+++ b/pyramid/config/__init__.py
@@ -125,6 +125,14 @@ class Configurator(
     is passed (the default), the package is assumed to be the Python package
     in which the *caller* of the ``Configurator`` constructor lives.
 
+    If the ``root_package`` is passed, it will propagate through the
+    configuration hierarchy as a way for included packages to locate
+    resources relative to the package in which the main ``Configurator`` was
+    created. If ``None`` is passed (the default), the ``root_package`` will
+    be derived from the ``package`` argument. The ``package`` attribute is
+    always pointing at the package being included when using :meth:`.include`,
+    whereas the ``root_package`` does not change.
+
     If the ``settings`` argument is passed, it should be a Python dictionary
     representing the :term:`deployment settings` for this application.  These
     are later retrievable using the
@@ -243,6 +251,9 @@ class Configurator(
 
     .. versionadded:: 1.3
        The ``introspection`` argument.
+
+    .. versionadded:: 1.6
+       The ``root_package`` argument.
     """
     manager = manager # for testing injection
     venusian = venusian # for testing injection
@@ -272,13 +283,17 @@ class Configurator(
                  exceptionresponse_view=default_exceptionresponse_view,
                  route_prefix=None,
                  introspection=True,
+                 root_package=None,
                  ):
         if package is None:
             package = caller_package()
+        if root_package is None:
+            root_package = package
         name_resolver = DottedNameResolver(package)
         self.name_resolver = name_resolver
         self.package_name = name_resolver.get_package_name()
         self.package = name_resolver.get_package()
+        self.root_package = root_package
         self.registry = registry
         self.autocommit = autocommit
         self.route_prefix = route_prefix
@@ -747,6 +762,7 @@ class Configurator(
             configurator = self.__class__(
                 registry=self.registry,
                 package=package_of(module),
+                root_package=self.root_package,
                 autocommit=self.autocommit,
                 route_prefix=route_prefix,
                 )
@@ -806,6 +822,7 @@ class Configurator(
         configurator = self.__class__(
             registry=self.registry,
             package=package,
+            root_package=self.root_package,
             autocommit=self.autocommit,
             route_prefix=self.route_prefix,
             introspection=self.introspection,
diff --git a/pyramid/tests/test_config/test_init.py b/pyramid/tests/test_config/test_init.py
index d6dba17f6..1e58e4d0f 100644
--- a/pyramid/tests/test_config/test_init.py
+++ b/pyramid/tests/test_config/test_init.py
@@ -736,6 +736,18 @@ pyramid.tests.test_config.dummy_include2""",
         else: # pragma: no cover
             raise AssertionError
 
+    def test_include_constant_root_package(self):
+        from pyramid import tests
+        from pyramid.tests import test_config
+        config = self._makeOne(root_package=tests)
+        results = {}
+        def include(config):
+            results['package'] = config.package
+            results['root_package'] = config.root_package
+        config.include(include)
+        self.assertEqual(results['root_package'], tests)
+        self.assertEqual(results['package'], test_config)
+
     def test_action_branching_kw_is_None(self):
         config = self._makeOne(autocommit=True)
         self.assertEqual(config.action('discrim'), None)