mposcli 0.1.0__py3-none-any.whl

mposcli/__init__.py

@@ -0,0 +1,8 @@
+"""
+    mposcli
+    CLI helper for MicroPythonOS: https://github.com/MicroPythonOS/MicroPythonOS
+"""
+
+# See https://packaging.python.org/en/latest/specifications/version-specifiers/
+__version__ = '0.1.0'
+__author__ = 'Jens Diemer <cookiecutter_templates@jensdiemer.de>'

mposcli/__main__.py

@@ -0,0 +1,10 @@
+"""
+    Allow mposcli to be executable
+    through `python -m mposcli`.
+"""
+
+from mposcli.cli_app import main
+
+
+if __name__ == '__main__':
+    main()

mposcli/cli_app/__init__.py

@@ -0,0 +1,41 @@
+"""
+    CLI for usage
+"""
+
+import logging
+import sys
+from collections.abc import Sequence
+
+from cli_base.autodiscover import import_all_files
+from cli_base.cli_tools.version_info import print_version
+from rich import print  # noqa
+from tyro.extras import SubcommandApp
+
+import mposcli
+from mposcli import constants
+
+
+logger = logging.getLogger(__name__)
+
+app = SubcommandApp()
+
+# Register all CLI commands, just by import all files in this package:
+import_all_files(package=__package__, init_file=__file__)
+
+
+@app.command
+def version():
+    """Print version and exit"""
+    # Pseudo command, because the version always printed on every CLI call ;)
+    sys.exit(0)
+
+
+def main(args: Sequence[str] | None = None):
+    print_version(mposcli)
+    app.cli(
+        prog='mposcli',  # Enforce "pipx" usage
+        description=constants.CLI_EPILOG,
+        use_underscores=False,  # use hyphens instead of underscores
+        sort_subcommands=True,
+        args=args,
+    )

mposcli/cli_app/build.py

@@ -0,0 +1,46 @@
+import logging
+from typing import Annotated, Literal
+
+import tyro
+from bx_py_utils.path import assert_is_file
+from cli_base.cli_tools.subprocess_utils import verbose_check_call
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.tyro_commands import TyroVerbosityArgType
+from rich import print  # noqa
+
+from mposcli.cli_app import app
+from mposcli.mpos_utils import get_mpos_path
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def build(
+    target: Annotated[
+        Literal['esp32', 'esp32s3', 'unix', 'macOS'],
+        tyro.conf.arg(
+            help='Target platform to build for.',
+        ),
+    ] = 'unix',
+    verbosity: TyroVerbosityArgType = 1,
+):
+    """
+    Build MicroPythonOS by calling: ./scripts/build_mpos.sh <target>
+    see: https://docs.micropythonos.com/os-development/
+    """
+    setup_logging(verbosity=verbosity)
+
+    mpos_path = get_mpos_path()
+
+    script_path = mpos_path / 'scripts' / 'build_mpos.sh'
+    assert_is_file(script_path)
+
+    verbose_check_call(
+        script_path,
+        target,
+        verbose=True,
+        cwd=mpos_path,
+        timeout=None,
+        text=None,
+    )

mposcli/cli_app/run_deskop.py

@@ -0,0 +1,105 @@
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import tyro
+from bx_py_utils.path import assert_is_file
+from cli_base.cli_tools.subprocess_utils import verbose_check_call
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.tyro_commands import TyroVerbosityArgType
+from rich import print  # noqa
+
+from mposcli.cli_app import app
+from mposcli.fs_utils import list_executables
+from mposcli.mpos_utils import get_mpos_path
+from mposcli.user_input import file_chooser
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def run_desktop(
+    heapsize: Annotated[
+        int,
+        tyro.conf.arg(
+            help='Heap size in MB (default: 8, same as PSRAM on many ESP32-S3 boards)',
+        ),
+    ] = 8,
+    script: Annotated[
+        str | None,
+        tyro.conf.arg(help='Script file (.py) or app name to run. If omitted, starts normally.'),
+    ] = None,
+    binary: Annotated[
+        str | None,
+        tyro.conf.arg(
+            help='Optional name of the binary to start.'
+            ' If omitted, shows a file chooser to select one from the lvgl_micropython build directory.'
+        ),
+    ] = None,
+    verbosity: TyroVerbosityArgType = 1,
+):
+    """
+    Run MicroPythonOS on desktop.
+    see: https://docs.micropythonos.com/getting-started/running/#running-on-desktop
+    """
+    setup_logging(verbosity=verbosity)
+
+    mpos_path = get_mpos_path()
+
+    internal_fs = mpos_path / 'internal_filesystem'
+    lvgl_micropython_build_path = mpos_path / 'lvgl_micropython' / 'build'
+
+    executables = list_executables(lvgl_micropython_build_path)
+    if not executables:
+        print(f'Error: No executable found in {lvgl_micropython_build_path}.')
+        print('Hint: Download or build the lvgl_micropython binary first.')
+        print('Hint 2: Forgotten to make the binary executable? e.g.: chmod +x <binary>')
+        sys.exit(1)
+
+    if binary:
+        binary = lvgl_micropython_build_path / binary
+    else:
+        binary = file_chooser(executables)
+    assert_is_file(binary)
+
+    os.environ['HEAPSIZE'] = f'{heapsize}M'
+
+    # Change to internal_filesystem dir
+    os.chdir(internal_fs)
+
+    popenargs = [binary]
+
+    if script and script.endswith('.py') and Path(script).is_file():
+        # Run script file directly
+        script_path = str(Path(script).resolve())
+        popenargs += ('-v', '-i', script_path)
+    else:
+        if script:
+            # Treat as app name
+            config_file = Path('data/com.micropythonos.settings/config.json')
+            config_file.parent.mkdir(parents=True, exist_ok=True)
+            if config_file.exists():
+                with config_file.open('r', encoding='utf-8') as f:
+                    try:
+                        config = json.load(f)
+                    except Exception:
+                        config = {}
+            else:
+                config = {}
+            config['auto_start_app'] = script
+            with config_file.open('w', encoding='utf-8') as f:
+                json.dump(config, f)
+        popenargs += ('-X', f'heapsize={os.environ["HEAPSIZE"]}', '-v', '-i', '-c', Path('main.py').read_text())
+
+    verbose_check_call(
+        *popenargs,
+        env=os.environ,
+        verbose=True,
+        cwd=internal_fs,
+        timeout=None,
+        text=None,
+    )

mposcli/cli_app/update.py

@@ -0,0 +1,35 @@
+import logging
+
+from cli_base.cli_tools.subprocess_utils import verbose_check_call
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.tyro_commands import TyroVerbosityArgType
+from rich import print  # noqa
+
+from mposcli.cli_app import app
+from mposcli.mpos_utils import get_mpos_path
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def update_submodules(verbosity: TyroVerbosityArgType = 1):
+    """
+    Update MicroPythonOS repository and all submodules
+    see: https://docs.micropythonos.com/os-development/linux/#optional-updating-the-code
+    """
+    setup_logging(verbosity=verbosity)
+    mpos_path = get_mpos_path()
+
+    commands = (
+        ('git', 'submodule', 'foreach', '--recursive', 'git', 'clean', '-f', ';', 'git', 'checkout', '.'),
+        ('git', 'pull', '--recurse-submodules'),
+    )
+    for popenargs in commands:
+        verbose_check_call(
+            *popenargs,
+            verbose=True,
+            cwd=mpos_path,
+            timeout=None,
+            text=None,
+        )

mposcli/cli_dev/__init__.py

@@ -0,0 +1,70 @@
+"""
+    CLI for development
+"""
+
+import importlib
+import logging
+import sys
+from collections.abc import Sequence
+
+from bx_py_utils.path import assert_is_file
+from cli_base.autodiscover import import_all_files
+from cli_base.cli_tools.dev_tools import run_coverage, run_nox, run_unittest_cli
+from cli_base.cli_tools.version_info import print_version
+from typeguard import install_import_hook
+from tyro.extras import SubcommandApp
+
+import mposcli
+from mposcli import constants
+
+
+# Check type annotations via typeguard in all tests.
+# Sadly we must activate this here and can't do this in ./tests/__init__.py
+install_import_hook(packages=('mposcli',))
+
+# reload the module, after the typeguard import hook is activated:
+importlib.reload(mposcli)
+
+
+logger = logging.getLogger(__name__)
+
+
+PACKAGE_ROOT = constants.BASE_PATH.parent
+assert_is_file(PACKAGE_ROOT / 'pyproject.toml')  # Exists only in cloned git repo
+
+
+app = SubcommandApp()
+
+
+# Register all CLI commands, just by import all files in this package:
+import_all_files(package=__package__, init_file=__file__)
+
+
+@app.command
+def version():
+    """Print version and exit"""
+    # Pseudo command, because the version always printed on every CLI call ;)
+    sys.exit(0)
+
+
+def main(args: Sequence[str] | None = None):
+    print_version(mposcli)
+
+    if len(sys.argv) >= 2:
+        # Check if we can just pass a command call to origin CLI:
+        command = sys.argv[1]
+        command_map = {
+            'test': run_unittest_cli,
+            'nox': run_nox,
+            'coverage': run_coverage,
+        }
+        if real_func := command_map.get(command):
+            real_func(argv=sys.argv, exit_after_run=True)
+
+    app.cli(
+        prog='./dev-cli.py',
+        description=constants.CLI_EPILOG,
+        use_underscores=False,  # use hyphens instead of underscores
+        sort_subcommands=True,
+        args=args,
+    )

