5.4. State

• Changes based on class

• Open/Close principle

• Using polymorphism

The State design pattern is a behavioral design pattern that allows an object to change its behavior when its internal state changes. This pattern is close to the concept of finite-state machines. The main idea is to declare each possible state of an object as a separate class and extract all state-specific behaviors into these classes.

The State design pattern has several advantages:

1. Flexibility: It provides a way to define a family of behaviors within an object and change the behavior at runtime.

2. Encapsulation: Each state is encapsulated in its own class, which makes the code more maintainable and easier to understand.

3. Simplicity: It simplifies the code of the object that changes its behavior. Instead of having many conditional statements to determine what behavior to execute, the object can simply delegate this to the state object.

4. Open/Closed Principle: The State pattern adheres to the Open/Closed Principle as it allows introducing new states without changing the existing state classes or the context.

5. Localizing State-Specific Behavior: Each state class has all the behavior related to a particular state. This makes it easier to understand and modify the behavior associated with a particular state.

6. State Transitions: State transitions can be explicit and easy to understand because they are triggered by specific methods in the state classes.

7. Reducing State Transition Complexity: The pattern can also reduce the complexity of state transitions because the decision logic of the transition can be encapsulated within the state classes themselves.

5.4.1. Problem

>>> from enum import Enum
>>>
>>>
>>> class Tool(Enum):
...     PENCIL = 1
...     ERASER = 2
...     BRUSH = 3
>>>
>>>
>>> class Canvas:
...     tool: Tool | None
...
...     def __init__(self):
...         self.tool = None
...
...     def select_tool(self, tool: Tool):
...         self.tool = tool
...
...     def on_left_mouse_button(self):
...         match self.tool:
...             case Tool.PENCIL: print('Start drawing with pencil')
...             case Tool.ERASER: print('Start erasing with eraser')
...             case Tool.BRUSH:  print('Start painting with brush')
...             case _:           print('Invalid tool selected')
...
...     def on_right_mouse_button(self):
...         match self.tool:
...             case Tool.PENCIL: print('Stop drawing with pencil')
...             case Tool.ERASER: print('Stop erasing with eraser')
...             case Tool.BRUSH:  print('Stop painting with brush')
...             case _:           print('Invalid tool selected')

Usage:

>>> canvas = Canvas()
>>>
>>> canvas.select_tool(Tool.PENCIL)
>>> canvas.on_left_mouse_button()
Start drawing with pencil
>>> canvas.on_right_mouse_button()
Stop drawing with pencil
>>>
>>> canvas.select_tool(Tool.ERASER)
>>> canvas.on_left_mouse_button()
Start erasing with eraser
>>> canvas.on_right_mouse_button()
Stop erasing with eraser

5.4.2. Solution

>>> from abc import ABC, abstractmethod
>>>
>>>
>>> class Tool(ABC):
...     @abstractmethod
...     def on_left_mouse_button(self):
...         raise NotImplementedError
...
...     @abstractmethod
...     def on_right_mouse_button(self):
...         raise NotImplementedError
>>>
>>>
>>> class Pencil(Tool):
...     def on_left_mouse_button(self):
...         print('Start drawing with pencil')
...
...     def on_right_mouse_button(self):
...         print('Stop drawing with pencil')
>>>
>>> class Eraser(Tool):
...     def on_left_mouse_button(self):
...         print('Start erasing with eraser')
...
...     def on_right_mouse_button(self):
...         print('Stop erasing with eraser')
>>>
>>> class Brush(Tool):
...     def on_left_mouse_button(self):
...         print('Start painting with brush')
...
...     def on_right_mouse_button(self):
...         print('Stop painting with brush')
>>>
>>>
>>> class Canvas:
...     tool: Tool | None
...
...     def __init__(self):
...         self.tool = None
...
...     def select_tool(self, tool: Tool):
...         self.tool = tool
...
...     def on_left_mouse_button(self):
...         if not self.tool:
...             raise ValueError('Invalid tool selected')
...         return self.tool.on_left_mouse_button()
...
...     def on_right_mouse_button(self):
...         if not self.tool:
...             raise ValueError('Invalid tool selected')
...         return self.tool.on_right_mouse_button()

