Completion Support

Readline completion support.

Completer Interface

class rl.Completer

Interface to the readline completer.

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 (aka delimiters).

Completer.special_prefixes

Characters that are word break characters but should be left in the word passed to the completer.

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 he really wants to see all matches. Defaults to 100. A negative value means never prompt. The prompt is bypassed if a custom display_matches_hook is installed.

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 (and will use if the hook returns None).

Completer.directory_completion_hook

The directory completion 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.

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.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 (may be used to close quotes).

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.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.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.

Completer.reset()

Reset all completer variables to their default values.

Completion Interface

class rl.Completion

Interface to the active readline completion.

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 the results of matches as filenames. Directory names will have a slash appended, for example. Defaults to False.

Completion.filename_quoting_desired

If results are filenames, quote them. Defaults to True. Has no effect if filename_completion_desired is False.

Completion.rl_point

The position of the cursor in the line.

Completion.rl_end

The last position in the line. The cursor range is defined as: 0 <= rl_point <= rl_end

Completion.complete_filename(text)

Built-in filename completion.

Completion.complete_username(text)

Built-in username completion.

Completion.expand_tilde(text)

Built-in tilde expansion.

Completion.display_match_list(substitution, matches, longest_match_length)

Built-in matches display.

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.

Completion.reset()

Reset all completion variables to their default values.

Helper 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 func(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.