← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.11-docs-html/_sources/library/readline.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

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