Merge pull request #3119 from stevepiercy/docs-context-manager

Update docs to use a Configurator context manager

19 files changed, 97 insertions, 95 deletions

diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index 2504f32aa..c0a1f8336 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -1529,20 +1529,20 @@ inlined comments take into account what we've discussed in the
 .. code-block:: python
    :linenos:
 
-   from pyramid.response import Response # explicit response, no thread local
-   from wsgiref.simple_server import make_server # explicitly WSGI
+   from wsgiref.simple_server import make_server  # explicitly WSGI
+   from pyramid.config import Configurator  # to configure app registry
+   from pyramid.response import Response  # explicit response, no threadlocal
 
-   def hello_world(request):  # accepts a request; no request thread local reqd
+   def hello_world(request):  # accept a request; no request threadlocal reqd
        # explicit response object means no response threadlocal
        return Response('Hello world!')
 
    if __name__ == '__main__':
-       from pyramid.config import Configurator
-       config = Configurator()       # no global application object
-       config.add_view(hello_world)  # explicit non-decorator registration
-       app = config.make_wsgi_app()  # explicitly WSGI
+       with Configurator() as config:    # no global application object
+           config.add_view(hello_world)  # explicit non-decorator registration
+           app = config.make_wsgi_app()  # explicitly WSGI
        server = make_server('0.0.0.0', 8080, app)
-       server.serve_forever()        # explicitly WSGI
+       server.serve_forever()            # explicitly WSGI
 
 
 Pyramid doesn't offer pluggable apps
@@ -1634,7 +1634,7 @@ Let's take this criticism point-by-point.
 Too Complex
 +++++++++++
 
-If you can understand this hello world program, you can use Pyramid:
+If you can understand this "hello world" program, you can use Pyramid:
 
 .. code-block:: python
    :linenos:
@@ -1647,9 +1647,9 @@ If you can understand this hello world program, you can use Pyramid:
        return Response('Hello world!')
 
    if __name__ == '__main__':
-       config = Configurator()
-       config.add_view(hello_world)
-       app = config.make_wsgi_app()
+       with Configurator() as config:
+           config.add_view(hello_world)
+           app = config.make_wsgi_app()
        server = make_server('0.0.0.0', 8080, app)
        server.serve_forever()
 
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 54a9f8350..88be7f51d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1203,3 +1203,6 @@ Glossary
    side effect
       A statement or function has a side effect when it changes a value outside its own scope.
       Put another way, if one can observe the change made by a function from outside that function, it has a side effect.
+
+   context manager
+      A context manager is an object that defines the runtime context to be established when executing a :ref:`with <python:with>` statement in Python. The context manager handles the entry into, and the exit from, the desired runtime context for the execution of the block of code. Context managers are normally invoked using the ``with`` statement, but can also be used by directly invoking their methods. Pyramid adds context managers for :class:`pyramid.config.Configurator`, :meth:`pyramid.interfaces.IRouter.request_context`, :func:`pyramid.paster.bootstrap`, :func:`pyramid.scripting.prepare`, and :func:`pyramid.testing.testConfig`.
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index ee54e3acd..bbf01240e 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -47,9 +47,9 @@ configured imperatively:
        return Response('Hello world!')
 
    if __name__ == '__main__':
-       config = Configurator()
-       config.add_view(hello_world)
-       app = config.make_wsgi_app()
+       with Configurator() as config:
+           config.add_view(hello_world)
+           app = config.make_wsgi_app()
        server = make_server('0.0.0.0', 8080, app)
        server.serve_forever()
 
@@ -116,9 +116,9 @@ and its subpackages.  For example:
        return Response('Hello')
 
    if __name__ == '__main__':
-       config = Configurator()
-       config.scan()
-       app = config.make_wsgi_app()
+       with Configurator() as config:
+           config.scan()
+           app = config.make_wsgi_app()
        server = make_server('0.0.0.0', 8080, app)
        server.serve_forever()
 
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 63142edac..db55f2f9c 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -60,7 +60,7 @@ Imports
 The above ``helloworld.py`` script uses the following set of import statements:
 
 .. literalinclude:: helloworld.py
-   :linenos:
+   :lineno-match:
    :lines: 1-3
 
 The script imports the :class:`~pyramid.config.Configurator` class from the
@@ -83,7 +83,7 @@ The above script, beneath its set of imports, defines a function named
 ``hello_world``.
 
 .. literalinclude:: helloworld.py
-   :linenos:
+   :lineno-match:
    :pyobject: hello_world
 
 The function accepts a single argument (``request``) and it returns an instance
@@ -125,7 +125,7 @@ imports and function definitions, placed within the confines of an ``if``
 statement:
 
 .. literalinclude:: helloworld.py
-   :linenos:
+   :lineno-match:
    :lines: 9-15
 
 Let's break this down piece by piece.
