Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/prompt-toolkit/ptpython

A better Python REPL
https://github.com/prompt-toolkit/ptpython

Last synced: 3 days ago
JSON representation

A better Python REPL

Awesome Lists containing this project

README 

        
ptpython

========



|Build Status|  |PyPI|  |License|



*A better Python REPL*



::



    pip install ptpython



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/example1.png



Ptpython is an advanced Python REPL. It should work on all

Python versions from 2.6 up to 3.11 and work cross platform (Linux,

BSD, OS X and Windows).



Note: this version of ptpython requires at least Python 3.6. Install ptpython

2.0.5 for older Python versions.



Installation

************



Install it using pip:



::



    pip install ptpython



Start it by typing ``ptpython``.



Features

********



- Syntax highlighting.

- Multiline editing (the up arrow works).

- Autocompletion.

- Mouse support. [1]

- Support for color schemes.

- Support for `bracketed paste `_ [2].

- Both Vi and Emacs key bindings.

- Support for double width (Chinese) characters.

- ... and many other things.



[1] Disabled by default. (Enable in the menu.)



[2] If the terminal supports it (most terminals do), this allows pasting

without going into paste mode. It will keep the indentation.



Command Line Options

********************



The help menu shows basic command-line options.



::



    $ ptpython --help

    usage: ptpython [-h] [--vi] [-i] [--light-bg] [--dark-bg] [--config-file CONFIG_FILE]

                    [--history-file HISTORY_FILE] [-V]

                    [args ...]



    ptpython: Interactive Python shell.



    positional arguments:

      args                  Script and arguments



    optional arguments:

      -h, --help            show this help message and exit

      --vi                  Enable Vi key bindings

      -i, --interactive     Start interactive shell after executing this file.

      --asyncio             Run an asyncio event loop to support top-level "await".

      --light-bg            Run on a light background (use dark colors for text).

      --dark-bg             Run on a dark background (use light colors for text).

      --config-file CONFIG_FILE

                            Location of configuration file.

      --history-file HISTORY_FILE

                            Location of history file.

      -V, --version         show program's version number and exit



    environment variables:

      PTPYTHON_CONFIG_HOME: a configuration directory to use

      PYTHONSTARTUP: file executed on interactive startup (no default)



__pt_repr__: A nicer repr with colors

*************************************



When classes implement a ``__pt_repr__`` method, this will be used instead of

``__repr__`` for printing. Any `prompt_toolkit "formatted text"

`_

can be returned from here. In order to avoid writing a ``__repr__`` as well,

the ``ptpython.utils.ptrepr_to_repr`` decorator can be applied. For instance:



.. code:: python



    from ptpython.utils import ptrepr_to_repr

    from prompt_toolkit.formatted_text import HTML



    @ptrepr_to_repr

    class MyClass:

        def __pt_repr__(self):

            return HTML('Hello world!')



More screenshots

****************



The configuration menu:



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/ptpython-menu.png



The history page and its help:



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/ptpython-history-help.png



Autocompletion:



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/file-completion.png



Embedding the REPL

******************



Embedding the REPL in any Python application is easy:



.. code:: python



    from ptpython.repl import embed

    embed(globals(), locals())



You can make ptpython your default Python REPL by creating a `PYTHONSTARTUP file

`_ containing code

like this:



.. code:: python



   import sys

   try:

       from ptpython.repl import embed

   except ImportError:

       print("ptpython is not available: falling back to standard prompt")

   else:

       sys.exit(embed(globals(), locals()))



Note config file support currently only works when invoking `ptpython` directly.

That it, the config file will be ignored when embedding ptpython in an application.



Multiline editing

*****************



Multi-line editing mode will automatically turn on when you press enter after a

colon.



To execute the input in multi-line mode, you can either press ``Alt+Enter``, or

``Esc`` followed by ``Enter``. (If you want the first to work in the OS X

terminal, you have to check the "Use option as meta key" checkbox in your

terminal settings. For iTerm2, you have to check "Left option acts as +Esc" in

the options.)



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/multiline.png



Syntax validation

*****************



Before execution, ``ptpython`` will see whether the input is syntactically

