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 <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
Windows terminal integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are using the `Windows Terminal <https://aka.ms/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 <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://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
Raw data
{
"_id": null,
"home_page": "https://github.com/prompt-toolkit/ptpython",
"name": "ptpython",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Jonathan Slenders",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/56/61/352792c9f47de98a910526ff8a684466a6217e53ffa6627b3781960e4f0d/ptpython-3.0.29.tar.gz",
"platform": null,
"description": "ptpython\n========\n\n|Build Status| |PyPI| |License|\n\n*A better Python REPL*\n\n::\n\n pip install ptpython\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/example1.png\n\nPtpython is an advanced Python REPL. It should work on all\nPython versions from 2.6 up to 3.11 and work cross platform (Linux,\nBSD, OS X and Windows).\n\nNote: this version of ptpython requires at least Python 3.6. Install ptpython\n2.0.5 for older Python versions.\n\n\nInstallation\n************\n\nInstall it using pip:\n\n::\n\n pip install ptpython\n\nStart it by typing ``ptpython``.\n\n\nFeatures\n********\n\n- Syntax highlighting.\n- Multiline editing (the up arrow works).\n- Autocompletion.\n- Mouse support. [1]\n- Support for color schemes.\n- Support for `bracketed paste <https://cirw.in/blog/bracketed-paste>`_ [2].\n- Both Vi and Emacs key bindings.\n- Support for double width (Chinese) characters.\n- ... and many other things.\n\n\n[1] Disabled by default. (Enable in the menu.)\n\n[2] If the terminal supports it (most terminals do), this allows pasting\nwithout going into paste mode. It will keep the indentation.\n\nCommand Line Options\n********************\n\nThe help menu shows basic command-line options.\n\n::\n\n $ ptpython --help\n usage: ptpython [-h] [--vi] [-i] [--light-bg] [--dark-bg] [--config-file CONFIG_FILE]\n [--history-file HISTORY_FILE] [-V]\n [args ...]\n\n ptpython: Interactive Python shell.\n\n positional arguments:\n args Script and arguments\n\n optional arguments:\n -h, --help show this help message and exit\n --vi Enable Vi key bindings\n -i, --interactive Start interactive shell after executing this file.\n --asyncio Run an asyncio event loop to support top-level \"await\".\n --light-bg Run on a light background (use dark colors for text).\n --dark-bg Run on a dark background (use light colors for text).\n --config-file CONFIG_FILE\n Location of configuration file.\n --history-file HISTORY_FILE\n Location of history file.\n -V, --version show program's version number and exit\n\n environment variables:\n PTPYTHON_CONFIG_HOME: a configuration directory to use\n PYTHONSTARTUP: file executed on interactive startup (no default)\n\n\n__pt_repr__: A nicer repr with colors\n*************************************\n\nWhen classes implement a ``__pt_repr__`` method, this will be used instead of\n``__repr__`` for printing. Any `prompt_toolkit \"formatted text\"\n<https://python-prompt-toolkit.readthedocs.io/en/master/pages/printing_text.html>`_\ncan be returned from here. In order to avoid writing a ``__repr__`` as well,\nthe ``ptpython.utils.ptrepr_to_repr`` decorator can be applied. For instance:\n\n.. code:: python\n\n from ptpython.utils import ptrepr_to_repr\n from prompt_toolkit.formatted_text import HTML\n\n @ptrepr_to_repr\n class MyClass:\n def __pt_repr__(self):\n return HTML('<yellow>Hello world!</yellow>')\n\nMore screenshots\n****************\n\nThe configuration menu:\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/ptpython-menu.png\n\nThe history page and its help:\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/ptpython-history-help.png\n\nAutocompletion:\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/file-completion.png\n\n\nEmbedding the REPL\n******************\n\nEmbedding the REPL in any Python application is easy:\n\n.. code:: python\n\n from ptpython.repl import embed\n embed(globals(), locals())\n\nYou can make ptpython your default Python REPL by creating a `PYTHONSTARTUP file\n<https://docs.python.org/3/tutorial/appendix.html#the-interactive-startup-file>`_ containing code\nlike this:\n\n.. code:: python\n\n import sys\n try:\n from ptpython.repl import embed\n except ImportError:\n print(\"ptpython is not available: falling back to standard prompt\")\n else:\n sys.exit(embed(globals(), locals()))\n\nNote config file support currently only works when invoking `ptpython` directly.\nThat it, the config file will be ignored when embedding ptpython in an application.\n\nMultiline editing\n*****************\n\nMulti-line editing mode will automatically turn on when you press enter after a\ncolon.\n\nTo execute the input in multi-line mode, you can either press ``Alt+Enter``, or\n``Esc`` followed by ``Enter``. (If you want the first to work in the OS X\nterminal, you have to check the \"Use option as meta key\" checkbox in your\nterminal settings. For iTerm2, you have to check \"Left option acts as +Esc\" in\nthe options.)\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/multiline.png\n\n\nSyntax validation\n*****************\n\nBefore execution, ``ptpython`` will see whether the input is syntactically\ncorrect Python code. If not, it will show a warning, and move the cursor to the\nerror.\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/validation.png\n\n\nAsyncio REPL and top level await\n********************************\n\nIn order to get top-level ``await`` support, start ptpython as follows:\n\n.. code::\n\n ptpython --asyncio\n\nThis will spawn an asyncio event loop and embed the async REPL in the event\nloop. After this, top-level await will work and statements like ``await\nasyncio.sleep(10)`` will execute.\n\n\nAdditional features\n*******************\n\nRunning system commands: Press ``Meta-!`` in Emacs mode or just ``!`` in Vi\nnavigation mode to see the \"Shell command\" prompt. There you can enter system\ncommands without leaving the REPL.\n\nSelecting text: Press ``Control+Space`` in Emacs mode or ``V`` (major V) in Vi\nnavigation mode.\n\n\nConfiguration\n*************\n\nIt is possible to create a ``config.py`` file to customize configuration.\nptpython will look in an appropriate platform-specific directory via `appdirs\n<https://pypi.org/project/appdirs/>`. See the ``appdirs`` documentation for the\nprecise location for your platform. A ``PTPYTHON_CONFIG_HOME`` environment\nvariable, if set, can also be used to explicitly override where configuration\nis looked for.\n\nHave a look at this example to see what is possible:\n`config.py <https://github.com/jonathanslenders/ptpython/blob/master/examples/ptpython_config/config.py>`_\n\nNote config file support currently only works when invoking `ptpython` directly.\nThat it, the config file will be ignored when embedding ptpython in an application.\n\n\nIPython support\n***************\n\nRun ``ptipython`` (prompt_toolkit - IPython), to get a nice interactive shell\nwith all the power that IPython has to offer, like magic functions and shell\nintegration. Make sure that IPython has been installed. (``pip install\nipython``)\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/ipython.png\n\nThis is also available for embedding:\n\n.. code:: python\n\n from ptpython.ipython import embed\n embed(globals(), locals())\n\n\nDjango support\n**************\n\n`django-extensions <https://github.com/django-extensions/django-extensions>`_\nhas a ``shell_plus`` management command. When ``ptpython`` has been installed,\nit will by default use ``ptpython`` or ``ptipython``.\n\n\nPDB\n***\n\nThere is an experimental PDB replacement: `ptpdb\n<https://github.com/jonathanslenders/ptpdb>`_.\n\n\nWindows support\n***************\n\n``prompt_toolkit`` and ``ptpython`` works better on Linux and OS X than on\nWindows. Some things might not work, but it is usable:\n\n.. image :: https://github.com/jonathanslenders/ptpython/raw/master/docs/images/windows.png\n\nWindows terminal integration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf you are using the `Windows Terminal <https://aka.ms/terminal>`_ and want to \nintegrate ``ptpython`` as a profile, go to *Settings -> Open JSON file* and add the\nfollowing profile under *profiles.list*:\n\n.. code-block:: JSON\n\n {\n \"commandline\": \"%SystemRoot%\\\\System32\\\\cmd.exe /k ptpython\",\n \"guid\": \"{f91d49a3-741b-409c-8a15-c4360649121f}\",\n \"hidden\": false,\n \"icon\": \"https://upload.wikimedia.org/wikipedia/commons/e/e6/Python_Windows_interpreter_icon_2006%E2%80%932016_Tiny.png\",\n \"name\": \"ptpython@cmd\"\n }\n\nFAQ\n***\n\n**Q**: The ``Ctrl-S`` forward search doesn't work and freezes my terminal.\n\n**A**: Try to run ``stty -ixon`` in your terminal to disable flow control.\n\n**Q**: The ``Meta``-key doesn't work.\n\n**A**: For some terminals you have to enable the Alt-key to act as meta key, but you\ncan also type ``Escape`` before any key instead.\n\n\nAlternatives\n************\n\n- `BPython <http://bpython-interpreter.org/downloads.html>`_\n- `IPython <https://ipython.org/>`_\n\nIf you find another alternative, you can create an issue and we'll list it\nhere. If you find a nice feature somewhere that is missing in ``ptpython``,\nalso create a GitHub issue and maybe we'll implement it.\n\n\nSpecial thanks to\n*****************\n\n- `Pygments <http://pygments.org/>`_: Syntax highlighter.\n- `Jedi <http://jedi.jedidjah.ch/en/latest/>`_: Autocompletion library.\n- `wcwidth <https://github.com/jquast/wcwidth>`_: Determine columns needed for a wide characters.\n- `prompt_toolkit <http://github.com/jonathanslenders/python-prompt-toolkit>`_ for the interface.\n\n.. |Build Status| image:: https://github.com/prompt-toolkit/ptpython/actions/workflows/test.yaml/badge.svg\n :target: https://github.com/prompt-toolkit/ptpython/actions/workflows/test.yaml\n\n.. |License| image:: https://img.shields.io/github/license/prompt-toolkit/ptpython.svg\n :target: https://github.com/prompt-toolkit/ptpython/blob/master/LICENSE\n\n.. |PyPI| image:: https://img.shields.io/pypi/v/ptpython.svg\n :target: https://pypi.org/project/ptpython/\n :alt: Latest Version\n",
"bugtrack_url": null,
"license": null,
"summary": "Python REPL build on top of prompt_toolkit",
"version": "3.0.29",
"project_urls": {
"Bug Tracker": "https://github.com/prompt-toolkit/ptpython/issues",
"Changelog": "https://github.com/prompt-toolkit/ptpython/blob/master/CHANGELOG",
"Homepage": "https://github.com/prompt-toolkit/ptpython",
"Source Code": "https://github.com/prompt-toolkit/ptpython"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0f39c6fd4dd531e067b6a01624126cff0b3ddc6569e22f83e48d8418ffa9e3be",
"md5": "c45ba76b74ad8eeca09d2daf85824aa5",
"sha256": "65d75c4871859e4305a020c9b9e204366dceb4d08e0e2bd7b7511bd5e917a402"
},
"downloads": -1,
"filename": "ptpython-3.0.29-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c45ba76b74ad8eeca09d2daf85824aa5",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 67057,
"upload_time": "2024-07-22T12:43:17",
"upload_time_iso_8601": "2024-07-22T12:43:17.217474Z",
"url": "https://files.pythonhosted.org/packages/0f/39/c6fd4dd531e067b6a01624126cff0b3ddc6569e22f83e48d8418ffa9e3be/ptpython-3.0.29-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5661352792c9f47de98a910526ff8a684466a6217e53ffa6627b3781960e4f0d",
"md5": "6f393a65b9c0396483fbac513ff46ce2",
"sha256": "b9d625183aef93a673fc32cbe1c1fcaf51412e7a4f19590521cdaccadf25186e"
},
"downloads": -1,
"filename": "ptpython-3.0.29.tar.gz",
"has_sig": false,
"md5_digest": "6f393a65b9c0396483fbac513ff46ce2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 72622,
"upload_time": "2024-07-22T12:43:20",
"upload_time_iso_8601": "2024-07-22T12:43:20.053665Z",
"url": "https://files.pythonhosted.org/packages/56/61/352792c9f47de98a910526ff8a684466a6217e53ffa6627b3781960e4f0d/ptpython-3.0.29.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-22 12:43:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "prompt-toolkit",
"github_project": "ptpython",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ptpython"
}
JSON
