Merge branch 'fix/import_error_msg_v5.4' into 'release/v5.4'

fix(tools): re-raise ImportError without module name (v5.4)

See merge request espressif/esp-idf!35073

Author: dobairoland

tools/idf.py

@@ -1,30 +1,35 @@
 #!/usr/bin/env python
 #
-# SPDX-FileCopyrightText: 2019-2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
 #
 # SPDX-License-Identifier: Apache-2.0
 #
 # 'idf.py' is a top-level config/build command line tool for ESP-IDF
 #
 # You don't have to use idf.py, you can use cmake directly
 # (or use cmake in an IDE)
-
 # WARNING: we don't check for Python build-time dependencies until
 # check_environment() function below. If possible, avoid importing
 # any external libraries here - put in external script, or import in
 # their specific function instead.
 import codecs
 import json
 import locale
-import os
 import os.path
 import shlex
 import subprocess
 import sys
-from collections import Counter, OrderedDict, _OrderedDictKeysView
+from collections import Counter
+from collections import OrderedDict
+from collections.abc import KeysView
 from importlib import import_module
 from pkgutil import iter_modules
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Union
 
 # pyc files remain in the filesystem when switching between branches which might raise errors for incompatible
 # idf.py extensions. Therefore, pyc file generation is turned off:
@@ -39,13 +44,19 @@
     if os.getenv('IDF_COMPONENT_MANAGER') != '0':
         from idf_component_manager import idf_extensions
 except ImportError as e:
-    # For example, importing click could cause this.
-    print((f'Cannot import module "{e.name}". This usually means that "idf.py" was not '
+    print((f'{e}\n'
+           f'This usually means that "idf.py" was not '
            f'spawned within an ESP-IDF shell environment or the python virtual '
            f'environment used by "idf.py" is corrupted.\n'
            f'Please use idf.py only in an ESP-IDF shell environment. If problem persists, '
            f'please try to install ESP-IDF tools again as described in the Get Started guide.'),
           file=sys.stderr)
+    if e.name is None:
+        # The ImportError or ModuleNotFoundError might be raised without
+        # specifying a module name. In this not so common situation, re-raise
+        # the exception to print all the information that could assist in
+        # identifying the problem.
+        raise
 
     sys.exit(1)
 
@@ -128,7 +139,7 @@ def _safe_relpath(path: str, start: Optional[str]=None) -> str:
         return os.path.abspath(path)
 
 
-def init_cli(verbose_output: List=None) -> Any:
+def init_cli(verbose_output: Optional[List]=None) -> Any:
     # Click is imported here to run it after check_environment()
     import click
 
@@ -194,7 +205,7 @@ def __init__(self, callback: Callable, name: str, aliases: List, dependencies: O
             self.action_args = action_args
             self.aliases = aliases
 
-        def __call__(self, context: click.core.Context, global_args: PropertyDict, action_args: Dict=None) -> None:
+        def __call__(self, context: click.core.Context, global_args: PropertyDict, action_args: Optional[Dict]=None) -> None:
             if action_args is None:
                 action_args = self.action_args
 
@@ -295,7 +306,7 @@ class Scope(object):
 
         SCOPES = ('default', 'global', 'shared')
 
-        def __init__(self, scope: Union['Scope', str]=None) -> None:  # noqa: F821
+        def __init__(self, scope: Optional[Union['Scope', str]]=None) -> None:  # noqa: F821
             if scope is None:
                 self._scope = 'default'
             elif isinstance(scope, str) and scope in self.SCOPES:
@@ -318,7 +329,7 @@ def __str__(self) -> str:
 
     class Option(click.Option):
         """Option that knows whether it should be global"""
-        def __init__(self, scope: Union[Scope, str]=None, deprecated: Union[Dict, str, bool]=False, hidden: bool=False, **kwargs: str) -> None:
+        def __init__(self, scope: Optional[Union[Scope, str]]=None, deprecated: Union[Dict, str, bool]=False, hidden: bool=False, **kwargs: str) -> None:
             """
             Keyword arguments additional to Click's Option class:
 
@@ -356,7 +367,7 @@ def get_help_record(self, ctx: click.core.Context) -> Any:
 
     class CLI(click.MultiCommand):
         """Action list contains all actions with options available for CLI"""
-        def __init__(self, all_actions: Dict=None, verbose_output: List=None, help: str=None) -> None:
+        def __init__(self, all_actions: Optional[Dict]=None, verbose_output: Optional[List]=None, help: Optional[str]=None) -> None:
             super(CLI, self).__init__(
                 chain=True,
                 invoke_without_command=True,
@@ -440,7 +451,7 @@ def get_command(self, ctx: click.core.Context, name: str) -> Optional[Action]:
                     return Action(name=name, callback=callback.unwrapped_callback)
                 return None
 
-        def _print_closing_message(self, args: PropertyDict, actions: _OrderedDictKeysView) -> None:
+        def _print_closing_message(self, args: PropertyDict, actions: KeysView) -> None:
             # print a closing message of some kind,
             # except if any of the following actions were requested
             if any(t in str(actions) for t in ('flash', 'dfu', 'uf2', 'uf2-app', 'qemu')):
@@ -578,7 +589,7 @@ def execute_tasks(self, tasks: List, **kwargs: str) -> OrderedDict:
 
                 dependecies_processed = True
 
-                # If task have some dependecies they have to be executed before the task.
+                # If task have some dependencies they have to be executed before the task.
                 for dep in task.dependencies:
                     if dep not in tasks_to_run.keys():
                         # If dependent task is in the list of unprocessed tasks move to the front of the list
@@ -711,11 +722,11 @@ def parse_project_dir(project_dir: str) -> Any:
     return CLI(help=cli_help, verbose_output=verbose_output, all_actions=all_actions)
 
 
-def main(argv: List[Any] = None) -> None:
+def main(argv: Optional[List[Any]] = None) -> None:
     # Check the environment only when idf.py is invoked regularly from command line.
     checks_output = None if SHELL_COMPLETE_RUN else check_environment()
 
-    # Check existance of the current working directory to prevent exceptions from click cli.
+    # Check existence of the current working directory to prevent exceptions from click cli.
     try:
         os.getcwd()
     except FileNotFoundError as e: