idf-build-apps 2.3.1__py3-none-any.whl → 2.4.0__py3-none-any.whl

idf_build_apps/__init__.py

@@ -8,7 +8,7 @@ Tools for building ESP-IDF related apps.
 # ruff: noqa: E402
 # avoid circular imports
 
-__version__ = '2.3.1'
+__version__ = '2.4.0'
 
 from .session_args import (
     SessionArgs,

idf_build_apps/autocompletions.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+from typing import Optional
+
+from .utils import AutocompleteActivationError
+
+
+def append_to_file(file_path: str, content: str) -> None:
+    """Add commands to shell configuration file
+
+    :param file_path: path to shell configurations file
+    :param content: commands to add
+    """
+    if os.path.exists(file_path):
+        with open(file_path) as file:
+            if content.strip() in file.read():
+                print(f'Autocompletion already set up in {file_path}')
+                return
+    with open(file_path, 'a') as file:
+        file.write(f'\n# Begin added by idf-build-apps \n{content} \n# End added by idf-build-apps')
+    print(f'Autocompletion added to {file_path}')
+
+
+def activate_completions(shell_type: Optional[str]) -> None:
+    """Activates autocompletion for supported shells.
+
+    :raises AutocompleteActivationError: if the $SHELL env variable is empty, or if the detected shell is unsupported.
+    """
+    supported_shells = ['bash', 'zsh', 'fish']
+
+    if shell_type == 'auto':
+        shell_type = os.path.basename(os.environ.get('SHELL', ''))
+
+    if not shell_type:
+        raise AutocompleteActivationError('$SHELL is empty. Please provide your shell type with the `--shell` option')
+
+    if shell_type not in supported_shells:
+        raise AutocompleteActivationError('Unsupported shell. Autocompletion is supported for bash, zsh and fish.')
+
+    if shell_type == 'bash':
+        completion_command = 'eval "$(register-python-argcomplete idf-build-apps)"'
+    elif shell_type == 'zsh':
+        completion_command = (
+            'autoload -U bashcompinit && bashcompinit && eval "$(register-python-argcomplete idf-build-apps)"'
+        )
+    elif shell_type == 'fish':
+        completion_command = 'register-python-argcomplete --shell fish idf-build-apps | source'
+
+    rc_file = {'bash': '~/.bashrc', 'zsh': '~/.zshrc', 'fish': '~/.config/fish/completions/idf-build-apps.fish'}
+
+    shell_rc = os.path.expanduser(rc_file[shell_type])
+    append_to_file(shell_rc, completion_command)

idf_build_apps/constants.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 
 import enum
@@ -95,3 +95,37 @@ class BuildStage(str, enum.Enum):
     @classmethod
     def max_length(cls) -> int:
         return max(len(v.value) for v in cls.__members__.values())
+
+
+completion_instructions = """
+With `--activate` option detect your shell type and add the appropriate commands to your shell's config file
+so that it is run on startup. You will likely have to restart
+or re-login for the autocompletion to start working.
+
+You can also specify your shell by the `--shell` option.
+
+If you do not want automaticall modifying your shell config file
+you can manually add commands provided below to activate autocompletion
+or run them in your current terminal session for one-time activation.
+
+Once again, you will likely have to restart
+or re-login for the autocompletion to start working.
+
+bash:
+    eval "$(register-python-argcomplete idf-build-apps)"
+
+zsh:
+    To activate completions in zsh, first make sure compinit is marked for
+    autoload and run autoload:
+
+    autoload -U compinit
+    compinit
+
+    Afterwards you can enable completions for idf-build-apps:
+
+    eval "$(register-python-argcomplete idf-build-apps)"
+
+fish:
+    # Not required to be in the config file, only run once
+    register-python-argcomplete --shell fish idf-build-apps >~/.config/fish/completions/idf-build-apps.fish
+"""

idf_build_apps/main.py

@@ -1,3 +1,5 @@
+# PYTHON_ARGCOMPLETE_OK
+
 # SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 
@@ -10,6 +12,7 @@ import sys
 import textwrap
 import typing as t
 
+import argcomplete
 from pydantic import (
     Field,
     create_model,
@@ -24,16 +27,14 @@ from .app import (
     CMakeApp,
     MakeApp,
 )
+from .autocompletions import activate_completions
 from .build_apps_args import (
     BuildAppsArgs,
 )
 from .config import (
     get_valid_config,
 )
-from .constants import (
-    ALL_TARGETS,
-    BuildStatus,
-)
+from .constants import ALL_TARGETS, BuildStatus, completion_instructions
 from .finder import (
     _find_apps,
 )
@@ -50,6 +51,7 @@ from .manifest.manifest import (
     Manifest,
 )
 from .utils import (
+    AutocompleteActivationError,
     InvalidCommand,
     files_matches_patterns,
     get_parallel_start_stop,
@@ -606,10 +608,27 @@ def get_parser() -> argparse.ArgumentParser:
         help='enable colored output by default on UNIX-like systems. enable this flag to make the logs uncolored.',
     )
 
-    find_parser = actions.add_parser('find', parents=[common_args], formatter_class=IdfBuildAppsCliFormatter)
+    find_parser = actions.add_parser(
+        'find',
+        help='Find the buildable applications. Run `idf-build-apps find --help` for more information on a command',
+        description='Find the buildable applications in the given path or paths for specified chips. '
+        '`--path` and `--target` options must be provided. '
+        'By default, print the found apps in stdout. '
+        'To find apps for all chips use the `--target` option with the `all` argument.',
+        parents=[common_args],
+        formatter_class=IdfBuildAppsCliFormatter,
+    )
+
     find_parser.add_argument('-o', '--output', help='Print the found apps to the specified file instead of stdout')
 
-    build_parser = actions.add_parser('build', parents=[common_args], formatter_class=IdfBuildAppsCliFormatter)
+    build_parser = actions.add_parser(
+        'build',
+        help='Build the found applications. Run `idf-build-apps build --help` for more information on a command',
+        description='Build the application in the given path or paths for specified chips. '
+        '`--path` and `--target` options must be provided.',
+        parents=[common_args],
+        formatter_class=IdfBuildAppsCliFormatter,
+    )
     build_parser.add_argument(
         '--build-verbose',
         action='store_true',
@@ -674,14 +693,48 @@ def get_parser() -> argparse.ArgumentParser:
         help='Path to the junitxml file. If specified, the junitxml file will be generated. Can expand placeholder @p',
     )
 
+    completions_parser = actions.add_parser(
+        'completions',
+        help='Add the autocompletion activation script to the shell rc file. '
+        'Run `idf-build-apps complations --help` for more information on a command',
+        description='Without `--activate` option print instructions for manual activation. '
+        'With `--activate` option add the autocompletion activation script to the shell rc file '
+        'for bash, zsh, or fish. Other shells are not supported. '
+        'The `--shell` option used only with the `--activate` option, '
+        'if provided, add the autocompletion activation script to the given shell; '
+        'without this argument, will detect shell type automatically. '
+        'May need to restart or re-login for the autocompletion to start working',
+        formatter_class=IdfBuildAppsCliFormatter,
+    )
+    completions_parser.add_argument(
+        '-a', '--activate', action='store_true', help='Activate autocompletion automatically and permanently'
+    )
+    completions_parser.add_argument(
+        '-s',
+        '--shell',
+        choices=['bash', 'zsh', 'fish'],
+        help='Specify the shell type for the autocomplite activation script. ',
+    )
+
     return parser
 
 
+def handle_completions(args: argparse.Namespace) -> None:
+    if args.activate:
+        if not args.shell:
+            args.shell = 'auto'
+        activate_completions(args.shell)
+    elif not args.activate and args.shell:
+        raise AutocompleteActivationError('The --shell option can only be used with the --activate option.')
+    else:
+        print(completion_instructions)
+
+
 def validate_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
     # validate cli subcommands
-    if args.action not in ['find', 'build']:
+    if args.action not in ['find', 'build', 'completions']:
         parser.print_help()
-        raise InvalidCommand('subcommand is required. {find, build}')
+        raise InvalidCommand('subcommand is required. {find, build, completions}')
 
     if not args.paths:
         raise InvalidCommand(
@@ -728,8 +781,13 @@ def apply_config_args(args: argparse.Namespace) -> None:
 
 def main():
     parser = get_parser()
+    argcomplete.autocomplete(parser)
     args = parser.parse_args()
 
+    if args.action == 'completions':
+        handle_completions(args)
+        sys.exit(0)
+
     apply_config_args(args)
     validate_args(parser, args)
 

idf_build_apps/manifest/soc_header.py

@@ -1,5 +1,6 @@
 # SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
+import glob
 import logging
 import os.path
 import typing as t
@@ -82,35 +83,47 @@ class SocHeader(dict):
         super().__init__(**soc_header_dict)
 
     @staticmethod
-    def _get_dir_from_candidates(candidates: t.List[str]) -> t.Optional[str]:
+    def _get_dirs_from_candidates(candidates: t.List[str]) -> t.List[str]:
+        dirs = []
         for d in candidates:
             if not os.path.isdir(d):
                 LOGGER.debug('folder "%s" not found. Skipping...', os.path.abspath(d))
             else:
-                return d
+                dirs.append(d)
 
-        return None
+        return dirs
+
+    @staticmethod
+    def _find_candidates_from_pattern(pattern: str) -> t.List[str]:
+        # get dirs from pattern
+        return [d for d in glob.glob(pattern) if os.path.isdir(d)]
 
     @classmethod
     def _parse_soc_header(cls, target: str) -> t.Dict[str, t.Any]:
-        soc_headers_dir = cls._get_dir_from_candidates([
+        soc_headers_dirs = cls._get_dirs_from_candidates([
+            # master c5
+            *cls._find_candidates_from_pattern(
+                os.path.join(IDF_PATH, 'components', 'soc', target, '*', 'include', 'soc')
+            ),
             # other branches
             os.path.abspath(os.path.join(IDF_PATH, 'components', 'soc', target, 'include', 'soc')),
             # release/v4.2
             os.path.abspath(os.path.join(IDF_PATH, 'components', 'soc', 'soc', target, 'include', 'soc')),
         ])
-        esp_rom_headers_dir = cls._get_dir_from_candidates([
+        esp_rom_headers_dirs = cls._get_dirs_from_candidates([
+            # master c5
+            *cls._find_candidates_from_pattern(os.path.join(IDF_PATH, 'components', 'esp_rom', target, '*', target)),
             os.path.join(IDF_PATH, 'components', 'esp_rom', target),
         ])
 
         header_files: t.List[str] = []
-        if soc_headers_dir:
-            header_files += [str(p.resolve()) for p in Path(soc_headers_dir).glob(cls.CAPS_HEADER_FILEPATTERN)]
-        if esp_rom_headers_dir:
-            header_files += [str(p.resolve()) for p in Path(esp_rom_headers_dir).glob(cls.CAPS_HEADER_FILEPATTERN)]
+        for d in [*soc_headers_dirs, *esp_rom_headers_dirs]:
+            LOGGER.debug('Checking dir %s', d)
+            header_files += [str(p.resolve()) for p in Path(d).glob(cls.CAPS_HEADER_FILEPATTERN)]
 
         output_dict = {}
         for f in header_files:
+            LOGGER.debug('Checking header file %s', f)
             for line in get_defines(f):
                 try:
                     res = parse_define(line)

idf_build_apps/utils.py

@@ -85,6 +85,10 @@ class BuildError(RuntimeError):
     pass
 
 
+class AutocompleteActivationError(SystemExit):
+    pass
+
+
 class InvalidCommand(SystemExit):
     def __init__(self, msg: str) -> None:
         super().__init__('Invalid Command: ' + msg.strip())

{idf_build_apps-2.3.1.dist-info → idf_build_apps-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: idf-build-apps
-Version: 2.3.1
+Version: 2.4.0
 Summary: Tools for building ESP-IDF related apps.
 Author-email: Fu Hanxi <fuhanxi@espressif.com>
 Requires-Python: >=3.7
@@ -18,6 +18,7 @@ Requires-Dist: pyyaml
 Requires-Dist: packaging
 Requires-Dist: toml; python_version < '3.11'
 Requires-Dist: pydantic~=2.0
+Requires-Dist: argcomplete>=3
 Requires-Dist: typing-extensions ; extra == "dev" and ( python_version < '3.8')
 Requires-Dist: sphinx ; extra == "doc"
 Requires-Dist: sphinx-rtd-theme ; extra == "doc"
@@ -68,10 +69,11 @@ pipx install idf-build-apps
 
 `idf-build-apps` is a python package that could be used as a library or a CLI tool.
 
-As a CLI tool, it contains two sub-commands.
+As a CLI tool, it contains three sub-commands.
 
 - `find` to find the buildable applications
 - `build` to build the found applications
+- `completions` to activate autocompletions or print instructions for manual activation
 
 For detailed explanation to all CLI options, you may run
 
@@ -79,6 +81,7 @@ For detailed explanation to all CLI options, you may run
 idf-build-apps -h
 idf-build-apps find -h
 idf-build-apps build -h
+idf-build-apps completions -h
 ```
 
 As a library, you may check the [API documentation][api-doc] for more information. Overall it provides

{idf_build_apps-2.3.1.dist-info → idf_build_apps-2.4.0.dist-info}/RECORD

@@ -1,25 +1,26 @@
-idf_build_apps/__init__.py,sha256=z1ITg-Ywq6Ena0ioI98C9E6iK4aFe--1PiSFX-iUHl4,650
+idf_build_apps/__init__.py,sha256=C3lZ5AdMBO7eTuVsdBtoQ6npF65DDzpgHgBXhP3-AAA,650
 idf_build_apps/__main__.py,sha256=8E-5xHm2MlRun0L88XJleNh5U50dpE0Q1nK5KqomA7I,182
 idf_build_apps/app.py,sha256=z6i55q_XaMjea34_nbAKgNTU-qOEkO_qTHCYSeQNUFw,35887
+idf_build_apps/autocompletions.py,sha256=g-bx0pzXoFKI0VQqftkHyGVWN6MLjuFOdozeuAf45yo,2138
 idf_build_apps/build_apps_args.py,sha256=r6VCJDdCzE873X8OTputYkCBZPgECaKoNlAejfcamJk,1644
 idf_build_apps/config.py,sha256=I75uOQGarCWVKGi16ZYpo0qTVU25BUP4eh6-RWCtbvw,2924
-idf_build_apps/constants.py,sha256=xqclwUpWE5dEByL4kxdg2HaHjbAfkJtxodFfLZuAk8A,2818
+idf_build_apps/constants.py,sha256=s-b-wAKjrIjF4tAspJBkXaDVC6HMX3Hv1mM2vGuLrB8,3952
 idf_build_apps/finder.py,sha256=qw5moNq7U5mHSsR0CCfGkKE9p4QsWYNcfkxzeQ73HgM,6252
 idf_build_apps/log.py,sha256=JysogBHoompfW9E9w0U4wZH7tt8dBdfoh-stPXQz1hw,2573
-idf_build_apps/main.py,sha256=lP2rUqtBfU7gxN63owZlAshdXvSFUfElfTsKthhBQus,34651
+idf_build_apps/main.py,sha256=17w4VaIjmdbosBqU7EF4-0gziM6veslQOBPH_JXK75U,37293
 idf_build_apps/session_args.py,sha256=2WDTy40IFAc0KQ57HaeBcYj_k10eUXRKkDOWLrFCaHY,2985
-idf_build_apps/utils.py,sha256=n9PNJEDDsA9hbbM0SNPdTFsO2_E8alNrX7CNYzaFHik,9644
+idf_build_apps/utils.py,sha256=dYxNXPe7FRWxzUFlTzOb3G-LpKpRUrNWdQrsO5MXAB8,9702
 idf_build_apps/junit/__init__.py,sha256=IxvdaS6eSXp7kZxRuXqyZyGxuA_A1nOW1jF1HMi8Gns,231
 idf_build_apps/junit/report.py,sha256=vHE5RcBa7Bj4a1p2lXaTh0m9eJIO_uTGrOnJg8NEi4I,6430
 idf_build_apps/junit/utils.py,sha256=gtibRs8WTE8IXTIAS73QR_k_jrJlOjCl2y-9KiP5_Nk,1304
 idf_build_apps/manifest/__init__.py,sha256=Q2-cb3ngNjnl6_zWhUfzZZB10f_-Rv2JYNck3Lk7UkQ,133
 idf_build_apps/manifest/if_parser.py,sha256=r0pivV9gmniPn3Ia6sTMbW5tFAKInhOXk-Lfd6GokqE,6381
 idf_build_apps/manifest/manifest.py,sha256=P5ZaUd72A_HOVF6iuwap__Bw-w7WI72ugiTURm9PNNQ,10708
-idf_build_apps/manifest/soc_header.py,sha256=ULLad1TI8mGfdJhB7LJ4T9A_8BugF1TmckgdO7jO7Fg,3956
+idf_build_apps/manifest/soc_header.py,sha256=uAS944qDN3z9lvFHXE7du7bsQXQbgCcf2Lt90iiDano,4472
 idf_build_apps/yaml/__init__.py,sha256=W-3z5no07RQ6eYKGyOAPA8Z2CLiMPob8DD91I4URjrA,162
 idf_build_apps/yaml/parser.py,sha256=Y2OyB4g1DCC7C7jrvpIyZV9lgeCB_XvuB75iGmqiTaM,2093
-idf_build_apps-2.3.1.dist-info/entry_points.txt,sha256=3pVUirUEsb6jsDRikkQWNUt4hqLK2ci1HvW_Vf8b6uE,59
-idf_build_apps-2.3.1.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-idf_build_apps-2.3.1.dist-info/WHEEL,sha256=EZbGkh7Ie4PoZfRQ8I0ZuP9VklN_TvcZ6DSE5Uar4z4,81
-idf_build_apps-2.3.1.dist-info/METADATA,sha256=ET5FxoKnaafQWJGkpERufP1p7J_JLzz3gO3ZYLsRPVg,4458
-idf_build_apps-2.3.1.dist-info/RECORD,,
+idf_build_apps-2.4.0.dist-info/entry_points.txt,sha256=3pVUirUEsb6jsDRikkQWNUt4hqLK2ci1HvW_Vf8b6uE,59
+idf_build_apps-2.4.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+idf_build_apps-2.4.0.dist-info/WHEEL,sha256=EZbGkh7Ie4PoZfRQ8I0ZuP9VklN_TvcZ6DSE5Uar4z4,81
+idf_build_apps-2.4.0.dist-info/METADATA,sha256=WN1SIhaqA3rl5ZOWe_SzfQlkwDrW5iQFDkOe0FrKaug,4608
+idf_build_apps-2.4.0.dist-info/RECORD,,