update doxs to use a Configurator context manager

Steve Piercy

2017-07-04 d91e5d4d5d0165a7f7599c84c988b981b5fd0d2d

update doxs to use a Configurator context manager

backport of #3119 to 1.9-branch

- Add term "context manager"
- Link context manager term to glossary
- Update example apps to use config context manager
- Use lineno-match instead of linenos
- Update example apps to use config context manager in Quick Tour
- Add a term for context manager in Quick Tour
- Add a term for context manager in Quick Tutorial

 docs/designdefense.rst

@@ -1529,20 +1529,20 @@
.. 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 @@
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 @@
       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()


 docs/glossary.rst

@@ -1203,3 +1203,6 @@
   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`.

 docs/narr/configuration.rst

@@ -47,9 +47,9 @@
       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 @@
       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()


 docs/narr/firstapp.rst

@@ -60,7 +60,7 @@
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 @@
``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 @@
statement:

.. literalinclude:: helloworld.py
   :linenos:
   :lineno-match:
   :lines: 9-15

Let's break this down piece by piece.
@@ -134,7 +134,7 @@
~~~~~~~~~~~~~~~~~~~~~~~~~

.. 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 @@
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 @@
~~~~~~~~~~~~~~~~~~~~

.. 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 @@
~~~~~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: helloworld.py
   :linenos:
   :lineno-match:
   :lines: 13

After configuring views and ending configuration, the script creates a WSGI
@@ -212,7 +212,7 @@
~~~~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: helloworld.py
   :linenos:
   :lineno-match:
   :lines: 14-15

Finally, we actually serve the application to requestors by starting up a WSGI

 docs/narr/helloworld.py

@@ -7,10 +7,9 @@
    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()
   

 docs/narr/testing.rst

@@ -158,7 +158,7 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.


 docs/quick_tour.rst

@@ -90,7 +90,7 @@
#. *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`.

 docs/quick_tour/hello_world/app.py

@@ -8,9 +8,9 @@


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()

 docs/quick_tour/jinja2/app.py

@@ -2,10 +2,10 @@
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()

 docs/quick_tour/json/app.py

@@ -2,12 +2,12 @@
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()

 docs/quick_tour/requests/app.py

@@ -16,9 +16,9 @@


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()

 docs/quick_tour/routing/app.py

@@ -2,9 +2,9 @@
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()
    server.serve_forever()

 docs/quick_tour/static_assets/app.py

@@ -2,11 +2,11 @@
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()

 docs/quick_tour/templating/app.py

@@ -2,10 +2,10 @@
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()

 docs/quick_tour/view_classes/app.py

@@ -2,12 +2,12 @@
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()

 docs/quick_tour/views/app.py

@@ -2,12 +2,12 @@
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()

 docs/quick_tutorial/hello_world.rst

@@ -75,7 +75,7 @@
   "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`.

 docs/quick_tutorial/hello_world/app.py

@@ -9,9 +9,9 @@


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()

 docs/quick_tutorial/package/tutorial/app.py

@@ -4,14 +4,14 @@


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()
    server.serve_forever()