micropython-microbit-fs 0.1.0__tar.gz

micropython_microbit_fs-0.1.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: micropython-microbit-fs
+Version: 0.1.0
+Summary: Library and cli app to add and extract files from MicroPython Hex files for micro:bit
+Keywords: microbit,micropython,filesystem,intel-hex,embedded
+Author: Carlos Pereira Atencio
+Author-email: Carlos Pereira Atencio <carlosperate@embeddedlog.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Dist: cyclopts>=3.24.0
+Requires-Dist: intelhex>=2.3.0
+Requires-Dist: packaging>=21.0
+Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0.0 ; extra == 'dev'
+Requires-Dist: pytest-sugar>=1.0.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
+Requires-Dist: mini-racer>=0.12.4 ; extra == 'dev'
+Requires-Python: >=3.9
+Project-URL: Changelog, https://github.com/carlosperate/python-microbit-fs/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/carlosperate/python-microbit-fs
+Project-URL: Issues, https://github.com/carlosperate/python-microbit-fs/issues
+Project-URL: Repository, https://github.com/carlosperate/python-microbit-fs.git
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# micropython-microbit-fs
+
+[![Test](https://github.com/carlosperate/python-microbit-fs/actions/workflows/test.yml/badge.svg)](https://github.com/carlosperate/python-microbit-fs/actions/workflows/test.yml)
+[![PyPI versions](https://img.shields.io/pypi/pyversions/micropython-microbit-fs.svg)](https://pypi.org/project/micropython-microbit-fs/)
+[![PyPI - License](https://img.shields.io/pypi/l/micropython-microbit-fs.svg)](LICENSE)
+
+A Python library and command line tool to inject and extract files from
+[MicroPython](https://microbit-micropython.readthedocs.io)
+Intel Hex file for the [BBC micro:bit](https://microbit.org).
+
+## Features
+
+- **Inject files** into a MicroPython hex file for flashing to micro:bit.
+- **Extract files** from an existing micro:bit MicroPython hex file.
+- **Get device info** from hex, including filesystem size and MicroPython version.
+- **Command-line interface** for easy scripting and automation.
+- Includes the latest MicroPython releases for micro:bit V1 and V2 boards.
+
+## Installation
+
+To install this terminal tool we recommend using [uv](https://docs.astral.sh/uv/):
+
+```
+uv tool install micropython-microbit-fs
+```
+
+It can also be installed via pip as a normal Python package:
+
+```bash
+pip install micropython-microbit-fs
+```
+
+## Command Line Interface
+
+The package includes a `microbit-fs` command for working with hex files from
+the terminal.
+
+### Usage
+
+Display device information:
+
+```bash
+$ microbit-fs info micropython.hex
+
+Device: micro:bit V2
+MicroPython version: micro:bit v2.1.2+0697c6d on 2023-10-30; MicroPython v1.18 on 2023-10-30
+Flash page size: 4096 bytes
+Filesystem size: 20480 bytes
+Filesystem start: 0x0006D000
+Filesystem end: 0x00073000
+```
+
+List files in a hex file:
+
+```bash
+$ microbit-fs list micropython_with_files.hex
+
+File                                             Size
+──────────────────────────────────────── ────────────
+main.py                                     183 bytes
+──────────────────────────────────────── ────────────
+Total (1 files)                             183 bytes
+```
+
+Add files to a hex file:
+
+```bash
+# Add a single file using an existing MicroPython hex
+microbit-fs add main.py --hex-file micropython.hex
+
+# Add multiple files with a custom output file
+microbit-fs add main.py helper.py --hex-file micropython.hex --output output.hex
+
+# Use bundled micro:bit V1 MicroPython hex (latest version)
+microbit-fs add main.py --v1=latest
+
+# Use bundled micro:bit V2 MicroPython hex (latest version)
+microbit-fs add main.py --v2=latest --output my_program.hex
+
+# Use a specific MicroPython version
+microbit-fs add main.py --v1=1.1.1 --output output.hex
+microbit-fs add main.py --v2=2.1.2 --output output.hex
+```
+
+List available bundled MicroPython versions:
+
+```bash
+$ microbit-fs versions
+Bundled MicroPython hex files:
+
+micro:bit V1:
+  - 1.1.1
+
+micro:bit V2:
+  - 2.1.2
+```
+
+Extract files from a hex file:
+
+```bash
+# Extract all files to the current directory
+microbit-fs get micropython_with_files.hex
+
+# Extract all files to a specific directory
+microbit-fs get micropython_with_files.hex --output-dir ./extracted
+
+# Extract a specific file
+microbit-fs get micropython_with_files.hex --filename main.py
+
+# Overwrite existing files without prompting
+microbit-fs get micropython_with_files.hex --force
+```
+
+
+## Library Quick Start
+
+### Add files to a MicroPython hex
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# Read your MicroPython hex file
+with open("micropython.hex") as f:
+    micropython_hex = f.read()
+
+# Create files to add
+files = [
+    microbit_fs.File.from_text("main.py", "from microbit import *\ndisplay.scroll('Hello!')"),
+    microbit_fs.File.from_text("helper.py", "def greet(name):\n    return f'Hello {name}'"),
+]
+
+# Add files and get new hex string
+new_hex = microbit_fs.add_files(micropython_hex, files)
+
+with open("micropython_with_files.hex", "w") as f:
+    f.write(new_hex)
+```
+
+### Get files from a MicroPython hex
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# Read hex file with embedded files
+with open("micropython_with_files.hex") as f:
+    hex_data = f.read()
+
+# Get all files
+files = microbit_fs.get_files(hex_data)
+
+for file in files:
+    print(f"{file.name}: {file.size} bytes")
+    print(file.get_text())
+```
+
+### Get device information
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+with open("micropython.hex") as f:
+    hex_data = f.read()
+
+info = microbit_fs.get_device_info(hex_data)
+print(f"Device: micro:bit {info.device_version.value}")
+print(f"MicroPython: {info.micropython_version}")
+print(f"Filesystem size: {info.fs_size} bytes")
+print(f"Flash page size: {info.flash_page_size} bytes")
+```
+
+### Use bundled MicroPython hex files
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# List available bundled versions (dict keyed by device)
+versions = microbit_fs.list_bundled_versions()
+# {1: ['1.1.1'], 2: ['2.1.2']}
+v1_versions = versions[1]
+v2_versions = versions[2]
+
+# Get the latest bundled hex for micro:bit V1
+hex_data = microbit_fs.get_bundled_hex(1)
+
+# Get a specific version
+hex_data = microbit_fs.get_bundled_hex(2, "2.1.2")
+
+# Add files to the bundled hex
+files = [microbit_fs.File.from_text("main.py", "from microbit import *")]
+new_hex = microbit_fs.add_files(hex_data, files)
+
+with open("my_program.hex", "w") as f:
+    f.write(new_hex)
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for project management.
+
+### Setup
+
+```bash
+git clone https://github.com/carlosperate/python-microbit-fs.git
+cd python-microbit-fs
+uv sync --all-extras --dev
+```
+
+### Development Commands
+
+This project includes a `make.py` script to automate common development tasks.
+
+```bash
+# Run all checks (lint, typecheck, format check, test with coverage)
+uv run python make.py check
+
+# Format code (ruff check --fix + ruff format)
+uv run python make.py format
+
+# Show all available commands
+uv run python make.py help
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- This project has been ported (AI assisted) from the original
+  [microbit-fs](https://github.com/microbit-foundation/microbit-fs)
+  TypeScript library.
+- This project packs the files inside a micro:bit MicroPython hex, which
+  can then be flashed to a micro:bit.
+  Alternatively, to read and write files from a running micro:bit device over
+  USB, the [microFs](https://github.com/ntoll/microfs) CLI tool can be used.

micropython_microbit_fs-0.1.0/README.md

@@ -0,0 +1,235 @@
+# micropython-microbit-fs
+
+[![Test](https://github.com/carlosperate/python-microbit-fs/actions/workflows/test.yml/badge.svg)](https://github.com/carlosperate/python-microbit-fs/actions/workflows/test.yml)
+[![PyPI versions](https://img.shields.io/pypi/pyversions/micropython-microbit-fs.svg)](https://pypi.org/project/micropython-microbit-fs/)
+[![PyPI - License](https://img.shields.io/pypi/l/micropython-microbit-fs.svg)](LICENSE)
+
+A Python library and command line tool to inject and extract files from
+[MicroPython](https://microbit-micropython.readthedocs.io)
+Intel Hex file for the [BBC micro:bit](https://microbit.org).
+
+## Features
+
+- **Inject files** into a MicroPython hex file for flashing to micro:bit.
+- **Extract files** from an existing micro:bit MicroPython hex file.
+- **Get device info** from hex, including filesystem size and MicroPython version.
+- **Command-line interface** for easy scripting and automation.
+- Includes the latest MicroPython releases for micro:bit V1 and V2 boards.
+
+## Installation
+
+To install this terminal tool we recommend using [uv](https://docs.astral.sh/uv/):
+
+```
+uv tool install micropython-microbit-fs
+```
+
+It can also be installed via pip as a normal Python package:
+
+```bash
+pip install micropython-microbit-fs
+```
+
+## Command Line Interface
+
+The package includes a `microbit-fs` command for working with hex files from
+the terminal.
+
+### Usage
+
+Display device information:
+
+```bash
+$ microbit-fs info micropython.hex
+
+Device: micro:bit V2
+MicroPython version: micro:bit v2.1.2+0697c6d on 2023-10-30; MicroPython v1.18 on 2023-10-30
+Flash page size: 4096 bytes
+Filesystem size: 20480 bytes
+Filesystem start: 0x0006D000
+Filesystem end: 0x00073000
+```
+
+List files in a hex file:
+
+```bash
+$ microbit-fs list micropython_with_files.hex
+
+File                                             Size
+──────────────────────────────────────── ────────────
+main.py                                     183 bytes
+──────────────────────────────────────── ────────────
+Total (1 files)                             183 bytes
+```
+
+Add files to a hex file:
+
+```bash
+# Add a single file using an existing MicroPython hex
+microbit-fs add main.py --hex-file micropython.hex
+
+# Add multiple files with a custom output file
+microbit-fs add main.py helper.py --hex-file micropython.hex --output output.hex
+
+# Use bundled micro:bit V1 MicroPython hex (latest version)
+microbit-fs add main.py --v1=latest
+
+# Use bundled micro:bit V2 MicroPython hex (latest version)
+microbit-fs add main.py --v2=latest --output my_program.hex
+
+# Use a specific MicroPython version
+microbit-fs add main.py --v1=1.1.1 --output output.hex
+microbit-fs add main.py --v2=2.1.2 --output output.hex
+```
+
+List available bundled MicroPython versions:
+
+```bash
+$ microbit-fs versions
+Bundled MicroPython hex files:
+
+micro:bit V1:
+  - 1.1.1
+
+micro:bit V2:
+  - 2.1.2
+```
+
+Extract files from a hex file:
+
+```bash
+# Extract all files to the current directory
+microbit-fs get micropython_with_files.hex
+
+# Extract all files to a specific directory
+microbit-fs get micropython_with_files.hex --output-dir ./extracted
+
+# Extract a specific file
+microbit-fs get micropython_with_files.hex --filename main.py
+
+# Overwrite existing files without prompting
+microbit-fs get micropython_with_files.hex --force
+```
+
+
+## Library Quick Start
+
+### Add files to a MicroPython hex
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# Read your MicroPython hex file
+with open("micropython.hex") as f:
+    micropython_hex = f.read()
+
+# Create files to add
+files = [
+    microbit_fs.File.from_text("main.py", "from microbit import *\ndisplay.scroll('Hello!')"),
+    microbit_fs.File.from_text("helper.py", "def greet(name):\n    return f'Hello {name}'"),
+]
+
+# Add files and get new hex string
+new_hex = microbit_fs.add_files(micropython_hex, files)
+
+with open("micropython_with_files.hex", "w") as f:
+    f.write(new_hex)
+```
+
+### Get files from a MicroPython hex
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# Read hex file with embedded files
+with open("micropython_with_files.hex") as f:
+    hex_data = f.read()
+
+# Get all files
+files = microbit_fs.get_files(hex_data)
+
+for file in files:
+    print(f"{file.name}: {file.size} bytes")
+    print(file.get_text())
+```
+
+### Get device information
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+with open("micropython.hex") as f:
+    hex_data = f.read()
+
+info = microbit_fs.get_device_info(hex_data)
+print(f"Device: micro:bit {info.device_version.value}")
+print(f"MicroPython: {info.micropython_version}")
+print(f"Filesystem size: {info.fs_size} bytes")
+print(f"Flash page size: {info.flash_page_size} bytes")
+```
+
+### Use bundled MicroPython hex files
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# List available bundled versions (dict keyed by device)
+versions = microbit_fs.list_bundled_versions()
+# {1: ['1.1.1'], 2: ['2.1.2']}
+v1_versions = versions[1]
+v2_versions = versions[2]
+
+# Get the latest bundled hex for micro:bit V1
+hex_data = microbit_fs.get_bundled_hex(1)
+
+# Get a specific version
+hex_data = microbit_fs.get_bundled_hex(2, "2.1.2")
+
+# Add files to the bundled hex
+files = [microbit_fs.File.from_text("main.py", "from microbit import *")]
+new_hex = microbit_fs.add_files(hex_data, files)
+
+with open("my_program.hex", "w") as f:
+    f.write(new_hex)
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for project management.
+
+### Setup
+
+```bash
+git clone https://github.com/carlosperate/python-microbit-fs.git
+cd python-microbit-fs
+uv sync --all-extras --dev
+```
+
+### Development Commands
+
+This project includes a `make.py` script to automate common development tasks.
+
+```bash
+# Run all checks (lint, typecheck, format check, test with coverage)
+uv run python make.py check
+
+# Format code (ruff check --fix + ruff format)
+uv run python make.py format
+
+# Show all available commands
+uv run python make.py help
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- This project has been ported (AI assisted) from the original
+  [microbit-fs](https://github.com/microbit-foundation/microbit-fs)
+  TypeScript library.
+- This project packs the files inside a micro:bit MicroPython hex, which
+  can then be flashed to a micro:bit.
+  Alternatively, to read and write files from a running micro:bit device over
+  USB, the [microFs](https://github.com/ntoll/microfs) CLI tool can be used.

micropython_microbit_fs-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "micropython-microbit-fs"
+version = "0.1.0"
+description = "Library and cli app to add and extract files from MicroPython Hex files for micro:bit"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Carlos Pereira Atencio", email = "carlosperate@embeddedlog.com" },]
+keywords = ["microbit", "micropython", "filesystem", "intel-hex", "embedded"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Embedded Systems",
+]
+
+dependencies = [
+    "cyclopts>=3.24.0",
+    "intelhex>=2.3.0",
+    "packaging>=21.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.8.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-xdist>=3.0.0",
+    "pytest-sugar>=1.0.0",
+    "mypy>=1.0.0",
+    "mini-racer>=0.12.4",
+]
+
+[project.scripts]
+microbit-fs = "micropython_microbit_fs.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/carlosperate/python-microbit-fs"
+Repository = "https://github.com/carlosperate/python-microbit-fs.git"
+Issues = "https://github.com/carlosperate/python-microbit-fs/issues"
+Changelog = "https://github.com/carlosperate/python-microbit-fs/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.20,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by ruff format)
+    "B008",   # do not perform function calls in argument defaults
+    "UP045",  # Use `X | None` - conflicts with py39 support using Optional
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["micropython_microbit_fs"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "--tb=short"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = false
+ignore_missing_imports = true
+
+[tool.coverage.run]
+source = ["src/micropython_microbit_fs"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]

micropython_microbit_fs-0.1.0/src/micropython_microbit_fs/__init__.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""
+micropython-microbit-fs: Inject and extract files from MicroPython Intel Hex files.
+
+This library provides a simple API for working with MicroPython filesystem
+embedded in Intel Hex files for the BBC micro:bit.
+
+Main functions:
+    - add_files: Add files to a MicroPython hex file
+    - get_files: Read files from a MicroPython hex file
+    - get_device_info: Get device memory information from a hex file
+    - get_bundled_hex: Get a bundled MicroPython hex file
+    - list_bundled_versions: List available bundled hex versions
+"""
+
+from micropython_microbit_fs.api import (
+    add_files,
+    get_device_info,
+    get_files,
+)
+from micropython_microbit_fs.device_info import DeviceInfo, DeviceVersion
+from micropython_microbit_fs.exceptions import (
+    FilesystemError,
+    HexNotFoundError,
+    InvalidFileError,
+    InvalidHexError,
+    NotMicroPythonError,
+    StorageFullError,
+)
+from micropython_microbit_fs.file import File
+from micropython_microbit_fs.hexes import (
+    MicroPythonHex,
+    get_bundled_hex,
+    list_bundled_versions,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main API functions
+    "add_files",
+    "get_files",
+    "get_device_info",
+    # Bundled hex functions
+    "MicroPythonHex",
+    "get_bundled_hex",
+    "list_bundled_versions",
+    # Data classes
+    "File",
+    "DeviceInfo",
+    "DeviceVersion",
+    # Exceptions
+    "FilesystemError",
+    "InvalidHexError",
+    "NotMicroPythonError",
+    "InvalidFileError",
+    "StorageFullError",
+    "HexNotFoundError",
+]