mpflash 1.26.0__tar.gz → 1.26.4__tar.gz

mpflash-1.26.4/.all-contributorsrc

@@ -0,0 +1,177 @@
+{
+    "files": [
+        "readme.md"
+    ],
+    "imageSize": 100,
+    "commit": false,
+    "types": {
+        "stubs": {
+            "symbol": "🖍️",
+            "description": "MicroPython stubs"
+        },
+        "mpflash": {
+            "symbol": "💥",
+            "description": "mpflash"
+        },
+        "test": {
+            "symbol": "✅",
+            "description": "Test"
+        }
+    },
+    "contributors": [
+        {
+            "login": "josverl",
+            "name": "Jos Verlinde",
+            "avatar_url": "https://avatars2.githubusercontent.com/u/981654?v=4",
+            "profile": "https://github.com/Josverl",
+            "contributions": [
+                "code",
+                "research",
+                "ideas",
+                "content",
+                "test",
+                "mpflash"
+            ]
+        },
+        {
+            "login": "shariltumin",
+            "name": "shariltumin",
+            "avatar_url": "https://avatars.githubusercontent.com/u/186120?v=4",
+            "profile": "https://github.com/shariltumin",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "mattytrentini",
+            "name": "Matt Trentini",
+            "avatar_url": "https://avatars.githubusercontent.com/u/194201?v=4",
+            "profile": "https://github.com/mattytrentini",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "scruss",
+            "name": "Stewart Russell",
+            "avatar_url": "https://avatars.githubusercontent.com/u/425706?v=4",
+            "profile": "http://scruss.com/blog/",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "andrewleech",
+            "name": "Andrew Leech",
+            "avatar_url": "https://avatars.githubusercontent.com/u/3318786?v=4",
+            "profile": "https://www.gitlab.com/alelec",
+            "contributions": [
+                "mpflash",
+                "test",
+                "tooling"
+            ]
+        },
+        {
+            "login": "wovo",
+            "name": "Wouter van Ooijen",
+            "avatar_url": "https://avatars.githubusercontent.com/u/9039468?v=4",
+            "profile": "https://github.com/wovo",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "shaneapowell",
+            "name": "Shane Powell",
+            "avatar_url": "https://avatars.githubusercontent.com/u/12113620?v=4",
+            "profile": "https://github.com/shaneapowell",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "robert-hh",
+            "name": "Robert Hammelrath",
+            "avatar_url": "https://avatars.githubusercontent.com/u/12476868?v=4",
+            "profile": "https://github.com/robert-hh",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "beetlegigg",
+            "name": "Bg",
+            "avatar_url": "https://avatars.githubusercontent.com/u/34552737?v=4",
+            "profile": "https://github.com/beetlegigg",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "rkompass",
+            "name": "Raul Kompaß",
+            "avatar_url": "https://avatars.githubusercontent.com/u/90282516?v=4",
+            "profile": "https://github.com/rkompass",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "garryp4",
+            "name": "garryp4",
+            "avatar_url": "https://avatars.githubusercontent.com/u/96994876?v=4",
+            "profile": "https://github.com/garryp4",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "shanepowell-ast",
+            "name": "Shane Powell",
+            "avatar_url": "https://avatars.githubusercontent.com/u/102747617?v=4",
+            "profile": "https://github.com/shanepowell-ast",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "andypiper",
+            "name": "Andy Piper",
+            "avatar_url": "https://avatars.githubusercontent.com/u/552452?v=4",
+            "profile": "https://andypiper.org/",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        },
+        {
+            "login": "DavesCodeMusings",
+            "name": "David Horton",
+            "avatar_url": "https://avatars.githubusercontent.com/u/61114342?v=4",
+            "profile": "https://github.com/DavesCodeMusings",
+            "contributions": [
+                "mpflash",
+                "test"
+            ]
+        }
+    ],
+    "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg?style=flat-square)](#11---contributions)",
+    "projectName": "mpflash",
+    "projectOwner": "Josverl",
+    "repoType": "github",
+    "repoHost": "https://github.com",
+    "skipCi": true,
+    "commitConvention": "none",
+    "contributorsPerLine": 7,
+    "commitType": "docs"
+}

mpflash-1.26.4/.env

