README.rst

ptpython

A better Python REPL

pip install ptpython

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:

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:

The history page and its help:

Autocompletion:

Embedding the REPL

Embedding the REPL in any Python application is easy:

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:

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.)

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.

Asyncio REPL and top level await

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

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

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)

This is also available for embedding:

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:

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:

{
    "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.