mposcli/cli_dev/__main__.py

@@ -0,0 +1,10 @@
+"""
+    Allow mposcli to be executable
+    through `python -m mposcli.cli_dev`.
+"""
+
+from mposcli.cli_dev import main
+
+
+if __name__ == '__main__':
+    main()

mposcli/cli_dev/code_style.py

@@ -0,0 +1,12 @@
+from cli_base.cli_tools.code_style import assert_code_style
+from cli_base.tyro_commands import TyroVerbosityArgType
+
+from mposcli.cli_dev import PACKAGE_ROOT, app
+
+
+@app.command
+def lint(verbosity: TyroVerbosityArgType = 1):
+    """
+    Check/fix code style by run: "ruff check --fix"
+    """
+    assert_code_style(package_root=PACKAGE_ROOT, verbose=bool(verbosity), sys_exit=True)

mposcli/cli_dev/packaging.py

@@ -0,0 +1,62 @@
+import logging
+
+from cli_base.cli_tools.dev_tools import run_unittest_cli
+from cli_base.cli_tools.subprocess_utils import ToolsExecutor
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.run_pip_audit import run_pip_audit
+from cli_base.tyro_commands import TyroVerbosityArgType
+from manageprojects.utilities.publish import publish_package
+
+import mposcli
+from mposcli.cli_dev import PACKAGE_ROOT, app
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def install():
+    """
+    Install requirements and 'mposcli' via pip as editable.
+    """
+    tools_executor = ToolsExecutor(cwd=PACKAGE_ROOT)
+    tools_executor.verbose_check_call('uv', 'sync')
+    tools_executor.verbose_check_call('uv', 'pip', 'install', '--no-deps', '-e', '.')
+
+
+@app.command
+def pip_audit(verbosity: TyroVerbosityArgType):
+    """
+    Run pip-audit check against current requirements files
+    """
+    setup_logging(verbosity=verbosity)
+    run_pip_audit(base_path=PACKAGE_ROOT, verbosity=verbosity)
+
+
+@app.command
+def update(verbosity: TyroVerbosityArgType):
+    """
+    Update dependencies (uv.lock) and git pre-commit hooks
+    """
+    setup_logging(verbosity=verbosity)
+
+    tools_executor = ToolsExecutor(cwd=PACKAGE_ROOT)
+    tools_executor.verbose_check_call('uv', 'lock', '--upgrade')
+
+    run_pip_audit(base_path=PACKAGE_ROOT, verbosity=verbosity)
+
+    # Install new dependencies in current .venv:
+    tools_executor.verbose_check_call('uv', 'sync')
+
+    # Update git pre-commit hooks:
+    tools_executor.verbose_check_call('pre-commit', 'autoupdate')
+
+
+@app.command
+def publish():
+    """
+    Build and upload this project to PyPi
+    """
+    run_unittest_cli(verbose=False, exit_after_run=False)  # Don't publish a broken state
+
+    publish_package(module=mposcli, package_path=PACKAGE_ROOT)

mposcli/cli_dev/shell_completion.py

@@ -0,0 +1,23 @@
+import logging
+
+from cli_base.cli_tools.shell_completion import setup_tyro_shell_completion
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.tyro_commands import TyroVerbosityArgType
+from rich import print  # noqa
+
+from mposcli.cli_dev import app
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def shell_completion(verbosity: TyroVerbosityArgType = 1, remove: bool = False) -> None:
+    """
+    Setup shell completion for this CLI (Currently only for bash shell)
+    """
+    setup_logging(verbosity=verbosity)
+    setup_tyro_shell_completion(
+        prog_name='mposcli_dev_cli',
+        remove=remove,
+    )

mposcli/cli_dev/testing.py

@@ -0,0 +1,52 @@
+from cli_base.cli_tools.dev_tools import run_coverage, run_nox, run_unittest_cli
+from cli_base.cli_tools.subprocess_utils import verbose_check_call
+from cli_base.cli_tools.test_utils.snapshot import UpdateTestSnapshotFiles
+from cli_base.tyro_commands import TyroVerbosityArgType
+
+from mposcli.cli_dev import PACKAGE_ROOT, app
+
+
+@app.command
+def mypy(verbosity: TyroVerbosityArgType):
+    """Run Mypy (configured in pyproject.toml)"""
+    verbose_check_call('mypy', '.', cwd=PACKAGE_ROOT, verbose=verbosity > 0, exit_on_error=True)
+
+
+@app.command
+def update_test_snapshot_files(verbosity: TyroVerbosityArgType):
+    """
+    Update all test snapshot files (by remove and recreate all snapshot files)
+    """
+    with UpdateTestSnapshotFiles(root_path=PACKAGE_ROOT, verbose=verbosity > 0):
+        # Just recreate them by running tests:
+        run_unittest_cli(
+            extra_env=dict(
+                RAISE_SNAPSHOT_ERRORS='0',  # Recreate snapshot files without error
+            ),
+            verbose=verbosity > 1,
+            exit_after_run=False,
+        )
+
+
+@app.command  # Dummy command
+def test():
+    """
+    Run unittests
+    """
+    run_unittest_cli()
+
+
+@app.command  # Dummy command
+def coverage():
+    """
+    Run tests and show coverage report.
+    """
+    run_coverage()
+
+
+@app.command  # Dummy "nox" command
+def nox():
+    """
+    Run nox
+    """
+    run_nox()

