refactor(stub_class): Make into a mixin to avoid code repetition

Author: radimkarnis

.pre-commit-config.yaml

@@ -25,9 +25,11 @@ repos:
       additional_dependencies:
         - tomli
   - repo: https://github.com/espressif/conventional-precommit-linter
-    rev: v1.9.0
+    rev: v1.10.0
     hooks:
       - id: conventional-precommit-linter
         stages: [commit-msg]
+        args:
+          - --allow-breaking
 default_stages: [commit]
 default_install_hook_types: [pre-commit, commit-msg]

esptool/loader.py

@@ -1614,6 +1614,26 @@ def watchdog_reset(self):
         self.hard_reset()
 
 
+class StubMixin:
+    """
+    Mixin class bundling the stub loader-specific properties.
+    Not intended for direct instantiation.
+    A child class (e.g. ESP32StubLoader) uses multiple inheritance
+    to combine this mixin class (StubMixin) with a parent class (e.g. ESP32ROM).
+    """
+
+    FLASH_WRITE_SIZE = 0x4000  # Default value, can be overridden
+    STATUS_BYTES_LENGTH = 2
+    IS_STUB = True
+
+    def __init__(self, rom_loader):
+        self.secure_download_mode = rom_loader.secure_download_mode
+        self._port = rom_loader._port
+        self._trace_enabled = rom_loader._trace_enabled
+        self.cache = rom_loader.cache
+        self.flush_input()  # resets _slip_reader
+
+
 def slip_reader(port, trace_function):
     """Generator to read SLIP packets from a serial port.
     Yields one full SLIP packet at a time, raises exception on timeout or invalid data.

esptool/targets/esp32.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2014-2022 Fredrik Ahlberg, Angus Gratton,
+# SPDX-FileCopyrightText: 2025 Fredrik Ahlberg, Angus Gratton,
 # Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
@@ -7,7 +7,7 @@
 import time
 from typing import Dict, Optional
 
-from ..loader import ESPLoader
+from ..loader import ESPLoader, StubMixin
 from ..util import FatalError, NotSupportedError
 
 
@@ -452,19 +452,8 @@ def check_spi_connection(self, spi_connection):
             raise FatalError("SPI Pin numbers must be in the range 0-29, 32, or 33.")
 
 
-class ESP32StubLoader(ESP32ROM):
-    """Access class for ESP32 stub loader, runs on top of ROM."""
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+class ESP32StubLoader(StubMixin, ESP32ROM):
+    """Stub loader for ESP32, runs on top of ROM."""
 
     def change_baud(self, baud):
         ESPLoader.change_baud(self, baud)

esptool/targets/esp32c2.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
+# SPDX-FileCopyrightText: 2014-2025 Fredrik Ahlberg, Angus Gratton,
 # Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
@@ -8,7 +8,7 @@
 from typing import Dict
 
 from .esp32c3 import ESP32C3ROM
-from ..loader import ESPLoader
+from ..loader import ESPLoader, StubMixin
 from ..util import FatalError
 
 
@@ -166,23 +166,10 @@ def check_spi_connection(self, spi_connection):
             raise FatalError("SPI Pin numbers must be in the range 0-20.")
 
 
-class ESP32C2StubLoader(ESP32C2ROM):
-    """Access class for ESP32C2 stub loader, runs on top of ROM.
+class ESP32C2StubLoader(StubMixin, ESP32C2ROM):
+    """Stub loader for ESP32-C2, runs on top of ROM."""
 
-    (Basically the same as ESP32StubLoader, but different base class.
-    Can possibly be made into a mixin.)
-    """
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+    pass
 
 
 ESP32C2ROM.STUB_CLASS = ESP32C2StubLoader

esptool/targets/esp32c3.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
+# SPDX-FileCopyrightText: 2014-2025 Fredrik Ahlberg, Angus Gratton,
 # Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
@@ -8,7 +8,7 @@
 from typing import Dict
 
 from .esp32 import ESP32ROM
-from ..loader import ESPLoader
+from ..loader import ESPLoader, StubMixin
 from ..util import FatalError, NotImplementedInROMError
 
 
@@ -273,23 +273,10 @@ def check_spi_connection(self, spi_connection):
             )
 
 
-class ESP32C3StubLoader(ESP32C3ROM):
-    """Access class for ESP32C3 stub loader, runs on top of ROM.
+class ESP32C3StubLoader(StubMixin, ESP32C3ROM):
+    """Stub loader for ESP32-C3, runs on top of ROM."""
 
-    (Basically the same as ESP32StubLoader, but different base class.
-    Can possibly be made into a mixin.)
-    """
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+    pass
 
 
 ESP32C3ROM.STUB_CLASS = ESP32C3StubLoader

esptool/targets/esp32c5.py

@@ -1,4 +1,5 @@
-# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2024-2025 Fredrik Ahlberg, Angus Gratton,
+# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 
@@ -8,7 +9,7 @@
 
 from .esp32c3 import ESP32C3ROM
 from .esp32c6 import ESP32C6ROM
-from ..loader import ESPLoader
+from ..loader import ESPLoader, StubMixin
 from ..util import FatalError
 
 
@@ -168,23 +169,10 @@ def watchdog_reset(self):
         ESP32C3ROM.watchdog_reset(self)
 
 
-class ESP32C5StubLoader(ESP32C5ROM):
-    """Access class for ESP32C5 stub loader, runs on top of ROM.
+class ESP32C5StubLoader(StubMixin, ESP32C5ROM):
+    """Stub loader for ESP32-C5, runs on top of ROM."""
 