Usage:

>>> canvas = Canvas()
>>>
>>> canvas.select_tool(Pencil())
>>> canvas.on_left_mouse_button()
Start drawing with pencil
>>> canvas.on_right_mouse_button()
Stop drawing with pencil
>>>
>>> canvas.select_tool(Eraser())
>>> canvas.on_left_mouse_button()
Start erasing with eraser
>>> canvas.on_right_mouse_button()
Stop erasing with eraser

5.4.3. Case Study

• Canvas object can behave differently depending on selected Tool

• All behaviors are represented by subclass of the tool interface

Problem:

from enum import Enum


class Tool(Enum):
    SELECTION = 1
    PENCIL = 2
    ERASE = 3
    BRUSH = 4


class Window:
    current_tool: Tool

    def on_left_mouse_button(self):
        if self.current_tool == Tool.SELECTION:
            print('Select')
        elif self.current_tool == Tool.PENCIL:
            print('Draw')
        elif self.current_tool == Tool.ERASE:
            print('Erase')
        elif self.current_tool == Tool.BRUSH:
            print('Paint')

    def on_right_mouse_button(self):
        if self.current_tool == Tool.SELECTION:
            print('Unselect')
        elif self.current_tool == Tool.PENCIL:
            print('Stop drawing')
        elif self.current_tool == Tool.ERASE:
            print('Undo erase')
        elif self.current_tool == Tool.BRUSH:
            print('Stop painting')


if __name__ == '__main__':
    window = Window()

    window.current_tool = Tool.BRUSH
    window.on_left_mouse_button()
    window.on_right_mouse_button()

    window.current_tool = Tool.SELECTION
    window.on_left_mouse_button()
    window.on_right_mouse_button()

    window.current_tool = Tool.ERASE
    window.on_left_mouse_button()
    window.on_right_mouse_button()

# Paint
# Stop painting
# Select
# Unselect
# Erase
# Undo erase

Solution:

from abc import ABC, abstractmethod


## Abstract

class WindowEvents(ABC):
    @abstractmethod
    def on_left_mouse_button(self): ...

    @abstractmethod
    def on_right_mouse_button(self): ...


class Tool(WindowEvents, ABC):
    pass


## Tools

class SelectionTool(Tool):
    def on_left_mouse_button(self):
        print('Select')

    def on_right_mouse_button(self):
        print('Unselect')


class EraseTool(Tool):
    def on_left_mouse_button(self):
        print('Erase')

    def on_right_mouse_button(self):
        print('Undo erase')

class PencilTool(Tool):
    def on_left_mouse_button(self):
        print('Draw')

    def on_right_mouse_button(self):
        print('Stop drawing')

class BrushTool(Tool):
    def on_left_mouse_button(self):
        print('Paint')

    def on_right_mouse_button(self):
        print('Stop painting')


## Main

class Window(WindowEvents):
    current_tool: Tool

    def on_left_mouse_button(self):
        self.current_tool.on_left_mouse_button()

    def on_right_mouse_button(self):
        self.current_tool.on_right_mouse_button()


if __name__ == '__main__':
    window = Window()

    window.current_tool = BrushTool()
    window.on_left_mouse_button()
    window.on_right_mouse_button()

    window.current_tool = SelectionTool()
    window.on_left_mouse_button()
    window.on_right_mouse_button()

    window.current_tool = EraseTool()
    window.on_left_mouse_button()
    window.on_right_mouse_button()

# Paint
# Stop painting
# Select
# Unselect
# Erase
# Undo erase

Class Diagram:

5.4.4. Use Case - 1

