feat(cli): add autocompletions

docs/en/installation.rst

@@ -68,3 +68,41 @@ If updating directly is unavoidable, make sure you update to a compatible versio
 ::
 
    $ pip install esptool==3.3.2
+
+Shell completions
+-----------------
+
+To activate autocompletion, you can manually add commands provided below to your shell's config file
+or run them in your current terminal session for one-time activation.
+You will likely have to restart or re-login for the autocompletion to start working.
+
+bash:
+::
+
+   eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"
+
+zsh:
+
+To activate completions in zsh, first make sure `compinit` is marked for
+autoload and run autoload:
+
+.. code-block:: bash
+
+   autoload -U compinit
+   compinit
+
+Afterwards you can enable completions for esptool.py, espsecure.py and espefuse.py:
+
+::
+
+   eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"
+
+fish:
+
+Not required to be in the config file, only run once
+
+::
+
+   register-python-argcomplete --shell fish esptool.py espsecure.py espefuse.py >~/.config/fish/completions/esptool.py.fish
+
+Other shells nor OS Windows are not supported.

espefuse/__init__.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
+# PYTHON_ARGCOMPLETE_OK
 
 import argparse
 import os
@@ -285,6 +286,15 @@ def main(custom_commandline=None, esp=None):
 
     efuse_operations.add_commands(subparsers, efuses)
 
+    # Enable argcomplete only on Unix-like systems
+    if sys.platform != "win32":
+        try:
+            import argcomplete
+
+            argcomplete.autocomplete(parser)
+        except ImportError:
+            pass
+
     grouped_remaining_args, used_cmds = split_on_groups(remaining_args)
     if len(grouped_remaining_args) == 0:
         parser.print_help()

espsecure/__init__.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: 2016-2023 Espressif Systems (Shanghai) CO LTD
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
-
+# PYTHON_ARGCOMPLETE_OK
 import argparse
 import hashlib
 import operator
@@ -1867,6 +1867,15 @@ def main(custom_commandline=None):
         type=argparse.FileType("rb"),
     )
 
+    # Enable argcomplete only on Unix-like systems
+    if sys.platform != "win32":
+        try:
+            import argcomplete
+
+            argcomplete.autocomplete(parser)
+        except ImportError:
+            pass
+
     args = parser.parse_args(custom_commandline)
     print("espsecure.py v%s" % esptool.__version__)
     if args.operation is None:

esptool/__init__.py

@@ -2,7 +2,7 @@
 # Espressif Systems (Shanghai) CO LTD, other contributors as noted.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
-
+# PYTHON_ARGCOMPLETE_OK
 __all__ = [
     "chip_id",
     "detect_chip",
@@ -690,6 +690,15 @@ def add_spi_flash_subparsers(
     for operation in subparsers.choices.keys():
         assert operation in globals(), "%s should be a module function" % operation
 
+    # Enable argcomplete only on Unix-like systems
+    if sys.platform != "win32":
+        try:
+            import argcomplete
+
+            argcomplete.autocomplete(parser)
+        except ImportError:
+            pass
+
     argv = expand_file_arguments(argv or sys.argv[1:])
 
     args = parser.parse_args(argv)

pyproject.toml

@@ -40,6 +40,7 @@
         "reedsolo>=1.5.3,<1.8",
         "PyYAML>=5.1",
         "intelhex",
+        'argcomplete>=3; sys_platform != "win32"',
     ]
 
 [project.urls]