Class Settable

cmd2/utils.py:67–161

Used to configure an attribute to be settable via the set command in the CLI.

class Settable:
    """Used to configure an attribute to be settable via the set command in the CLI."""

    def __init__(
        self,
        name: str,
        val_type: type[Any] | Callable[[Any], Any],
        description: str,
        settable_object: object,
        *,
        settable_attrib_name: str | None = None,
        onchange_cb: Callable[[str, Any, Any], Any] | None = None,
        choices: Iterable[Any] | None = None,
        choices_provider: UnboundChoicesProvider[CmdOrSetT] | None = None,
        completer: UnboundCompleter[CmdOrSetT] | None = None,
    ) -> None:
        """Settable Initializer.

        :param name: The user-facing name for this setting in the CLI.
        :param val_type: A callable used to cast the string value from the CLI into its
                         proper type and validate it. This function should raise an
                         exception (like ValueError or TypeError) if the conversion or
                         validation fails, which will be caught and displayed to the user
                         by the set command. For example, setting this to int ensures the
                         input is a valid integer. Specifying bool automatically provides
                         completion for 'true' and 'false' and uses a built-in function
                         for conversion and validation.
        :param description: A concise string that describes the purpose of this setting.
        :param settable_object: The object that owns the attribute being made settable (e.g. self).
        :param settable_attrib_name: The name of the attribute on the settable_object that
                                     will be modified. This defaults to the value of the name
                                     parameter if not specified.
        :param onchange_cb: An optional function or method to call when the value of this
                            setting is altered by the set command. The callback is invoked
                            only if the new value is different from the old one.

                            It receives three arguments:
                                param_name: str - name of the parameter
                                old_value: Any - the parameter's old value
                                new_value: Any - the parameter's new value

        The following optional settings provide completion for a parameter's values.
        They correspond to the same settings in argparse-based completion. A maximum
        of one of these should be provided.

        :param choices: iterable of accepted values
        :param choices_provider: function that provides choices for this argument
        :param completer: completion function that provides choices for this argument
        """
        if val_type is bool:
            from .completion import Choices

            def get_bool_choices(_cmd2_self: CmdOrSet) -> Choices:
                """Tab complete lowercase boolean values."""
                return Choices.from_values(["true", "false"])

            val_type = to_bool
            choices_provider = get_bool_choices