Merge pull request #2012 from mmerickel/feature/pshell-list

add pshell --list-shells and default_shell ini options

1 files changed, 43 insertions, 29 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 9db92b669..430641a50 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -107,9 +107,7 @@ found* message.
 
 .. index::
    single: interactive shell
-   single: IPython
    single: pshell
-   single: bpython
 
 .. _interactive_shell:
 
@@ -263,38 +261,40 @@ request is configured to generate urls from the host
     >>> request.route_url('home')
     'https://www.example.com/'
 
-.. index::
-   single: IPython
-   single: bpython
+Alternative Shells
+~~~~~~~~~~~~~~~~~~
 
-.. _ipython_or_bpython:
+The ``pshell`` command can be easily extended with alternate REPLs if the
+default python REPL is not satisfactory. Assuming you have a binding
+installed such as ``pyramid_ipython`` it will normally be auto-selected and
+used. You may also specifically invoke your choice with the ``-p choice`` or
+``--python-shell choice`` option.
 
-IPython or bpython
-~~~~~~~~~~~~~~~~~~
+.. code-block:: text
+
+   $ $VENV/bin/pshell -p ipython development.ini#MyProject
 
-If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ and/or `bpython
-<http://bpython-interpreter.org/>`_ in the interpreter you use to invoke the
-``pshell`` command, ``pshell`` will autodiscover and use the first one found,
-in this order: IPython, bpython, standard Python interpreter. However you could
-specifically invoke your choice with the ``-p choice`` or ``--python-shell
-choice`` option.
+You may use the ``--list-shells`` option to see the available shells.
 
 .. code-block:: text
 
-   $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject
+   $ $VENV/bin/pshell --list-shells
+   Available shells:
+     bpython
+     ipython
+     python
 
-Alternative Shells
-~~~~~~~~~~~~~~~~~~
 If you want to use a shell that isn't supported out of the box, you can
 introduce a new shell by registering an entry point in your setup.py:
 
 .. code-block:: python
 
     setup(
-        entry_points = """\
-            [pyramid.pshell]
-            myshell=my_app:ptpython_shell_factory
-        """
+        entry_points={
+            'pyramid.pshell_runner': [
+              'myshell=my_app:ptpython_shell_factory',
+            ],
+        },
     )
 
 And then your shell factory should return a function that accepts two
@@ -302,16 +302,30 @@ arguments, ``env`` and ``help``, which would look like this:
 
 .. code-block:: python
 
-    def ptpython_shell_factory():
-        from ptpython.repl import embed
-        def PTPShell(banner, **kwargs):
-            print(banner)
-            return embed(**kwargs)
+    from ptpython.repl import embed
 
-        def shell(env, help):
-            PTPShell(banner=help, locals=env)
+    def ptpython_shell_runner(env, help):
+        print(help)
+        return embed(locals=env)
 
-        return shell
+.. versionchanged:: 1.6
+   User-defined shells may be registered using entry points. Prior to this
+   the only supported shells were ``ipython``, ``bpython`` and ``python``.
+
+   ``ipython`` and ``bpython`` have been moved into their respective
+   packages ``pyramid_ipython`` and ``pyramid_bpython``.
+
+Setting a Default Shell
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You may use the ``default_shell`` option in your ``[pshell]`` ini section to
+specify a list of preferred shells.
+
+.. code-block:: ini
+   :linenos:
+
+   [pshell]
+   default_shell = ptpython ipython bpython
 
 .. versionadded:: 1.6