Merge branch 'feature.pshell' of https://github.com/mmerickel/pyramid into mmerickel-feature.pshell

3 files changed, 74 insertions, 42 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 631412f42..be673c370 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -258,8 +258,9 @@ develop``, you can use an interactive Python shell to examine your
 :app:`Pyramid` project's :term:`resource` and :term:`view` objects from a
 Python prompt.  To do so, use your virtualenv's ``paster pshell`` command.
 
-The first argument to ``pshell`` is the path to your application's ``.ini``
-file.  The second is the ``app`` section name inside the ``.ini`` file which
+The argument to ``pshell`` follows the format ``config_file#section_name``
+where ``config_file`` is the path to your application's ``.ini`` file and
+``section_name`` is the ``app`` section name inside the ``.ini`` file which
 points to *your application* as opposed to any other section within the
 ``.ini`` file.  For example, if your application ``.ini`` file might have a
 ``[app:MyProject]`` section that looks like so:
@@ -280,16 +281,21 @@ name ``MyProject`` as a section name:
 
 .. code-block:: text
 
-   [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject
+   [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini#MyProject
    Python 2.4.5 (#1, Aug 29 2008, 12:27:37)
    [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
-   Type "help" for more information. "root" is the Pyramid app root object,
-   "registry" is the Pyramid registry object.
+
+   Default Variables:
+     app          The WSGI Application
+     root         The root of the default resource tree.
+     registry     The Pyramid registry object.
+     settings     The Pyramid settings object.
+
    >>> root
    <myproject.resources.MyResource object at 0x445270>
    >>> registry
    <Registry myproject>
-   >>> registry.settings['debug_notfound']
+   >>> settings['debug_notfound']
    False
    >>> from myproject.views import my_view
    >>> from pyramid.request import Request
@@ -297,31 +303,16 @@ name ``MyProject`` as a section name:
    >>> my_view(r)
    {'project': 'myproject'}
 
-Two names are made available to the pshell user as globals: ``root`` and
-``registry``.  ``root`` is the the object returned by the default :term:`root
-factory` in your application.  ``registry`` is the :term:`application
-registry` object associated with your project's application (often accessed
-within view code as ``request.registry``).
-
-If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ installed in
-the interpreter you use to invoke the ``paster`` command, the ``pshell``
-command will use an IPython interactive shell instead of a standard Python
-interpreter shell.  If you don't want this to happen, even if you have
-IPython installed, you can pass the ``--disable-ipython`` flag to the
-``pshell`` command to use a standard Python interpreter shell
-unconditionally.
-
-.. code-block:: text
-
-   [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \
-                                development.ini MyProject
+The WSGI application that is loaded will be available in the shell as the
+``app`` global. Also, if the application that is loaded is the
+:app:`Pyramid` app with no surrounding middleware, the ``root`` object
+returned by the default :term:`root factory`, ``registry``, and ``settings``
+will be available.
 
-You should always use a section name argument that refers to the actual
-``app`` section within the Paste configuration file that points at your
-:app:`Pyramid` application *without any middleware wrapping*.  In particular,
-a section name is inappropriate as the second argument to ``pshell`` if the
-configuration section it names is a ``pipeline`` rather than an ``app``.  For
-example, if you have the following ``.ini`` file content:
+The interactive shell will not be able to load some of the globals like
+``root``, ``registry`` and ``settings`` if the section name specified when
+loading ``pshell`` is not referencing your :app:`Pyramid` application directly.
+For example, if you have the following ``.ini`` file content:
 
 .. code-block:: ini
    :linenos:
@@ -341,12 +332,51 @@ example, if you have the following ``.ini`` file content:
 
 Use ``MyProject`` instead of ``main`` as the section name argument to
 ``pshell`` against the above ``.ini`` file (e.g. ``paster pshell
-development.ini MyProject``).  If you use ``main`` instead, an error will
-occur.  Use the most specific reference to your application within the
-``.ini`` file possible as the section name argument.
+development.ini#MyProject``).
 
 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
 
+Extending the Shell
+~~~~~~~~~~~~~~~~~~~
+
+It is sometimes 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 shell.
+
+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.
+
+.. code-block:: ini
+   :linenos:
+
+   [pshell]
+   m = myapp.models
+   session = myapp.models.DBSession
+   t = transaction
+
+When this INI file is loaded, the extra variables ``m``, ``session`` and
+``t`` will be available for use immediately. This happens regardless of
+whether the ``registry`` and other special variables are loaded.
+
+IPython
+~~~~~~~
+
+If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ installed in
+the interpreter you use to invoke the ``paster`` command, the ``pshell``
+command will use an IPython interactive shell instead of a standard Python
+interpreter shell.  If you don't want this to happen, even if you have
+IPython installed, you can pass the ``--disable-ipython`` flag to the
+``pshell`` command to use a standard Python interpreter shell
+unconditionally.
+
+.. code-block:: text
+
+   [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \
+                                development.ini#MyProject
+
 .. index::
    single: running an application
    single: paster serve
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index f94ed3ba8..51a840b8d 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -1084,16 +1084,17 @@ Displaying All Application Routes
 You can use the ``paster proutes`` command in a terminal window to print a
 summary of routes related to your application.  Much like the ``paster
 pshell`` command (see :ref:`interactive_shell`), the ``paster proutes``
-command accepts two arguments.  The first argument to ``proutes`` is the path
-to your application's ``.ini`` file.  The second is the ``app`` section name
-inside the ``.ini`` file which points to your application.
+command accepts one argument with the format ``config_file#section_name``.
+The ``config_file`` is the path to your application's ``.ini`` file,
+and ``section_name`` is the ``app`` section name inside the ``.ini`` file
+which points to your application.
 
 For example:
 
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko MyProject]$ ../bin/paster proutes development.ini MyProject
+   [chrism@thinko MyProject]$ ../bin/paster proutes development.ini#MyProject
    Name            Pattern                        View
    ----            -------                        ----                     
    home            /                              <function my_view>
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index ec42446ff..67ac39259 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -795,10 +795,11 @@ For a big application with several views, it can be hard to keep the view
 configuration details in your head, even if you defined all the views
 yourself. You can use the ``paster pviews`` command in a terminal window to
 print a summary of matching routes and views for a given URL in your
-application. The ``paster pviews`` command accepts three arguments. The
-first argument to ``pviews`` is the path to your application's ``.ini`` file.
-The second is the ``app`` section name inside the ``.ini`` file which points
-to your application. The third is the URL to test for matching views.
+application. The ``paster pviews`` command accepts two arguments. The
+first argument to ``pviews`` is the path to your application's ``.ini`` file
+and section name inside the ``.ini`` file which points to your application.
+This should be of the format ``config_file#section_name``. The second argument
+is the URL to test for matching views.
 
 Here is an example for a simple view configuration using :term:`traversal`:
 
@@ -829,7 +830,7 @@ A more complex configuration might generate something like this:
 .. code-block:: text
    :linenos:
 
-   $ ../bin/paster pviews development.ini shootout /about
+   $ ../bin/paster pviews development.ini#shootout /about
 
    URL = /about