util.command module

Command objects serve to encapsulate actions so that they may be used in an undo/redo list, typically mapped to cmd-z and shift-cmd-Z keys (or ctl-z for non-Mac). They are also extended in the commandParser for use in command line applications using the argparse module.

This module defines the following command hierarchy:

Inheritance diagram of Command, LambdaCommand, CommandWrapper, DoList

Command abstract (requires do(), undo(), __str__())

LambdaCommand

CommandWrapper

DoList

Created on Sep 16, 2024

Code author: Rob Kremer <robkremer@me.com>

exception util.command.RedoError

Bases: RuntimeError

exception util.command.UndoError

Bases: RuntimeError

class util.command.Command(name: str)

Bases: ABC

The top-level object for do/undo command objects. The minimal interface for these are are and __init__(name:str) constructor and the zero-parameter do() and undo() methods. The do() and undo() methods are specified as abstract; however, they have implementations that check to so they are not called back-to-back without the other between them and that do() is called before undo(), so you may want to call the relevant super() methods.

__init__(name: str)

Constructor

Parameters:

name (str)

abstractmethod do() → Any

The execution of this command. This isn’t really abstract in the you can (should?) call this method as the first instruction of your do() method to check that the do() isn’t being called twice in a row without an undo() in between (a problem in the code logic?).

Returns:

Return type:

Any

abstractmethod undo() → Any

The undoing of this command. This isn’t really abstract in the you can (should?) call this method as the first instruction of your undo() method to check that the undo() isn’t being called twice in a row without an do() in between (a problem in the code logic?).

Returns:

Return type:

Any

delete()

Override to destroy any data when the the command becomes unreachable. Called from DoList when new commands override the tail of the do-queue.

__str__()
Returns:

Return type:

_abc_impl = <_abc._abc_data object>
class util.command.LambdaCommand(name: str, do: Callable[[], NoReturn], undo: Callable[[], NoReturn], changesState=True)

Bases: Command

A alternative to implementing a new class overriding the do() and undo() methods. Instead this class’s constructor takes “do” and “undo” zero-parameter function references (typically lambda functions) and merely calls them in the do() and undo() methods. Typical instantiation:

incr = LambdaCommand(“inc”, lambda x=num: x.inc(), lambda x=num: x.dec())

__init__(name: str, do: Callable[[], NoReturn], undo: Callable[[], NoReturn], changesState=True)
Parameters:

  • name (str)

  • do (Callable[[], NoReturn])

  • undo (Callable[[], NoReturn])

  • changesState (bool)

do() → Any
Returns:

Return type:

Any

undo() → Any
Returns:

Return type:

Any

__str__()
Returns:

Return type:

_abc_impl = <_abc._abc_data object>
class util.command.CommandWrapper(command: Command, name: str | None = None, setup: Callable | None = None, teardown: Callable | None = None, initSetup: Callable | None = None, initTeardown: Callable | None = None)

Bases: Command

A Command wrapper that always executes a setup function before a do() and undo() and a teardown function after (if the setup and teardown are supplied).

__init__(command: Command, name: str | None = None, setup: Callable | None = None, teardown: Callable | None = None, initSetup: Callable | None = None, initTeardown: Callable | None = None)
Parameters:

  • command – A Command to wrap.

  • name – [Optional] The name of the command; provided by Command if None.

  • setup – [Optional] A function to execute before a do() or undo() call on command

  • teardown – [Optional] A function to execute after a do() or undo() call on command

  • initSetup – [Optional] Like setup but only called on the first do() (before setup )

  • initTeardown – [Optional] Like teardown but only called on the first do() (after teardown )

command: Command
setup: Callable | None
teardown: Callable | None
initSetup: Callable | None
initTeardown: Callable | None
do() → Any

Calls the following functions specified in this object’s constructor (if the are not None):

  • initSetup() if this is the first call to do()

  • setup() always

  • command.do() always

  • teardown() always

  • initTeardown() if this is the first call to do()

Returns:

Return type:

Any

undo() → Any

Calls the following functions specified in this object’s constructor (if the are not None):

  • setup()

  • command.undo()

  • teardown()

Returns:

Return type:

Any

__str__()
Returns:

Return type:

_abc_impl = <_abc._abc_data object>
class util.command.DoList

Bases: object

A do/undo list responsible to execute Commands, keeping track of do’s and undo’s.

__init__()
queue: list[Command]
do(c: Command) → Any

Appends a new Command after the current place in the queue and calls do() on that Command, possibly removing the tail of the queue if the current index is not past the end of the queue (eg: we have done one or more undo()’s).

Parameters:

c (Command)

Returns:

Return type:

Any

redo() → Any
Raises:

RedoError – if trying to redo past the end of the command queue.

Returns:

Return type:

Any

undo() → Any
Raises:

UndoError – if trying to undo an empty command queue.

Returns:

Return type:

Any

getRedoDesc() → str

Returns a description of the command that will be executed on a redo(), or None if nothing to redo.

Returns:

Return type:

str

getUndoDesc() → str

Returns a description of the command that will be executed on a undo(), or None if nothing to undo.

Returns:

Return type:

str

undoQueue() → list[str]

Returns a list of string representation of the commands in the undo list starting with the next to the undone.

Returns:

Return type:

list[str]

redoQueue() → list[str]

Returns a list of string representation of the commands in the redo list starting with the next to the redone.

Returns:

Return type:

list[str]

nextUndo() → str

Returns the string representation of the next command to be undone.

Returns:

Return type:

str

nextRedo()

Returns the string representation of the next command to be redone.

Returns:

Return type: