add docs for pyramid.includes; allow space-separated or cr separated items or both for tweens and includes

5 files changed, 163 insertions, 4 deletions

diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 6465c2a1e..cb6bc6a5d 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -185,6 +185,104 @@ The value supplied here is used as the default locale name when a
 |                                 |                                   |
 +---------------------------------+-----------------------------------+
 
+Including Packages
+------------------
+
+``pyramid.includes`` instructs your application to include other packages.
+Using the setting is equivalent to using the
+:meth:`pyramid.config.Configurator.include` method.  
+
++---------------------------------+
+| Config File Setting Name        |
++=================================+
+| ``pyramid.includes``            |
+|                                 |
+|                                 |
+|                                 |
++---------------------------------+
+
+The value supplied as ``pyramid.includes`` should be a sequence.  The
+sequence can take several different forms.
+
+1) It can be a string.
+
+   If it is a string, the package names can be separated by spaces::
+
+      package1 package2 package3
+
+    The package names can also be separated by carriage returns::
+
+       package1
+       package2
+       package3
+
+2) It can be a Python list, where the values are strings::
+
+   ['package1', 'package2', 'package3']
+
+Each value in the sequence should be a :term:`dotted Python name`.
+
+``pyramid.includes`` vs. :meth:`pyramid.config.Configurator.include`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PasteDeploy
++++++++++++
+
+Using the following ``pyramid.includes`` setting in the PasteDeploy ``.ini``
+file in your application:
+
+.. code-block:: ini
+
+  [app:myapp]
+  pyramid.includes = pyramid_debugtoolbar
+                     pyramid_tm
+
+Is equivalent to using the following statements in your configuration code:
+
+.. code-block:: python
+   :linenos:
+
+  from pyramid.config import Configurator
+
+  def main(global_config, **settings):
+      config = Configurator(settings=settings)
+      # ...
+      config.include('pyramid_debugtoolbar')
+      config.include('pyramid_tm')
+      # ...
+
+It is fine to use both or either form.
+
+Plain Python
+++++++++++++
+
+Using the following ``pyramid.includes`` setting in your plain-Python Pyramid
+application: 
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+
+   if __name__ == '__main__':
+       settings = {'pyramid.includes':'pyramid_debugtoolbar pyramid_tm'}
+       config = Configurator(settings=settings)
+
+Is equivalent to using the following statements in your configuration code:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+
+   if __name__ == '__main__':
+       settings = {}
+       config = Configurator(settings=settings)
+       config.include('pyramid_debugtoolbar')
+       config.include('pyramid_tm')
+
+It is fine to use both or either form.
+
 .. _mako_template_renderer_settings:
 
 Mako Template Render Settings
diff --git a/pyramid/config.py b/pyramid/config.py
index 988c35a54..827144828 100644
--- a/pyramid/config.py
+++ b/pyramid/config.py
@@ -73,6 +73,7 @@ from pyramid.asset import PackageOverrides
 from pyramid.asset import resolve_asset_spec
 from pyramid.security import NO_PERMISSION_REQUIRED
 from pyramid.settings import Settings
+from pyramid.settings import aslist
 from pyramid.static import StaticURLInfo
 from pyramid.threadlocal import get_current_registry
 from pyramid.threadlocal import get_current_request
@@ -771,10 +772,8 @@ class Configurator(object):
         tweens = []
         includes = []
         if settings:
-            includes = [x.strip() for x in
-                        settings.get('pyramid.includes', '').splitlines()]
-            tweens =   [x.strip() for x in
-                        settings.get('pyramid.tweens','').splitlines()]
+            includes = aslist(settings.get('pyramid.includes', ''))
+            tweens   = aslist(settings.get('pyramid.tweens', ''))
         registry = self.registry
         self._fix_registry()
         self._set_settings(settings)
diff --git a/pyramid/settings.py b/pyramid/settings.py
index 7540cb6d6..677ea15f3 100644
--- a/pyramid/settings.py
+++ b/pyramid/settings.py
@@ -6,6 +6,7 @@ from zope.interface import implements
 from pyramid.interfaces import ISettings
 
 from pyramid.threadlocal import get_current_registry
+from pyramid.util import DottedNameResolver
 
 class Settings(dict):
     """ Deployment settings.  Update application settings (usually
@@ -138,3 +139,15 @@ def asbool(s):
     s = str(s).strip()
     return s.lower() in ('t', 'true', 'y', 'yes', 'on', '1')
 
+def aslist_cronly(value):
+    if isinstance(value, basestring):
+        value = filter(None, [x.strip() for x in value.splitlines()])
+    return value
+
+def aslist(value):
+    values = aslist_cronly(value)
+    result = []
+    for value in values:
+        subvalues = value.split()
+        result.extend(subvalues)
+    return result
diff --git a/pyramid/tests/test_config.py b/pyramid/tests/test_config.py
index d0c8d9312..4620c05aa 100644
--- a/pyramid/tests/test_config.py
+++ b/pyramid/tests/test_config.py
@@ -584,6 +584,17 @@ pyramid.tests.test_config.dummy_include2""",
         self.assert_(reg.included)
         self.assert_(reg.also_included)
 
+    def test_setup_registry_includes_spaces(self):
+        from pyramid.registry import Registry
+        reg = Registry()
+        config = self._makeOne(reg)
+        settings = {
+            'pyramid.includes': """pyramid.tests.test_config.dummy_include pyramid.tests.test_config.dummy_include2""",
+        }
+        config.setup_registry(settings=settings)
+        self.assert_(reg.included)
+        self.assert_(reg.also_included)
+
     def test_setup_registry_tweens(self):
         from pyramid.interfaces import ITweens
         from pyramid.registry import Registry
diff --git a/pyramid/tests/test_settings.py b/pyramid/tests/test_settings.py
index 5037959aa..36c628f31 100644
--- a/pyramid/tests/test_settings.py
+++ b/pyramid/tests/test_settings.py
@@ -527,3 +527,41 @@ class Test_asbool(unittest.TestCase):
     def test_s_is_1(self):
         result = self._callFUT(1)
         self.assertEqual(result, True)
+
+class Test_aslist_cronly(unittest.TestCase):
+    def _callFUT(self, val):
+        from pyramid.settings import aslist_cronly
+        return aslist_cronly(val)
+
+    def test_with_list(self):
+        result = self._callFUT(['abc', 'def'])
+        self.assertEqual(result, ['abc', 'def'])
+        
+    def test_with_string(self):
+        result = self._callFUT('abc def')
+        self.assertEqual(result, ['abc def'])
+
+    def test_with_string_crsep(self):
+        result = self._callFUT(' abc\n def')
+        self.assertEqual(result, ['abc', 'def'])
+
+class Test_aslist(unittest.TestCase):
+    def _callFUT(self, val):
+        from pyramid.settings import aslist
+        return aslist(val)
+
+    def test_with_list(self):
+        result = self._callFUT(['abc', 'def'])
+        self.assertEqual(result, ['abc', 'def'])
+        
+    def test_with_string(self):
+        result = self._callFUT('abc def')
+        self.assertEqual(result, ['abc', 'def'])
+
+    def test_with_string_crsep(self):
+        result = self._callFUT(' abc\n def')
+        self.assertEqual(result, ['abc', 'def'])
+
+    def test_with_string_crsep_spacesep(self):
+        result = self._callFUT(' abc\n def ghi')
+        self.assertEqual(result, ['abc', 'def', 'ghi'])