Skip to content

Commit 1d8d556

Browse files
jonathanslendersjonathanslenders
committed
Moved ptpython code from prompt-toolkit inside this repository.
1 parent 6956a1e commit 1d8d556

24 files changed

Lines changed: 1965 additions & 18 deletions

‎README.rst‎

Lines changed: 171 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,176 @@
1-
ptpython
2-
========
1+
ptpython: a better Python REPL
2+
==============================
33

4-
`ptpython` is a Python REPL build on top of the `prompt_toolkit
5-
<http://github.com/jonathanslenders/python-prompt-toolkit>`_ library. For now
6-
it's still still shipped with ``prompt_toolkit`` itself. Maybe, later on (when
7-
APIs are sure to be stable) we will pull it out and put it here instead.
4+
``ptpython`` is an advanced Python REPL build on top of the `prompt_toolkit
5+
<http://github.com/jonathanslenders/python-prompt-toolkit>`_ library.
86

9-
To install ``ptpython``, run:
7+
It works best on all Posix systems like Linux, BSD and OS X. But it should work
8+
as well on Windows. It works on all Python versions from 2.6 up to 3.4.
9+
10+
11+
Installation
12+
************
13+
14+
To install ``ptpython``, type:
1015

1116
::
1217

13-
pip install prompt-toolkit
18+
pip install ptpython
19+
20+
21+
The REPL
22+
********
23+
24+
Run ``ptpython`` to get an interactive Python prompt with syntax highlighting,
25+
code completion, etc...
26+
27+
.. image :: docs/images/example1.png
28+
29+
By default, you will have Emacs key bindings, but if you prefer Vi bindings
30+
(like in the above screenshot) then run ``ptpython --vi``.
31+
32+
If you want to embed the REPL inside your application at one point, do:
33+
34+
.. code:: python
35+
36+
from ptpython.repl import embed
37+
embed(globals(), locals(), vi_mode=False, history_filename=None)
38+
39+
40+
Autocompletion
41+
**************
42+
43+
``Tab`` and ``shift+tab`` complete the input.
44+
In Vi-mode, you can also use ``Ctrl+N`` and ``Ctrl+P``.
45+
46+
There is even completion on file names inside strings:
47+
48+
.. image :: docs/images/file-completion.png
49+
50+
51+
Multiline editing
52+
*****************
53+
54+
Usually, multi-line editing mode will automatically turn on when you press enter
55+
after a colon, however you can always turn it on by pressing ``F7``.
56+
57+
To execute the input in multi-line mode, you can either press ``Alt+Enter``, or
58+
``Esc`` followed by ``Enter``. (If you want the first to work in the OS X
59+
terminal, you have to check the "Use option as meta key" checkbox in your
60+
terminal settings. For iTerm2, you have to check "Left option acts as +Esc" in
61+
the options.)
62+
63+
.. image :: docs/images/multiline.png
64+
65+
66+
Tab pages
67+
*********
68+
69+
Suppose that you were editing a long multiline Python command, but suddenly you
70+
want to test something else in between in the same shell and go back. We have
71+
tab pages for this. Each tab has its own input buffer, but they are all
72+
evaluated in the same environment (sharing locals/globals).
73+
74+
.. image :: docs/images/tab-pages.png
75+
76+
The shortcuts:
77+
78+
+------------------------+-----------------------+
79+
| Create a new tab page | Control-N |
80+
+------------------------+-----------------------+
81+
| Close current tab page | Control-D |
82+
+------------------------+-----------------------+
83+
| Navigate to next tab | Control-Arrow-right |
84+
| | (Or in Vi-mode: 'gt') |
85+
+------------------------+-----------------------+
86+
| Navigate to previous | Control-Arrow-left |
87+
| tab | (Or in Vi-mode: 'gT') |
88+
+------------------------+-----------------------+
89+
90+
Other features
91+
***************
92+
93+
Running system commands: Press ``Meta-!`` in Emacs mode or just ``!`` in Vi
94+
navigation mode to see the "Shell command" prompt. There you can enter system
95+
commands without leaving the REPL.
96+
97+
Selecting text: Press ``Control+Space`` in Emacs mode on ``V`` (major V) in Vi
98+
navigation mode.
99+
100+
101+
You love IPython?
102+
*****************
103+
104+
Run ``ptipython`` (prompt_toolkit - IPython), to get a nice interactive shell
105+
with all the power that IPython has to offer, like magic functions and shell
106+
integration. Make sure that IPython has been installed. (``pip install
107+
ipython``)
108+
109+
.. image :: docs/images/ipython.png
110+
111+
112+
You are using Django?
113+
*********************
114+
115+
`django-extensions <https://github.com/django-extensions/django-extensions>`_
116+
has a ``shell_plus`` management command. When ``ptpython`` has been installed,
117+
it will by default use ``ptpython`` or ``ptipython``.
118+
119+
120+
PDB
121+
***
122+
123+
There is an experimental PDB replacement: `ptpdb
124+
<https://github.com/jonathanslenders/ptpdb>`_.
125+
126+
127+
About Windows support
128+
*********************
129+
130+
``prompt_toolkit`` works still a little better on systems like Linux and OS X
131+
than on Windows, but it certainly is usable. One thing that still needs
132+
attention is the colorscheme. Windows terminals don't support all colors, so we
133+
have to create another colorscheme for Windows.
134+
135+
.. image :: docs/images/windows.png
136+
137+
138+
FAQ
139+
---
140+
141+
Q
142+
The ``Ctrl-S`` forward search doesn't work and freezes my terminal.
143+
A
144+
Try to run ``stty -ixon`` in your terminal to disable flow control.
145+
146+
Q
147+
The ``Meta``-key doesn't work.
148+
A
149+
For some terminals you have to enable the Alt-key to act as meta key, but you
150+
can also type ``Escape`` before any key instead.
151+
152+
153+
Alternatives
154+
************
155+
156+
Have a look at the alternatives.
157+
158+
- `BPython <http://bpython-interpreter.org/downloads.html>`_
159+
160+
If you find another alternative, you can create an issue and we'll list it
161+
here. If you find a nice feature somewhere that is missing in ``ptpython``,
162+
also create a GitHub issue and mabye we'll implement it.
163+
164+
165+
Special thanks to
166+
*****************
167+
168+
- `Pygments <http://pygments.org/>`_: Syntax highlighter.
169+
- `Jedi <http://jedi.jedidjah.ch/en/latest/>`_: Autocompletion library.
170+
- `Docopt <http://docopt.org/>`_: Command-line interface description language.
171+
- `wcwidth <https://github.com/jquast/wcwidth>`_: Determine columns needed for a wide characters.
172+
- `prompt_toolkit <http://github.com/jonathanslenders/python-prompt-toolkit>`_ for the interface.
173+
174+
.. |PyPI| image:: https://pypip.in/version/prompt-toolkit/badge.svg
175+
:target: https://pypi.python.org/pypi/prompt-toolkit/
176+
:alt: Latest Version

‎docs/images/example1.png‎

44.6 KB
Loading

‎docs/images/file-completion.png‎

41.1 KB
Loading

‎docs/images/ipython.png‎

36.1 KB
Loading

‎docs/images/multiline.png‎

26.5 KB
Loading

‎docs/images/tab-pages.png‎

19.4 KB
Loading

‎docs/images/windows.png‎

17.9 KB
Loading

‎examples/python-embed.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/usr/bin/env python
2+
"""
3+
"""
4+
from __future__ import unicode_literals
5+
6+
from ptpython.repl import embed
7+
8+
9+
def main():
10+
embed(globals(), locals(), vi_mode=False)
11+
12+
13+
if __name__ == '__main__':
14+
main()

‎examples/python-input.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#!/usr/bin/env python
2+
"""
3+
"""
4+
from __future__ import unicode_literals
5+
6+
from ptpython.python_input import PythonCommandLineInterface
7+
8+
9+
def main():
10+
cli = PythonCommandLineInterface()
11+
12+
code_obj = cli.cli.read_input()
13+
print('You said: ' + code_obj.text)
14+
15+
16+
if __name__ == '__main__':
17+
main()

‎ptpython/__init__.py‎

Whitespace-only changes.

0 commit comments

Comments
 (0)