diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..8ec9aca --- /dev/null +++ b/README.rst @@ -0,0 +1,299 @@ +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 |