Complete

This module provides autocompletion functionality for widgets and CLI.

Completer basics

All completers are derived from the Completer base class with a simple interface:

class yuio.complete.Completer

An interface for text completion providers.

complete(text: str, pos: int, /, *, do_corrections: bool = True) → List[Completion]

Complete the given text at the given cursor position.

Parameters:

• text – text that is being completed.

• pos – position of the cursor in the text. 0 means the cursor is before the first character, len(text) means the cursor is after the last character.

• do_corrections – if True (default), completion system will try to guess if there are any misspells in the text, and offer to correct them.

class yuio.complete.Completion(iprefix: str, completion: str, rsuffix: str, rsymbols: str, isuffix: str, comment: str | None, dprefix: str, dsuffix: str, group_id: SupportsLt[Any], group_color_tag: str | None)

A single completion.

iprefix: str

See CompletionCollector.iprefix for details.

completion: str

Text of the completion.

rsuffix: str

See CompletionCollector.rsuffix for details.

rsymbols: str

See CompletionCollector.rsymbols for details.

isuffix: str

See CompletionCollector.isuffix for details.

comment: str | None

Short comment displayed alongside the completion.

dprefix: str

Prefix that will be displayed before completion when listing completions, but will not be inserted once completion is applied.

dsuffix: str

Like dprefix, but it’s a suffix.

group_id: SupportsLt[Any]

Group id, used to sort completions.

Actual content of this property is an implementation detail.

group_color_tag: str | None

Color tag that’s used when displaying this completion.

See CompletionCollector.add_group() for details.

Completers

Yuio provides basic completers that cover most of the cases:

class yuio.complete.Empty

An empty completer that returns no values.

class yuio.complete.Choice(choices: Collection[Option], /)

Completes input from a predefined list of completions.

class yuio.complete.Option(completion: str, comment: str | None = None)

A single completion option for the Choice completer.

class yuio.complete.List(inner: Completer, /, *, delimiter: str | None = None, allow_duplicates: bool = False)

Completes a value-separated list of elements.

class yuio.complete.Tuple(*inners: Completer, delimiter: str | None = None)

Completes a value-separated tuple of elements.

class yuio.complete.File(extensions: str | Collection[str] | None = None)

class yuio.complete.Dir

Implementing your own completer

To implement a custom completer, subclass Completer and implement its _process() method.

Note

When using a custom completer for CLI flags in yuio.app, yuio will pickle it, and integrate it into a shell script that provides command line completions.

class yuio.complete.Completer

abstract _process(collector: CompletionCollector, /)

Generate completions and add them to the given collector.

Implementing this class is straight forward, just feed all possible completions to the collector. For example, let’s implement a completer for environment variables:

class EnvVarCompleter(Completer):
    def _process(self, collector: CompletionCollector):
        for var in os.environ.keys():
            collector.add(var)

The core of the completion system, however, is a CompletionCollector. This is the class that is responsible for generating a final list of completions:

class yuio.complete.CompletionCollector(text: str, pos: int, /)

A class that collects completions as completers are running.

The text that is being completed is split into four parts, similar to what you might see in ZSH completion widgets. The main two are:

prefix: str

Portion of the completed text before the cursor.

suffix: str

Portion of the completed text after the cursor.

When completions are added to the collector, they are checked against the current prefix to determine if they match the entered text. If they do, the completion system will replace text from prefix and suffix with the new completion string.

The two additional parts are:

iprefix: str

Contains text that goes before the prefix.

This prefix is not considered when checking whether a completion matches a text, and it is not replaced by the completion. It will also not be shown in the table of completions.

This prefix starts empty, and then parts of prefix are moved to iprefix as completers split it into list elements.

isuffix: str

Similar to CompletionCollector.iprefix, but for suffixes.

For example, suppose you’re completing a second element of a colon-separated list. The list completer will set up the collector so that prefix and suffix contain parts of the current list element, while iprefix and isuffix contain the rest of the elements:

list_element_1:list_el|ement_2:list_element_3
└┬────────────┘└┬────┘│└┬────┘└┬────────────┘
 iprefix       prefix │ suffix isuffix
                      └ cursor

Now, if the completer adds a completion 'list_elements', this text will replace the prefix and suffix, but not iprefix and isuffix. So, after the completion is applied, the string will look like so:

list_element_1:list_elements:list_element_3
               └┬──────────┘
                this got replaced

Finally, there is rsuffix:

rsuffix: str

Starts empty, and may be set to hold a list separator.

This suffix will be added after the completion. However, it will be automatically removed if the user types one of CompletionCollector.rsymbols, or moves cursor, or alters input in some other way.

rsymbols: str

So, when completing a colon-separated list, colons will be added and removed automatically, similar to how ZSH does it.

dedup_words: FrozenSet[str]

Completions from this set will not be added. This is useful when completing lists of unique values.

full_prefix

Portion of the final completed text that goes before the cursor.

full_suffix

Portion of the final completed text that goes after the cursor.

text

Portion of the text that is being autocompleted.

num_completions

Return number of completions that were added so far.

add(completion: str, /, *, comment: str | None = None, dprefix: str = '', dsuffix: str = '', color_tag: str | None = None)

Add a new completion.

Parameters:

• completion – completed text without iprefix and isuffix. This text will replace prefix and suffix.

• comment – additional comment that will be displayed near the completion.

• color_tag – allows overriding color tag from the group.

add_group(*, sorted: bool = True, color_tag: str | None = None)

Add a new completions group.

All completions added after call to this method will be placed to the new group. They will be grouped together, and colored according to the group’s color tag.

Parameters:

• sorted – controls whether completions in the new group should be sorted.

• color_tag –

  which color tag should be used to display completions and their help messages for this group.

  See yuio.widget.Option.color_tag for details.

save_state()

Save current state of the collector, i.e. prefixes, suffixes, etc., upon entering this context manager, then restore state upon exiting.

Use this context manager when you need to call nested completers more than once to prevent changes made in one nested completer bleeding out into another nested completer.

split_off_prefix(delim: str | None = None, /)

Move everything up to the last occurrence of delim from prefix to iprefix.

split_off_suffix(delim: str | None = None, /)

Move everything past the first occurrence of delim from suffix to isuffix.

finalize() → List[Completion]

Finish collecting completions and return everything that was collected.

Do not reuse a collector after it was finalized.