-    (Basically the same as ESP32StubLoader, but different base class.
-    Can possibly be made into a mixin.)
-    """
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+    pass
 
 
 ESP32C5ROM.STUB_CLASS = ESP32C5StubLoader

esptool/targets/esp32c5beta3.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 
@@ -7,7 +7,7 @@
 from typing import Dict
 
 from .esp32c6 import ESP32C6ROM
-from ..loader import ESPLoader
+from ..loader import ESPLoader, StubMixin
 
 
 class ESP32C5BETA3ROM(ESP32C6ROM):
@@ -104,23 +104,10 @@ def change_baud(self, baud):
             ESPLoader.change_baud(self, baud)
 
 
-class ESP32C5BETA3StubLoader(ESP32C5BETA3ROM):
-    """Access class for ESP32C5BETA3 stub loader, runs on top of ROM.
+class ESP32C5BETA3StubLoader(StubMixin, ESP32C5BETA3ROM):
+    """Stub loader for ESP32-C5(beta3), runs on top of ROM."""
 
-    (Basically the same as ESP32StubLoader, but different base class.
-    Can possibly be made into a mixin.)
-    """
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+    pass
 
 
 ESP32C5BETA3ROM.STUB_CLASS = ESP32C5BETA3StubLoader

esptool/targets/esp32c6.py

@@ -1,12 +1,12 @@
-# SPDX-FileCopyrightText: 2024 Fredrik Ahlberg, Angus Gratton,
+# SPDX-FileCopyrightText: 2024-2025 Fredrik Ahlberg, Angus Gratton,
 # Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 import struct
 
 from .esp32c3 import ESP32C3ROM
-from ..loader import ESPLoader
+from ..loader import ESPLoader, StubMixin
 from ..util import FatalError, NotImplementedInROMError
 
 
@@ -198,23 +198,10 @@ def watchdog_reset(self):
         ESPLoader.watchdog_reset(self)
 
 
-class ESP32C6StubLoader(ESP32C6ROM):
-    """Access class for ESP32C6 stub loader, runs on top of ROM.
+class ESP32C6StubLoader(StubMixin, ESP32C6ROM):
+    """Stub loader for ESP32-C6, runs on top of ROM."""
 
-    (Basically the same as ESP32StubLoader, but different base class.
-    Can possibly be made into a mixin.)
-    """
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+    pass
 
 
 ESP32C6ROM.STUB_CLASS = ESP32C6StubLoader

esptool/targets/esp32c61.py

@@ -1,4 +1,5 @@
-# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2024-2025 Fredrik Ahlberg, Angus Gratton,
+# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 
@@ -7,6 +8,7 @@
 
 from .esp32c3 import ESP32C3ROM
 from .esp32c6 import ESP32C6ROM
+from ..loader import StubMixin
 
 
 class ESP32C61ROM(ESP32C6ROM):
@@ -124,23 +126,10 @@ def watchdog_reset(self):
         ESP32C3ROM.watchdog_reset(self)
 
 
-class ESP32C61StubLoader(ESP32C61ROM):
-    """Access class for ESP32C61 stub loader, runs on top of ROM.
+class ESP32C61StubLoader(StubMixin, ESP32C61ROM):
+    """Stub loader for ESP32-C61, runs on top of ROM."""
 
-    (Basically the same as ESP32StubLoader, but different base class.
-    Can possibly be made into a mixin.)
-    """
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+    pass
 
 
 ESP32C61ROM.STUB_CLASS = ESP32C61StubLoader

esptool/targets/esp32h2.py

@@ -1,12 +1,12 @@
-# SPDX-FileCopyrightText: 2024 Fredrik Ahlberg, Angus Gratton,
+# SPDX-FileCopyrightText: 2024-2025 Fredrik Ahlberg, Angus Gratton,
 # Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 from typing import Dict
 
 from .esp32c6 import ESP32C6ROM
-from ..loader import ESPLoader
+from ..loader import ESPLoader, StubMixin
 from ..util import FatalError
 
 
@@ -93,23 +93,10 @@ def check_spi_connection(self, spi_connection):
             )
 
 
-class ESP32H2StubLoader(ESP32H2ROM):
-    """Access class for ESP32H2 stub loader, runs on top of ROM.
+class ESP32H2StubLoader(StubMixin, ESP32H2ROM):
+    """Stub loader for ESP32-H2, runs on top of ROM."""
 
-    (Basically the same as ESP32StubLoader, but different base class.
-    Can possibly be made into a mixin.)
-    """
-
-    FLASH_WRITE_SIZE = 0x4000  # matches MAX_WRITE_BLOCK in stub_loader.c
-    STATUS_BYTES_LENGTH = 2  # same as ESP8266, different to ESP32 ROM
-    IS_STUB = True
-
-    def __init__(self, rom_loader):
-        self.secure_download_mode = rom_loader.secure_download_mode
-        self._port = rom_loader._port
-        self._trace_enabled = rom_loader._trace_enabled
-        self.cache = rom_loader.cache
-        self.flush_input()  # resets _slip_reader
+    pass
 
 
 ESP32H2ROM.STUB_CLASS = ESP32H2StubLoader