Completion Support

Readline completion support.

Completer Interface

class rl.Completer

Interface to the readline completer. Used to configure the completion aspects of readline.

This class is not intended for instantiation beyond the one completer object in this module. Typically, applications will import the completer object and use its properties and methods to configure readline:

from rl import completer

completer.quote_characters = '"\''
completer.query_items = 100
completer.parse_and_bind('TAB: complete')

Settings made through the completer object are global and permanent. If you want them restored you have to take care of it yourself.

Completer.quote_characters: Characters that may be used in pairs to quote substrings of the line.

Completer.word_break_characters: Characters that define word boundaries (a.k.a. delimiters).

Completer.special_prefixes: Characters that are word break characters but should be left in the word passed to the completion entry function.

Completer.filename_quote_characters: Characters that must be quoted when they occur in filenames.

Completer.inhibit_completion: If True, completion is disabled and the completion character is inserted as any other character. Defaults to False.

Completer.query_items: Threshold above which the user is prompted if they really want to see all matches. Defaults to 100. A negative value means never prompt.

Completer.completer: 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 for text. See the generator() factory for a simple way to support this protocol.

Completer.startup_hook: The startup hook function. The function is called with no arguments just before readline prints the first prompt.

Completer.pre_input_hook: 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.

Completer.word_break_hook: The word break hook function. The function is called as function(begidx, endidx) once per completion and should return a string of word break characters for the current completion or None to indicate no change. The passed-in begidx and endidx are what readline would use if the hook did not exist.

Completer.char_is_quoted_function: The char-is-quoted function. The function is called as function(text, index) and should return True if the character at index is quoted, False otherwise.

Completer.filename_quoting_function: The filename quoting function. The function is called as function(text, single_match, quote_char) and should return 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.

Completer.filename_dequoting_function: The filename dequoting function. The function is called as function(text, quote_char) and should return a dequoted version of text or None to indicate no change.

Completer.directory_completion_hook: The directory completion hook function. 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.

Completer.ignore_some_completions_function: The filename filter function. The function is called as function(substitution, matches) after all filenames have been generated and should return a filtered subset of matches or None to indicate no change.

Completer.display_matches_hook: The display matches hook function. The function is called as function(substitution, matches, longest_match_length) once each time matches need to be displayed. It typically calls display_match_list() to do the actual work. Note that longest_match_length is not a character count but the “printed length” of the longest string in matches.

Completer.read_init_file(filename=None): Parse a readline initialization file. The default filename is the last filename used.

Completer.parse_and_bind(line): Parse one line of a readline initialization file.

Additional hooks for when the filesystem representation differs from the representation in the terminal

Completer.directory_rewrite_hook

The directory rewrite hook function. This hook is used to prepare the directory 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. New in readline 6.2.

Under Python 3 this hook returns filesystem encoding to readline.

Completer.filename_rewrite_hook

The filename rewrite hook function. This hook 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. New in readline 6.1.

Under Python 3 this hook returns preferred encoding to readline.

Completer.filename_stat_hook

The filename stat hook function. This hook 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 or None to indicate no change. New in readline 6.3.

Under Python 3 this hook returns filesystem encoding to readline.

Note

If directory_rewrite_hook and/or filename_stat_hook are set, the directory_completion_hook must be None, and vice versa.

Completion Interface

class rl.Completion

Interface to the active readline completion. Used to interact with readline when a completion is in progress.

This class is not intended for instantiation beyond the one completion object in this module. Typically, applications will import the completion object and use its properties and methods when implementing custom completions:

from rl import completion

def complete(text):
    completion.append_character = '@'
    return completion.complete_username(text)

Settings made through the completion object are only valid for the duration of the current completion. They are reset to their defaults when a new completion starts.

Completion.line_buffer: The line buffer readline uses. This property may be assigned to to change the contents of the line.

Completion.completion_type: The type of completion readline performs.

Completion.begidx: The start index of the word in the line.

Completion.endidx: The end index of the word in the line.

Completion.found_quote: True if the word contains or is delimited by any quote character, including backslashes.

Completion.quote_character: The quote character found (not including backslashes).

Completion.suppress_quote: Do not append a matching quote character when completing a quoted string. Defaults to False.

Completion.append_character: The character appended when the completion returns a single match. Defaults to the space character.

Completion.suppress_append: Suppress the append character for this completion. Defaults to False.

Completion.filename_completion_desired: Treat matches as filenames. Directory names will have a slash appended, for example. Defaults to False. Set to True by complete_filename().

Completion.filename_quoting_desired: If matches are filenames, quote them. Defaults to True. Has no effect if filename_completion_desired is False.

Completion.complete_filename(text): Built-in filename completion. May be called from a completion entry function to initiate readline’s filename completion. Returns a list of matches.

Completion.complete_username(text): Built-in username completion. May be called from a completion entry function to initiate readline’s username completion. Returns a list of matches.

Completion.expand_tilde(text): Built-in tilde expansion. May be called from anywhere to tilde-expand a filename.

Completion.display_match_list(substitution, matches, longest_match_length): Built-in matches display. May be called from a custom display_matches_hook to perform the default action: columnar display of matches.

Completion.redisplay(force=False): Update the screen to reflect the current contents of line_buffer. If force is True, readline redisplays the prompt area as well as the line.

Functions

rl.generator(func)

Generator function factory.

Takes a function returning a list of matches and returns an object implementing the generator protocol readline requires. The function is called as function(text) and should return an iterable of matches for text.

rl.print_exc(func)

Decorator printing exceptions to stderr.

Useful when debugging completions and hooks, as exceptions occurring there are usually swallowed by the in-between C code.