Patterns of Python: Encountering the Command Pattern

Table of Contents

1. Understanding the Command Pattern: What and Why?
2. Core Components of the Command Pattern
3. When to Use the Command Pattern
4. Implementing the Command Pattern in Python: A Step-by-Step Example
5. Advanced Use Cases: Undo/Redo and Macros
6. Pros and Cons
7. Real-World Applications
8. Common Pitfalls and Best Practices
9. Conclusion
10. References

1. Understanding the Command Pattern: What and Why?

The Command Pattern is a behavioral design pattern that turns a request into a stand-alone object. This object encapsulates all information needed to execute the request, including:

• The method to call.
• The arguments to pass.
• The receiver (the object that performs the actual work).

By wrapping requests in objects, the pattern decouples the sender (the code that triggers the request) from the receiver (the code that performs the action). This decoupling unlocks powerful capabilities:

• Queueing or logging requests: Commands can be stored in a list and executed later (e.g., task queues).
• Undo/redo functionality: Commands can track their inverse operations.
• Extensibility: New commands can be added without modifying existing sender or receiver code.

2. Core Components of the Command Pattern

The Command Pattern relies on five key participants. Let’s define each with their role:

3. When to Use the Command Pattern

Use the Command Pattern when:

• You need to parameterize objects with actions (e.g., GUI buttons that trigger different actions).
• You need to queue, log, or replay requests (e.g., job schedulers, transaction logs).
• You need undo/redo functionality (e.g., text editors, graphic design tools).
• You want to decouple senders and receivers (e.g., allowing multiple senders to trigger the same receiver without tight coupling).

4. Implementing the Command Pattern in Python: A Step-by-Step Example

Let’s build a simple smart home remote control to demonstrate the Command Pattern. Our remote will have buttons to control devices like lights and fans.

Step 1: Define the Command Interface

First, we’ll create an abstract base class (ABC) for the Command interface. This ensures all concrete commands implement an execute() method.

from abc import ABC, abstractmethod

class Command(ABC):
    @abstractmethod
    def execute(self):
        pass

Step 2: Create Receiver Classes

Receivers perform the actual work. Let’s define Light and Fan receivers with methods to turn on/off.

class Light:
    def __init__(self, room: str):
        self.room = room

    def turn_on(self):
        print(f"{self.room} light is ON")

    def turn_off(self):
        print(f"{self.room} light is OFF")

class Fan:
    def __init__(self, room: str):
        self.room = room
        self.speed = 0  # 0=off, 1=low, 2=medium, 3=high

    def turn_on(self, speed: int = 1):
        self.speed = speed
        print(f"{self.room} fan is ON at speed {self.speed}")

    def turn_off(self):
        self.speed = 0
        print(f"{self.room} fan is OFF")

Step 3: Implement ConcreteCommand Classes

Concrete commands bind receivers to actions. For example, LightOnCommand will trigger Light.turn_on().

class LightOnCommand(Command):
    def __init__(self, light: Light):
        self.light = light  # Reference to the receiver

    def execute(self):
        self.light.turn_on()  # Call the receiver's method

class LightOffCommand(Command):
    def __init__(self, light: Light):
        self.light = light

    def execute(self):
        self.light.turn_off()

class FanOnCommand(Command):
    def __init__(self, fan: Fan, speed: int = 1):
        self.fan = fan
        self.speed = speed

    def execute(self):
        self.fan.turn_on(self.speed)

class FanOffCommand(Command):
    def __init__(self, fan: Fan):
        self.fan = fan

    def execute(self):
        self.fan.turn_off()

Step 4: Create the Invoker (Remote Control)

The Invoker (remote control) stores commands and triggers their execute() method when a button is pressed.

class RemoteControl:
    def __init__(self, num_buttons: int = 2):
        self.commands = [None] * num_buttons  # List to store commands for each button

    def set_command(self, button_index: int, command: Command):
        """Assign a command to a button."""
        if 0 <= button_index < len(self.commands):
            self.commands[button_index] = command

    def press_button(self, button_index: int):
        """Trigger the command for a button."""
        if 0 <= button_index < len(self.commands) and self.commands[button_index]:
            self.commands[button_index].execute()

Step 5: The Client Sets It All Up

The client creates receivers, concrete commands, and assigns commands to the invoker (remote).

def main():
    # Create receivers
    living_room_light = Light("Living Room")
    bedroom_fan = Fan("Bedroom")

    # Create concrete commands
    light_on = LightOnCommand(living_room_light)
    light_off = LightOffCommand(living_room_light)
    fan_high = FanOnCommand(bedroom_fan, speed=3)
    fan_off = FanOffCommand(bedroom_fan)

    # Create invoker (remote) and assign commands to buttons
    remote = RemoteControl(num_buttons=4)
    remote.set_command(0, light_on)    # Button 0: Turn on living room light
    remote.set_command(1, light_off)   # Button 1: Turn off living room light
    remote.set_command(2, fan_high)    # Button 2: Turn on bedroom fan (high)
    remote.set_command(3, fan_off)     # Button 3: Turn off bedroom fan

    # Test the remote
    print("Pressing Button 0...")
    remote.press_button(0)  # Output: "Living Room light is ON"

    print("\nPressing Button 2...")
    remote.press_button(2)  # Output: "Bedroom fan is ON at speed 3"

    print("\nPressing Button 1...")
    remote.press_button(1)  # Output: "Living Room light is OFF"

    print("\nPressing Button 3...")
    remote.press_button(3)  # Output: "Bedroom fan is OFF"

if __name__ == "__main__":
    main()

