Readline Bindings

Importing this module enables command line editing using GNU Readline.

Readline Interface

The rl.readline module is an API-compatible replacement for the standard library’s readline bindings. The standard library documentation applies, with the following exceptions:

  1. get_completion_type() returns a string.

  2. get_completion_append_character() defaults to the space character.

  3. get_history_item() is zero-based.

  4. redisplay() accepts an optional force argument.

Beyond that, rl.readline adds a plethora of new functionality which is typically accessed through the high-level interfaces rl.completer, rl.completion, and rl.history. Functions not exposed through a high-level interface:

Note

It is possible to use rl.readline without the high-level APIs. To switch an existing application to rl, change occurrences of import readline to from rl import readline.

Note

Applications must not use the standard library readline and rl.readline simultaneously. This is because only one module can own the PyOS_ReadlineFunctionPointer.

Functions

rl.readline.add_history(string) None

Add a line to the readline history.

rl.readline.append_history_file(nelements[, filename]) None

Append the last nelements of the history to a readline history file. The default filename is ~/.history.

rl.readline.clear_history() None

Clear the current readline history.

rl.readline.complete_internal(what_to_do) int

Complete the word at or before the cursor position.

rl.readline.display_match_list(substitution, matches, longest_match_length) None

Display a list of matches in columnar format on readline’s output stream.

rl.readline.filename_completion_function(text, state) string

A built-in generator function for filename completion.

rl.readline.get_auto_history() bool

True if automatic history is enabled.

rl.readline.get_begidx() int

Get the beginning index of the readline tab-completion scope.

rl.readline.get_char_is_quoted_function() function

Get the function that determines whether or not a specific character in the line buffer is quoted.

rl.readline.get_completer() function

Get the current completion entry function.

rl.readline.get_completer_delims() string

Get the readline word delimiters for tab-completion.

rl.readline.get_completer_quote_characters() string

Get list of characters that may be used to quote a substring of the line.

rl.readline.get_completion_append_character() string

Get the character appended after the current completion.

rl.readline.get_completion_display_matches_hook() function

Get the current completion display function.

rl.readline.get_completion_found_quote() bool

When readline is completing quoted text, it sets this variable to True if the word being completed contains any quoting character (including backslashes).

rl.readline.get_completion_query_items() int

Up to this many items will be displayed in response to a possible-completions call.

rl.readline.get_completion_quote_character() string

When readline is completing quoted text, it sets this variable to the quoting character found.

rl.readline.get_completion_suppress_append() bool

Do not append the completion_append_character after the current completion.

rl.readline.get_completion_suppress_quote() bool

Do not append a matching quote character when performing completion on a quoted string.

rl.readline.get_completion_type() string

Get the type of completion being attempted.

rl.readline.get_completion_word_break_hook() function

A function to call when readline is deciding where to separate words for word completion.

rl.readline.get_current_history_length() int

Return the current (not the maximum) length of history.

rl.readline.get_directory_completion_hook() function

Get the current directory completion hook function.

rl.readline.get_directory_rewrite_hook() function

Get the current directory rewrite hook function.

rl.readline.get_endidx() int

Get the ending index of the readline tab-completion scope.

rl.readline.get_filename_completion_desired() bool

If True, treat the results of matches as filenames.

rl.readline.get_filename_dequoting_function() function

Get the current filename dequoting function.

rl.readline.get_filename_quote_characters() string

Get list of characters that cause a filename to be quoted by the completer.

rl.readline.get_filename_quoting_desired() bool

If True, filenames will be quoted.

rl.readline.get_filename_quoting_function() function

Get the current filename quoting function.

rl.readline.get_filename_rewrite_hook() function

Get the current filename rewrite hook function.

rl.readline.get_filename_stat_hook() function

Get the current filename stat hook function.

rl.readline.get_history_item(pos) string

Return the current contents of history item at pos.

rl.readline.get_history_iter() iterator

Return a forward iterator over the history (oldest to newest).

rl.readline.get_history_length() int

Return the maximum number of items written to the history file.

rl.readline.get_history_list() list

Return the entire history as a Python list. Element 0 of the list is the beginning of time.

rl.readline.get_history_max_entries() int

Return the current history size limit.

rl.readline.get_history_reverse_iter() iterator

Return a reverse iterator over the history (newest to oldest).

rl.readline.get_ignore_some_completions_function() function

This function may filter the results of filename completion.

rl.readline.get_inhibit_completion() bool

If True, completion is disabled.

rl.readline.get_line_buffer() string

Return the current contents of the line buffer.

rl.readline.get_pre_input_hook() function

Get the current pre_input_hook function.

rl.readline.get_rl_end() int

Return rl_end.

rl.readline.get_rl_point() int

Return rl_point.

rl.readline.get_special_prefixes() string

Characters that are word break characters, but should be left in text when it is passed to the completion function.

rl.readline.get_startup_hook() function

Get the current startup_hook function.

rl.readline.history_is_stifled() bool

True if a history size limit is set.

rl.readline.insert_text(string) None

Insert text into the command line.

rl.readline.parse_and_bind(string) None

Parse and execute single line of a readline init file.

rl.readline.read_history_file([filename]) None

Load a readline history file. The default filename is ~/.history.

rl.readline.read_init_file([filename]) None

Parse a readline initialization file. The default filename is the last filename used.

rl.readline.read_key() string

Read a key from readline’s input stream, typically the keyboard. Returns characters inserted with stuff_char() before starting to read from the stream.

rl.readline.readline_version() int

