From 208e7b5e363b07476797d9f754962982c686e907 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 19 Oct 2015 23:44:17 -0500 Subject: add pshell --list and default_shell ini options --- docs/narr/commandline.rst | 59 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 9db92b669..c3791adf2 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -269,32 +269,39 @@ request is configured to generate urls from the host .. _ipython_or_bpython: -IPython or bpython +Alternative Shells ~~~~~~~~~~~~~~~~~~ - If you have `IPython `_ and/or `bpython `_ 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. +``pshell`` command, ``pshell`` will autodiscover and use the first one found. +However you could specifically invoke your choice with the ``-p choice`` or +``--python-shell choice`` option. .. code-block:: text - $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject + $ $VENV/bin/pshell -p ipython development.ini#MyProject + +You may use the ``--list-shells`` option to see the available shells. + +.. code-block:: text + + $ $VENV/bin/pshell --list-shells + Available shells: + bpython [not available] + 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': [ + 'myshell=my_app:ptpython_shell_factory', + ], + }, ) And then your shell factory should return a function that accepts two @@ -303,7 +310,12 @@ arguments, ``env`` and ``help``, which would look like this: .. code-block:: python def ptpython_shell_factory(): - from ptpython.repl import embed + try: + from ptpython.repl import embed + except ImportError: + # ptpython is not installed + return None + def PTPShell(banner, **kwargs): print(banner) return embed(**kwargs) @@ -313,6 +325,25 @@ arguments, ``env`` and ``help``, which would look like this: return shell +If the factory returns ``None`` then it is assumed that the shell is not +supported. + +.. versionchanged:: 1.6 + User-defined shells may be registered using entry points. Prior to this + the only supported shells were ``ipython``, ``bpython`` and ``python``. + +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 .. index:: -- cgit v1.2.3 From b7350ee78ad4101ea4112741ab26ce583b620ea7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 21 Oct 2015 01:32:48 -0500 Subject: remove ipython and bpython from core --- docs/narr/commandline.rst | 43 +++++++++++++------------------------------ 1 file changed, 13 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index c3791adf2..d466bed44 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,18 +261,13 @@ request is configured to generate urls from the host >>> request.route_url('home') 'https://www.example.com/' -.. index:: - single: IPython - single: bpython - -.. _ipython_or_bpython: - Alternative Shells ~~~~~~~~~~~~~~~~~~ -If you have `IPython `_ and/or `bpython -`_ in the interpreter you use to invoke the -``pshell`` command, ``pshell`` will autodiscover and use the first one found. -However you could specifically invoke your choice with the ``-p choice`` or + +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. .. code-block:: text @@ -287,7 +280,7 @@ You may use the ``--list-shells`` option to see the available shells. $ $VENV/bin/pshell --list-shells Available shells: - bpython [not available] + bpython ipython python @@ -309,29 +302,19 @@ arguments, ``env`` and ``help``, which would look like this: .. code-block:: python - def ptpython_shell_factory(): - try: - from ptpython.repl import embed - except ImportError: - # ptpython is not installed - return None + from ptpython.repl import embed - def PTPShell(banner, **kwargs): - print(banner) - return embed(**kwargs) - - def shell(env, help): - PTPShell(banner=help, locals=env) - - return shell - -If the factory returns ``None`` then it is assumed that the shell is not -supported. + def ptpython_shell_runner(env, help): + print(help) + return embed(locals=env) .. 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 ~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From aac38eab09547d5dfb11ff00128c3aab91e947ac Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 22 Oct 2015 21:58:47 -0500 Subject: fix entry point example --- docs/narr/commandline.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index d466bed44..430641a50 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -291,7 +291,7 @@ introduce a new shell by registering an entry point in your setup.py: setup( entry_points={ - 'pyramid.pshell': [ + 'pyramid.pshell_runner': [ 'myshell=my_app:ptpython_shell_factory', ], }, -- cgit v1.2.3