tools/mpremote: Add automatic .mpy compilation on mount.

Implement on-the-fly compilation of Python files to .mpy bytecode when
MicroPython imports them via mounted filesystem. This improves import
performance while maintaining backward compatibility.

Features:
- Auto-detect device architecture during mount
- Compile .py to .mpy on-demand when device requests it
- Intelligent caching with mtime-based invalidation (100MB limit)
- Resource limits: cache size management with LRU eviction, 1MB file limit
- Graceful fallbacks when mpy-cross unavailable or compilation fails
- Command-line options: --auto-mpy (default) / --no-auto-mpy
- Verbose logging support for debugging

Implementation:
- New module: mpremote/mpy_compiler.py (MpyCrossCompiler class)
- Modified: transport_serial.py (architecture detection, stat interception)
- Modified: main.py (CLI options, fixed _bool_flag for hyphenated flags)
- Modified: commands.py (pass auto_mpy parameter to mount)
- Modified: pyproject.toml (add mpy-cross optional dependency)
- Modified: README.md (user documentation)

Testing:
- 25 unit tests with 100% coverage (tests/test_mpy_compiler.py)
- Integration test script (tests/test_auto_mpy.sh)
- All tests passing

Requires mpy-cross Python package for compilation feature.
Install with: pip install mpremote[mpy]

Co-authored-by: Claude <[email protected]>
Signed-off-by: Andrew Leech <[email protected]>

Author: pi-anl

tools/mpremote/README.md

@@ -16,6 +16,10 @@ The full list of supported commands are:
                                          or any valid device name/path
     mpremote disconnect               -- disconnect current device
     mpremote mount <local-dir>        -- mount local directory on device
+                                         options:
+                                             --unsafe-links / -l: follow symlinks outside mount
+                                             --auto-mpy / -m: auto-compile .py to .mpy (default)
+                                             --no-auto-mpy: disable auto-compilation
     mpremote eval <string>            -- evaluate and print the string
     mpremote exec <string>            -- execute the string
     mpremote run <file>               -- run the given local script
@@ -82,3 +86,88 @@ Examples:
     mpremote mip install aioble
     mpremote mip install github:org/repo@branch
     mpremote mip install gitlab:org/repo@branch