Output

Pressing Button 0...
Living Room light is ON

Pressing Button 2...
Bedroom fan is ON at speed 3

Pressing Button 1...
Living Room light is OFF

Pressing Button 3...
Bedroom fan is OFF

5. Advanced Use Cases: Undo/Redo and Macros

The Command Pattern shines with advanced features like undo/redo and macros. Let’s extend our example to support these.

Adding Undo Functionality

To enable undo, modify the Command interface to include an undo() method. Concrete commands will track the receiver’s state before execution to reverse the action.

class Command(ABC):
    @abstractmethod
    def execute(self):
        pass

    @abstractmethod
    def undo(self):
        pass  # New: Reverse the execute() action

Update LightOnCommand and LightOffCommand to track the light’s previous state:

class LightOnCommand(Command):
    def __init__(self, light: Light):
        self.light = light
        self.previous_state = False  # Track if light was off before execution

    def execute(self):
        self.previous_state = False  # Assume light was off (simplified)
        self.light.turn_on()

    def undo(self):
        if self.previous_state:
            self.light.turn_on()
        else:
            self.light.turn_off()

class LightOffCommand(Command):
    def __init__(self, light: Light):
        self.light = light
        self.previous_state = True  # Track if light was on before execution

    def execute(self):
        self.previous_state = True  # Assume light was on (simplified)
        self.light.turn_off()

    def undo(self):
        if self.previous_state:
            self.light.turn_on()
        else:
            self.light.turn_off()

Update the RemoteControl to track the last command for undo:

class RemoteControl:
    def __init__(self, num_buttons: int = 2):
        self.commands = [None] * num_buttons
        self.last_command: Command | None = None  # Track last executed command

    def press_button(self, button_index: int):
        if 0 <= button_index < len(self.commands) and self.commands[button_index]:
            self.last_command = self.commands[button_index]  # Save last command
            self.commands[button_index].execute()

    def press_undo(self):
        """Undo the last command."""
        if self.last_command:
            print("Undoing last action...")
            self.last_command.undo()

Now, test undo:

# In main() after setting up the remote:
print("\nPressing Button 0...")
remote.press_button(0)  # Light ON

print("\nPressing Undo...")
remote.press_undo()     # Light OFF (undo)

Output:

Pressing Button 0...
Living Room light is ON

Pressing Undo...
Undoing last action...
Living Room light is OFF

Macro Commands

A macro command executes a sequence of commands. For example, a “Good Morning” macro could turn on the light, start the fan, and play music.

class MacroCommand(Command):
    def __init__(self, commands: list[Command]):
        self.commands = commands

    def execute(self):
        for cmd in self.commands:
            cmd.execute()

    def undo(self):
        for cmd in reversed(self.commands):  # Undo in reverse order
            cmd.undo()

# Usage:
good_morning_commands = [light_on, fan_high]
good_morning_macro = MacroCommand(good_morning_commands)
remote.set_command(4, good_morning_macro)  # Assign macro to button 4
remote.press_button(4)  # Executes both light_on and fan_high

6. Pros and Cons

Pros

• Decouples senders and receivers: Senders (e.g., remote buttons) don’t need to know about receivers (e.g., lights).
• Supports undo/redo: Commands can track state to reverse actions.
• Extensible: Add new commands without modifying existing code (Open/Closed Principle).
• Queues and logs: Commands can be stored in lists for delayed execution or logging.

Cons

• Increased complexity: Requires creating multiple classes (one per command), which can bloat code for simple use cases.
• Overhead: Wrapping simple actions in command objects adds minor performance overhead.
• Learning curve: New developers may find the pattern unintuitive for trivial tasks.

7. Real-World Applications

• GUI Frameworks: Buttons, menus, and shortcuts use commands (e.g., QAction in Qt).
• Task Queues: Tools like Celery or RQ treat tasks as commands to be executed asynchronously.
• Text Editors: Undo/redo stacks rely on command objects to reverse/restore actions.
• Database Transactions: Commands represent database operations, with undo/redo for rollbacks.
• Remote Procedure Calls (RPC): Commands can serialize requests to be executed on remote servers.

8. Common Pitfalls and Best Practices

Pitfalls

• Overusing the pattern: For simple actions (e.g., a single function call), a command object is unnecessary. Use Python functions directly instead.
• Inconsistent Command interfaces: Failing to standardize execute() or undo() across commands can break invokers.
• State management for undo: Tracking state in commands can become complex for nested or dependent actions.

Best Practices

• Keep commands lightweight: Commands should focus on invoking receiver methods, not contain business logic.
• Use ABCs for the Command interface: Enforce execute() (and undo()) with abstract methods.
• Document command intent: Name commands clearly (e.g., LightOnCommand instead of Cmd1).
• Handle exceptions: Wrap execute() calls in try/except blocks to avoid breaking queues or macros.

9. Conclusion

The Command Pattern transforms actions into objects, unlocking flexibility in how we execute, queue, and reverse operations. While it adds some complexity, its benefits—decoupling, undo/redo, and extensibility—make it invaluable for applications like GUI tools, task schedulers, and transactional systems.

In Python, the pattern can be implemented cleanly with ABCs and first-class functions, though it’s important to avoid overengineering. By understanding when and how to apply the Command Pattern, you’ll write code that’s more modular, maintainable, and adaptable to change.

10. References

• Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley.
• Nesteruk, D. (2018). Python Design Patterns. Packt Publishing.
• Real Python: Design Patterns in Python
• Python ABC Documentation
• Refactoring Guru: Command Pattern