Skip to content

cmd2.completion

cmd2.completion

Provides classes and functions related to command-line completion.

CompletionItem dataclass 

CompletionItem(
    *,
    value,
    text=_UNSET_STR,
    display=_UNSET_STR,
    display_meta="",
    table_data=tuple(),
)

A single completion result.

value class-attribute instance-attribute 

value = field(kw_only=False)

text class-attribute instance-attribute 

text = _UNSET_STR

display class-attribute instance-attribute 

display = _UNSET_STR

display_meta class-attribute instance-attribute 

display_meta = ''

table_data class-attribute instance-attribute 

table_data = field(default_factory=tuple)

display_plain class-attribute instance-attribute 

display_plain = field(default='', init=False)

display_meta_plain class-attribute instance-attribute 

display_meta_plain = field(default='', init=False)

CompletionResultsBase dataclass 

CompletionResultsBase(*, items=tuple(), is_sorted=False)

Base class for results containing a collection of CompletionItems.

items class-attribute instance-attribute 

items = field(default_factory=tuple, kw_only=False)

is_sorted class-attribute instance-attribute 

is_sorted = False

numeric_display class-attribute instance-attribute 

numeric_display = field(default=False, init=False)

from_values classmethod 

from_values(values, *, is_sorted=False)

Create a CompletionItem instance from arbitrary objects.

PARAMETER DESCRIPTION
values

the raw objects (e.g. strs, ints, Paths) to be converted into CompletionItems.

TYPE: Iterable[Any]

is_sorted

whether the values are already in the desired order.

TYPE: bool DEFAULT: False

Source code in cmd2/completion.py 
218
219
220
221
222
223
224
225
226
@classmethod
def from_values(cls, values: Iterable[Any], *, is_sorted: bool = False) -> Self:
    """Create a CompletionItem instance from arbitrary objects.

    :param values: the raw objects (e.g. strs, ints, Paths) to be converted into CompletionItems.
    :param is_sorted: whether the values are already in the desired order.
    """
    items = [v if isinstance(v, CompletionItem) else CompletionItem(value=v) for v in values]
    return cls(items=items, is_sorted=is_sorted)

to_strings 

to_strings()

Return a tuple of the completion strings (the 'text' field of each item).

Source code in cmd2/completion.py 
228
229
230
def to_strings(self) -> tuple[str, ...]:
    """Return a tuple of the completion strings (the 'text' field of each item)."""
    return tuple(item.text for item in self.items)

Choices dataclass 

Choices(*, items=tuple(), is_sorted=False)

Bases: CompletionResultsBase

A collection of potential values available for completion, typically provided by a choice provider.

items class-attribute instance-attribute 

items = field(default_factory=tuple, kw_only=False)

is_sorted class-attribute instance-attribute 

is_sorted = False

numeric_display class-attribute instance-attribute 

numeric_display = field(default=False, init=False)

from_values classmethod 

from_values(values, *, is_sorted=False)

Create a CompletionItem instance from arbitrary objects.

PARAMETER DESCRIPTION
values

the raw objects (e.g. strs, ints, Paths) to be converted into CompletionItems.

TYPE: Iterable[Any]

is_sorted

whether the values are already in the desired order.

TYPE: bool DEFAULT: False

Source code in cmd2/completion.py 
218
219
220
221
222
223
224
225
226
@classmethod
def from_values(cls, values: Iterable[Any], *, is_sorted: bool = False) -> Self:
    """Create a CompletionItem instance from arbitrary objects.

    :param values: the raw objects (e.g. strs, ints, Paths) to be converted into CompletionItems.
    :param is_sorted: whether the values are already in the desired order.
    """
    items = [v if isinstance(v, CompletionItem) else CompletionItem(value=v) for v in values]
    return cls(items=items, is_sorted=is_sorted)

to_strings 

to_strings()

Return a tuple of the completion strings (the 'text' field of each item).

Source code in cmd2/completion.py 
228
229
230
def to_strings(self) -> tuple[str, ...]:
    """Return a tuple of the completion strings (the 'text' field of each item)."""
    return tuple(item.text for item in self.items)

Completions dataclass 

Completions(
    *,
    items=tuple(),
    is_sorted=False,
    hint="",
    error="",
    table=None,
    allow_finalization=True,
    _add_opening_quote=False,
    _search_text_offset=0,
    _quote_char="",
)

Bases: CompletionResultsBase

The results of a completion operation.

hint class-attribute instance-attribute 

hint = ''

error class-attribute instance-attribute 

error = ''

table class-attribute instance-attribute 

table = None

allow_finalization class-attribute instance-attribute 

allow_finalization = True

items class-attribute instance-attribute 

items = field(default_factory=tuple, kw_only=False)

is_sorted class-attribute instance-attribute 

is_sorted = False

numeric_display class-attribute instance-attribute 

numeric_display = field(default=False, init=False)

from_values classmethod 

from_values(values, *, is_sorted=False)

Create a CompletionItem instance from arbitrary objects.

PARAMETER DESCRIPTION
values

the raw objects (e.g. strs, ints, Paths) to be converted into CompletionItems.

TYPE: Iterable[Any]

is_sorted

whether the values are already in the desired order.

TYPE: bool DEFAULT: False

Source code in cmd2/completion.py 
218
219
220
221
222
223
224
225
226
@classmethod
def from_values(cls, values: Iterable[Any], *, is_sorted: bool = False) -> Self:
    """Create a CompletionItem instance from arbitrary objects.

    :param values: the raw objects (e.g. strs, ints, Paths) to be converted into CompletionItems.
    :param is_sorted: whether the values are already in the desired order.
    """
    items = [v if isinstance(v, CompletionItem) else CompletionItem(value=v) for v in values]
    return cls(items=items, is_sorted=is_sorted)

to_strings 

to_strings()

Return a tuple of the completion strings (the 'text' field of each item).

Source code in cmd2/completion.py 
228
229
230
def to_strings(self) -> tuple[str, ...]:
    """Return a tuple of the completion strings (the 'text' field of each item)."""
    return tuple(item.text for item in self.items)