mposcli/cli_dev/update_readme_history.py

@@ -0,0 +1,33 @@
+import logging
+import sys
+from pathlib import Path
+
+from cli_base.cli_tools import git_history
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.tyro_commands import TyroVerbosityArgType
+from rich import print  # noqa
+
+from mposcli.cli_dev import app
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def update_readme_history(verbosity: TyroVerbosityArgType):
+    """
+    Update project history base on git commits/tags in README.md
+
+    Will be exited with 1 if the README.md was updated otherwise with 0.
+
+    Also, callable via e.g.:
+        python -m cli_base update-readme-history -v
+    """
+    setup_logging(verbosity=verbosity)
+
+    logger.debug('%s called. CWD: %s', __name__, Path.cwd())
+    updated = git_history.update_readme_history(verbosity=verbosity)
+    exit_code = 1 if updated else 0
+    if verbosity:
+        print(f'{exit_code=}')
+    sys.exit(exit_code)

mposcli/constants.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+import mposcli
+
+
+CLI_EPILOG = 'Project Homepage: https://github.com/jedie/mposcli'
+
+BASE_PATH = Path(mposcli.__file__).parent

mposcli/fs_utils.py

@@ -0,0 +1,6 @@
+import os
+from pathlib import Path
+
+
+def list_executables(directory: Path) -> list[Path]:
+    return [f for f in directory.iterdir() if f.is_file() and os.access(f, os.X_OK)]

mposcli/mpos_utils.py

@@ -0,0 +1,28 @@
+import logging
+import sys
+from pathlib import Path
+
+from rich import print  # noqa
+
+
+logger = logging.getLogger(__name__)
+
+
+def get_mpos_path() -> Path:
+    """
+    Get the path to the MicroPythonOS project root directory.
+    Assume that mposcli is only called from the root directory of a MicroPythonOS project.
+    """
+    current_path = Path().cwd().resolve()
+    logger.info('Current working directory: %s', current_path)
+
+    for dir_name in ('internal_filesystem', Path('lvgl_micropython', 'build')):
+        dir_path = current_path / dir_name
+        logger.debug('Checking for directory: %s', dir_path)
+        if not dir_path.is_dir():
+            print(f"Error: Directory '{dir_name}' not found in {current_path}.")
+            print('Hint: Call "mposcli" only in the root directory of a MicroPythonOS project!')
+            sys.exit(1)
+
+    mpos_path = current_path
+    return mpos_path

mposcli/tests/__init__.py

@@ -0,0 +1,36 @@
+import os
+import unittest.util
+from pathlib import Path
+
+from bx_py_utils.test_utils.deny_requests import deny_any_real_request
+from cli_base.cli_tools.verbosity import MAX_LOG_LEVEL, setup_logging
+from rich import print  # noqa
+from typeguard import install_import_hook
+
+
+# Check type annotations via typeguard in all tests:
+install_import_hook(packages=('mposcli',))
+
+
+def pre_configure_tests() -> None:
+    print(f'Configure unittests via "load_tests Protocol" from {Path(__file__).relative_to(Path.cwd())}')
+
+    # Hacky way to display more "assert"-Context in failing tests:
+    _MIN_MAX_DIFF = unittest.util._MAX_LENGTH - unittest.util._MIN_DIFF_LEN
+    unittest.util._MAX_LENGTH = int(os.environ.get('UNITTEST_MAX_LENGTH', 2000))
+    unittest.util._MIN_DIFF_LEN = unittest.util._MAX_LENGTH - _MIN_MAX_DIFF
+
+    # Deny any request via docket/urllib3 because tests they should mock all requests:
+    deny_any_real_request()
+
+    # Display DEBUG logs in tests:
+    setup_logging(verbosity=MAX_LOG_LEVEL)
+
+
+def load_tests(loader, tests, pattern):
+    """
+    Use unittest "load_tests Protocol" as a hook to setup test environment before running tests.
+    https://docs.python.org/3/library/unittest.html#load-tests-protocol
+    """
+    pre_configure_tests()
+    return loader.discover(start_dir=Path(__file__).parent, pattern=pattern)

