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:
get_completion_type()
returns a string.get_completion_append_character()
defaults to the space character.get_history_item()
is zero-based.redisplay()
accepts an optionalforce
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:
readline_version()
returns the readline library version as an integer.read_key()
reads a character from the keyboard.stuff_char()
stuffs a character into the input stream.complete_internal()
executes the completer. Used in tests.
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.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.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_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_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_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_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_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_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.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
, whereMM
is the major andmm
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.replace_history_item(pos, string) None ¶
Replace history item given by its position with string.
- 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 atindex
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)
, forstate
in 0, 1, 2, …, until it returns None. It should return the next possible completion starting withtext
.
- 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_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 asfunction(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_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 oftext
, 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 oftext
, or None to indicate no change. Thesingle_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 asfunction(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.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.username_completion_function(text, state) string ¶
A built-in generator function for username completion.