Reworked pyramid.scripting. Modified docs and made make_request private.

Renamed make_request to _make_request to make clear that it's not a
private API.

p.scripting.prepare now raises an exception if no valid pyramid app can
be found to avoid obscure errors later on.

3 files changed, 45 insertions, 35 deletions

diff --git a/docs/api/scripting.rst b/docs/api/scripting.rst
index 79136a98b..51bd3c7a0 100644
--- a/docs/api/scripting.rst
+++ b/docs/api/scripting.rst
@@ -9,5 +9,3 @@
 
   .. autofunction:: prepare
 
-  .. autofunction:: make_request
-
diff --git a/pyramid/scripting.py b/pyramid/scripting.py
index c04915d3a..47178c22e 100644
--- a/pyramid/scripting.py
+++ b/pyramid/scripting.py
@@ -1,4 +1,5 @@
 from pyramid.config import global_registries
+from pyramid.exceptions import ConfigurationError
 from pyramid.request import Request
 from pyramid.interfaces import IRequestFactory
 from pyramid.interfaces import IRootFactory
@@ -12,13 +13,14 @@ def get_root(app, request=None):
     is a callable (accepting no arguments) that should be called when
     your scripting application is finished using the root.
 
-    If ``request`` is not None, it is used as the request passed to the
-    :app:`Pyramid` application root factory. A request is constructed
-    using :meth:`pyramid.scripting.make_request` and passed to the root
-    factory if ``request`` is None."""
+    ``request`` is passed to the :app:`Pyramid` application root
+    factory to compute the root. If ``request`` is None, a default
+    will be constructed using the registry's :term:`Request Factory`
+    via the :meth:`pyramid.interfaces.IRequestFactory.blank` method.
+    """
     registry = app.registry
     if request is None:
-        request = make_request('/', registry)
+        request = _make_request('/', registry)
     threadlocals = {'registry':registry, 'request':request}
     app.threadlocal_manager.push(threadlocals)
     def closer(request=request): # keep request alive via this function default
@@ -27,37 +29,43 @@ def get_root(app, request=None):
     return root, closer
 
 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.
+    """ 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 request is constructed using
-    :meth:`pyramid.scripting.make_request`. The request passed to the
-    :app:`Pyramid` application root factory to compute the root.
+    ``request`` is passed to the :app:`Pyramid` application root
+    factory to compute the root. If ``request`` is None, a default
+    will be constructed using the registry's :term:`Request Factory`
+    via the :meth:`pyramid.interfaces.IRequestFactory.blank` method.
 
     If ``registry`` is not supplied, the last registry loaded from
-    :attr:`pyramid.config.global_registries` will be used. If you have
-    loaded more than one :app:`Pyramid` application in the current
-    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.
+    :attr:`pyramid.config.global_registries` will be used. If you
+    have loaded more than one :app:`Pyramid` application in the
+    current 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
+    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.
+    ``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)
+    if registry is None:
+        raise ConfigurationError('No valid Pyramid applications could be '
+                                 'found, make sure one has been created '
+                                 'before trying to activate it.')
     if request is None:
-        request = make_request('/', registry)
+        request = _make_request('/', registry)
     request.registry = registry
     threadlocals = {'registry':registry, 'request':request}
     threadlocal_manager.push(threadlocals)
@@ -69,14 +77,14 @@ def prepare(request=None, registry=None):
     return {'root':root, 'closer':closer, 'registry':registry,
             'request':request, 'root_factory':root_factory}
 
-def make_request(path, registry=None):
+def _make_request(path, registry=None):
     """ Return a :meth:`pyramid.request.Request` object anchored at a
     given path. The object returned will be generated from the supplied
     registry's :term:`Request Factory` using the
     :meth:`pyramid.interfaces.IRequestFactory.blank` method.
 
-    This request object can be passed to
-    :meth:`pyramid.scripting.get_root` to initialize an application in
+    This request object can be passed to :meth:`pyramid.scripting.get_root`
+    or :meth:`pyramid.scripting.prepare` to initialize an application in
     preparation for executing a script with a proper environment setup.
     URLs can then be generated with the object, as well as rendering
     templates.
diff --git a/pyramid/tests/test_scripting.py b/pyramid/tests/test_scripting.py
index ccc6656df..f01e744b8 100644
--- a/pyramid/tests/test_scripting.py
+++ b/pyramid/tests/test_scripting.py
@@ -48,6 +48,10 @@ class Test_prepare(unittest.TestCase):
         self.manager = manager
         self.default = manager.get()
 
+    def test_it_no_valid_apps(self):
+        from pyramid.exceptions import ConfigurationError
+        self.assertRaises(ConfigurationError, self._callFUT)
+
     def test_it_norequest(self):
         registry = self._makeRegistry()
         info = self._callFUT(registry=registry)
@@ -85,10 +89,10 @@ class Test_prepare(unittest.TestCase):
         closer()
         self.assertEqual(self.default, self.manager.get())
 
-class TestMakeRequest(unittest.TestCase):
+class Test__make_request(unittest.TestCase):
     def _callFUT(self, path='/', registry=None):
-        from pyramid.scripting import make_request
-        return make_request(path, registry)
+        from pyramid.scripting import _make_request
+        return _make_request(path, registry)
 
     def test_it_with_registry(self):
         request = self._callFUT('/', dummy_registry)