← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/tutorial/interactive.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/tutorial/interactive.rst
 
1
.. _tut-interacting:
 
2
 
 
3
**************************************************
 
4
Interactive Input Editing and History Substitution
 
5
**************************************************
 
6
 
 
7
Some versions of the Python interpreter support editing of the current input
 
8
line and history substitution, similar to facilities found in the Korn shell and
 
9
the GNU Bash shell.  This is implemented using the *GNU Readline* library, which
 
10
supports Emacs-style and vi-style editing.  This library has its own
 
11
documentation which I won't duplicate here; however, the basics are easily
 
12
explained.  The interactive editing and history described here are optionally
 
13
available in the Unix and Cygwin versions of the interpreter.
 
14
 
 
15
This chapter does *not* document the editing facilities of Mark Hammond's
 
16
PythonWin package or the Tk-based environment, IDLE, distributed with Python.
 
17
The command line history recall which operates within DOS boxes on NT and some
 
18
other DOS and Windows flavors  is yet another beast.
 
19
 
 
20
 
 
21
.. _tut-lineediting:
 
22
 
 
23
Line Editing
 
24
============
 
25
 
 
26
If supported, input line editing is active whenever the interpreter prints a
 
27
primary or secondary prompt.  The current line can be edited using the
 
28
conventional Emacs control characters.  The most important of these are:
 
29
:kbd:`C-A` (Control-A) moves the cursor to the beginning of the line, :kbd:`C-E`
 
30
to the end, :kbd:`C-B` moves it one position to the left, :kbd:`C-F` to the
 
31
right.  Backspace erases the character to the left of the cursor, :kbd:`C-D` the
 
32
character to its right. :kbd:`C-K` kills (erases) the rest of the line to the
 
33
right of the cursor, :kbd:`C-Y` yanks back the last killed string.
 
34
:kbd:`C-underscore` undoes the last change you made; it can be repeated for
 
35
cumulative effect.
 
36
 
 
37
 
 
38
.. _tut-history:
 
39
 
 
40
History Substitution
 
41
====================
 
42
 
 
43
History substitution works as follows.  All non-empty input lines issued are
 
44
saved in a history buffer, and when a new prompt is given you are positioned on
 
45
a new line at the bottom of this buffer. :kbd:`C-P` moves one line up (back) in
 
46
the history buffer, :kbd:`C-N` moves one down.  Any line in the history buffer
 
47
can be edited; an asterisk appears in front of the prompt to mark a line as
 
48
modified.  Pressing the :kbd:`Return` key passes the current line to the
 
49
interpreter.  :kbd:`C-R` starts an incremental reverse search; :kbd:`C-S` starts
 
50
a forward search.
 
51
 
 
52
 
 
53
.. _tut-keybindings:
 
54
 
 
55
Key Bindings
 
56
============
 
57
 
 
58
The key bindings and some other parameters of the Readline library can be
 
59
customized by placing commands in an initialization file called
 
60
:file:`~/.inputrc`.  Key bindings have the form ::
 
61
 
 
62
   key-name: function-name
 
63
 
 
64
or ::
 
65
 
 
66
   "string": function-name
 
67
 
 
68
and options can be set with ::
 
69
 
 
70
   set option-name value
 
71
 
 
72
For example::
 
73
 
 
74
   # I prefer vi-style editing:
 
75
   set editing-mode vi
 
76
 
 
77
   # Edit using a single line:
 
78
   set horizontal-scroll-mode On
 
79
 
 
80
   # Rebind some keys:
 
81
   Meta-h: backward-kill-word
 
82
   "\C-u": universal-argument
 
83
   "\C-x\C-r": re-read-init-file
 
84
 
 
85
Note that the default binding for :kbd:`Tab` in Python is to insert a :kbd:`Tab`
 
86
character instead of Readline's default filename completion function.  If you
 
87
insist, you can override this by putting ::
 
88
 
 
89
   Tab: complete
 
90
 
 
91
in your :file:`~/.inputrc`.  (Of course, this makes it harder to type indented
 
92
continuation lines if you're accustomed to using :kbd:`Tab` for that purpose.)
 
93
 
 
94
.. index::
 
95
   module: rlcompleter
 
96
   module: readline
 
97
 
 
98
Automatic completion of variable and module names is optionally available.  To
 
99
enable it in the interpreter's interactive mode, add the following to your
 
100
startup file: [#]_  ::
 
101
 
 
102
   import rlcompleter, readline
 
103
   readline.parse_and_bind('tab: complete')
 
104
 
 
105
This binds the :kbd:`Tab` key to the completion function, so hitting the
 
106
:kbd:`Tab` key twice suggests completions; it looks at Python statement names,
 
107
the current local variables, and the available module names.  For dotted
 
108
expressions such as ``string.a``, it will evaluate the expression up to the
 
109
final ``'.'`` and then suggest completions from the attributes of the resulting
 
110
object.  Note that this may execute application-defined code if an object with a
 
111
:meth:`__getattr__` method is part of the expression.
 
112
 
 
113
A more capable startup file might look like this example.  Note that this
 
114
deletes the names it creates once they are no longer needed; this is done since
 
115
the startup file is executed in the same namespace as the interactive commands,
 
116
and removing the names avoids creating side effects in the interactive
 
117
environment.  You may find it convenient to keep some of the imported modules,
 
118
such as :mod:`os`, which turn out to be needed in most sessions with the
 
119
interpreter. ::
 
120
 
 
121
   # Add auto-completion and a stored history file of commands to your Python
 
122
   # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is
 
123
   # bound to the Esc key by default (you can change it - see readline docs).
 
124
   #
 
125
   # Store the file in ~/.pystartup, and set an environment variable to point
 
126
   # to it:  "export PYTHONSTARTUP=/home/user/.pystartup" in bash.
 
127
   #
 
128
   # Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the
 
129
   # full path to your home directory.
 
130
 
 
131
   import atexit
 
132
   import os
 
133
   import readline
 
134
   import rlcompleter
 
135
 
 
136
   historyPath = os.path.expanduser("~/.pyhistory")
 
137
 
 
138
   def save_history(historyPath=historyPath):
 
139
       import readline
 
140
       readline.write_history_file(historyPath)
 
141
 
 
142
   if os.path.exists(historyPath):
 
143
       readline.read_history_file(historyPath)
 
144
 
 
145
   atexit.register(save_history)
 
146
   del os, atexit, readline, rlcompleter, save_history, historyPath
 
147
 
 
148
 
 
149
.. _tut-commentary:
 
150
 
 
151
Commentary
 
152
==========
 
153
 
 
154
This facility is an enormous step forward compared to earlier versions of the
 
155
interpreter; however, some wishes are left: It would be nice if the proper
 
156
indentation were suggested on continuation lines (the parser knows if an indent
 
157
token is required next).  The completion mechanism might use the interpreter's
 
158
symbol table.  A command to check (or even suggest) matching parentheses,
 
159
quotes, etc., would also be useful.
 
160
 
 
161
.. %
 
162
   Do we mention IPython? DUBOIS
 
163
 
 
164
.. rubric:: Footnotes
 
165
 
 
166
.. [#] Python will execute the contents of a file identified by the
 
167
   :envvar:`PYTHONSTARTUP` environment variable when you start an interactive
 
168
   interpreter.
 
169