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

{idf_build_apps-2.9.0 → idf_build_apps-2.10.0}/.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.0}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idf-build-apps
-Version: 2.9.0
+Version: 2.10.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.0/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.0}/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.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.9.0'
+__version__ = '2.10.0'
 
 from .session_args import (
     SessionArgs,

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

@@ -414,10 +414,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(

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

@@ -4,6 +4,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import argparse
+import importlib
 import json
 import logging
 import os
@@ -90,13 +91,24 @@ def find_apps(
 
     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
+        elif ':' in find_arguments.build_system:
+            # Custom App class in format "module:class"
+            try:
+                module_path, class_name = find_arguments.build_system.split(':')
+                module = importlib.import_module(module_path)
+                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, ImportError, AttributeError) as e:
+                raise ValueError(f'Invalid custom App class path: {find_arguments.build_system}. Error: {e!s}')
         else:
-            raise ValueError('Only Support "make" and "cmake"')
+            raise ValueError(
+                'build_system must be either "cmake", "make" or a custom App class path in format "module:class"'
+            )
     else:
         app_cls = find_arguments.build_system
 

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

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

{idf_build_apps-2.9.0 → idf_build_apps-2.10.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.9.0',
+      version='2.10.0',
       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.0}/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)