Return the readline library version encoded in an integer. The format is 0xMMmm, where MM is the major and mm the minor version number.

rl.readline.redisplay([force]) None

Update the screen to reflect the current contents of the line buffer. If force is True, readline redisplays the prompt area as well as the line.

rl.readline.remove_history_item(pos) None

Remove history item given by its position.

rl.readline.replace_history_item(pos, string) None

Replace history item given by its position with string.

rl.readline.replace_line(string) None

Replace the line buffer contents with string.

rl.readline.set_auto_history(bool) None

Enable or disable automatic history.

rl.readline.set_begidx(int) None

Set the beginning index of the readline tab-completion scope.

rl.readline.set_char_is_quoted_function([function]) None

Set or remove the function that determines whether or not a specific character in the line buffer is quoted. The function is called as function(text, index) and should return True if the character at index is quoted, and False otherwise.

rl.readline.set_completer([function]) None

Set or remove the completion entry function. The function is called as function(text, state), for state in 0, 1, 2, …, until it returns None. It should return the next possible completion starting with text.

rl.readline.set_completer_delims(string) None

Set the readline word delimiters for tab-completion.

rl.readline.set_completer_quote_characters(string) None

Set list of characters that may be used to quote a substring of the line.

rl.readline.set_completion_append_character(string) None

Set the character appended after the current completion. May only be called from within custom completers.

rl.readline.set_completion_display_matches_hook([function]) None

Set or remove the completion display function. The function is called as function(substitution, matches, longest_match_length) once each time matches need to be displayed.

rl.readline.set_completion_found_quote(bool) None

When readline is completing quoted text, it sets this variable to True if the word being completed contains any quoting character (including backslashes).

rl.readline.set_completion_query_items(int) None

Up to this many items will be displayed in response to a possible-completions call.

rl.readline.set_completion_quote_character(string) None

When readline is completing quoted text, it sets this variable to the quoting character found.

rl.readline.set_completion_suppress_append(bool) None

Do not append the completion_append_character after the current completion. May only be called from within custom completers.

rl.readline.set_completion_suppress_quote(bool) None

Do not append a matching quote character when performing completion on a quoted string. May only be called from within custom completers.

rl.readline.set_completion_type(string) None

Set the type of completion being attempted.

rl.readline.set_completion_word_break_hook([function]) None

A function to call when readline is deciding where to separate words for word completion. The function is called as function(begidx, endidx) once for every completion, and should return a string of word break characters for the current completion, or None to indicate no change.

rl.readline.set_directory_completion_hook([function]) None

This function is allowed to modify the directory portion of filenames readline completes. The function is called as function(dirname) and should return a new directory name or None to indicate no change. At the least, the function must perform all necessary dequoting.

rl.readline.set_directory_rewrite_hook([function]) None

This function is used to prepare the director name passed to opendir() during filename completion. The function is called as function(dirname) and should return a new directory name or None to indicate no change. At the least, the function must perform all necessary dequoting.

rl.readline.set_endidx(int) None

Set the ending index of the readline tab-completion scope.

rl.readline.set_filename_completion_desired(bool) None

If True, treat the results of matches as filenames. May only be called from within custom completers.

rl.readline.set_filename_dequoting_function([function]) None

Set or remove the filename dequoting function. The function is called as function(text, quote_char) and should return a string representing a dequoted version of text, or None to indicate no change.

rl.readline.set_filename_quote_characters(string) None

Set list of characters that cause a filename to be quoted by the completer.

rl.readline.set_filename_quoting_desired(bool) None

If True, filenames will be quoted. May only be called from within custom completers.

rl.readline.set_filename_quoting_function([function]) None

Set or remove the filename quoting function. The function is called as function(text, single_match, quote_char) and should return a string representing a quoted version of text, or None to indicate no change. The single_match argument is True if the completion has generated only one match.

rl.readline.set_filename_rewrite_hook([function]) None

This function is called for every filename before it is compared against the completion word. The function is called as function(filename) and should return a new filename or None to indicate no change.

rl.readline.set_filename_stat_hook([function]) None

This function is used to prepare the filename passed to stat() during match display. The function is called as function(filename) and should return a new filename name or None to indicate no change.

rl.readline.set_history_length(int) None

Set the maximum number of items written to the history file. A negative value inhibits history file truncation.

rl.readline.set_ignore_some_completions_function([function]) None

This function may filter the results of filename completion. The function is called as function(substitution, matches) and should return a filtered subset of matches or None to indicate no change.

rl.readline.set_inhibit_completion(bool) None

If True, completion is disabled and the completion character is inserted as any other character.

rl.readline.set_pre_input_hook([function]) None

Set or remove the pre_input_hook function. The function is called with no arguments after the first prompt has been printed and just before readline starts reading input characters.

rl.readline.set_special_prefixes(string) None

Characters that are word break characters, but should be left in text when it is passed to the completion function.

rl.readline.set_startup_hook([function]) None

Set or remove the startup_hook function. The function is called with no arguments just before readline prints the first prompt.

rl.readline.stifle_history(max_entries) None

Limit the history size to max_entries entries.

rl.readline.stuff_char(string) bool

Insert a character into readline’s input stream. Returns True if the insert was successful.

rl.readline.tilde_expand(string) string

Return a new string which is the result of tilde expanding string.

rl.readline.unstifle_history() int

Remove the history size limit.

rl.readline.username_completion_function(text, state) string

A built-in generator function for username completion.

rl.readline.write_history_file([filename]) None

Save a readline history file. The default filename is ~/.history.