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.9 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 <https://cirw.in/blog/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" <https://python-prompt-toolkit.readthedocs.io/en/master/pages/printing_text.html>_ 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('<yellow>Hello world!</yellow>')

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 <https://docs.python.org/3/tutorial/appendix.html#the-interactive-startup-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 <https://pypi.org/project/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 <https://github.com/jonathanslenders/ptpython/blob/master/examples/ptpython_config/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 <https://github.com/django-extensions/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 <https://github.com/jonathanslenders/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

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 <http://bpython-interpreter.org/downloads.html>_
• IPython <https://ipython.org/>_

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 <http://pygments.org/>_: Syntax highlighter.
• Jedi <http://jedi.jedidjah.ch/en/latest/>_: Autocompletion library.
• wcwidth <https://github.com/jquast/wcwidth>_: Determine columns needed for a wide characters.
• prompt_toolkit <http://github.com/jonathanslenders/python-prompt-toolkit>_ for the interface.

.. |Build Status| image:: https://api.travis-ci.org/prompt-toolkit/ptpython.svg?branch=master :target: https://travis-ci.org/prompt-toolkit/ptpython#

.. |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://pypip.in/version/ptpython/badge.svg :target: https://pypi.python.org/pypi/ptpython/ :alt: Latest Version