idf-build-apps 2.10.3__tar.gz → 2.11.0__tar.gz

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.11.0 (2025-06-03)
+
+### Feat
+
+- support extra_pythonpaths injection during the runtime
+
 ## v2.10.3 (2025-06-03)
 
 ### Fix

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idf-build-apps
-Version: 2.10.3
+Version: 2.11.0
 Summary: Tools for building ESP-IDF related apps.
 Author-email: Fu Hanxi <fuhanxi@espressif.com>
 Requires-Python: >=3.7

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/docs/en/references/config_file.rst

@@ -101,7 +101,7 @@ This indicates that in the configuration file, you should specify it with the na
  Expand Environment Variables
 ******************************
 
-Some configuration options support environment variables. You can use environment variables in the configuration file by using the syntax ``${VAR_NAME}`` or ``$VAR_NAME``. Undeclared environment variables will be replaced with an empty string. For exmaple:
+All configuration options support environment variables. You can use environment variables in the configuration file by using the syntax ``${VAR_NAME}`` or ``$VAR_NAME``. Undeclared environment variables will be replaced with an empty string. For example:
 
 .. code:: toml
 

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/idf_build_apps/__init__.py

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

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/idf_build_apps/args.py

@@ -39,7 +39,6 @@ LOGGER = logging.getLogger(__name__)
 
 class ValidateMethod(str, enum.Enum):
     TO_LIST = 'to_list'
-    EXPAND_VARS = 'expand_vars'
 
 
 @dataclass
@@ -174,12 +173,17 @@ class BaseArguments(BaseSettings):
         if info.field_name and info.field_name in cls.model_fields:
             f = cls.model_fields[info.field_name]
             meta = get_meta(f)
+
+            # always expand vars for all fields
+            if isinstance(v, str):
+                v = expand_vars(v)
+            elif isinstance(v, list):
+                v = [expand_vars(item) if isinstance(item, str) else item for item in v]
+
             if meta and meta.validate_method:
                 for method in meta.validate_method:
                     if method == ValidateMethod.TO_LIST:
                         v = to_list(v)
-                    elif method == ValidateMethod.EXPAND_VARS:
-                        v = expand_vars(v)
                     else:
                         raise NotImplementedError(f'Unknown validate method: {method}')
 
@@ -241,9 +245,7 @@ class DependencyDrivenBuildArguments(GlobalArguments):
         default=None,  # type: ignore
     )
     manifest_rootpath: str = field(
-        FieldMetadata(
-            validate_method=[ValidateMethod.EXPAND_VARS],
-        ),
+        None,
         description='Root path to resolve the relative paths defined in the manifest files. '
         'By default set to the current directory. Support environment variables.',
         default=os.curdir,  # type: ignore
@@ -420,6 +422,15 @@ class FindBuildArguments(DependencyDrivenBuildArguments):
         description='Filter the apps by target. By default set to "all"',
         default='all',  # type: ignore
     )
