Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`readline` --- GNU readline interface |
| 2 | ========================================== |
| 3 | |
| 4 | .. module:: readline |
| 5 | :platform: Unix |
| 6 | :synopsis: GNU readline support for Python. |
Christian Heimes | 895627f | 2007-12-08 17:28:33 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Skip Montanaro <skip@pobox.com> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 14 | interactive prompt and the prompts offered by the built-in :func:`input` |
| 15 | function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Ezio Melotti | 6e40e27 | 2010-01-04 09:29:10 +0000 | [diff] [blame] | 17 | .. note:: |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 23 | of GNU readline. If you programmatically load configuration strings |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 24 | you can check for the text "libedit" in :const:`readline.__doc__` |
| 25 | to differentiate between GNU readline and libedit. |
| 26 | |
| 27 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Benjamin Peterson | 33f8f15 | 2014-11-26 13:58:16 -0600 | [diff] [blame] | 62 | .. function:: append_history_file(nelements[, filename]) |
| 63 | |
| 64 | Append the last *nelements* of history to a file. The default filename is |
| 65 | :file:`~/.history`. The file must already exist. |
| 66 | |
| 67 | .. versionadded:: 3.5 |
| 68 | |
| 69 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | .. function:: clear_history() |
| 71 | |
| 72 | Clear the current history. (Note: this function is not available if the |
| 73 | installed version of GNU readline doesn't support it.) |
| 74 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
| 76 | .. function:: get_history_length() |
| 77 | |
| 78 | Return the desired length of the history file. Negative values imply unlimited |
| 79 | history file size. |
| 80 | |
| 81 | |
| 82 | .. function:: set_history_length(length) |
| 83 | |
| 84 | Set the number of lines to save in the history file. :func:`write_history_file` |
| 85 | uses this value to truncate the history file when saving. Negative values imply |
| 86 | unlimited history file size. |
| 87 | |
| 88 | |
| 89 | .. function:: get_current_history_length() |
| 90 | |
| 91 | Return the number of lines currently in the history. (This is different from |
| 92 | :func:`get_history_length`, which returns the maximum number of lines that will |
| 93 | be written to a history file.) |
| 94 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
| 96 | .. function:: get_history_item(index) |
| 97 | |
| 98 | Return the current contents of history item at *index*. |
| 99 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | .. function:: remove_history_item(pos) |
| 102 | |
| 103 | Remove history item specified by its position from the history. |
| 104 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
| 106 | .. function:: replace_history_item(pos, line) |
| 107 | |
| 108 | Replace history item specified by its position with the given line. |
| 109 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
| 111 | .. function:: redisplay() |
| 112 | |
| 113 | Change what's displayed on the screen to reflect the current contents of the |
| 114 | line buffer. |
| 115 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | .. function:: set_startup_hook([function]) |
| 118 | |
| 119 | Set or remove the startup_hook function. If *function* is specified, it will be |
| 120 | used as the new startup_hook function; if omitted or ``None``, any hook function |
| 121 | already installed is removed. The startup_hook function is called with no |
| 122 | arguments just before readline prints the first prompt. |
| 123 | |
| 124 | |
| 125 | .. function:: set_pre_input_hook([function]) |
| 126 | |
| 127 | Set or remove the pre_input_hook function. If *function* is specified, it will |
| 128 | be used as the new pre_input_hook function; if omitted or ``None``, any hook |
| 129 | function already installed is removed. The pre_input_hook function is called |
| 130 | with no arguments after the first prompt has been printed and just before |
| 131 | readline starts reading input characters. |
| 132 | |
| 133 | |
| 134 | .. function:: set_completer([function]) |
| 135 | |
| 136 | Set or remove the completer function. If *function* is specified, it will be |
| 137 | used as the new completer function; if omitted or ``None``, any completer |
| 138 | function already installed is removed. The completer function is called as |
| 139 | ``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it |
| 140 | returns a non-string value. It should return the next possible completion |
| 141 | starting with *text*. |
| 142 | |
| 143 | |
| 144 | .. function:: get_completer() |
| 145 | |
| 146 | Get the completer function, or ``None`` if no completer function has been set. |
| 147 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 149 | .. function:: get_completion_type() |
| 150 | |
| 151 | Get the type of completion being attempted. |
| 152 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 153 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | .. function:: get_begidx() |
| 155 | |
| 156 | Get the beginning index of the readline tab-completion scope. |
| 157 | |
| 158 | |
| 159 | .. function:: get_endidx() |
| 160 | |
| 161 | Get the ending index of the readline tab-completion scope. |
| 162 | |
| 163 | |
| 164 | .. function:: set_completer_delims(string) |
| 165 | |
| 166 | Set the readline word delimiters for tab-completion. |
| 167 | |
| 168 | |
| 169 | .. function:: get_completer_delims() |
| 170 | |
| 171 | Get the readline word delimiters for tab-completion. |
| 172 | |
Georg Brandl | 6554cb9 | 2007-12-02 23:15:43 +0000 | [diff] [blame] | 173 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 174 | .. function:: set_completion_display_matches_hook([function]) |
| 175 | |
| 176 | Set or remove the completion display function. If *function* is |
| 177 | specified, it will be used as the new completion display function; |
| 178 | if omitted or ``None``, any completion display function already |
| 179 | installed is removed. The completion display function is called as |
| 180 | ``function(substitution, [matches], longest_match_length)`` once |
| 181 | each time matches need to be displayed. |
| 182 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 183 | |
| 184 | .. function:: add_history(line) |
| 185 | |
| 186 | Append a line to the history buffer, as if it was the last line typed. |
| 187 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 188 | .. seealso:: |
| 189 | |
| 190 | Module :mod:`rlcompleter` |
| 191 | Completion of Python identifiers at the interactive prompt. |
| 192 | |
| 193 | |
| 194 | .. _readline-example: |
| 195 | |
| 196 | Example |
| 197 | ------- |
| 198 | |
| 199 | The following example demonstrates how to use the :mod:`readline` module's |
| 200 | history reading and writing functions to automatically load and save a history |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 201 | file named :file:`.python_history` from the user's home directory. The code |
| 202 | below would normally be executed automatically during interactive sessions |
| 203 | from the user's :envvar:`PYTHONSTARTUP` file. :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 204 | |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 205 | import atexit |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 206 | import os |
Georg Brandl | a102ae3 | 2010-10-06 05:08:32 +0000 | [diff] [blame] | 207 | import readline |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 208 | |
| 209 | histfile = os.path.join(os.path.expanduser("~"), ".python_history") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 210 | try: |
| 211 | readline.read_history_file(histfile) |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 212 | except FileNotFoundError: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | pass |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 214 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | atexit.register(readline.write_history_file, histfile) |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 216 | |
| 217 | This code is actually automatically run when Python is run in |
| 218 | :ref:`interactive mode <tut-interactive>` (see :ref:`rlcompleter-config`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 219 | |
Benjamin Peterson | 33f8f15 | 2014-11-26 13:58:16 -0600 | [diff] [blame] | 220 | The following example achieves the same goal but supports concurrent interactive |
| 221 | sessions, by only appending the new history. :: |
| 222 | |
| 223 | import atexit |
| 224 | import os |
| 225 | import realine |
| 226 | histfile = os.path.join(os.path.expanduser("~"), ".python_history") |
| 227 | |
| 228 | try: |
| 229 | readline.read_history_file(histfile) |
| 230 | h_len = readline.get_history_length() |
| 231 | except FileNotFoundError: |
| 232 | open(histfile, 'wb').close() |
| 233 | h_len = 0 |
| 234 | |
| 235 | def save(prev_h_len, histfile): |
| 236 | new_h_len = readline.get_history_length() |
| 237 | readline.append_history_file(new_h_len - prev_h_len, histfile) |
| 238 | atexit.register(save, h_len, histfile) |
| 239 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | The following example extends the :class:`code.InteractiveConsole` class to |
| 241 | support history save/restore. :: |
| 242 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 243 | import atexit |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 244 | import code |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 245 | import os |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 246 | import readline |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
| 248 | class HistoryConsole(code.InteractiveConsole): |
| 249 | def __init__(self, locals=None, filename="<console>", |
| 250 | histfile=os.path.expanduser("~/.console-history")): |
Georg Brandl | ee8783d | 2009-09-16 16:00:31 +0000 | [diff] [blame] | 251 | code.InteractiveConsole.__init__(self, locals, filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 252 | self.init_history(histfile) |
| 253 | |
| 254 | def init_history(self, histfile): |
| 255 | readline.parse_and_bind("tab: complete") |
| 256 | if hasattr(readline, "read_history_file"): |
| 257 | try: |
| 258 | readline.read_history_file(histfile) |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 259 | except FileNotFoundError: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 260 | pass |
| 261 | atexit.register(self.save_history, histfile) |
| 262 | |
| 263 | def save_history(self, histfile): |
| 264 | readline.write_history_file(histfile) |