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