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,
  10 which 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 Alternatives to the Interactive Interpreter
 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 One alternative enhanced interactive interpreter that has been around for quite
 162 some time is `IPython`_, which features tab completion, object exploration and
 163 advanced history management.  It can also be thoroughly customized and embedded
 164 into other applications.  Another similar enhanced interactive environment is
 165 `bpython`_.
 166
 167
 168 .. rubric:: Footnotes
 169
 170 .. [#] Python will execute the contents of a file identified by the
 171    :envvar:`PYTHONSTARTUP` environment variable when you start an interactive
 172    interpreter.
 173
 174
 175 .. _GNU Readline: http://tiswww.case.edu/php/chet/readline/rltop.html
 176 .. _IPython: http://ipython.scipy.org/
 177 .. _bpython: http://www.bpython-interpreter.org/