mposcli/tests/test_doctests.py

@@ -0,0 +1,10 @@
+from bx_py_utils.test_utils.unittest_utils import BaseDocTests
+
+import mposcli
+
+
+class DocTests(BaseDocTests):
+    def test_doctests(self):
+        self.run_doctests(
+            modules=(mposcli,),
+        )

mposcli/tests/test_project_setup.py

@@ -0,0 +1,46 @@
+import subprocess
+from unittest import TestCase
+
+from bx_py_utils.path import assert_is_file
+from cli_base.cli_tools.code_style import assert_code_style
+from cli_base.cli_tools.subprocess_utils import ToolsExecutor
+from manageprojects.test_utils.project_setup import check_editor_config, get_py_max_line_length
+from packaging.version import Version
+
+from mposcli import __version__
+from mposcli.cli_dev import PACKAGE_ROOT
+
+
+class ProjectSetupTestCase(TestCase):
+    def test_version(self):
+        self.assertIsNotNone(__version__)
+
+        version = Version(__version__)  # Will raise InvalidVersion() if wrong formatted
+        self.assertEqual(str(version), __version__)
+
+        cli_bin = PACKAGE_ROOT / 'cli.py'
+        assert_is_file(cli_bin)
+
+        output = subprocess.check_output([cli_bin, 'version'], text=True)
+        self.assertIn(f'mposcli v{__version__}', output)
+
+        dev_cli_bin = PACKAGE_ROOT / 'dev-cli.py'
+        assert_is_file(dev_cli_bin)
+
+        output = subprocess.check_output([dev_cli_bin, 'version'], text=True)
+        self.assertIn(f'mposcli v{__version__}', output)
+
+    def test_code_style(self):
+        return_code = assert_code_style(package_root=PACKAGE_ROOT)
+        self.assertEqual(return_code, 0, 'Code style error, see output above!')
+
+    def test_check_editor_config(self):
+        check_editor_config(package_root=PACKAGE_ROOT)
+
+        max_line_length = get_py_max_line_length(package_root=PACKAGE_ROOT)
+        self.assertEqual(max_line_length, 119)
+
+    def test_pre_commit_hooks(self):
+        executor = ToolsExecutor(cwd=PACKAGE_ROOT)
+        for command in ('migrate-config', 'validate-config', 'validate-manifest'):
+            executor.verbose_check_call('pre-commit', command, exit_on_error=True)

mposcli/tests/test_readme.py

@@ -0,0 +1,88 @@
+from bx_py_utils.auto_doc import assert_readme_block
+from bx_py_utils.path import assert_is_file
+from cli_base.cli_tools.test_utils.assertion import assert_in
+from cli_base.cli_tools.test_utils.rich_test_utils import NoColorEnvRich, invoke
+from manageprojects.tests.base import BaseTestCase
+
+from mposcli import constants
+from mposcli.cli_dev import PACKAGE_ROOT
+
+
+def assert_cli_help_in_readme(text_block: str, marker: str):
+    README_PATH = PACKAGE_ROOT / 'README.md'
+    assert_is_file(README_PATH)
+
+    text_block = text_block.replace(constants.CLI_EPILOG, '')
+    text_block = f'```\n{text_block.strip()}\n```'
+    assert_readme_block(
+        readme_path=README_PATH,
+        text_block=text_block,
+        start_marker_line=f'[comment]: <> (✂✂✂ auto generated {marker} start ✂✂✂)',
+        end_marker_line=f'[comment]: <> (✂✂✂ auto generated {marker} end ✂✂✂)',
+    )
+
+
+class ReadmeTestCase(BaseTestCase):
+
+    def test_main_help(self):
+        with NoColorEnvRich():
+            stdout = invoke(
+                cli_bin=PACKAGE_ROOT / 'cli.py',
+                args=['--help'],
+                strip_line_prefix='usage: ',
+            )
+        assert_in(
+            content=stdout,
+            parts=(
+                'usage: mposcli [-h]',
+                ' version ',
+                'Print version and exit',
+                constants.CLI_EPILOG,
+            ),
+        )
+        assert_cli_help_in_readme(text_block=stdout, marker='main help')
+
+    def test_dev_help(self):
+        with NoColorEnvRich():
+            stdout = invoke(
+                cli_bin=PACKAGE_ROOT / 'dev-cli.py',
+                args=['--help'],
+                strip_line_prefix='usage: ',
+            )
+        assert_in(
+            content=stdout,
+            parts=(
+                'usage: ./dev-cli.py [-h]',
+                ' lint ',
+                ' coverage ',
+                ' update-readme-history ',
+                ' publish ',
+                constants.CLI_EPILOG,
+            ),
+        )
+        assert_cli_help_in_readme(text_block=stdout, marker='dev help')
+
+    def test_cli_commands(self):
+        from mposcli.cli_app import app
+
+        # Dynamically build command list from app object
+        # tyro SubcommandApp stores subcommands in _subcommands dict
+        commands = set(command.replace('_', '-') for command in app._subcommands.keys())
+
+        commands.discard('version')  # version is pseudo command, because the version always printed on every CLI call
+        commands = sorted(commands)
+        self.assertEqual(commands, ['build', 'run-desktop', 'update-submodules'])
+
+        for command in commands:
+            with self.subTest(command):
+                with NoColorEnvRich():
+                    stdout = invoke(
+                        cli_bin=PACKAGE_ROOT / 'cli.py',
+                        args=[command, '--help'],
+                        strip_line_prefix='usage: ',
+                    )
+                assert_in(
+                    content=stdout,
+                    parts=(f'usage: mposcli {command} [-h]',),
+                )
+                assert_cli_help_in_readme(text_block=stdout, marker=command)