Figure 5.2. GIMP (GNU Image Manipulation Project) window with tools and canvas [1]

>>> class Tool:
...     def on_mouse_over(self): raise NotImplementedError
...     def on_mouse_out(self): raise NotImplementedError
...     def on_mouse_click_leftbutton(self): raise NotImplementedError
...     def on_mouse_unclick_leftbutton(self): raise NotImplementedError
...     def on_mouse_click_rightbutton(self): raise NotImplementedError
...     def on_mouse_unclick_rightbutton(self): raise NotImplementedError
...     def on_key_press(self): raise NotImplementedError
...     def on_key_unpress(self): raise NotImplementedError
>>>
>>>
>>> class Pencil(Tool):
...     def on_mouse_over(self):
...         ...
...
...     def on_mouse_out(self):
...         ...
...
...     def on_mouse_click_leftbutton(self):
...         ...
...
...     def on_mouse_unclick_leftbutton(self):
...         ...
...
...     def on_mouse_click_rightbutton(self):
...         ...
...
...     def on_mouse_unclick_rightbutton(self):
...         ...
...
...     def on_key_press(self):
...         ...
...
...     def on_key_unpress(self):
...         ...
>>>
>>>
>>> class Pen(Tool):
...     def on_mouse_over(self):
...         ...
...
...     def on_mouse_out(self):
...         ...
...
...     def on_mouse_click_leftbutton(self):
...         ...
...
...     def on_mouse_unclick_leftbutton(self):
...         ...
...
...     def on_mouse_click_rightbutton(self):
...         ...
...
...     def on_mouse_unclick_rightbutton(self):
...         ...
...
...     def on_key_press(self):
...         ...
...
...     def on_key_unpress(self):
...         ...

5.4.5. References

[1]

Download GIMP. Year: 2022. Retrieved: 2022-08-11. URL: https://anderbot.com/wp-content/uploads/2020/10/GIMP5.jpg

5.4.6. Assignments

# %% About
# - Name: DesignPatterns Behavioral State
# - Difficulty: easy
# - Lines: 29
# - Minutes: 13

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% English
# 1. Modify class `Translation`
# 2. Implement State pattern
# 3. Run doctests - all must succeed

# %% Polish
# 1. Zmodyfikuj klasę `Translation`
# 2. Zaimplementuj wzorzec State
# 3. Uruchom doctesty - wszystkie muszą się powieść

# %% Doctests
"""
>>> import sys; sys.tracebacklimit = 0
>>> assert sys.version_info >= (3, 9), \
'Python 3.9+ required'

>>> polish = Translation(Polish())
>>> english = Translation(English())
>>> spanish = Translation(Spanish())

>>> polish.hello()
'Cześć'
>>> polish.goodbye()
'Do widzenia'

>>> english.hello()
'Hello'
>>> english.goodbye()
'Goodbye'

>>> spanish.hello()
'Buenos Días'
>>> spanish.goodbye()
'Adiós'
"""

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -v myfile.py`

# %% Imports
from enum import Enum

# %% Types
Translation: type
Language: type
Polish: type
English: type
Spanish: type

# %% Data

# %% Result
class Language(Enum):
    POLISH = 'pl'
    ENGLISH = 'en'
    SPANISH = 'es'


class Translation:
    language: Language

    def __init__(self, language: Language):
        self.language = language

    def hello(self) -> str:
        if self.language is Language.POLISH:
            return 'Cześć'
        elif self.language is Language.ENGLISH:
            return 'Hello'
        elif self.language is Language.SPANISH:
            return 'Buenos Días'
        else:
            return 'Unknown language'

    def goodbye(self) -> str:
        if self.language is Language.POLISH:
            return 'Do widzenia'
        elif self.language is Language.ENGLISH:
            return 'Goodbye'
        elif self.language is Language.SPANISH:
            return 'Adiós'
        else:
            return 'Unknown language'