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/narr/commandline.rst') 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/narr/commandline.rst') 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/narr/commandline.rst') 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 From 4429b543d97712dbec1ce10e3489385ff16a3639 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Tue, 27 Oct 2015 12:23:15 -0400 Subject: Restore link target used by 'whatsnew-1.3.rst'. Should fix Jenkins breakage. --- docs/narr/commandline.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 430641a50..eb79dffb6 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -261,6 +261,8 @@ request is configured to generate urls from the host >>> request.route_url('home') 'https://www.example.com/' +.. _ipython_or_bpython: + Alternative Shells ~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 5ff3d2dfdbf936d115e3486696401ad7dbffedc3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Dec 2015 01:24:34 -0800 Subject: - add p* scripts - add links to p* scripts - add a blank line to keep indices and labels better visually related to the subsequent heading --- docs/narr/commandline.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'docs/narr/commandline.rst') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index eb79dffb6..34b12e1e9 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -6,6 +6,7 @@ Command-Line Pyramid Your :app:`Pyramid` application can be controlled and inspected using a variety of command-line utilities. These utilities are documented in this chapter. + .. index:: pair: matching views; printing single: pviews @@ -15,6 +16,8 @@ of command-line utilities. These utilities are documented in this chapter. Displaying Matching Views for a Given URL ----------------------------------------- +.. seealso:: See also the output of :ref:`pviews --help `. + 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 ``pviews`` command in a terminal window to print a summary of @@ -114,6 +117,8 @@ found* message. The Interactive Shell --------------------- +.. seealso:: See also the output of :ref:`pshell --help `. + Once you've installed your program for development using ``setup.py develop``, you can use an interactive Python shell to execute expressions in a Python environment exactly like the one that will be used when your application runs @@ -179,6 +184,7 @@ hash after the filename: Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). + .. index:: pair: pshell; extending @@ -261,6 +267,7 @@ request is configured to generate urls from the host >>> request.route_url('home') 'https://www.example.com/' + .. _ipython_or_bpython: Alternative Shells @@ -317,6 +324,7 @@ arguments, ``env`` and ``help``, which would look like this: ``ipython`` and ``bpython`` have been moved into their respective packages ``pyramid_ipython`` and ``pyramid_bpython``. + Setting a Default Shell ~~~~~~~~~~~~~~~~~~~~~~~ @@ -331,6 +339,7 @@ specify a list of preferred shells. .. versionadded:: 1.6 + .. index:: pair: routes; printing single: proutes @@ -340,6 +349,8 @@ specify a list of preferred shells. Displaying All Application Routes --------------------------------- +.. seealso:: See also the output of :ref:`proutes --help `. + You can use the ``proutes`` command in a terminal window to print a summary of routes related to your application. Much like the ``pshell`` command (see :ref:`interactive_shell`), the ``proutes`` command accepts one argument with @@ -421,6 +432,8 @@ include. The current available formats are ``name``, ``pattern``, ``view``, and Displaying "Tweens" ------------------- +.. seealso:: See also the output of :ref:`ptweens --help `. + A :term:`tween` is a bit of code that sits between the main Pyramid application request handler and the WSGI application which calls it. A user can get a representation of both the implicit tween ordering (the ordering specified by @@ -497,6 +510,7 @@ used: See :ref:`registering_tweens` for more information about tweens. + .. index:: single: invoking a request single: prequest @@ -506,6 +520,8 @@ See :ref:`registering_tweens` for more information about tweens. Invoking a Request ------------------ +.. seealso:: See also the output of :ref:`prequest --help `. + You can use the ``prequest`` command-line utility to send a request to your application and see the response body without starting a server. @@ -555,6 +571,7 @@ of the ``prequest`` process is used as the ``POST`` body:: $ $VENV/bin/prequest -mPOST development.ini / < somefile + Using Custom Arguments to Python when Running ``p*`` Scripts ------------------------------------------------------------ @@ -566,11 +583,22 @@ Python interpreter at runtime. For example:: python -3 -m pyramid.scripts.pserve development.ini + +.. index:: + single: pdistreport + single: distributions, showing installed + single: showing installed distributions + +.. _showing_distributions: + Showing All Installed Distributions and Their Versions ------------------------------------------------------ .. versionadded:: 1.5 +.. seealso:: See also the output of :ref:`pdistreport --help + `. + You can use the ``pdistreport`` command to show the :app:`Pyramid` version in use, the Python version in use, and all installed versions of Python distributions in your Python environment:: @@ -590,6 +618,7 @@ pastebin when you are having problems and need someone with more familiarity with Python packaging and distribution than you have to look at your environment. + .. _writing_a_script: Writing a Script @@ -702,6 +731,7 @@ The above example specifies the ``another`` ``app``, ``pipeline``, or object present in the ``env`` dictionary returned by :func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router`. + Changing the Request ~~~~~~~~~~~~~~~~~~~~ @@ -742,6 +772,7 @@ Now you can readily use Pyramid's APIs for generating URLs: env['request'].route_url('verify', code='1337') # will return 'https://example.com/prefix/verify/1337' + Cleanup ~~~~~~~ @@ -757,6 +788,7 @@ callback: env['closer']() + Setting Up Logging ~~~~~~~~~~~~~~~~~~ @@ -773,6 +805,7 @@ use the following command: See :ref:`logging_chapter` for more information on logging within :app:`Pyramid`. + .. index:: single: console script -- cgit v1.2.3