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. |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 12 | This module can be used directly, or via the :mod:`rlcompleter` module, which |
| 13 | supports completion of Python identifiers at the interactive prompt. Settings |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | made using this module affect the behaviour of both the interpreter's |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 15 | interactive prompt and the prompts offered by the built-in :func:`input` |
| 16 | function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | |
Ezio Melotti | 6e40e27 | 2010-01-04 09:29:10 +0000 | [diff] [blame] | 18 | .. note:: |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 19 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 20 | The underlying Readline library API may be implemented by |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 21 | the ``libedit`` library instead of GNU readline. |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 22 | On MacOS X the :mod:`readline` module detects which library is being used |
| 23 | at run time. |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 24 | |
| 25 | The configuration file for ``libedit`` is different from that |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 26 | of GNU readline. If you programmatically load configuration strings |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 27 | you can check for the text "libedit" in :const:`readline.__doc__` |
| 28 | to differentiate between GNU readline and libedit. |
| 29 | |
| 30 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 31 | Init file |
| 32 | --------- |
| 33 | |
| 34 | The following functions relate to the init file and user configuration: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | |
| 36 | |
| 37 | .. function:: parse_and_bind(string) |
| 38 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 39 | Execute the init line provided in the *string* argument. This calls |
| 40 | :c:func:`rl_parse_and_bind` in the underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
| 42 | |
| 43 | .. function:: read_init_file([filename]) |
| 44 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 45 | Execute a readline initialization file. The default filename is the last filename |
| 46 | used. This calls :c:func:`rl_read_init_file` in the underlying library. |
| 47 | |
| 48 | |
| 49 | Line buffer |
| 50 | ----------- |
| 51 | |
| 52 | The following functions operate on the line buffer: |
| 53 | |
| 54 | |
| 55 | .. function:: get_line_buffer() |
| 56 | |
| 57 | Return the current contents of the line buffer (:c:data:`rl_line_buffer` |
| 58 | in the underlying library). |
| 59 | |
| 60 | |
| 61 | .. function:: insert_text(string) |
| 62 | |
| 63 | Insert text into the line buffer at the cursor position. This calls |
| 64 | :c:func:`rl_insert_text` in the underlying library, but ignores |
| 65 | the return value. |
| 66 | |
| 67 | |
| 68 | .. function:: redisplay() |
| 69 | |
| 70 | Change what's displayed on the screen to reflect the current contents of the |
| 71 | line buffer. This calls :c:func:`rl_redisplay` in the underlying library. |
| 72 | |
| 73 | |
| 74 | History file |
| 75 | ------------ |
| 76 | |
| 77 | The following functions operate on a history file: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | |
| 80 | .. function:: read_history_file([filename]) |
| 81 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 82 | Load a readline history file, and append it to the history list. |
| 83 | The default filename is :file:`~/.history`. This calls |
| 84 | :c:func:`read_history` in the underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | |
| 87 | .. function:: write_history_file([filename]) |
| 88 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 89 | Save the history list to a readline history file, overwriting any |
| 90 | existing file. The default filename is :file:`~/.history`. This calls |
| 91 | :c:func:`write_history` in the underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | |
Benjamin Peterson | 33f8f15 | 2014-11-26 13:58:16 -0600 | [diff] [blame] | 94 | .. function:: append_history_file(nelements[, filename]) |
| 95 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 96 | Append the last *nelements* items of history to a file. The default filename is |
| 97 | :file:`~/.history`. The file must already exist. This calls |
| 98 | :c:func:`append_history` in the underlying library. |
Benjamin Peterson | 33f8f15 | 2014-11-26 13:58:16 -0600 | [diff] [blame] | 99 | |
| 100 | .. versionadded:: 3.5 |
| 101 | |
| 102 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 103 | .. function:: get_history_length() |
| 104 | set_history_length(length) |
| 105 | |
| 106 | Set or return the desired number of lines to save in the history file. |
| 107 | The :func:`write_history_file` function uses this value to truncate |
| 108 | the history file, by calling :c:func:`history_truncate_file` in |
| 109 | the underlying library. Negative values imply |
| 110 | unlimited history file size. |
| 111 | |
| 112 | |
| 113 | History list |
| 114 | ------------ |
| 115 | |
| 116 | The following functions operate on a global history list: |
| 117 | |
| 118 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | .. function:: clear_history() |
| 120 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 121 | Clear the current history. This calls :c:func:`clear_history` in the |
| 122 | underlying library. The Python function only exists if Python was |
| 123 | compiled for a version of the library that supports it. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
| 125 | |
| 126 | .. function:: get_current_history_length() |
| 127 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 128 | Return the number of items currently in the history. (This is different from |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | :func:`get_history_length`, which returns the maximum number of lines that will |
| 130 | be written to a history file.) |
| 131 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
| 133 | .. function:: get_history_item(index) |
| 134 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 135 | Return the current contents of history item at *index*. The item index |
| 136 | is one-based. This calls :c:func:`history_get` in the underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 137 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
| 139 | .. function:: remove_history_item(pos) |
| 140 | |
| 141 | Remove history item specified by its position from the history. |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 142 | The position is zero-based. This calls :c:func:`remove_history` in |
| 143 | the underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
| 146 | .. function:: replace_history_item(pos, line) |
| 147 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 148 | Replace history item specified by its position with *line*. |
| 149 | The position is zero-based. This calls :c:func:`replace_history_entry` |
| 150 | in the underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 153 | .. function:: add_history(line) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 155 | Append *line* to the history buffer, as if it was the last line typed. |
| 156 | This calls :c:func:`add_history` in the underlying library. |
| 157 | |
| 158 | |
| 159 | Startup hooks |
| 160 | ------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 161 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 162 | |
| 163 | .. function:: set_startup_hook([function]) |
| 164 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 165 | Set or remove the function invoked by the :c:data:`rl_startup_hook` |
| 166 | callback of the underlying library. If *function* is specified, it will |
| 167 | be used as the new hook function; if omitted or ``None``, any function |
| 168 | already installed is removed. The hook is called with no |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | arguments just before readline prints the first prompt. |
| 170 | |
| 171 | |
| 172 | .. function:: set_pre_input_hook([function]) |
| 173 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 174 | Set or remove the function invoked by the :c:data:`rl_pre_input_hook` |
| 175 | callback of the underlying library. If *function* is specified, it will |
| 176 | be used as the new hook function; if omitted or ``None``, any |
| 177 | function already installed is removed. The hook is called |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 178 | with no arguments after the first prompt has been printed and just before |
| 179 | readline starts reading input characters. |
| 180 | |
| 181 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 182 | Completion |
| 183 | ---------- |
| 184 | |
| 185 | The following functions relate to implementing a custom word completion |
| 186 | function. This is typically operated by the Tab key, and can suggest and |
| 187 | automatically complete a word being typed. By default, Readline is set up |
| 188 | to be used by :mod:`rlcompleter` to complete Python identifiers for |
| 189 | the interactive interpreter. If the :mod:`readline` module is to be used |
| 190 | with a custom completer, a different set of word delimiters should be set. |
| 191 | |
| 192 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 193 | .. function:: set_completer([function]) |
| 194 | |
| 195 | Set or remove the completer function. If *function* is specified, it will be |
| 196 | used as the new completer function; if omitted or ``None``, any completer |
| 197 | function already installed is removed. The completer function is called as |
| 198 | ``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it |
| 199 | returns a non-string value. It should return the next possible completion |
| 200 | starting with *text*. |
| 201 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 202 | The installed completer function is invoked by the *entry_func* callback |
| 203 | passed to :c:func:`rl_completion_matches` in the underlying library. |
| 204 | The *text* string comes from the first parameter to the |
| 205 | :c:data:`rl_attempted_completion_function` callback of the |
| 206 | underlying library. |
| 207 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | |
| 209 | .. function:: get_completer() |
| 210 | |
| 211 | Get the completer function, or ``None`` if no completer function has been set. |
| 212 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 214 | .. function:: get_completion_type() |
| 215 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 216 | Get the type of completion being attempted. This returns the |
| 217 | :c:data:`rl_completion_type` variable in the underlying library as |
| 218 | an integer. |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 219 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 220 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 221 | .. function:: get_begidx() |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 222 | get_endidx() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 223 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 224 | Get the beginning or ending index of the completion scope. |
| 225 | These indexes are the *start* and *end* arguments passed to the |
| 226 | :c:data:`rl_attempted_completion_function` callback of the |
| 227 | underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 228 | |
| 229 | |
| 230 | .. function:: set_completer_delims(string) |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 231 | get_completer_delims() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 233 | Set or get the word delimiters for completion. These determine the |
| 234 | start of the word to be considered for completion (the completion scope). |
| 235 | These functions access the :c:data:`rl_completer_word_break_characters` |
| 236 | variable in the underlying library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | |
Georg Brandl | 6554cb9 | 2007-12-02 23:15:43 +0000 | [diff] [blame] | 238 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 239 | .. function:: set_completion_display_matches_hook([function]) |
| 240 | |
| 241 | Set or remove the completion display function. If *function* is |
| 242 | specified, it will be used as the new completion display function; |
| 243 | if omitted or ``None``, any completion display function already |
Martin Panter | 0f76739 | 2016-04-05 07:37:22 +0000 | [diff] [blame] | 244 | installed is removed. This sets or clears the |
| 245 | :c:data:`rl_completion_display_matches_hook` callback in the |
| 246 | underlying library. The completion display function is called as |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 247 | ``function(substitution, [matches], longest_match_length)`` once |
| 248 | each time matches need to be displayed. |
| 249 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 250 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 251 | .. _readline-example: |
| 252 | |
| 253 | Example |
| 254 | ------- |
| 255 | |
| 256 | The following example demonstrates how to use the :mod:`readline` module's |
| 257 | history reading and writing functions to automatically load and save a history |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 258 | file named :file:`.python_history` from the user's home directory. The code |
| 259 | below would normally be executed automatically during interactive sessions |
| 260 | from the user's :envvar:`PYTHONSTARTUP` file. :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 261 | |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 262 | import atexit |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | import os |
Georg Brandl | a102ae3 | 2010-10-06 05:08:32 +0000 | [diff] [blame] | 264 | import readline |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 265 | |
| 266 | histfile = os.path.join(os.path.expanduser("~"), ".python_history") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 267 | try: |
| 268 | readline.read_history_file(histfile) |
Ezio Melotti | 7c018aa | 2016-01-11 23:30:56 +0200 | [diff] [blame] | 269 | # default history len is -1 (infinite), which may grow unruly |
| 270 | readline.set_history_length(1000) |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 271 | except FileNotFoundError: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 272 | pass |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 273 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 274 | atexit.register(readline.write_history_file, histfile) |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 275 | |
| 276 | This code is actually automatically run when Python is run in |
| 277 | :ref:`interactive mode <tut-interactive>` (see :ref:`rlcompleter-config`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 278 | |
Benjamin Peterson | 33f8f15 | 2014-11-26 13:58:16 -0600 | [diff] [blame] | 279 | The following example achieves the same goal but supports concurrent interactive |
| 280 | sessions, by only appending the new history. :: |
| 281 | |
| 282 | import atexit |
| 283 | import os |
Berker Peksag | 964ec8b | 2015-11-01 00:55:12 +0300 | [diff] [blame] | 284 | import readline |
Benjamin Peterson | 33f8f15 | 2014-11-26 13:58:16 -0600 | [diff] [blame] | 285 | histfile = os.path.join(os.path.expanduser("~"), ".python_history") |
| 286 | |
| 287 | try: |
| 288 | readline.read_history_file(histfile) |
| 289 | h_len = readline.get_history_length() |
| 290 | except FileNotFoundError: |
| 291 | open(histfile, 'wb').close() |
| 292 | h_len = 0 |
| 293 | |
| 294 | def save(prev_h_len, histfile): |
| 295 | new_h_len = readline.get_history_length() |
Ezio Melotti | 7c018aa | 2016-01-11 23:30:56 +0200 | [diff] [blame] | 296 | readline.set_history_length(1000) |
Benjamin Peterson | 33f8f15 | 2014-11-26 13:58:16 -0600 | [diff] [blame] | 297 | readline.append_history_file(new_h_len - prev_h_len, histfile) |
| 298 | atexit.register(save, h_len, histfile) |
| 299 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 300 | The following example extends the :class:`code.InteractiveConsole` class to |
| 301 | support history save/restore. :: |
| 302 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 303 | import atexit |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 304 | import code |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 305 | import os |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 306 | import readline |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 307 | |
| 308 | class HistoryConsole(code.InteractiveConsole): |
| 309 | def __init__(self, locals=None, filename="<console>", |
| 310 | histfile=os.path.expanduser("~/.console-history")): |
Georg Brandl | ee8783d | 2009-09-16 16:00:31 +0000 | [diff] [blame] | 311 | code.InteractiveConsole.__init__(self, locals, filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 312 | self.init_history(histfile) |
| 313 | |
| 314 | def init_history(self, histfile): |
| 315 | readline.parse_and_bind("tab: complete") |
| 316 | if hasattr(readline, "read_history_file"): |
| 317 | try: |
| 318 | readline.read_history_file(histfile) |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 319 | except FileNotFoundError: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 320 | pass |
| 321 | atexit.register(self.save_history, histfile) |
| 322 | |
| 323 | def save_history(self, histfile): |
Ezio Melotti | 7c018aa | 2016-01-11 23:30:56 +0200 | [diff] [blame] | 324 | readline.set_history_length(1000) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | readline.write_history_file(histfile) |