turn the Configurator into a context manager

fixes #2872

README.rst

@@ -31,10 +31,10 @@ and deployment more fun, more predictable, and more productive.
        return Response('Hello %(name)s!' % request.matchdict)
 
    if __name__ == '__main__':
-       config = Configurator()
-       config.add_route('hello', '/hello/{name}')
-       config.add_view(hello_world, route_name='hello')
-       app = config.make_wsgi_app()
+       with Configurator() as config:
+           config.add_route('hello', '/hello/{name}')
+           config.add_view(hello_world, route_name='hello')
+           app = config.make_wsgi_app()
        server = make_server('0.0.0.0', 8080, app)
        server.serve_forever()
 

pyramid/config/__init__.py

@@ -110,6 +110,19 @@ class Configurator(
     A Configurator is used to configure a :app:`Pyramid`
     :term:`application registry`.
 
+    To enable all application state to be available during configuration,
+    the Configurator may be used as a context manager to automatically handle
+    calling :meth:`pyramid.config.Configurator.begin` and
+    :meth:`pyramid.config.Configurator.end`. Without using one of the
+    following approaches, certain APIs such as :term:`asset spec` resolution
+    may not work as intended.
+
+    .. code-block:: python
+
+        with Configurator() as config:
+            config.add_route('home', '/')
+            app = config.make_wsgi_app()
+
     If the ``registry`` argument is not ``None``, it must
     be an instance of the :class:`pyramid.registry.Registry` class
     representing the registry to configure.  If ``registry`` is ``None``, the
@@ -265,6 +278,11 @@ class Configurator(
     .. versionadded:: 1.6
        The ``root_package`` argument.
        The ``response_factory`` argument.
+
+    .. versionadded:: 1.8
+       The ability to use the configurator as a context manager with the
+       ``with``-statement to make threadlocal configuration available for
+       further configuration.
     """
     manager = manager # for testing injection
     venusian = venusian # for testing injection
@@ -903,6 +921,13 @@ def end(self):
         """
         return self.manager.pop()
 
+    def __enter__(self):
+        self.begin()
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        self.end()
+
     # this is *not* an action method (uses caller_package)
     def scan(self, package=None, categories=None, onerror=None, ignore=None,
              **kw):

pyramid/tests/test_config/test_init.py

@@ -100,6 +100,18 @@ def test_end(self):
         self.assertEqual(manager.pushed, None)
         self.assertEqual(manager.popped, True)
 
+    def test_context_manager(self):
+        from pyramid.config import Configurator
+        config = Configurator()
+        manager = DummyThreadLocalManager()
+        config.manager = manager
+        with config as ctx:
+            self.assertEqual(config, ctx)
+            self.assertEqual(manager.pushed,
+                             {'registry': config.registry, 'request': None})
+            self.assertFalse(manager.popped)
+        self.assertTrue(manager.popped)
+
     def test_ctor_with_package_registry(self):
         import sys
         from pyramid.config import Configurator