mposcli/tests/test_readme_history.py

@@ -0,0 +1,9 @@
+from unittest import TestCase
+
+from cli_base.cli_tools.git_history import update_readme_history
+
+
+class ReadmeHistoryTestCase(TestCase):
+    def test_readme_history(self):
+        with self.assertLogs():
+            update_readme_history(raise_update_error=True)

mposcli/user_input.py

@@ -0,0 +1,37 @@
+import datetime
+import sys
+
+from rich import print
+
+
+def file_chooser(paths):
+    """
+    Display a numbered list of files sorted by modification time (newest first).
+    Show mtime and file name. Input number, ENTER = 1. Return selected Path.
+    """
+
+    files = [(p, p.stat().st_mtime) for p in paths if p.is_file()]
+    if not files:
+        print('[red]No files found.[/red]')
+        return None
+    files.sort(key=lambda x: x[1], reverse=True)
+
+    print('[bold]Choose a file:[/bold]')
+    for idx, (p, mtime) in enumerate(files):
+        dt = datetime.datetime.fromtimestamp(mtime).strftime('%Y-%m-%d %H:%M:%S')
+        print(f'[{idx}] {dt}  {p.name}')
+
+    number = input('Enter number (ENTER = 0 - the newest file): ').strip() or 0
+    try:
+        number = int(number)
+    except Exception as err:
+        print(f'[red]Invalid input: {err}[/red]')
+        sys.exit(1)
+
+    try:
+        selection = files[number][0]
+    except IndexError:
+        print(f'[red]Invalid selection: {number}[/red]')
+        sys.exit(1)
+
+    return selection

