idf-build-apps 2.9.0__tar.gz → 2.10.1__tar.gz

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
           - --use-current-year
         exclude: 'idf_build_apps/vendors/'
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.11.5'
+    rev: 'v0.11.6'
     hooks:
       - id: ruff
         args: ['--fix']

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.10.1 (2025-05-05)
+
+### Fix
+
+- cache custom app classes
+
+## v2.10.0 (2025-04-22)
+
+### Feat
+
+- support custom class load from CLI
+
 ## v2.9.0 (2025-04-16)
 
 ### Feat

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: idf-build-apps
-Version: 2.9.0
+Version: 2.10.1
 Summary: Tools for building ESP-IDF related apps.
 Author-email: Fu Hanxi <fuhanxi@espressif.com>
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 License-File: LICENSE
 Requires-Dist: pyparsing
 Requires-Dist: pyyaml

idf_build_apps-2.10.1/docs/en/guides/custom_app.md

@@ -0,0 +1,80 @@
+# Custom App Classes
+
+`idf-build-apps` allows you to create custom app classes by subclassing the base `App` class. This is useful when you need to implement custom build logic or handle special project types.
+
+## Creating a Custom App Class
+
+Here's an example of creating a custom app class:
+
+```python
+from idf_build_apps import App
+from idf_build_apps.constants import BuildStatus
+import os
+from typing import Literal  # Python 3.8+ only. from typing_extensions import Literal for earlier versions
+
+class CustomApp(App):
+    build_system: Literal['custom'] = 'custom'  # Must be unique to identify your custom app type
+
+    def build(self, *args, **kwargs):
+        # Implement your custom build logic here
+        os.makedirs(self.build_path, exist_ok=True)
+        with open(os.path.join(self.build_path, 'dummy.txt'), 'w') as f:
+            f.write('Custom build successful')
+        self.build_status = BuildStatus.SUCCESS
+        print('Custom build successful')
+
+    @classmethod
+    def is_app(cls, path: str) -> bool:
+        # Implement logic to determine if a path contains your custom app type
+        return True
+```
+
+## Using Custom App Classes
+
+You can use custom app classes in two ways:
+
+### Via CLI
+
+```shell
+idf-build-apps build -p /path/to/app --target esp32 --build-system custom:CustomApp
+```
+
+Where `custom:CustomApp` is in the format `module:class`. The module must be in your Python path.
+
+### Via Python API
+
+```python
+from idf_build_apps import find_apps
+
+apps = find_apps(
+    paths=['/path/to/app'],
+    target='esp32',
+    build_system=CustomApp,
+)
+
+for app in apps:
+    app.build()
+```
+
+## Important Notes
+
+- Your custom app class must subclass `App`
+- The `build_system` attribute must be unique to identify your app type
+- You must implement the `is_app()` class method to identify your app type
+- For JSON serialization support, you need to pass your custom class to `json_to_app()` when deserializing
+
+## Example: JSON Serialization
+
+```python
+from idf_build_apps import json_to_app
+
+# Serialize
+json_str = custom_app.to_json()
+
+# Deserialize
+deserialized_app = json_to_app(json_str, extra_classes=[CustomApp])
+```
+
+## Available Methods and Properties
+
+Please refer to the [API reference of the class `App`](https://docs.espressif.com/projects/idf-build-apps/en/latest/references/api/idf_build_apps.html#idf_build_apps.app.App)

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/docs/en/index.rst

@@ -16,8 +16,9 @@ This documentation is for idf-build-apps. idf-build-apps is a tool that allows d
 .. toctree::
    :maxdepth: 1
    :caption: Guides
+   :glob:
 
-   guides/1.x_to_2.x
+   guides/*
 
 .. toctree::
    :maxdepth: 1

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/idf_build_apps/__init__.py

@@ -8,7 +8,7 @@ Tools for building ESP-IDF related apps.
 # ruff: noqa: E402
 # avoid circular imports
 
-__version__ = '2.9.0'
+__version__ = '2.10.1'
 
 from .session_args import (
     SessionArgs,
@@ -28,6 +28,7 @@ from .log import (
 from .main import (
     build_apps,
     find_apps,
+    json_list_files_to_apps,
     json_to_app,
 )
 
@@ -38,6 +39,7 @@ __all__ = [
     'MakeApp',
     'build_apps',
     'find_apps',
+    'json_list_files_to_apps',
     'json_to_app',
     'setup_logging',
 ]

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/idf_build_apps/app.py

@@ -1011,3 +1011,11 @@ class AppDeserializer(BaseModel):
     def from_json(cls, json_data: t.Union[str, bytes, bytearray]) -> App:
         json_dict = json.loads(json_data.strip())
         return cls.model_validate({'app': json_dict}).app
+
+    @classmethod
+    def from_json_list(cls, json_list: t.Sequence[t.Union[str, bytes, bytearray]]) -> t.List[App]:
+        apps = []
+        for app_json in json_list:
+            apps.append(cls.from_json(app_json))
+
+        return apps

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/idf_build_apps/args.py

@@ -4,6 +4,7 @@
 import argparse
 import enum
 import glob
+import importlib
 import inspect
 import logging
 import os
@@ -27,7 +28,7 @@ from pydantic_settings import (
 )
 from typing_extensions import Concatenate, ParamSpec
 
-from . import SESSION_ARGS, App, setup_logging
+from . import SESSION_ARGS, App, CMakeApp, MakeApp, setup_logging
 from .constants import ALL_TARGETS, IDF_BUILD_APPS_TOML_FN, SUPPORTED_TARGETS
 from .manifest.manifest import FolderRule, Manifest
 from .utils import InvalidCommand, files_matches_patterns, semicolon_separated_str_to_list, to_absolute_path, to_list
@@ -397,6 +398,12 @@ class DependencyDrivenBuildArguments(GlobalArguments):
 
 
 class FindBuildArguments(DependencyDrivenBuildArguments):
+    _KNOWN_APP_CLASSES: t.ClassVar[t.Dict[str, t.Type[App]]] = {
+        'cmake': CMakeApp,
+        'make': MakeApp,
+    }
+    _LOADED_MODULE_APPS: t.ClassVar[t.Dict[str, t.Type[App]]] = {}
+
     paths: t.List[str] = field(
         FieldMetadata(
             validate_method=[ValidateMethod.TO_LIST],
@@ -414,10 +421,9 @@ class FindBuildArguments(DependencyDrivenBuildArguments):
         default='all',  # type: ignore
     )
     build_system: t.Union[str, t.Type[App]] = field(
-        FieldMetadata(
-            choices=['cmake', 'make'],
-        ),
-        description='Filter the apps by build system. By default set to "cmake"',
+        None,
+        description='Filter the apps by build system. By default set to "cmake". '
+        'Can be either "cmake", "make" or a custom App class path in format "module:class"',
         default='cmake',  # type: ignore
     )
     recursive: bool = field(
@@ -587,12 +593,56 @@ class FindBuildArguments(DependencyDrivenBuildArguments):
 
         if self.disable_targets and FolderRule.DEFAULT_BUILD_TARGETS:
             LOGGER.info('Disable targets: %s', self.disable_targets)
-            self.default_build_targets = [t for t in FolderRule.DEFAULT_BUILD_TARGETS if t not in self.disable_targets]
+            self.default_build_targets = [
+                _target for _target in FolderRule.DEFAULT_BUILD_TARGETS if _target not in self.disable_targets
+            ]
             FolderRule.DEFAULT_BUILD_TARGETS = self.default_build_targets
 
         if self.override_sdkconfig_files or self.override_sdkconfig_items:
             SESSION_ARGS.set(self)
 
+        # load build system
+        # here could be a string or a class of type App
+        if not isinstance(self.build_system, str):
+            # do nothing, only cache
+            self._KNOWN_APP_CLASSES[self.build_system('', '').build_system] = self.build_system
+            return
+
+        # here could only be a string
+        if self.build_system in self._KNOWN_APP_CLASSES:
+            self.build_system = self._KNOWN_APP_CLASSES[self.build_system]
+            return
+
+        if ':' not in self.build_system:
+            raise ValueError(
+                f'Invalid build system: {self.build_system}. '
+                f'Known build systems: {", ".join(self._KNOWN_APP_CLASSES.keys())}'
+            )
+
+        # here could only be a string in format "module:class"
+        if self.build_system in self._LOADED_MODULE_APPS:
+            self.build_system = self._LOADED_MODULE_APPS[self.build_system]
+            return
+
+        # here could only be a string in format "module:class", and not loaded yet
+        module_path, class_name = self.build_system.split(':')
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as e:
+            raise ImportError(f'Failed to import module {module_path}. Error: {e!s}')
+
+        try:
+            app_cls = getattr(module, class_name)
+            if not issubclass(app_cls, App):
+                raise ValueError(f'Class {class_name} must be a subclass of App')
+        except (ValueError, AttributeError):
+            raise ValueError(f'Class {class_name} not found in module {module_path}')
+
+        self._LOADED_MODULE_APPS[self.build_system] = app_cls
+        self._KNOWN_APP_CLASSES[app_cls('', '').build_system] = app_cls
+
+        self.build_system = app_cls
+
 
 class FindArguments(FindBuildArguments):
     output: t.Optional[str] = field(

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/idf_build_apps/main.py

@@ -29,8 +29,6 @@ from idf_build_apps.args import (
 from .app import (
     App,
     AppDeserializer,
-    CMakeApp,
-    MakeApp,
 )
 from .autocompletions import activate_completions
 from .constants import ALL_TARGETS, BuildStatus, completion_instructions
@@ -88,18 +86,6 @@ def find_apps(
             **kwargs,
         )
 
-    app_cls: t.Type[App]
-    if isinstance(find_arguments.build_system, str):
-        # backwards compatible
-        if find_arguments.build_system == 'cmake':
-            app_cls = CMakeApp
-        elif find_arguments.build_system == 'make':
-            app_cls = MakeApp
-        else:
-            raise ValueError('Only Support "make" and "cmake"')
-    else:
-        app_cls = find_arguments.build_system
-
     apps: t.Set[App] = set()
     if find_arguments.target == 'all':
         targets = ALL_TARGETS
@@ -115,7 +101,7 @@ def find_apps(
                 _find_apps(
                     _p,
                     _t,
-                    app_cls=app_cls,
+                    app_cls=find_arguments.build_system,  # type: ignore
                     args=find_arguments,
                 )
             )
@@ -487,14 +473,43 @@ def json_to_app(json_str: str, extra_classes: t.Optional[t.List[t.Type[App]]] =
     :param extra_classes: extra App class
     :return: App object
     """
-    types = [App, CMakeApp, MakeApp]
+    _known_classes = list(FindArguments()._KNOWN_APP_CLASSES.values())
     if extra_classes:
-        types.extend(extra_classes)
+        _known_classes.extend(extra_classes)
 
     custom_deserializer = create_model(
         '_CustomDeserializer',
-        app=(t.Union[tuple(types)], Field(discriminator='build_system')),
+        app=(t.Union[tuple(_known_classes)], Field(discriminator='build_system')),
         __base__=AppDeserializer,
     )
 
     return custom_deserializer.from_json(json_str)
+
+
+def json_list_files_to_apps(
+    json_list_filepaths: t.List[str],
+    extra_classes: t.Optional[t.List[t.Type[App]]] = None,
+) -> t.List[App]:
+    """
+    Deserialize a list of json strings to App objects
+
+    :param json_list_filepaths: filepath to the files, each line is a json string
+    :param extra_classes: extra App class
+    :return: list of App object
+    """
+    _known_classes = list(FindArguments()._KNOWN_APP_CLASSES.values())
+    if extra_classes:
+        _known_classes.extend(extra_classes)
+
+    custom_deserializer = create_model(
+        '_CustomDeserializer',
+        app=(t.Union[tuple(_known_classes)], Field(discriminator='build_system')),
+        __base__=AppDeserializer,
+    )
+
+    jsons = []
+    for fp in json_list_filepaths:
+        with open(fp) as fr:
+            jsons.extend(fr.readlines())
+
+    return custom_deserializer.from_json_list(jsons)

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/pyproject.toml

@@ -10,7 +10,7 @@ authors = [
 readme = "README.md"
 license = {file = "LICENSE"}
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 5 - Production/Stable",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
@@ -18,6 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
 dynamic = ["version", "description"]
 requires-python = ">=3.7"
@@ -64,7 +65,7 @@ idf-build-apps = "idf_build_apps:main.main"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "2.9.0"
+version = "2.10.1"
 tag_format = "v$version"
 version_files = [
     "idf_build_apps/__init__.py",

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/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.9.0',
+      version='2.10.1',
       description='Tools for building ESP-IDF related apps.',
       author=None,
       author_email='Fu Hanxi <fuhanxi@espressif.com>',

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/tests/test_app.py

@@ -79,8 +79,7 @@ def test_app_deserializer():
 
     with pytest.raises(
         ValidationError,
-        match="Input tag 'custom' found using 'build_system' does not match "
-        "any of the expected tags: 'unknown', 'cmake', 'make'",
+        match="Input tag 'custom' found using 'build_system' does not match any of the expected tags: 'cmake', 'make'",
     ):
         assert json_to_app(c.to_json()) == c
 

{idf_build_apps-2.9.0 → idf_build_apps-2.10.1}/tests/test_build.py

@@ -3,9 +3,11 @@
 
 import os
 import shutil
+import subprocess
 from copy import (
     deepcopy,
 )
+from pathlib import Path
 from xml.etree import (
     ElementTree,
 )
@@ -20,6 +22,7 @@ from idf_build_apps import (
     find_apps,
 )
 from idf_build_apps.app import (
+    App,
     CMakeApp,
 )
 from idf_build_apps.args import BuildArguments
@@ -27,6 +30,7 @@ from idf_build_apps.constants import (
     IDF_PATH,
     BuildStatus,
 )
+from idf_build_apps.utils import Literal
 
 
 @pytest.mark.skipif(not shutil.which('idf.py'), reason='idf.py not found')
@@ -205,6 +209,105 @@ class TestBuild:
         assert test_suite.findall('testcase')[0].attrib['name'] == 'foo/bar/build'
 
 
+class CustomClassApp(App):
+    build_system: Literal['custom_class'] = 'custom_class'  # type: ignore
+
+    def build(self, *args, **kwargs):
+        # For testing, we'll just create a dummy build directory
+        if not self.dry_run:
+            os.makedirs(self.build_path, exist_ok=True)
+            with open(os.path.join(self.build_path, 'dummy.txt'), 'w') as f:
+                f.write('Custom build successful')
+        self.build_status = BuildStatus.SUCCESS
+        print('Custom build successful')
+
+    @classmethod
+    def is_app(cls, path: str) -> bool:  # noqa: ARG003
+        return True
+
+
+@pytest.mark.skipif(not shutil.which('idf.py'), reason='idf.py not found')
+class TestBuildWithCustomApp:
+    custom_app_code = """
+from idf_build_apps import App
+import os
+from idf_build_apps.constants import BuildStatus
+from idf_build_apps.utils import Literal
+
+class CustomApp(App):
+    build_system: Literal['custom'] = 'custom'
+
+    def build(self, *args, **kwargs):
+        # For testing, we'll just create a dummy build directory
+        if not self.dry_run:
+            os.makedirs(self.build_path, exist_ok=True)
+            with open(os.path.join(self.build_path, 'dummy.txt'), 'w') as f:
+                f.write('Custom build successful')
+        self.build_status = BuildStatus.SUCCESS
+        print('Custom build successful')
+
+    @classmethod
+    def is_app(cls, path: str) -> bool:
+        return True
+    """
+
+    @pytest.fixture(autouse=True)
+    def _setup(self, tmp_path: Path, monkeypatch):
+        os.chdir(tmp_path)
+
+        test_app = tmp_path / 'test_app'
+
+        test_app.mkdir()
+        (test_app / 'main' / 'main.c').parent.mkdir(parents=True)
+        (test_app / 'main' / 'main.c').write_text('void app_main() {}')
+
+        # Create a custom app module
+        custom_module = tmp_path / 'custom.py'
+        custom_module.write_text(self.custom_app_code)
+
+        monkeypatch.setenv('PYTHONPATH', os.getenv('PYTHONPATH', '') + os.pathsep + str(tmp_path))
+
+        return test_app
+
+    def test_custom_app_cli(self, tmp_path):
+        subprocess.run(
+            [
+                'idf-build-apps',
+                'build',
+                '-p',
+                'test_app',
+                '--target',
+                'esp32',
+                '--build-system',
+                'custom:CustomApp',
+            ],
+            check=True,
+        )
+
+        assert (tmp_path / 'test_app' / 'build' / 'dummy.txt').exists()
+        assert (tmp_path / 'test_app' / 'build' / 'dummy.txt').read_text() == 'Custom build successful'
+
+    def test_custom_app_function(self, tmp_path):
+        # Import the custom app class
+        # Find and build the app using the imported CustomApp class
+        apps = find_apps(
+            paths=['test_app'],
+            target='esp32',
+            build_system=CustomClassApp,
+        )
+
+        assert len(apps) == 1
+        app = apps[0]
+        assert isinstance(app, CustomClassApp)
+        assert app.build_system == 'custom_class'
+
+        # Build the app
+        app.build()
+        assert app.build_status == BuildStatus.SUCCESS
+        assert (tmp_path / 'test_app' / 'build' / 'dummy.txt').exists()
+        assert (tmp_path / 'test_app' / 'build' / 'dummy.txt').read_text() == 'Custom build successful'
+
+
 def test_build_apps_collect_files_when_no_apps_built(tmp_path):
     os.chdir(tmp_path)