- get_root2 -> prepare

- change prepare return value to a dict, and return the registry,
  request, etc

- various docs and changelog entries.

9 files changed, 123 insertions, 37 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index bc906772d..0e1f67cdc 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -16,6 +16,39 @@ Features
   ``pyramid.static.static_view`` exposes a ``use_subpath`` flag for use when
   you want the static view to behave like the older deprecated version.
 
+- A new API function ``pyramid.paster.bootstrap`` has been added to make
+  writing scripts that bootstrap a Pyramid environment easier, e.g.::
+
+      from pyramid.paster import bootstrap
+      info = bootstrap('/path/to/my/development.ini')
+      request = info['request']
+      print request.route_url('myroute')
+
+- A new API function ``pyramid.scripting.prepare`` has been added.  It is a
+  lower-level analogue of ``pyramid.paster.boostrap`` that accepts a request
+  and a registry instead of a config file argument, and is used for the same
+  purpose::
+
+      from pyramid.scripting import prepare
+      info = prepare(registry=myregistry)
+      request = info['request']
+      print request.route_url('myroute')
+
+- A new API function ``pyramid.scripting.make_request`` has been added.  The
+  resulting request will have a ``registry`` attribute.  It is meant to be
+  used in conjunction with ``pyramid.scripting.prepare`` and/or
+  ``pyramid.paster.bootstrap`` (both of which accept a request as an
+  argument)::
+
+      from pyramid.scripting import make_request
+      request = make_request('/')
+
+- New API attribute ``pyramid.config.global_registries`` is an iterable
+  object that contains references to every Pyramid registry loaded into the
+  current process via ``pyramid.config.Configurator.make_app``.  It also has
+  a ``last`` attribute containing the last registry loaded.  This is used by
+  the scripting machinery, and is available for introspection.
+
 Deprecations
 ------------
 
diff --git a/docs/api/config.rst b/docs/api/config.rst
index d021412b8..2c394ac41 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -88,9 +88,11 @@
 
   .. attribute:: global_registries
 
-     A set of registries that have been created for :app:`Pyramid`
-     applications. The object itself supports iteration and has a
-     ``last`` property containing the last registry loaded.
+     The set of registries that have been created for :app:`Pyramid`
+     applications, one per each call to
+     :meth:`pyramid.config.Configurator.make_app` in the current process. The
+     object itself supports iteration and has a ``last`` property containing
+     the last registry loaded.
 
      The registries contained in this object are stored as weakrefs,
      thus they will only exist for the lifetime of the actual
diff --git a/docs/api/scripting.rst b/docs/api/scripting.rst
index 3e9a814fc..79136a98b 100644
--- a/docs/api/scripting.rst
+++ b/docs/api/scripting.rst
@@ -7,7 +7,7 @@
 
   .. autofunction:: get_root
 
-  .. autofunction:: get_root2
+  .. autofunction:: prepare
 
   .. autofunction:: make_request
 
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index d57687477..f35f6dd7d 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -312,7 +312,7 @@ its behavior is almost exactly the same once it's configured.
    ``add_view`` (at least those without a ``route_name``).  A
    :class:`~pyramid.static.static_view` static view cannot be made
    root-relative when you use traversal unless it's registered as a
-   :term:`NotFound view`.
+   :term:`Not Found view`.
 
 To serve files within a directory located on your filesystem at
 ``/path/to/static/dir`` as the result of a "catchall" route hanging from the
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index dd4d488a0..32955ab75 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -266,6 +266,45 @@ Minor Feature Additions
   :class:`pyramid.static.static_view` exposes a ``use_subpath`` flag for use
   when you want the static view to behave like the older deprecated version.
 
+- A new API function :func:`pyramid.paster.bootstrap` has been added to make
+  writing scripts that bootstrap a Pyramid environment easier, e.g.:
+
+  .. code-block:: python
+
+      from pyramid.paster import bootstrap
+      info = bootstrap('/path/to/my/development.ini')
+      request = info['request']
+      print request.route_url('myroute')
+
+- A new api function :func:`pyramid.scripting.prepare` has been added.  It is
+  a lower-level analogue of :func:`pyramid.paster.boostrap` that accepts a
+  request and a registry instead of a config file argument, and is used for
+  the same purpose:
+
+  .. code-block:: python
+
+      from pyramid.scripting import prepare
+      info = prepare(registry=myregistry)
+      request = info['request']
+      print request.route_url('myroute')
+
+- A new API function :func:`pyramid.scripting.make_request` has been added.
+  The resulting request will have a ``registry`` attribute.  It is meant to
+  be used in conjunction with :func:`pyramid.scripting.prepare` and/or
+  :func:`pyramid.paster.bootstrap` (both of which accept a request as an
+  argument):
+
+  .. code-block:: python
+
+      from pyramid.scripting import make_request
+      request = make_request('/')
+
+- New API attribute :attr:`pyramid.config.global_registries` is an iterable
+  object that contains references to every Pyramid registry loaded into the
+  current process via :meth:`pyramid.config.Configurator.make_app`.  It also
+  has a ``last`` attribute containing the last registry loaded.  This is used
+  by the scripting machinery, and is available for introspection.
+
 Backwards Incompatibilities
 ---------------------------
 