mposcli-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: mposcli
+Version: 0.1.0
+Summary: CLI helper for MicroPythonOS: https://github.com/MicroPythonOS/MicroPythonOS
+Project-URL: Documentation, https://github.com/jedie/mposcli
+Project-URL: Source, https://github.com/jedie/mposcli
+Author-email: Jens Diemer <cookiecutter_templates@jensdiemer.de>
+License: GPL-3.0-or-later
+Requires-Python: >=3.12
+Requires-Dist: bx-py-utils
+Requires-Dist: cli-base-utilities>=0.27.4
+Requires-Dist: rich
+Requires-Dist: tyro
+Description-Content-Type: text/markdown
+
+# mposcli
+
+[![tests](https://github.com/jedie/mposcli/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/jedie/mposcli/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/github/jedie/mposcli/branch/main/graph/badge.svg)](https://app.codecov.io/github/jedie/mposcli)
+[![mposcli @ PyPi](https://img.shields.io/pypi/v/mposcli?label=mposcli%20%40%20PyPi)](https://pypi.org/project/mposcli/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mposcli)](https://github.com/jedie/mposcli/blob/main/pyproject.toml)
+[![License GPL-3.0-or-later](https://img.shields.io/pypi/l/mposcli)](https://github.com/jedie/mposcli/blob/main/LICENSE)
+
+Experimental CLI helper for MicroPythonOS: https://github.com/MicroPythonOS/MicroPythonOS
+
+Main Idea: Install it via pipx (see below) and use `mposcli` command in MicroPythonOS repository path.
+
+## CLI
+
+[comment]: <> (✂✂✂ auto generated main help start ✂✂✂)
+```
+usage: mposcli [-h] {build,run-desktop,update-submodules,version}
+
+
+
+╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help             show this help message and exit                                                               │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ subcommands ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ (required)                                                                                                           │
+│   • build              Build MicroPythonOS by calling: ./scripts/build_mpos.sh <target> see:                         │
+│                        https://docs.micropythonos.com/os-development/                                                │
+│   • run-desktop        Run MicroPythonOS on desktop. see:                                                            │
+│                        https://docs.micropythonos.com/getting-started/running/#running-on-desktop                    │
+│   • update-submodules  Update MicroPythonOS repository and all submodules see:                                       │
+│                        https://docs.micropythonos.com/os-development/linux/#optional-updating-the-code               │
+│   • version            Print version and exit                                                                        │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated main help end ✂✂✂)
+
+
+## CLI - build
+
+[comment]: <> (✂✂✂ auto generated build start ✂✂✂)
+```
+usage: mposcli build [-h] [--target {esp32,esp32s3,unix,macOS}] [-v]
+
+Build MicroPythonOS by calling: ./scripts/build_mpos.sh <target> see: https://docs.micropythonos.com/os-development/
+
+╭─ options ────────────────────────────────────────────────────────────────╮
+│ -h, --help       show this help message and exit                         │
+│ --target {esp32,esp32s3,unix,macOS}                                      │
+│                  Target platform to build for. (default: unix)           │
+│ -v, --verbosity  Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable) │
+╰──────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated build end ✂✂✂)
+
+
+
+## CLI - run-desktop
+
+
+[comment]: <> (✂✂✂ auto generated run-desktop start ✂✂✂)
+```
+usage: mposcli run-desktop [-h] [--heapsize INT] [--script {None}|STR] [--binary {None}|STR] [-v]
+
+Run MicroPythonOS on desktop. see: https://docs.micropythonos.com/getting-started/running/#running-on-desktop
+
+╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help           show this help message and exit                                                                 │
+│ --heapsize INT       Heap size in MB (default: 8, same as PSRAM on many ESP32-S3 boards) (default: 8)                │
+│ --script {None}|STR  Script file (.py) or app name to run. If omitted, starts normally. (default: None)              │
+│ --binary {None}|STR  Optional name of the binary to start. If omitted, shows a file chooser to select one from the   │
+│                      lvgl_micropython build directory. (default: None)                                               │
+│ -v, --verbosity      Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)                                         │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated run-desktop end ✂✂✂)
+
+
+## CLI - update-submodules
+
+
+[comment]: <> (✂✂✂ auto generated update-submodules start ✂✂✂)
+```
+usage: mposcli update-submodules [-h] [-v]
+
+Update MicroPythonOS repository and all submodules see: https://docs.micropythonos.com/os-development/linux/#optional-updating-the-code
+
+╭─ options ────────────────────────────────────────────────────────────────╮
+│ -h, --help       show this help message and exit                         │
+│ -v, --verbosity  Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable) │
+╰──────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated update-submodules end ✂✂✂)
+
+
+
+
+
+
+## start development
+
+At least `uv` is needed. Install e.g.: via pipx:
+```bash
+apt-get install pipx
+pipx install uv
+```
+
+Clone the project and just start the CLI help commands.
+A virtual environment will be created/updated automatically.
+
+```bash
+~$ git clone https://github.com/jedie/mposcli.git
+~$ cd mposcli
+~/mposcli$ ./cli.py --help
+~/mposcli$ ./dev-cli.py --help
+```
+
+[comment]: <> (✂✂✂ auto generated dev help start ✂✂✂)
+```
+usage: ./dev-cli.py [-h] {coverage,install,lint,mypy,nox,pip-audit,publish,shell-completion,test,update,update-readme-history,update-test-snapshot-files,version}
+
+
+
+╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help     show this help message and exit                                                                       │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ subcommands ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ (required)                                                                                                           │
+│   • coverage   Run tests and show coverage report.                                                                   │
+│   • install    Install requirements and 'mposcli' via pip as editable.                                               │
+│   • lint       Check/fix code style by run: "ruff check --fix"                                                       │
+│   • mypy       Run Mypy (configured in pyproject.toml)                                                               │
+│   • nox        Run nox                                                                                               │
+│   • pip-audit  Run pip-audit check against current requirements files                                                │
+│   • publish    Build and upload this project to PyPi                                                                 │
+│   • shell-completion                                                                                                 │
+│                Setup shell completion for this CLI (Currently only for bash shell)                                   │
+│   • test       Run unittests                                                                                         │
+│   • update     Update dependencies (uv.lock) and git pre-commit hooks                                                │
+│   • update-readme-history                                                                                            │
+│                Update project history base on git commits/tags in README.md Will be exited with 1 if the README.md   │
+│                was updated otherwise with 0.                                                                         │
+│                                                                                                                      │
+│                Also, callable via e.g.:                                                                              │
+│                    python -m cli_base update-readme-history -v                                                       │
+│   • update-test-snapshot-files                                                                                       │
+│                Update all test snapshot files (by remove and recreate all snapshot files)                            │
+│   • version    Print version and exit                                                                                │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated dev help end ✂✂✂)
+
+
+## History
+
+[comment]: <> (✂✂✂ auto generated history start ✂✂✂)
+
+* [**dev**](https://github.com/jedie/mposcli/compare/1695026...main)
+  * 2026-02-16 - Add "update-submodules" command
+  * 2026-02-16 - Add "build" command
+  * 2026-02-16 - CLI command: "run-desktop"
+  * 2026-02-16 - first commit
+
+[comment]: <> (✂✂✂ auto generated history end ✂✂✂)

mposcli-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+mposcli/__init__.py,sha256=xJiMZ56FfdXOY73tYd5S2cxUMBXmiwtzl7kkbcEFdPI,270
+mposcli/__main__.py,sha256=Xyf-B30u54m12uBqpL1HDMdFtD64a-rhFPgmRZlevjU,150
+mposcli/constants.py,sha256=26abB8No0nNvCd--M7Z6sGgAPG_OloyUk5ugJGR6D6I,152
+mposcli/fs_utils.py,sha256=_S2TtgG5iY0ZHctKFZ-9J49WrV0QChbyU-JqpZjsBJg,175
+mposcli/mpos_utils.py,sha256=DJ9LHL0Dw0nFe7Kmqattc0kxoQIk6u8tiwFkv_GR5co,899
+mposcli/user_input.py,sha256=eUuRiGCHb7OxorDB-dyG6pbXKDeDIPc8VFcDLT7AWSg,1048
+mposcli/cli_app/__init__.py,sha256=ngvmI2LD2Qtc18TNxORzv4yvQT1QrflD3kj5EoOlyjs,966
+mposcli/cli_app/build.py,sha256=7fjxPYT5jTXgrqouMYlvnY5R0whd2H6JzuFmfFMlISU,1141
+mposcli/cli_app/run_deskop.py,sha256=cBl5-JMd6SK6dAKJ-ttjGmb8CXvciMfW2bO9svXaWqU,3330
+mposcli/cli_app/update.py,sha256=J2cAfITOa_GhmOzvsACSuqzKRVvDfD1XpAT8awb8GKo,1023
+mposcli/cli_dev/__init__.py,sha256=cPMttKS3TNZdP-CTSKCNSEIsquaUi8K-8VDxQ9Ey8xQ,1873
+mposcli/cli_dev/__main__.py,sha256=Yx-Cc_oeUQo_M1uPV37Evz0PvKy5gUsUeEH19oEzSvM,158
+mposcli/cli_dev/code_style.py,sha256=5kBHRqAPmAg27R00TWXE4EdPlTsOLkw65RKn4qEVkx8,382
+mposcli/cli_dev/packaging.py,sha256=bZH7DLIF9lVWwdKJjpe69VgGmTLGylSfU9i_WUlm0PY,1798
+mposcli/cli_dev/shell_completion.py,sha256=y96MQ8L0PLFYop9l8QTvRKs3q-aSC_5IrVf5AiSixqo,636
+mposcli/cli_dev/testing.py,sha256=j4yj6aMQLlEYDUoel3uJnfkFKArW0YtiSGPK7BPMxfM,1381
+mposcli/cli_dev/update_readme_history.py,sha256=k0wVSHMIRyQxiQdxHWwVxxQAYSqMWuEogEkdlWP0fBQ,900
+mposcli/tests/__init__.py,sha256=LsOCUKW7i2biT8mo4eGTiNqS6d_G0p7801FrrDJQku8,1338
+mposcli/tests/test_doctests.py,sha256=Gfv3EbactIO1JgDroQVp-sunSDWhasgEtElwc_ddL3Q,209
+mposcli/tests/test_project_setup.py,sha256=dSqtKBQo6lUFTnX22LU7buY_jWkUiGrM_rXfslYtwCY,1759
+mposcli/tests/test_readme.py,sha256=I9H5uxhASMCzxllPBShHQKS14ZdRZWiyvXOpYc4uLf8,3173
+mposcli/tests/test_readme_history.py,sha256=PbxF_yRspyRwkVCQosZXevIHrsla3WFBTUVeLI0bb-s,263
+mposcli-0.1.0.dist-info/METADATA,sha256=9TTGJ634Iun41T0m5w-XH8egoPx50z5IiEmvDSA0q30,13266
+mposcli-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mposcli-0.1.0.dist-info/entry_points.txt,sha256=N3mHDYWJTw7GQa9Kakr3fcyDpRIXRC04TllScaURHN4,50
+mposcli-0.1.0.dist-info/RECORD,,

mposcli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mposcli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mposcli = mposcli.__main__:main