Skip to content

# cmd2.command_set

## `` cmd2.command_set

Supports the definition of commands in separate classes to be composed into cmd2.Cmd.

### `` CommandSet

    CommandSet()

Bases: `Generic[CmdT]`

Base class for defining sets of commands to load in cmd2.

`do_`, `help_`, and `complete_` functions differ only in that self is the CommandSet instead of the cmd2 app.

This class is generic over the `Cmd` type it is expected to be loaded into. By providing the specific `Cmd` subclass as a type argument (e.g., `class MyCommandSet(CommandSet[MyApp]):`), type checkers will know the exact type of `self._cmd`, allowing for autocompletion and type validation when accessing custom attributes and methods on the main application instance.

Private reference to the CLI instance in which this CommandSet running.

This will be set when the CommandSet is registered and it should be accessed by child classes using the self._cmd property.

Source code in `cmd2/command_set.py`

    33
    34
    35
    36
    37
    38
    39
    40
    41
    42

    def __init__(self) -> None:
        """Private reference to the CLI instance in which this CommandSet running.

        This will be set when the CommandSet is registered and it should be
        accessed by child classes using the self._cmd property.
        """
        self._cmd_internal: CmdT | None = None

        self._settables: dict[str, Settable] = {}
        self._settable_prefix = self.__class__.__name__

#### `` DEFAULT_CATEGORY `class-attribute`

    DEFAULT_CATEGORY = 'CommandSet Commands'

#### `` settable_prefix `property`

    settable_prefix

Read-only accessor for the underlying private settable_prefix field.

#### `` settables `property`

    settables

Read-only accessor for the underlying private settables field.

#### `` on_register

    on_register(cmd)

First step to registering a CommandSet, called by cmd2.Cmd.

The commands defined in this class have not been added to the CLI object at this point. Subclasses can override this to perform any initialization requiring access to the Cmd object (e.g. configure commands and their parsers based on CLI state data).

PARAMETER | DESCRIPTION
--- | ---
`cmd` | The cmd2 main application TYPE: `CmdT`

RAISES | DESCRIPTION
--- | ---
`CommandSetRegistrationError` | if CommandSet is already registered.

Source code in `cmd2/command_set.py`

    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74

    def on_register(self, cmd: CmdT) -> None:
        """First step to registering a CommandSet, called by cmd2.Cmd.

        The commands defined in this class have not been added to the CLI object at this point.
        Subclasses can override this to perform any initialization requiring access to the Cmd object
        (e.g. configure commands and their parsers based on CLI state data).

        :param cmd: The cmd2 main application
        :raises CommandSetRegistrationError: if CommandSet is already registered.
        """
        if self._cmd_internal is not None:
            raise CommandSetRegistrationError("This CommandSet has already been registered")
        self._cmd_internal = cmd

#### `` on_registered

    on_registered()

2nd step to registering, called by cmd2.Cmd after a CommandSet is registered and all its commands have been added.

Subclasses can override this to perform custom steps related to the newly added commands (e.g. setting them to a disabled state).

Source code in `cmd2/command_set.py`

    76
    77
    78
    79
    80
    81

    def on_registered(self) -> None:
        """2nd step to registering, called by cmd2.Cmd after a CommandSet is registered and all its commands have been added.

        Subclasses can override this to perform custom steps related to the newly added commands (e.g. setting
        them to a disabled state).
        """

#### `` on_unregister

    on_unregister()

First step to unregistering a CommandSet, called by `cmd2.Cmd`.

Subclasses can override this to perform any cleanup steps which require their commands being registered in the CLI.

Source code in `cmd2/command_set.py`

    83
    84
    85
    86
    87

    def on_unregister(self) -> None:
        """First step to unregistering a CommandSet, called by ``cmd2.Cmd``.

        Subclasses can override this to perform any cleanup steps which require their commands being registered in the CLI.
        """

#### `` on_unregistered

    on_unregistered()

2nd step to unregistering, called by `cmd2.Cmd` after a CommandSet is unregistered and all its commands removed.

Subclasses can override this to perform remaining cleanup steps.

Source code in `cmd2/command_set.py`

    89
    90
    91
    92
    93
    94

    def on_unregistered(self) -> None:
        """2nd step to unregistering, called by ``cmd2.Cmd`` after a CommandSet is unregistered and all its commands removed.

        Subclasses can override this to perform remaining cleanup steps.
        """
        self._cmd_internal = None

#### `` add_settable

    add_settable(settable)

Add a settable parameter to the CommandSet.

PARAMETER | DESCRIPTION
--- | ---
`settable` | Settable object being added TYPE: `Settable`

Source code in `cmd2/command_set.py`

    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118

    def add_settable(self, settable: Settable) -> None:
        """Add a settable parameter to the CommandSet.

        :param settable: Settable object being added
        """
        if (cmd := self._cmd_internal) is not None:
            # Determine the name to check for collisions in the main app
            check_name = settable.name if not cmd.always_prefix_settables else f"{self._settable_prefix}.{settable.name}"

            if check_name in cmd.settables and settable.name not in self._settables:
                raise KeyError(f"Duplicate settable: {settable.name}")

        self._settables[settable.name] = settable

#### `` remove_settable

    remove_settable(name)

Remove a settable parameter from the CommandSet.

PARAMETER | DESCRIPTION
--- | ---
`name` | name of the settable being removed TYPE: `str`

RAISES | DESCRIPTION
--- | ---
`KeyError` | if the Settable matches this name

Source code in `cmd2/command_set.py`

    120
    121
    122
    123
    124
    125
    126
    127
    128
    129

    def remove_settable(self, name: str) -> None:
        """Remove a settable parameter from the CommandSet.

        :param name: name of the settable being removed
        :raises KeyError: if the Settable matches this name
        """
        try:
            del self._settables[name]
        except KeyError as exc:
            raise KeyError(name + " is not a settable parameter") from exc

#### `` sigint_handler

    sigint_handler()

Handle a SIGINT that occurred for a command in this CommandSet.

RETURNS | DESCRIPTION
--- | ---
`bool` | True if this completes the interrupt handling and no KeyboardInterrupt will be raised. False to raise a KeyboardInterrupt.

Source code in `cmd2/command_set.py`

    131
    132
    133
    134
    135
    136
    137

    def sigint_handler(self) -> bool:
        """Handle a SIGINT that occurred for a command in this CommandSet.

        :return: True if this completes the interrupt handling and no KeyboardInterrupt will be raised.
                 False to raise a KeyboardInterrupt.
        """
        return False