+    extra_pythonpaths: t.Optional[t.List[str]] = field(
+        FieldMetadata(
+            validate_method=[ValidateMethod.TO_LIST],
+            nargs='+',
+        ),
+        description='space-separated list of additional Python paths to search for the app classes. '
+        'Will be injected into the head of sys.path.',
+        default=None,  # type: ignore
+    )
     build_system: t.Union[str, t.Type[App]] = field(
         None,
         description='Filter the apps by build system. By default set to "cmake". '
@@ -608,6 +619,14 @@ class FindBuildArguments(DependencyDrivenBuildArguments):
         if self.override_sdkconfig_files or self.override_sdkconfig_items:
             SESSION_ARGS.set(self)
 
+        # update PYTHONPATH
+        if self.extra_pythonpaths:
+            LOGGER.debug('Adding extra Python paths: %s', self.extra_pythonpaths)
+            for path in self.extra_pythonpaths:
+                abs_path = to_absolute_path(path)
+                if abs_path not in sys.path:
+                    sys.path.insert(0, abs_path)
+
         # load build system
         # here could be a string or a class of type App
         if not isinstance(self.build_system, str):
@@ -770,7 +789,6 @@ class BuildArguments(FindBuildArguments):
         FieldMetadata(
             deprecates={'collect_size_info': {}},
             hidden=True,
-            validate_method=[ValidateMethod.EXPAND_VARS],
         ),
         description='Record size json filepath of the built apps to the specified file. '
         'Each line is a json string. Can expand placeholders @p. Support environment variables.',
@@ -782,7 +800,6 @@ class BuildArguments(FindBuildArguments):
         FieldMetadata(
             deprecates={'collect_app_info': {}},
             hidden=True,
-            validate_method=[ValidateMethod.EXPAND_VARS],
         ),
         description='Record serialized app model of the built apps to the specified file. '
         'Each line is a json string. Can expand placeholders @p. Support environment variables.',
@@ -794,7 +811,6 @@ class BuildArguments(FindBuildArguments):
         FieldMetadata(
             deprecates={'junitxml': {}},
             hidden=True,
-            validate_method=[ValidateMethod.EXPAND_VARS],
         ),
         description='Path to the junitxml file to record the build results. Can expand placeholder @p. '
         'Support environment variables.',

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/pyproject.toml

@@ -65,7 +65,7 @@ idf-build-apps = "idf_build_apps:main.main"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "2.10.3"
+version = "2.11.0"
 tag_format = "v$version"
 version_files = [
     "idf_build_apps/__init__.py",

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/setup.py

@@ -38,7 +38,7 @@ entry_points = \
 {'console_scripts': ['idf-build-apps = idf_build_apps:main.main']}
 
 setup(name='idf-build-apps',
-      version='2.10.3',
+      version='2.11.0',
       description='Tools for building ESP-IDF related apps.',
       author=None,
       author_email='Fu Hanxi <fuhanxi@espressif.com>',

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/tests/test_args.py

@@ -97,12 +97,19 @@ def test_empty_argument():
     assert args.config_rules is None
 
 
-def test_build_args_expansion():
+def test_build_args_expansion(monkeypatch):
+    monkeypatch.setenv('FOO', '2')
+
     args = BuildArguments(
-        parallel_index=2, collect_app_info='@p.txt', junitxml='x_@p.txt', collect_size_info='@p_@p.txt'
+        parallel_index=2,
+        parallel_count='$FOO',
+        collect_app_info='@p.txt',
+        junitxml='x_@p.txt',
+        collect_size_info='@p_@p.txt',
     )
     assert args.collect_app_info == '2.txt'
     assert args.junitxml == 'x_2.txt'
+    assert args.parallel_count == 2
 
     args.parallel_index = 3
     assert args.collect_app_info == '3.txt'

{idf_build_apps-2.10.3 → idf_build_apps-2.11.0}/tests/test_finder.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import os
+import sys
 import tempfile
 from pathlib import (
     Path,
@@ -25,8 +26,9 @@ from idf_build_apps.manifest.manifest import Manifest
 
 
 class TestFindWithManifest:
-    def test_manifest_rootpath_chdir(self, capsys):
-        test_dir = Path(IDF_PATH) / 'examples' / 'get-started'
+    def test_manifest_rootpath_chdir(self, capsys, tmp_path):
+        test_dir = tmp_path / 'examples' / 'get-started'
+        create_project('hello_world', test_dir)
 
         yaml_file = test_dir / 'test.yml'
         yaml_file.write_text(
@@ -38,7 +40,7 @@ examples/get-started:
             encoding='utf8',
         )
 
-        os.chdir(IDF_PATH)
+        os.chdir(tmp_path)
         assert not find_apps(str(test_dir), 'esp32', recursive=True, manifest_files=str(yaml_file))
         assert not capsys.readouterr().err
 
@@ -769,3 +771,104 @@ def test_find_apps_with_duplicated_paths(tmp_path):
         == len(find_apps(str(tmp_path / 'folder1'), 'esp32', recursive=True))
         == 2
     )
+
+
+class TestFindWithExtraPythonPaths:
+    custom_app_code = """
+import os
+import typing as t
+from idf_build_apps import App
+from idf_build_apps.constants import BuildStatus
+from idf_build_apps.utils import Literal
+
+
+class ExtraPathTestApp(App):
+    build_system: Literal['extra_path_test'] = 'extra_path_test'  # type: ignore
+
+    @property
+    def supported_targets(self) -> t.List[str]:
+        return ['esp32', 'esp32s2', 'esp32c3']
+
+    def build(self, *args, **kwargs):
+        if not self.dry_run:
+            os.makedirs(self.build_path, exist_ok=True)
+            with open(os.path.join(self.build_path, 'extra_path_test_marker.txt'), 'w') as f:
+                f.write('Extra path test build successful')
+        self.build_status = BuildStatus.SUCCESS
+
+    @classmethod
+    def is_app(cls, path: str) -> bool:
+        return True
+"""
+
+    @pytest.fixture
+    def setup_custom_module_and_app(self, tmp_path):
+        """Set up a custom module in a separate directory and a test app"""
+        # Create custom module directory (separate from app directory)
+        custom_module_dir = tmp_path / 'custom_modules'
+        custom_module_dir.mkdir()
+
+        # Create the custom module file
+        custom_module_file = custom_module_dir / 'extra_path_test_module.py'
+        custom_module_file.write_text(self.custom_app_code)
+
+        # Create test app directory
+        test_app_dir = tmp_path / 'test_app'
+        test_app_dir.mkdir()
+
+        # Create basic app structure
+        main_dir = test_app_dir / 'main'
+        main_dir.mkdir()
+        (main_dir / 'main.c').write_text('void app_main() {}')
+        (main_dir / 'CMakeLists.txt').write_text('idf_component_register(SRCS "main.c")')
+        (test_app_dir / 'CMakeLists.txt').write_text(
+            'cmake_minimum_required(VERSION 3.16)\ninclude($ENV{IDF_PATH}/tools/cmake/project.cmake)\nproject(test_app)'
+        )
+
+        return {
+            'custom_module_dir': str(custom_module_dir),
+            'test_app_dir': str(test_app_dir),
+            'custom_module_file': str(custom_module_file),
+        }
+
+    def test_extra_pythonpaths_with_custom_build_system(self, setup_custom_module_and_app):
+        """Test that extra_pythonpaths allows loading custom build system classes"""
+        setup = setup_custom_module_and_app
+
+        original_path = sys.path.copy()
+
+        try:
+            # First verify that without extra_pythonpaths, the module cannot be found
+            with pytest.raises(ImportError, match=r'Failed to import module extra_path_test_module'):
+                find_apps(
+                    paths=[setup['test_app_dir']],
+                    target='esp32',
+                    build_system='extra_path_test_module:ExtraPathTestApp',
+                )
+
+            # Now test with extra_pythonpaths - this should work
+            apps = find_apps(
+                paths=[setup['test_app_dir']],
+                target='esp32',
+                build_system='extra_path_test_module:ExtraPathTestApp',
+                extra_pythonpaths=[setup['custom_module_dir']],
+            )
+
+            # Verify we found the app
+            assert len(apps) == 1
+            app = apps[0]
+
+            # Verify it's using our custom class
+            assert app.build_system == 'extra_path_test'
+            assert app.__class__.__name__ == 'ExtraPathTestApp'
+
+            # Verify the custom module dir was added to sys.path
+            assert setup['custom_module_dir'] in sys.path
+
+            # Test building the app
+            app.build(dry_run=True)
+            assert app.build_status == BuildStatus.SUCCESS
+
+        finally:
+            # Restore original sys.path
+            sys.path[:] = original_path