correct Python code. If not, it will show a warning, and move the cursor to the

error.



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/validation.png



Asyncio REPL and top level await

********************************



In order to get top-level ``await`` support, start ptpython as follows:



.. code::



   ptpython --asyncio



This will spawn an asyncio event loop and embed the async REPL in the event

loop. After this, top-level await will work and statements like ``await

asyncio.sleep(10)`` will execute.



Additional features

*******************



Running system commands: Press ``Meta-!`` in Emacs mode or just ``!`` in Vi

navigation mode to see the "Shell command" prompt. There you can enter system

commands without leaving the REPL.



Selecting text: Press ``Control+Space`` in Emacs mode or ``V`` (major V) in Vi

navigation mode.



Configuration

*************



It is possible to create a ``config.py`` file to customize configuration.

ptpython will look in an appropriate platform-specific directory via `appdirs

`. See the ``appdirs`` documentation for the

precise location for your platform. A ``PTPYTHON_CONFIG_HOME`` environment

variable, if set, can also be used to explicitly override where configuration

is looked for.



Have a look at this example to see what is possible:

`config.py `_



Note config file support currently only works when invoking `ptpython` directly.

That it, the config file will be ignored when embedding ptpython in an application.



IPython support

***************



Run ``ptipython`` (prompt_toolkit - IPython), to get a nice interactive shell

with all the power that IPython has to offer, like magic functions and shell

integration. Make sure that IPython has been installed. (``pip install

ipython``)



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/ipython.png



This is also available for embedding:



.. code:: python



    from ptpython.ipython import embed

    embed(globals(), locals())



Django support

**************



`django-extensions `_

has a ``shell_plus`` management command. When ``ptpython`` has been installed,

it will by default use ``ptpython`` or ``ptipython``.



PDB

***



There is an experimental PDB replacement: `ptpdb

`_.



Windows support

***************



``prompt_toolkit`` and ``ptpython`` works better on Linux and OS X than on

Windows. Some things might not work, but it is usable:



.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/windows.png



Windows terminal integration

~~~~~~~~~~~~~~~~~~~~~~~~~~~~



If you are using the `Windows Terminal `_ and want to 

integrate ``ptpython`` as a profile, go to *Settings -> Open JSON file* and add the

following profile under *profiles.list*:



.. code-block:: JSON



    {

        "commandline": "%SystemRoot%\\System32\\cmd.exe /k ptpython",

        "guid": "{f91d49a3-741b-409c-8a15-c4360649121f}",

        "hidden": false,

        "icon": "https://upload.wikimedia.org/wikipedia/commons/e/e6/Python_Windows_interpreter_icon_2006%E2%80%932016_Tiny.png",

        "name": "ptpython@cmd"

    }



FAQ

***



**Q**: The ``Ctrl-S`` forward search doesn't work and freezes my terminal.



**A**: Try to run ``stty -ixon`` in your terminal to disable flow control.



**Q**: The ``Meta``-key doesn't work.



**A**: For some terminals you have to enable the Alt-key to act as meta key, but you

can also type ``Escape`` before any key instead.



Alternatives

************



- `BPython `_

- `IPython `_



If you find another alternative, you can create an issue and we'll list it

here. If you find a nice feature somewhere that is missing in ``ptpython``,

also create a GitHub issue and maybe we'll implement it.



Special thanks to

*****************



- `Pygments `_: Syntax highlighter.

- `Jedi `_: Autocompletion library.

- `wcwidth `_: Determine columns needed for a wide characters.

- `prompt_toolkit `_ for the interface.



.. |Build Status| image:: https://github.com/prompt-toolkit/ptpython/actions/workflows/test.yaml/badge.svg

    :target: https://github.com/prompt-toolkit/ptpython/actions/workflows/test.yaml



.. |License| image:: https://img.shields.io/github/license/prompt-toolkit/ptpython.svg

    :target: https://github.com/prompt-toolkit/ptpython/blob/master/LICENSE



.. |PyPI| image:: https://img.shields.io/pypi/v/ptpython.svg

    :target: https://pypi.org/project/ptpython/

    :alt: Latest Version