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)