@@ -134,7 +134,7 @@ Configurator Construction
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. literalinclude:: helloworld.py
-   :linenos:
+   :lineno-match:
    :lines: 9-10
 
 The ``if __name__ == '__main__':`` line in the code sample above represents a
@@ -153,8 +153,8 @@ code within the ``if`` statement to execute if this module is imported from
 another; the code within the ``if`` block should only be run during a direct
 script execution.
 
-The ``config = Configurator()`` line above creates an instance of the
-:class:`~pyramid.config.Configurator` class.  The resulting ``config`` object
+The ``with Configurator() as config:`` line above creates an instance of the
+:class:`~pyramid.config.Configurator` class using a :term:`context manager`.  The resulting ``config`` object
 represents an API which the script uses to configure this particular
 :app:`Pyramid` application.  Methods called on the Configurator will cause
 registrations to be made in an :term:`application registry` associated with the
@@ -166,7 +166,7 @@ Adding Configuration
 ~~~~~~~~~~~~~~~~~~~~
 
 .. literalinclude:: helloworld.py
-   :linenos:
+   :lineno-match:
    :lines: 11-12
 
 The first line above calls the :meth:`pyramid.config.Configurator.add_route`
@@ -185,7 +185,7 @@ WSGI Application Creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. literalinclude:: helloworld.py
-   :linenos:
+   :lineno-match:
    :lines: 13
 
 After configuring views and ending configuration, the script creates a WSGI
@@ -212,7 +212,7 @@ WSGI Application Serving
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. literalinclude:: helloworld.py
-   :linenos:
+   :lineno-match:
    :lines: 14-15
 
 Finally, we actually serve the application to requestors by starting up a WSGI
diff --git a/docs/narr/helloworld.py b/docs/narr/helloworld.py
index c01329af9..29ed8e6f2 100644
--- a/docs/narr/helloworld.py
+++ b/docs/narr/helloworld.py
@@ -7,10 +7,9 @@ def hello_world(request):
     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()
-   
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index f124ac562..594badcb6 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -158,7 +158,7 @@ Test setup using a context manager
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An alternative style of setting up a test configuration is to use the ``with``
-statement and :func:`pyramid.testing.testConfig` to create a context manager.
+statement and :func:`pyramid.testing.testConfig` to create a :term:`context manager`.
 The context manager will call :func:`pyramid.testing.setUp` before the code
 under test and :func:`pyramid.testing.tearDown` afterwards.
 
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index f95bff4df..c6e696ae3 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -90,7 +90,7 @@ explanation:
 #. *Line 10*. ``if __name__ == '__main__':`` is Python's way of saying "Start
    here when running from the command line".
 
-#. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect :term:`view`
+#. *Lines 11-13*. Use Pyramid's :term:`configurator` in a :term:`context manager` to connect :term:`view`
    code to a particular URL :term:`route`.
 
 #. *Lines 6-7*. Implement the view code that generates the :term:`response`.
