diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/commandline.rst | 72 |
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 |