diff --git a/pyramid/paster.py b/pyramid/paster.py
index 8211dc637..b6d7777c0 100644
--- a/pyramid/paster.py
+++ b/pyramid/paster.py
@@ -9,7 +9,7 @@ from paste.deploy import loadapp
 from paste.script.command import Command
 
 from pyramid.scripting import get_root
-from pyramid.scripting import get_root2
+from pyramid.scripting import prepare
 from pyramid.util import DottedNameResolver
 
 from pyramid.scaffolds import PyramidTemplate # bw compat
@@ -72,12 +72,9 @@ def bootstrap(config_uri, request=None):
     to those parameters.
     """
     app = get_app(config_uri)
-    root, closer = get_root2(request)
-    return {
-        'app': app,
-        'root': root,
-        'closer': closer,
-    }
+    info = prepare(request)
+    info['app'] = app
+    return info
 
 _marker = object()
 
diff --git a/pyramid/scripting.py b/pyramid/scripting.py
index bdc287c83..c04915d3a 100644
--- a/pyramid/scripting.py
+++ b/pyramid/scripting.py
@@ -26,15 +26,15 @@ def get_root(app, request=None):
     root = app.root_factory(request)
     return root, closer
 
-def get_root2(request=None, registry=None):
-    """ Return a tuple composed of ``(root, closer)``.  The ``root``
-    returned is the application's root object.  The ``closer`` returned
-    is a callable (accepting no arguments) that should be called when
-    your scripting application is finished using the root.
+def prepare(request=None, registry=None):
+    """ This function pushes data onto the Pyramid threadlocal stack (request
+    and registry), making those objects 'current'.  It returns a dictionary
+    useful for bootstrapping a Pyramid application in a scripting
+    environment.
 
-    If ``request`` is None, a default one is constructed using
-    :meth:`pyramid.scripting.make_request`. It is used as the request
-    passed to the :app:`Pyramid` application root factory.
+    If ``request`` is None, a default request is constructed using
+    :meth:`pyramid.scripting.make_request`. The request passed to the
+    :app:`Pyramid` application root factory to compute the root.
 
     If ``registry`` is not supplied, the last registry loaded from
     :attr:`pyramid.config.global_registries` will be used. If you have
@@ -42,6 +42,17 @@ def get_root2(request=None, registry=None):
     process, you may not want to use the last registry loaded, thus
     you can search the ``global_registries`` and supply the appropriate
     one based on your own criteria.
+
+    The function returns a dictionary composed of ``root``, ``closer``,
+    ``registry``, ``request`` and ``root_factory``.  The ``root`` returned is
+    the application's root resource object.  The ``closer`` returned is a
+    callable (accepting no arguments) that should be called when your
+    scripting application is finished using the root.  ``registry`` is the
+    registry object passed or the last registry loaded into
+    :attr:`pyramid.config.global_registries` if no registry is passed.
+    ``request`` is the request object passed or the constructed request if no
+    request is passed.  ``root_factory`` is the root factory used to
+    construct the root.
     """
     if registry is None:
         registry = getattr(request, 'registry', global_registries.last)
@@ -50,12 +61,13 @@ def get_root2(request=None, registry=None):
     request.registry = registry
     threadlocals = {'registry':registry, 'request':request}
     threadlocal_manager.push(threadlocals)
-    def closer(request=request): # keep request alive via this function default
+    def closer():
         threadlocal_manager.pop()
     root_factory = registry.queryUtility(IRootFactory,
                                          default=DefaultRootFactory)
     root = root_factory(request)