@@ -0,0 +1,21 @@
+# Python .env file ..
+
+# PYTHONPYCACHEPREFIX=__my_pycache
+
+JUPYTER_PLATFORM_DIRS=1
+PYDEVD_DISABLE_FILE_VALIDATION=1
+# Allow tests to find sources
+PYTHONPATH = src
+
+# give 20 secs to complete : subprocess.getstatusoutput
+PYDEVD_WARN_EVALUATION_TIMEOUT = 20
+
+# stop nagging for updates
+PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# stop neggin during debug
+JUPYTER_PLATFORM_DIRS=1
+PYDEVD_DISABLE_FILE_VALIDATION=1
+
+
+MPFLASH_FIRMWARE=./scratch

mpflash-1.26.4/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# These owners will be the default owners for everything in the repo.
+*   @Josverl

mpflash-1.26.4/.github/codecov.yml

@@ -0,0 +1,13 @@
+# https://docs.codecov.com/docs/codecov-yaml
+coverage:
+  status:
+    patch:
+      default:
+        target: 80%
+
+# codecov:
+#   branch: main
+
+ignore:
+  - "test_.*.py"       # no cov on tests
+  - ".*_test.py"       # no cov on tests

mpflash-1.26.4/.github/copilot-instructions.md

@@ -0,0 +1,217 @@
+# GitHub Copilot Instructions for MPFlash
+
+This document provides guidance for GitHub Copilot to maintain consistency with MPFlash's architecture and coding standards.
+
+## Project Overview
+
+MPFlash is a command-line tool and Python library for managing MicroPython firmware across multiple hardware platforms. The project follows a layered architecture with clear separation of concerns.
+
+## AI Assistant rukes 
+ - When running in shell , always make sure the activate the virtual environment after starting the shell 
+ - when possible use MCP servers 
+
+## Code Style and Standards
+
+### Python Conventions
+- Use Python type annotations throughout the code
+- Follow snake_case for functions and variables
+- Follow CamelCase for class names
+- Use 4 spaces for indentation
+- Use double quotes for strings
+- Prefer f-strings for string formatting
+- Maximum line length: 88 characters (Black formatter standard)
+- Add comments, but not too much
+- Add docstrings to modules and methods (5-9 lines maximum)
+- Use double quotes for strings
+
+# Speed and performance
+
+- this is a CLI tool and loading speed is important
+- Use lazy loading for modules and packages where possible
+- Use generators for large data sets
+
+# dependencies
+
+- Use uv for package management
+- The project uses PEP standard pyproject.toml format and all dependencies should be added to the dependencies or optional-dependencies sections
+- Minimize the number of dependencies
+
+# Writing tests
+- when asked to create an MVP - keep the number of tests to a minimum
+- Use pytest for testing
+- Use pytest fixtures for setup and teardown
+- Use assert statements for testing
+- all tests shouod be located in or under the `tests` directory
+- Use descriptive names for test functions
+- Use pytest.mark.parametrize for parameterized tests
+- Use pytest.raises for testing exceptions
+- for database related tests testsL
+    - make use of the test database int tests/data
+    - add fixtures for database setup and teardown
+### Documentation
+- Do not include type hints in docstrings
+- Keep comments minimal but descriptive
+
+### Example Function Style
+```python
+def flash_firmware(
+    port: str,
+    firmware_path: Path,
+    timeout: float = 30.0
+) -> bool:
+    """Flash MicroPython firmware to a connected board.
+
+    Args:
+        port: Serial port identifier (e.g., 'COM3' or '/dev/ttyUSB0')
+        firmware_path: Path to the firmware file
+        timeout: Maximum time to wait for flashing (seconds)
+
+    Returns:
+        True if flashing succeeded, False otherwise
+
+    Raises:
+        FlashError: If flashing operation fails
+    """
+    # Implementation
+```
+
+## Project Structure Patterns
+
+### CLI Commands
+- Place in `mpflash/cli_*.py`
+- Use Click decorators
+- Include help text and type annotations
+- Handle errors gracefully
+
+### Core Components
+- Follow interface-based design
+- Use abstract base classes for common patterns
+- Implement strategy pattern for varying behaviors
+
+### Database Operations
+- Use SQLAlchemy ORM
+- Follow repository pattern
+- Include proper error handling
+- Use migrations for schema changes
+
+## Common Patterns
+
+### Hardware Abstraction
+```python
+class FlashBase(ABC):
+    """Base class for flash implementations."""
+    
+    @abstractmethod
+    def flash_firmware(self) -> bool:
+        """Flash firmware to device."""
+        pass
+```
+
+### Error Handling
+```python
+class MPFlashError(Exception):
+    """Base exception for MPFlash operations."""
+    pass
+
+def safe_operation(func: Callable) -> Callable:
+    """Decorator for safe operations with proper error handling."""
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except MPFlashError as e:
+            log.error(f"Operation failed: {e}")
+            return None
+    return wrapper
+```
+
+### Configuration Management
+```python
+@dataclass
+class Config:
+    """Configuration dataclass with type hints."""
+    firmware_dir: Path
+    log_level: str = "INFO"
+    timeout: float = 30.0
+```
+
+## Testing Conventions
+
+### Test Structure
+- Place tests in `tests/` directory
+- Match test file names with implementation files
+- Use pytest fixtures for setup
+- Include unit, integration, and end-to-end tests
+
+### Example Test Pattern
+```python
+def test_flash_firmware(mock_board, temp_firmware):
+    """Test firmware flashing with mocked board."""
+    result = flash_firmware(
+        port=mock_board.port,
+        firmware_path=temp_firmware
+    )
+    assert result is True
+```
+
+## Performance Considerations
+
+### Lazy Loading
+```python
+class LazyLoader:
+    """Lazy loading pattern for expensive imports."""
+    def __init__(self):
+        self._module = None
+
+    @property
+    def module(self):
+        if self._module is None:
+            import expensive_module
+            self._module = expensive_module
+        return self._module
+```
+
+### Caching
+```python
+@lru_cache(maxsize=100)
+def get_board_info(board_id: str) -> dict:
+    """Cached board information retrieval."""
+    # Implementation
+```
+
+## Security Patterns
+
+### Input Validation
+```python
+def validate_input(value: str, pattern: str) -> bool:
+    """Validate input against security pattern."""
+    import re
+    return bool(re.match(pattern, value))
+```
+
+### Safe File Operations
+```python
+def safe_file_operation(path: Path) -> None:
+    """Safe file operation pattern."""
+    if not path.suffix in {'.bin', '.uf2', '.hex'}:
+        raise SecurityError("Invalid file type")
+    # Implementation
+```
+
+## Database Update Process
+
+When working with the board database:
+- Use `gather_boards.py` for updating board definitions
+- Package updates in `micropython_boards.zip`
+- Follow the repository pattern for database operations
+- Maintain proper versioning and migrations
+
+## Bootloader Operations
+
+When implementing bootloader-related code:
+- Use the BootloaderManager class
+- Implement proper error handling
+- Follow the strategy pattern for different bootloader types
+- Include timeout mechanisms
+
+Remember to maintain consistency with these patterns when suggesting code completions and implementations.

