add some docs for pshell setup with an example of handling transactions

1 files changed, 38 insertions, 21 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 98663cca6..d0c1e6edd 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -196,51 +196,61 @@ Extending the Shell
 It is convenient when using the interactive shell often to have some variables
 significant to your application already loaded as globals when you start the
 ``pshell``. To facilitate this, ``pshell`` will look for a special ``[pshell]``
-section in your INI file and expose the subsequent key/value pairs to the
+section in your ``.ini`` file and expose the subsequent key/value pairs to the
 shell.  Each key is a variable name that will be global within the pshell
 session; each value is a :term:`dotted Python name`. If specified, the special
 key ``setup`` should be a :term:`dotted Python name` pointing to a callable
 that accepts the dictionary of globals that will be loaded into the shell. This
 allows for some custom initializing code to be executed each time the
 ``pshell`` is run. The ``setup`` callable can also be specified from the
-commandline using the ``--setup`` option which will override the key in the INI
+commandline using the ``--setup`` option which will override the key in the ``.ini``
 file.
 
 For example, you want to expose your model to the shell along with the database
 session so that you can mutate the model on an actual database. Here, we'll
-assume your model is stored in the ``myapp.models`` package.
+assume your model is stored in the ``myapp.models`` package and that you're
+using ``pyramid_tm`` to configure a transaction manager on the request as
+``request.tm``.
 
 .. code-block:: ini
    :linenos:
 
    [pshell]
    setup = myapp.lib.pshell.setup
-   m = myapp.models
-   session = myapp.models.DBSession
-   t = transaction
+   models = myapp.models
 
-By defining the ``setup`` callable, we will create the module
-``myapp.lib.pshell`` containing a callable named ``setup`` that will receive
-the global environment before it is exposed to the shell. Here we mutate the
-environment's request as well as add a new value containing a WebTest version
-of the application to which we can easily submit requests.
+By defining the ``setup`` callable, we will create the module ``myapp.lib.pshell`` containing a callable named ``setup`` that will receive the global environment before it is exposed to the shell. Here we mutate the environment's request as well as add a new value containing a WebTest version of the application to which we can easily submit requests. The ``setup`` callable can also be a generator which can wrap the entire shell lifecycle, executing code when the shell exits.
 
 .. code-block:: python
     :linenos:
 
     # myapp/lib/pshell.py
+    from contextlib import suppress
+    from transaction.interfaces import NoTransaction
     from webtest import TestApp
 
     def setup(env):
-        env['request'].host = 'www.example.com'
-        env['request'].scheme = 'https'
+        request = env['request']
+        request.host = 'www.example.com'
+        request.scheme = 'https'
+
         env['testapp'] = TestApp(env['app'])
 
-When this INI file is loaded, the extra variables ``m``, ``session`` and ``t``
-will be available for use immediately. Since a ``setup`` callable was also
-specified, it is executed and a new variable ``testapp`` is exposed, and the
-request is configured to generate urls from the host
-``http://www.example.com``. For example:
+        # start a transaction which can be used in the shell
+        request.tm.begin()
+
+        # if using the alchemy cookiecutter, the dbsession is connected
+        # to the transaction manager above
+        env['tm'] = request.tm
+        env['dbsession'] = request.dbsession
+        try:
+            yield
+
+        finally:
+            with suppress(NoTransaction):
+                request.tm.abort()
+
+When this ``.ini`` file is loaded, the extra variable ``models`` will be available for use immediately. Since a ``setup`` callable was also specified, it is executed and new variables ``testapp``, ``tm``, and ``dbsession`` are exposed, and the request is configured to generate URLs from the host ``http://www.example.com``. For example:
 
 .. code-block:: text
 
@@ -258,14 +268,21 @@ request is configured to generate urls from the host
       testapp      <webtest.TestApp object at ...>
 
     Custom Variables:
-      m            myapp.models
-      session      myapp.models.DBSession
-      t            transaction
+      dbsession
+      model        myapp.models
+      tm
 
     >>> testapp.get('/')
     <200 OK text/html body='<!DOCTYPE...l>\n'/3337>
     >>> request.route_url('home')
     'https://www.example.com/'
+    >>> user = dbsession.query(models.User).get(1)
+    >>> user.name = 'Joe'
+    >>> tm.commit()
+    >>> tm.begin()
+    >>> user = dbsession.query(models.User).get(1)
+    >>> user.name == 'Joe'
+    'Joe'
 
 
 .. _ipython_or_bpython: