Completion System

clitic provides a completion system with pluggable providers.

Completion

Dataclass representing a single completion suggestion.

class clitic.completion.Completion(text: str, display_text: str, cursor_offset: int = 0, description: str = '', priority: int = 0, metadata: dict[str, ~typing.Any]=<factory>)[source]

Bases: object

Represents a single completion suggestion.

text

The text to insert when the completion is selected.

Type:: str

display_text

The text to display in the completion dropdown.

Type:: str

cursor_offset

Offset to move cursor after insertion (default 0).

Type:: int

description

Optional description shown in the dropdown.

Type:: str

priority

Priority for ordering (higher = shown first).

Type:: int

metadata

Additional data associated with the completion.

Type:: dict[str, Any]

text: str

display_text: str

cursor_offset: int = 0

description: str = ''

priority: int = 0

metadata: dict[str, Any]

Creating Completions

from clitic.completion import Completion

# Basic completion
completion = Completion(
    text="print",
    display_text="print()"
)

# With details
completion = Completion(
    text="function_name",
    display_text="function_name(args)",
    cursor_offset=-1,  # Cursor before closing paren
    description="Call function",
    priority=10,
    metadata={"type": "function"}
)

CompletionProvider

Base class for completion providers.

class clitic.completion.CompletionProvider[source]

Bases: ABC

Abstract base class for completion providers.

Completion providers generate completion suggestions based on the current input context. They are called as the user types to provide context-aware completions.

name: Human-readable name of the provider.

priority: Priority for provider ordering (higher = preferred).

abstract property name: str: Return the human-readable name of this provider.

property priority: int

Return the priority for this provider.

Higher priority providers are queried first. Default is 0.

Returns:: Priority value (higher = more preferred).

abstractmethod get_completions(text: str, cursor_position: int) → list[Completion][source]

Get completion suggestions for the current input.

Parameters:

text – Current input text.
cursor_position – Current cursor position in the text.

Returns:

List of Completion suggestions, sorted by priority.

async get_completions_async(text: str, cursor_position: int) → list[Completion][source]

Asynchronously get completion suggestions.

Default implementation calls the synchronous method. Subclasses may override for async completion generation.

Parameters:

text – Current input text.
cursor_position – Current cursor position in the text.

Returns:

List of Completion suggestions, sorted by priority.

Creating a Completion Provider

from clitic.completion import CompletionProvider, Completion

class PathCompletionProvider(CompletionProvider):
    @property
    def name(self) -> str:
        return "path"

    @property
    def priority(self) -> int:
        return 10

    def get_completions(self, text: str, cursor_position: int) -> list[Completion]:
        # Return completions based on current context
        completions = []

        # Check if we're in a path context
        if "/" in text or text.startswith("~"):
            # Find files matching pattern
            for path in find_matching_paths(text):
                completions.append(Completion(
                    text=path,
                    display_text=path,
                    priority=5
                ))

        return completions

    async def get_completions_async(self, text: str, cursor_position: int) -> list[Completion]:
        # Async version for slow sources
        return self.get_completions(text, cursor_position)

Completion Ordering

Completions are sorted by:

Priority (higher first)
Display text (alphabetically)

This ensures the most relevant completions appear first.

Using with InputBar

from clitic import App
from clitic.completion import CompletionProvider

class MyCompletionProvider(CompletionProvider):
    # ... implementation ...

app = App()
# InputBar will use registered providers
# (integration coming in future versions)