Class CompletionItem

cmd2/completion.py:45–170

A single completion result.

@dataclass(frozen=True, slots=True, kw_only=True)
class CompletionItem:
    """A single completion result."""

    # Regular expression to identify whitespace characters that are rendered as
    # control sequences (like ^J or ^I) in the completion menu.
    _CONTROL_WHITESPACE_RE = re.compile(r"\r\n|[\n\r\t\f\v]")

    # The source input for the completion. This is used to initialize the 'text'
    # field (defaults to str(value)). The original object is also preserved to
    # support object-based validation when this CompletionItem is used as an
    # argparse choice.
    value: Any = field(kw_only=False)

    # The string matched against user input and inserted into the command line.
    # Defaults to str(value). This should only be set manually if this
    # CompletionItem is used as an argparse choice and you want the choice
    # string to differ from str(value).
    text: str = _UNSET_STR

    # Optional string for displaying the completion differently in the completion menu.
    # This can contain ANSI style sequences. A plain version is stored in display_plain.
    # If not provided, defaults to the (possibly computed) value of 'text'.
    display: str = _UNSET_STR

    # Optional meta information about completion which displays in the completion menu.
    # This can contain ANSI style sequences. A plain version is stored in display_meta_plain.
    display_meta: str = ""

    # Optional data for completion tables. Length must match the associated argparse
    # argument's table_columns. This is stored internally as a tuple.
    table_data: Sequence[Any] = field(default_factory=tuple)

    # Plain text versions of display fields (stripped of ANSI) for sorting/filtering.
    display_plain: str = field(default="", init=False)
    display_meta_plain: str = field(default="", init=False)

    @classmethod
    def _clean_display(cls, val: str) -> str:
        """Clean a string for display in the completion menu.

        This replaces whitespace characters that are rendered as
        control sequences (like ^J or ^I) with spaces.

        :param val: string to be cleaned
        :return: the cleaned string
        """
        return cls._CONTROL_WHITESPACE_RE.sub(" ", val)

    def __post_init__(self) -> None:
        """Finalize the object after initialization.

        By using the sentinel pattern to distinguish between a field that was never
        set and one explicitly blanked out, this handles the two-stage lifecycle:

        1. Initial creation (usually by a developer-provided choices_provider or completer).
        2. Post-processing by cmd2 via dataclasses.replace(), which may modify fields or
           explicitly set them to empty strings.
        """