+
+## Auto-MPY Compilation
+
+When a local directory is mounted using `mpremote mount`, the tool can automatically
+compile Python files to bytecode (.mpy) format on-demand. This feature:
+
+- **Improves import performance**: .mpy files are pre-compiled and load faster
+- **Transparent operation**: Automatically compiles when device requests .mpy
+- **Caching**: Compiled files are cached to avoid recompilation
+- **Graceful fallback**: Uses .py files if compilation fails
+
+### Installation
+
+Auto-compilation requires the `mpy-cross` Python package:
+
+    pip install mpremote[mpy]
+
+Or install `mpy-cross` separately:
+
+    pip install mpy-cross
+
+### Usage
+
+    mpremote mount /path/to/code              # Auto-compile enabled (default)
+    mpremote mount --no-auto-mpy /path/to/code  # Disable auto-compilation
+
+### How it Works
+
+1. When MicroPython tries to import a module, it checks for .py files first
+2. mpremote intercepts the .py stat request and compiles to .mpy if needed
+3. mpremote returns "file not found" for .py to force MicroPython to use .mpy
+4. The compiled .mpy is saved both locally and in a cache directory
+5. Subsequent imports use the cached .mpy file
+6. Cache is automatically managed (100MB limit, LRU eviction)
+
+### Important Limitations
+
+When auto-mpy is enabled with `mount`, `.py` files on mounted filesystems become invisible to the device for ALL operations, not just imports.
+
+This means:
+- ✗ **`open("script.py")`** will fail (file appears not to exist)
+- ✗ **`os.stat("script.py")`** will return ENOENT
+- ✓ **`import script`** works (uses compiled .mpy)
+
+**Workaround:** Disable auto-mpy if you need direct .py file access:
+
+```bash
+mpremote mount --no-auto-mpy /path/to/code
+```
+
+This limitation exists because mpremote cannot distinguish between import-related file access and regular file operations at the stat interception level.
+
+### Requirements
+
+- The `mpy-cross` Python package must be installed
+- Device must support .mpy files (MicroPython v1.12+)
+- Architecture is auto-detected from the connected device
+
+### Cache Structure
+
+Compiled `.mpy` files are stored in a cache directory:
+
+**Location:** `/tmp/mpremote_mpy_cache/`
+
+**Cache key format:** `_<path>_<mtime>_<arch>.mpy`
+- Example: `_tmp_mpy_test_script_py_1732456789_0_xtensawin.mpy`
+- `<path>`: Source .py file path (sanitized, slashes/dots → underscores)
+- `<mtime>`: Modification timestamp of .py file
+- `<arch>`: Target architecture (e.g., xtensawin, armv7m)
+
+**Cache behavior:**
+- Automatic LRU eviction when cache exceeds 100MB
+- Cached .mpy is reused if source .py file hasn't changed (mtime check)
+- Different architectures maintain separate cache entries
+- Compiled .mpy files are ALSO copied to the mounted directory alongside .py files
+- Example: `/path/to/code/module.py` → `/path/to/code/module.mpy` + cache entry
+
+### Troubleshooting
+
+If auto-compilation isn't working:
+- Check if `mpy-cross` is installed: `python -c "import mpy_cross"`
+- Use verbose mode to see compilation messages: `mpremote -v mount /path/to/code`
+- Manually disable if needed: `mpremote mount --no-auto-mpy /path/to/code`
+- Check cache directory: `ls -lh /tmp/mpremote_mpy_cache/`
+- Clear cache if needed: `rm -rf /tmp/mpremote_mpy_cache/`

tools/mpremote/mpremote/commands.py

@@ -5,7 +5,6 @@
 import sys
 import tempfile
 import zlib
-
 import serial.tools.list_ports
 
 from .transport import TransportError, TransportExecError, stdout_write_bytes
@@ -506,19 +505,18 @@ def do_eval(state, args):
 
 
 def do_run(state, args):
-    filename = args.path[0]
     try:
-        with open(filename, "rb") as f:
+        with open(args.path[0], "rb") as f:
             buf = f.read()
     except OSError:
-        raise CommandError(f"could not read file '{filename}'")
+        raise CommandError(f"could not read file '{args.path[0]}'")
     _do_execbuffer(state, buf, args.follow)
 
 
 def do_mount(state, args):
     state.ensure_raw_repl()
     path = args.path[0]
-    state.transport.mount_local(path, unsafe_links=args.unsafe_links)
+    state.transport.mount_local(path, unsafe_links=args.unsafe_links, auto_mpy=args.auto_mpy)
     print(f"Local directory {path} is mounted at /remote")
 
 

tools/mpremote/mpremote/main.py

@@ -83,18 +83,20 @@ def do_version(state, _args=None):
 
 def _bool_flag(cmd_parser, name, short_name, default, description):
     # In Python 3.9+ this can be replaced with argparse.BooleanOptionalAction.
+    dest = name.replace("-", "_")
     group = cmd_parser.add_mutually_exclusive_group()
     group.add_argument(
         "--" + name,
         "-" + short_name,
         action="store_true",
         default=default,
+        dest=dest,
         help=description,
     )
     group.add_argument(
         "--no-" + name,
         action="store_false",
-        dest=name,
+        dest=dest,
     )
 
 
@@ -127,6 +129,13 @@ def argparse_mount():
         False,
         "follow symbolic links pointing outside of local directory",
     )
+    _bool_flag(
+        cmd_parser,
+        "auto-mpy",
+        "m",
+        True,
+        "automatically compile .py to .mpy on import (default)",
+    )
     cmd_parser.add_argument("path", nargs=1, help="local path to mount")
     return cmd_parser