diff --git a/docs/quick_tour/hello_world/app.py b/docs/quick_tour/hello_world/app.py
index 75d22ac96..dc6f32310 100644
--- a/docs/quick_tour/hello_world/app.py
+++ b/docs/quick_tour/hello_world/app.py
@@ -8,9 +8,9 @@ def hello_world(request):
 
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/')
-    config.add_view(hello_world, route_name='hello')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/')
+        config.add_view(hello_world, route_name='hello')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tour/jinja2/app.py b/docs/quick_tour/jinja2/app.py
index b7632807b..2683e0451 100644
--- a/docs/quick_tour/jinja2/app.py
+++ b/docs/quick_tour/jinja2/app.py
@@ -2,10 +2,10 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/howdy/{name}')
-    config.include('pyramid_jinja2')
-    config.scan('views')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/howdy/{name}')
+        config.include('pyramid_jinja2')
+        config.scan('views')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tour/json/app.py b/docs/quick_tour/json/app.py
index 40faddd00..a007dee14 100644
--- a/docs/quick_tour/json/app.py
+++ b/docs/quick_tour/json/app.py
@@ -2,12 +2,12 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/howdy/{name}')
-    config.add_route('hello_json', 'hello.json')
-    config.add_static_view(name='static', path='static')
-    config.include('pyramid_jinja2')
-    config.scan('views')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/howdy/{name}')
+        config.add_route('hello_json', 'hello.json')
+        config.add_static_view(name='static', path='static')
+        config.include('pyramid_jinja2')
+        config.scan('views')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tour/requests/app.py b/docs/quick_tour/requests/app.py
index f55264cff..58e8823cc 100644
--- a/docs/quick_tour/requests/app.py
+++ b/docs/quick_tour/requests/app.py
@@ -16,9 +16,9 @@ def hello_world(request):
 
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/')
-    config.add_view(hello_world, route_name='hello')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/')
+        config.add_view(hello_world, route_name='hello')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tour/routing/app.py b/docs/quick_tour/routing/app.py
index 12b547bfe..75c18b7d1 100644
--- a/docs/quick_tour/routing/app.py
+++ b/docs/quick_tour/routing/app.py
@@ -2,9 +2,9 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/howdy/{first}/{last}')
-    config.scan('views')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/howdy/{first}/{last}')
+        config.scan('views')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
-    server.serve_forever()
\ No newline at end of file
+    server.serve_forever()
diff --git a/docs/quick_tour/static_assets/app.py b/docs/quick_tour/static_assets/app.py
index 1849c0a5a..c31fc797c 100644
--- a/docs/quick_tour/static_assets/app.py
+++ b/docs/quick_tour/static_assets/app.py
@@ -2,11 +2,11 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/howdy/{name}')
-    config.add_static_view(name='static', path='static')
-    config.include('pyramid_jinja2')
-    config.scan('views')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/howdy/{name}')
+        config.add_static_view(name='static', path='static')
+        config.include('pyramid_jinja2')
+        config.scan('views')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tour/templating/app.py b/docs/quick_tour/templating/app.py
index 52b7faf55..8db99df91 100644
--- a/docs/quick_tour/templating/app.py
+++ b/docs/quick_tour/templating/app.py
@@ -2,10 +2,10 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/howdy/{name}')
-    config.include('pyramid_chameleon')
-    config.scan('views')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/howdy/{name}')
+        config.include('pyramid_chameleon')
+        config.scan('views')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tour/view_classes/app.py b/docs/quick_tour/view_classes/app.py
index 40faddd00..a007dee14 100644
--- a/docs/quick_tour/view_classes/app.py
+++ b/docs/quick_tour/view_classes/app.py
@@ -2,12 +2,12 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/howdy/{name}')
-    config.add_route('hello_json', 'hello.json')
-    config.add_static_view(name='static', path='static')
-    config.include('pyramid_jinja2')
-    config.scan('views')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/howdy/{name}')
+        config.add_route('hello_json', 'hello.json')
+        config.add_static_view(name='static', path='static')
+        config.include('pyramid_jinja2')
+        config.scan('views')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tour/views/app.py b/docs/quick_tour/views/app.py
index e8df6eff2..12d9d25b5 100644
--- a/docs/quick_tour/views/app.py
+++ b/docs/quick_tour/views/app.py
@@ -2,12 +2,12 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('home', '/')
-    config.add_route('hello', '/howdy')
-    config.add_route('redirect', '/goto')
-    config.add_route('exception', '/problem')
-    config.scan('views')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('home', '/')
+        config.add_route('hello', '/howdy')
+        config.add_route('redirect', '/goto')
+        config.add_route('exception', '/problem')
+        config.scan('views')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst
index 2f2515fcd..94242f1f4 100644
--- a/docs/quick_tutorial/hello_world.rst
+++ b/docs/quick_tutorial/hello_world.rst
@@ -75,7 +75,7 @@ explanation:
    "Start here when running from the command line", rather than when this
    module is imported.
 
-#. *Lines 12-14*. Use Pyramid's :term:`configurator` to connect :term:`view`
+#. *Lines 12-14*. Use Pyramid's :term:`configurator` in a :term:`context manager` to connect :term:`view`
    code to a particular URL :term:`route`.
 
 #. *Lines 6-8*. Implement the view code that generates the :term:`response`.
diff --git a/docs/quick_tutorial/hello_world/app.py b/docs/quick_tutorial/hello_world/app.py
index 0a95f9ad3..d0351e251 100644
--- a/docs/quick_tutorial/hello_world/app.py
+++ b/docs/quick_tutorial/hello_world/app.py
@@ -9,9 +9,9 @@ def hello_world(request):
 
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/')
-    config.add_view(hello_world, route_name='hello')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/')
+        config.add_view(hello_world, route_name='hello')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
     server.serve_forever()
diff --git a/docs/quick_tutorial/package/tutorial/app.py b/docs/quick_tutorial/package/tutorial/app.py
index 210075023..d0351e251 100644
--- a/docs/quick_tutorial/package/tutorial/app.py
+++ b/docs/quick_tutorial/package/tutorial/app.py
@@ -4,14 +4,14 @@ from pyramid.response import Response
 
 
 def hello_world(request):
-    print ('Incoming request')
+    print('Incoming request')
     return Response('<body><h1>Hello World!</h1></body>')
 
 
 if __name__ == '__main__':
-    config = Configurator()
-    config.add_route('hello', '/')
-    config.add_view(hello_world, route_name='hello')
-    app = config.make_wsgi_app()
+    with Configurator() as config:
+        config.add_route('hello', '/')
+        config.add_view(hello_world, route_name='hello')
+        app = config.make_wsgi_app()
     server = make_server('0.0.0.0', 6543, app)
-    server.serve_forever()
\ No newline at end of file
+    server.serve_forever()