-    return root, closer
+    return {'root':root, 'closer':closer, 'registry':registry,
+            'request':request, 'root_factory':root_factory}
 
 def make_request(path, registry=None):
     """ Return a :meth:`pyramid.request.Request` object anchored at a
diff --git a/pyramid/tests/test_paster.py b/pyramid/tests/test_paster.py
index df55afcb8..7785b006e 100644
--- a/pyramid/tests/test_paster.py
+++ b/pyramid/tests/test_paster.py
@@ -937,7 +937,7 @@ class TestBootstrap(unittest.TestCase):
     def setUp(self):
         import pyramid.paster
         self.original_get_app = pyramid.paster.get_app
-        self.original_getroot2 = pyramid.paster.get_root2
+        self.original_prepare = pyramid.paster.prepare
         self.app = app = DummyApp()
         self.root = root = Dummy()
 
@@ -948,17 +948,17 @@ class TestBootstrap(unittest.TestCase):
                 return app
         self.get_app = pyramid.paster.get_app = DummyGetApp()
 
-        class DummyGetRoot2(object):
+        class DummyPrepare(object):
             def __call__(self, *a, **kw):
                 self.a = a
                 self.kw = kw
-                return (root, lambda: None)
-        self.getroot = pyramid.paster.get_root2 = DummyGetRoot2()
+                return {'root':root, 'closer':lambda: None}
+        self.getroot = pyramid.paster.prepare = DummyPrepare()
 
     def tearDown(self):
         import pyramid.paster
         pyramid.paster.get_app = self.original_get_app
-        pyramid.paster.get_root2 = self.original_getroot2
+        pyramid.paster.prepare = self.original_prepare
 
     def test_it_request_with_registry(self):
         request = DummyRequest({})
diff --git a/pyramid/tests/test_scripting.py b/pyramid/tests/test_scripting.py
index 50dbaae85..ccc6656df 100644
--- a/pyramid/tests/test_scripting.py
+++ b/pyramid/tests/test_scripting.py
@@ -1,6 +1,6 @@
 import unittest
 
-class TestGetRoot(unittest.TestCase):
+class Test_get_root(unittest.TestCase):
     def _callFUT(self, app, request=None):
         from pyramid.scripting import get_root
         return get_root(app, request)
@@ -35,10 +35,10 @@ class TestGetRoot(unittest.TestCase):
         pushed = app.threadlocal_manager.pushed[0]
         self.assertEqual(pushed['request'].environ['path'], '/')
 
-class TestGetRoot2(unittest.TestCase):
+class Test_prepare(unittest.TestCase):
     def _callFUT(self, request=None, registry=None):
-        from pyramid.scripting import get_root2
-        return get_root2(request, registry)
+        from pyramid.scripting import prepare
+        return prepare(request, registry)
 
     def _makeRegistry(self):
         return DummyRegistry(DummyFactory)
@@ -48,39 +48,42 @@ class TestGetRoot2(unittest.TestCase):
         self.manager = manager
         self.default = manager.get()
 
-    def tearDown(self):
-        self.assertEqual(self.default, self.manager.get())
-
     def test_it_norequest(self):
         registry = self._makeRegistry()
-        root, closer = self._callFUT(registry=registry)
+        info = self._callFUT(registry=registry)
+        root, closer = info['root'], info['closer']
         pushed = self.manager.get()
         self.assertEqual(pushed['registry'], registry)
         self.assertEqual(pushed['request'].registry, registry)
         self.assertEqual(root.a, (pushed['request'],))
         closer()
+        self.assertEqual(self.default, self.manager.get())
 
     def test_it_withrequest(self):
         request = DummyRequest({})
         registry = request.registry = self._makeRegistry()
-        root, closer = self._callFUT(request)
+        info = self._callFUT(request=request)
+        root, closer = info['root'], info['closer']
         pushed = self.manager.get()
         self.assertEqual(pushed['request'], request)
         self.assertEqual(pushed['registry'], registry)
         self.assertEqual(pushed['request'].registry, registry)
         self.assertEqual(root.a, (request,))
         closer()
+        self.assertEqual(self.default, self.manager.get())
 
     def test_it_with_request_and_registry(self):
         request = DummyRequest({})
         registry = request.registry = self._makeRegistry()
-        root, closer = self._callFUT(request, registry)
+        info = self._callFUT(request=request, registry=registry)
+        root, closer = info['root'], info['closer']
         pushed = self.manager.get()
         self.assertEqual(pushed['request'], request)
         self.assertEqual(pushed['registry'], registry)
         self.assertEqual(pushed['request'].registry, registry)
         self.assertEqual(root.a, (request,))
         closer()
+        self.assertEqual(self.default, self.manager.get())
 
 class TestMakeRequest(unittest.TestCase):
     def _callFUT(self, path='/', registry=None):