refactor(cli_mode): Improve CLI mode workflow code

esptool/__init__.py

@@ -768,9 +768,15 @@ def main(argv=None, esp=None):
     operation_func = globals()[args.operation]
     operation_args = inspect.getfullargspec(operation_func).args
 
-    if (
+    # Commands that don't require an ESP object (image generation, etc.)
-        operation_args[0] == "esp"
+    if operation_args[0] != "esp":
-    ):  # operation function takes an ESPLoader connection object
+        operation_func(args)
+        return
+
+    # Commands that require an ESP object (flash read/write, etc.)
+    # 1) Get the ESP object
+    #######################
+
     if args.before != "no_reset_no_sync":
         initial_baud = min(
             ESPLoader.ESP_ROM_BAUD, args.baud
@@ -823,6 +829,9 @@ def main(argv=None, esp=None):
             f"on any of the {len(ser_list)} available serial ports."
         )
 
+    # 2) Print the chip info
+    ########################
+
     if esp.secure_download_mode:
         log.print(f"Chip is {esp.CHIP_NAME} in Secure Download Mode")
     else:
@@ -834,6 +843,9 @@ def main(argv=None, esp=None):
             log.print(f"USB mode: {usb_mode}")
         read_mac(esp, args)
 
+    # 3) Upload the stub flasher
+    ############################
+
     if not args.no_stub:
         if esp.secure_download_mode:
             log.warning(
@@ -868,6 +880,9 @@ def main(argv=None, esp=None):
                     )
                 raise
 
+    # 4) Configure the baud rate and voltage regulator
+    ##################################################
+
     if args.override_vddsdio:
         esp.override_vddsdio(args.override_vddsdio)
 
@@ -880,11 +895,16 @@ def main(argv=None, esp=None):
                 f"Keeping initial baud rate {initial_baud}"
             )
 
+    # 5) Attach the flash chip and set its parameters
+    #################################################
+
     flash_attach(esp, args.spi_connection if hasattr(args, "spi_connection") else None)
     if hasattr(args, "flash_size"):
         args.flash_size = flash_set_parameters(esp, args.flash_size)
 
-        # Detect flash size if "ALL" is specified
+    # 6) Perform argument processing and validation
+    ###############################################
+
     if getattr(args, "size", "") == "all":
         if esp.secure_download_mode:
             raise FatalError(
@@ -893,20 +913,25 @@ def main(argv=None, esp=None):
             )
         size_str = detect_flash_size(esp)
         if size_str is None:
-                raise FatalError(
+            raise FatalError("Detecting flash size failed. Set an exact size value.")
-                    "Detecting flash size failed. Set an exact size value."
-                )
         log.print(f"Detected flash size: {size_str}")
         args.size = flash_size_bytes(size_str)
 
-        # Check if we are writing past 16MB boundary
+    if (  # Check if we are writing/reading past 16MB boundary
-        if esp.IS_STUB and args.operation != "dump_mem" and hasattr(args, "address") and hasattr(args, "size"):
+        esp.IS_STUB
+        and args.operation != "dump_mem"
+        and hasattr(args, "address")
+        and hasattr(args, "size")
+    ):
         if esp.CHIP_NAME != "ESP32-S3" and args.address + args.size > 0x1000000:
             log.note(
                 "Flasher stub doesn't fully support flash size larger "
                 "than 16MB, in case of failure use --no-stub."
             )
 
+    # 7) Run the selected operation
+    ###############################
+
     try:
         operation_func(esp, args)
     finally:
@@ -916,6 +941,9 @@ def main(argv=None, esp=None):
         except AttributeError:
             pass
 
+    # 8) Reset the chip
+    ###################
+
     # Handle post-operation behaviour (reset or other)
     if operation_func == load_ram:
         # the ESP is now running the loaded image, so let it run
@@ -942,12 +970,12 @@ def main(argv=None, esp=None):
         if esp.IS_STUB:
             esp.soft_reset(True)  # exit stub back to ROM loader
 
+    # 9) Finish and close the port
+    ##############################
+
     if not external_esp:
         esp._port.close()
 
-    else:
-        operation_func(args)
-
 
 def arg_auto_int(x):
     return int(x, 0)