mpflash-1.26.4/.github/dependabot.yml

@@ -0,0 +1,20 @@
+# Basic set up for poetry and GHA dependencies
+version: 2
+updates:
+  # Maintain dependencies for mpflash
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    assignees:
+      - "josverl"
+
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    # Workflow files stored in the
+    # default location of `.github/workflows`
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    assignees:
+      - "josverl"

mpflash-1.26.4/.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,32 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
+      contents: read
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "latest"
+

mpflash-1.26.4/.github/workflows/dependency-review.yml

@@ -0,0 +1,20 @@
+# Dependency Review Action
+#
+# This Action will scan dependency manifest files that change as part of a Pull Request, surfacing known-vulnerable versions of the packages declared or updated in the PR. Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging.
+#
+# Source repository: https://github.com/actions/dependency-review-action
+# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
+name: "Dependency Review"
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v5
+      - name: "Dependency Review"
+        uses: actions/dependency-review-action@v4

mpflash-1.26.4/.github/workflows/pytest_mpflash.yml

@@ -0,0 +1,91 @@
+# This workflow will :
+# - test mpflash
+# - upload coverage stats to Codecov
+# - upload artifacts from the results folder
+
+name: pytest_mpflash
+on:
+    workflow_dispatch:
+    pull_request:
+        # branches: [main]
+
+    push:
+        branches: [main, dev/*, mpflash/*, feat/*, fix/*]
+        paths:
+            - .github/workflows/pytest_mpflash.yml
+            - .github/workflows/codecov.yml
+            - "mpflash/**"
+            - "pyproject.toml"
+            - "poetry.lock"
+            - "tests"
+
+env:
+    PYTHONIOENCODING: utf-8
+    # fix:  DeprecationWarning: Jupyter is migrating its paths to use standard platformdirs
+    JUPYTER_PLATFORM_DIRS: "1"
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    test_mpflash:
+        name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+        runs-on: ${{ matrix.os }}
+
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-latest, windows-latest, macos-latest]
+                python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+                # include: # for testing
+                #     - os: ubuntu-latest
+                #       python-version: "3.11"
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v5
+              with: 
+                fetch-tags: true
+
+            #----------------------------------------------
+            # uv is not in the default image
+            #----------------------------------------------
+            - name: Install the latest version of uv
+              uses: astral-sh/setup-uv@v6
+              with:
+                version: "latest"
+
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v6
+              with:
+                  python-version: ${{ matrix.python-version }}
+                  #   cache: "poetry"
+
+            #----------------------------------------------
+            # install project
+            #----------------------------------------------
+            - name: Install mpflash & test dependencies
+              run: uv sync --extra test
+
+            - name: Test mpflash
+              run: |
+                  # run once to bootstrap database (test hack)
+                  uv run mpflash download --board RPI_PICO
+                  uv run pytest --cov --cov-branch --cov-report=xml
+
+            #----------------------------------------------
+            # upload coverage stats
+            # .XML  to Codecov
+            #----------------------------------------------
+
+            - name: Upload coverage-mpflash-*.xml to Codecov
+              if: always() # ignore errors
+              continue-on-error: true
+              uses: codecov/codecov-action@v5
+              with:
+                  token: ${{ secrets.CODECOV_TOKEN }}
+                  # fail_ci_if_error: false
+                  # file: results/coverage-mpflash-${{ matrix.python-version }}-${{ matrix.os }}.xml
+                  # flags: mpflash
+
+

mpflash-1.26.4/.gitignore

@@ -0,0 +1,50 @@
+# no python virtual environment
+.venv*
+
+# no compiled python or caches
+**/__pycache__
+**/.*_cache
+__*/**/*
+my_pycache/*
+profile.*
+
+
+#ignore the scratchpad 
+scratch/*
+
+
+# tempfolder used by get_core  
+build
+
+# ignore test coverage reports
+.coverage*
+**/coverage/*
+**/coverage*.xml
+
+# no  test results 
+junit/*
+results/
+
+# OS specific stuff
+desktop.ini
+
+
+# Do not check in the autodoc generated API documentaion files 
+docs/_build
+docs/api
+docs/~$*
+
+# no node_modules ( pyright ) 
+node_modules
+
+# no poetry packaging 
+dist/
+
+src/mpflash/coverag*
+
+# no hypothesis patches
+**/.hypothesis
+
+profile.*
+
+

mpflash-1.26.4/.mailmap

@@ -0,0 +1,9 @@
+# merge different spelling / email addressess into one and the same 
+Jos Verlinde <Josverl@users.noreply.github.com> Josverl <Josverl@users.noreply.github.com>
+<Josverl@users.noreply.github.com> <jos_verlinde@hotmail.com> 
+<Josverl@users.noreply.github.com> <jos.verlinde@hotmail.com> 
+<Josverl@users.noreply.github.com> <Jos_Verlinde@hotmail.com> 
+<Josverl@users.noreply.github.com> <Jos.Verlinde@Microsoft.com> 
+<Josverl@users.noreply.github.com> <josverl@microsoft.com>
+
+Braden Mars <BradenM@users.noreply.github.com> <bradenmars@bradenmars.me>

mpflash-1.26.4/.readthedocs.yaml

@@ -0,0 +1,31 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      # Install poetry
+      # https://python-poetry.org/docs/#installing-manually
+      - pip install poetry
+      # Tell poetry to not use a virtual environment
+      - poetry config virtualenvs.create false
+      # Install dependencies with 'docs' dependency group
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      - poetry install --with docs
+
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+  # fail_on_warning: true
+  
+formats:
+  - pdf