Doc/library/readline.rst

   1
   2 :mod:`readline` --- GNU readline interface
   3 ==========================================
   4
   5 .. module:: readline
   6    :platform: Unix
   7    :synopsis: GNU readline support for Python.
   8 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
   9
  10
  11 The :mod:`readline` module defines a number of functions to facilitate
  12 completion and reading/writing of history files from the Python interpreter.
  13 This module can be used directly or via the :mod:`rlcompleter` module.  Settings
  14 made using  this module affect the behaviour of both the interpreter's
  15 interactive prompt  and the prompts offered by the :func:`raw_input` and
  16 :func:`input` built-in functions.
  17
  18 The :mod:`readline` module defines the following functions:
  19
  20
  21 .. function:: parse_and_bind(string)
  22
  23    Parse and execute single line of a readline init file.
  24
  25
  26 .. function:: get_line_buffer()
  27
  28    Return the current contents of the line buffer.
  29
  30
  31 .. function:: insert_text(string)
  32
  33    Insert text into the command line.
  34
  35
  36 .. function:: read_init_file([filename])
  37
  38    Parse a readline initialization file. The default filename is the last filename
  39    used.
  40
  41
  42 .. function:: read_history_file([filename])
  43
  44    Load a readline history file. The default filename is :file:`~/.history`.
  45
  46
  47 .. function:: write_history_file([filename])
  48
  49    Save a readline history file. The default filename is :file:`~/.history`.
  50
  51
  52 .. function:: clear_history()
  53
  54    Clear the current history.  (Note: this function is not available if the
  55    installed version of GNU readline doesn't support it.)
  56
  57    .. versionadded:: 2.4
  58
  59
  60 .. function:: get_history_length()
  61
  62    Return the desired length of the history file.  Negative values imply unlimited
  63    history file size.
  64
  65
  66 .. function:: set_history_length(length)
  67
  68    Set the number of lines to save in the history file. :func:`write_history_file`
  69    uses this value to truncate the history file when saving.  Negative values imply
  70    unlimited history file size.
  71
  72
  73 .. function:: get_current_history_length()
  74
  75    Return the number of lines currently in the history.  (This is different from
  76    :func:`get_history_length`, which returns the maximum number of lines that will
  77    be written to a history file.)
  78
  79    .. versionadded:: 2.3
  80
  81
  82 .. function:: get_history_item(index)
  83
  84    Return the current contents of history item at *index*.
  85
  86    .. versionadded:: 2.3
  87
  88
  89 .. function:: remove_history_item(pos)
  90
  91    Remove history item specified by its position from the history.
  92
  93    .. versionadded:: 2.4
  94
  95
  96 .. function:: replace_history_item(pos, line)
  97
  98    Replace history item specified by its position with the given line.
  99
 100    .. versionadded:: 2.4
 101
 102
 103 .. function:: redisplay()
 104
 105    Change what's displayed on the screen to reflect the current contents of the
 106    line buffer.
 107
 108    .. versionadded:: 2.3
 109
 110
 111 .. function:: set_startup_hook([function])
 112
 113    Set or remove the startup_hook function.  If *function* is specified, it will be
 114    used as the new startup_hook function; if omitted or ``None``, any hook function
 115    already installed is removed.  The startup_hook function is called with no
 116    arguments just before readline prints the first prompt.
 117
 118
 119 .. function:: set_pre_input_hook([function])
 120
 121    Set or remove the pre_input_hook function.  If *function* is specified, it will
 122    be used as the new pre_input_hook function; if omitted or ``None``, any hook
 123    function already installed is removed.  The pre_input_hook function is called
 124    with no arguments after the first prompt has been printed and just before
 125    readline starts reading input characters.
 126
 127
 128 .. function:: set_completer([function])
 129
 130    Set or remove the completer function.  If *function* is specified, it will be
 131    used as the new completer function; if omitted or ``None``, any completer
 132    function already installed is removed.  The completer function is called as
 133    ``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it
 134    returns a non-string value.  It should return the next possible completion
 135    starting with *text*.
 136
 137
 138 .. function:: get_completer()
 139
 140    Get the completer function, or ``None`` if no completer function has been set.
 141
 142    .. versionadded:: 2.3
 143
 144
 145 .. function:: get_completion_type()
 146
 147    Get the type of completion being attempted.
 148
 149    .. versionadded:: 2.6
 150
 151 .. function:: get_begidx()
 152
 153    Get the beginning index of the readline tab-completion scope.
 154
 155
 156 .. function:: get_endidx()
 157
 158    Get the ending index of the readline tab-completion scope.
 159
 160
 161 .. function:: set_completer_delims(string)
 162
 163    Set the readline word delimiters for tab-completion.
 164
 165
 166 .. function:: get_completer_delims()
 167
 168    Get the readline word delimiters for tab-completion.
 169
 170 .. function:: set_completion_display_matches_hook([function])
 171
 172    Set or remove the completion display function.  If *function* is
 173    specified, it will be used as the new completion display function;
 174    if omitted or ``None``, any completion display function already
 175    installed is removed.  The completion display function is called as
 176    ``function(substitution, [matches], longest_match_length)`` once
 177    each time matches need to be displayed.
 178
 179    .. versionadded:: 2.6
 180
 181 .. function:: add_history(line)
 182
 183    Append a line to the history buffer, as if it was the last line typed.
 184
 185
 186 .. seealso::
 187
 188    Module :mod:`rlcompleter`
 189       Completion of Python identifiers at the interactive prompt.
 190
 191
 192 .. _readline-example:
 193
 194 Example
 195 -------
 196
 197 The following example demonstrates how to use the :mod:`readline` module's
 198 history reading and writing functions to automatically load and save a history
 199 file named :file:`.pyhist` from the user's home directory.  The code below would
 200 normally be executed automatically during interactive sessions from the user's
 201 :envvar:`PYTHONSTARTUP` file. ::
 202
 203    import os
 204    histfile = os.path.join(os.environ["HOME"], ".pyhist")
 205    try:
 206        readline.read_history_file(histfile)
 207    except IOError:
 208        pass
 209    import atexit
 210    atexit.register(readline.write_history_file, histfile)
 211    del os, histfile
 212
 213 The following example extends the :class:`code.InteractiveConsole` class to
 214 support history save/restore. ::
 215
 216    import code
 217    import readline
 218    import atexit
 219    import os
 220
 221    class HistoryConsole(code.InteractiveConsole):
 222        def __init__(self, locals=None, filename="<console>",
 223                     histfile=os.path.expanduser("~/.console-history")):
 224            code.InteractiveConsole.__init__(self)
 225            self.init_history(histfile)
 226
 227        def init_history(self, histfile):
 228            readline.parse_and_bind("tab: complete")
 229            if hasattr(readline, "read_history_file"):
 230                try:
 231                    readline.read_history_file(histfile)
 232                except IOError:
 233                    pass
 234                atexit.register(self.save_history, histfile)
 235
 236        def save_history(self, histfile):
 237            readline.write_history_file(histfile)
 238