/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
 11The :mod:`readline` module defines a number of functions to facilitate
 12completion and reading/writing of history files from the Python interpreter.
 13This module can be used directly or via the :mod:`rlcompleter` module.  Settings
 14made using  this module affect the behaviour of both the interpreter's
 15interactive prompt  and the prompts offered by the :func:`raw_input` and
 16:func:`input` built-in functions.
 17
 18The :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
194Example
195-------
196
197The following example demonstrates how to use the :mod:`readline` module's
198history reading and writing functions to automatically load and save a history
199file named :file:`.pyhist` from the user's home directory.  The code below would
200normally 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
213The following example extends the :class:`code.InteractiveConsole` class to
214support 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