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 .. rubric:: Footnotes

   163 

   164 .. [#] Python will execute the contents of a file identified by the

   165    :envvar:`PYTHONSTARTUP` environment variable when you start an interactive

   166    interpreter.

   167