mpytool 2.2.4__tar.gz → 2.3.0__tar.gz

{mpytool-2.2.4 → mpytool-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.2.4
+Version: 2.3.0
 Summary: MPY tool - manage files on devices running MicroPython
 Author-email: Pavel Revak <pavel.revak@gmail.com>
 License-Expression: MIT
@@ -20,17 +20,31 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
 
 ## Features
 
-- **Fast file transfers** - optimized chunked transfer with automatic compression
-- **Skip unchanged files** - compares size + SHA256 hash, re-upload in <1s
-- **Auto-detect serial port** - no need to specify `-p` when only one device connected
-- **Robust REPL handling** - works reliably with USB-UART bridges (CP2102, CH340)
-- **Multiple reset options** - soft, MCU, hardware (RTS), bootloader entry
-- **General-purpose serial terminal** - `repl` and `monitor` work with any serial device
+- **Fast file transfers** - optimized chunked transfer with
+  automatic compression
+- **Skip unchanged files** - compares size + SHA256 hash,
+  re-upload in <1s
+- **Auto-detect serial port** - no need to specify `-p` when only
+  one device connected
+- **Robust REPL handling** - works reliably with USB-UART bridges
+  (CP2102, CH340)
+- **Multiple reset options** - soft, MCU, hardware (RTS),
+  bootloader entry
+- **General-purpose serial terminal** - `repl` and `monitor` work
+  with any serial device
+- **Mount local directory** - VFS mount (read-only or read-write)
+  for development without uploading to flash, with transparent
+  `.mpy` compilation and auto-remount after soft reset
+- **Virtual submounts** - `ln` links files/directories into
+  mounted VFS (PC-side only, no device changes)
 - **Python API** - suitable for IDE integration and automation
-- **Raw-paste mode** - flow-controlled code execution with reduced RAM usage (API)
+- **Raw-paste mode** - flow-controlled code execution with reduced
+  RAM usage (API)
 - **Shell completion** - ZSH and Bash with remote path completion
 - **Network support** - connect over TCP
 
+See [README_mpremote.md](README_mpremote.md) for detailed comparison with mpremote.
+
 ## Installation
 
 ```
@@ -163,8 +177,24 @@ $ mpytool cd :..                  # change to parent directory
 $ mpytool cd :/lib -- ls          # change directory and list files
 ```
 
-### Reset and REPL
+### Module search path (sys.path)
+```
+$ mpytool path                    # show current sys.path
+'', '/lib'
+$ mpytool path : :/lib            # replace entire sys.path
+$ mpytool path -f :/custom        # prepend to sys.path (remove duplicates)
+$ mpytool path -a :/sdcard/lib    # append to sys.path (remove duplicates)
+$ mpytool path -d :/custom        # delete from sys.path
+$ mpytool path -f : :/lib :/extra # prepend multiple paths
+$ mpytool cd :/app -- path -f :   # combine with cd to set working dir
+```
+
+Path semantics: `:` = empty string (CWD) in sys.path, `:/` = root directory. The `-f` and `-a` flags automatically remove duplicates (move existing paths to new position).
+
+### Stop, reset and REPL
 ```
+$ mpytool stop               # stop running program (Ctrl-C)
+$ mpytool stop -- repl       # stop and enter REPL
 $ mpytool reset              # soft reset (Ctrl-D, runs boot.py/main.py)
 $ mpytool reset --raw        # soft reset in raw REPL (clears RAM only)
 $ mpytool reset --machine    # MCU reset (machine.reset, auto-reconnect)
@@ -180,11 +210,18 @@ $ mpytool sleep 2            # sleep for 2 seconds (useful between commands)
 ### Serial terminal and monitor (general purpose)
 ```
 $ mpytool repl                       # auto-detect port, 115200 baud
+REPL (Ctrl+] to exit)
+
+$ mpytool -v repl                    # verbose: shows CWD and sys.path before REPL
+REPL (Ctrl+] to exit)  CWD: /  PATH: : :.frozen :/lib
+
 $ mpytool -p /dev/ttyUSB0 repl       # specify port
 $ mpytool -b 9600 repl               # specify baudrate
 $ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor at 9600 baud
 ```
 
+The `repl` command with `-v` flag displays current working directory (CWD) and `sys.path` before entering REPL, making it easy to see the device state after `mount`, `cd`, or `path` commands.
+
 Both `repl` and `monitor` can be used as general-purpose serial tools - not just for MicroPython devices. Use them to interact with any serial device (Arduino, ESP with custom firmware, GPS modules, etc.). When only one serial port is detected, it is used automatically. Default baudrate is 115200.
 
 ### Execute Python code on device
@@ -199,6 +236,121 @@ $ mpytool run script.py                  # run script (fire-and-forget)
 $ mpytool run script.py -- monitor       # run script and capture output
 ```
 
+### Edit file on device
+```
+$ mpytool edit :boot.py              # edit file (uses $VISUAL or $EDITOR)
+$ mpytool edit :/lib/config.py       # absolute path
+$ mpytool edit --editor vim :main.py # explicit editor
+$ mpytool edit :newfile.py           # create new file if doesn't exist
+```
+
+Downloads file to a temp file, opens in editor, uploads back if changed.
+Editor priority: `--editor` > `$VISUAL` > `$EDITOR` > error.
+
+### Device RTC (real-time clock)
+```
+$ mpytool rtc                        # display current RTC
+2026-02-21 15:30:45
+
+$ mpytool rtc --set                  # set RTC to local PC time
+RTC set to 2026-02-21 15:30:45 (local)
+
+$ mpytool rtc --utc                  # set RTC to UTC time
+RTC set to 2026-02-21 14:30:45 (UTC)
+
+$ mpytool rtc "2026-02-21 14:30:00"  # set RTC to specific datetime
+RTC set to 2026-02-21 14:30:00
+```
+
+Flags: `-s`/`--set` and `-l`/`--local` both set local time, `-u`/`--utc` sets UTC.
+Manual datetime format: `YYYY-MM-DD HH:MM:SS`.
+
+### Mount local directory on device
+```
+$ mpytool mount ./src                       # mount ./src as /remote, auto-start REPL
+Mounted ./src on /remote (readonly)
+Changed CWD to /remote
+REPL (Ctrl+] to exit)
+
+$ mpytool -v mount ./src :/app              # mount as /app instead of /remote (verbose)
+Mounted ./src on /app (readonly)
+Changed CWD to /app
+REPL (Ctrl+] to exit)  CWD: /app  PATH: : :.frozen :/lib
+
+$ mpytool mount -m ./src :/app              # mount with automatic .mpy compilation
+Mounted ./src on /app (readonly, .mpy compilation)
+Changed CWD to /app
+>>> import foo                              # imports /app/foo.mpy (compiled from ./src/foo.py)
+
+$ mpytool mount -w ./workspace :/work       # mount as read-write (can create/modify/delete files)
+Mounted ./workspace on /work (read-write)
+Changed CWD to /work
+>>> f = open('/work/test.txt', 'w'); f.write('hello'); f.close()  # creates local file
+>>> import os; os.mkdir('/work/newdir')     # creates local directory
+
+$ mpytool mount ./src -- exec "import main" # mount and run code
+$ mpytool mount ./src -- monitor            # mount and monitor output
+$ mpytool mount ./app :/app -- mount ./lib :/lib -- repl  # multiple mounts (CWD = /app)
+Mounted ./app on /app (readonly)
+Changed CWD to /app
+Mounted ./lib on /lib (readonly)
+```
+
+Mounts a local directory on the device as a VFS. The device can read,
+import and execute files from the local directory without uploading
+them to flash. Changes to local files are immediately visible on
+the device.
+
+**Memory overhead:** The VFS agent uses ~4.2KB of RAM on the device
+(154 lines of MicroPython code injected during mount).
+
+**By default, mounts are read-only.** Use `-w` / `--writable` flag
+to enable write support — the device can create, modify and delete
+files in the mounted directory. All changes are written directly to
+the local filesystem.
+
+**`-m` / `--mpy` flag:** Enables transparent `.mpy` compilation.
+When the device imports a module, the `.py` file is automatically
+compiled to `.mpy` bytecode on-demand and served from cache
+(`__pycache__/`). Benefits: faster imports, less RAM usage, support
+for `@native`/`@viper` code with `-march`. Boot files (`boot.py`,
+`main.py`) and empty files remain as `.py`. If compilation fails,
+automatically falls back to `.py`. Prebuilt `.mpy` files have
+priority over cache.
+
+The first mount automatically changes CWD to the mount point (mpremote
+compatibility). Subsequent mounts do not change CWD. Use `cd` command
+to change working directory manually if needed. Multiple independent
+(non-nested) mounts are supported.
+
+After mount, mpytool automatically enters REPL (unless `monitor` or
+`repl` follows). In REPL you can import modules from the mounted
+directory, Ctrl+D triggers soft reset with automatic re-mount and CWD
+restoration to the mount point.
+
+**Best for:** Development, testing, prototyping, debugging. For bulk
+file transfers (uploading/downloading many files), use `cp` command
+instead — it's optimized for throughput.
+
+**Security:** Paths are validated to prevent traversal outside mount
+root. Symlinks are followed and checked. Write operations require
+explicit `-w` flag.
+
+See [Mount VFS Comparison](README_mpremote.md#mount-vfs-comparison) for detailed comparison with mpremote.
+
+### Link files into mounted VFS
+```
+$ mpytool mount ./app :/ -- ln ./drivers :/lib/ -- repl       # mount app, link drivers into /lib/
+$ mpytool mount ./app :/ -- ln ./extra.py :/lib/ -- repl      # link single file into /lib/
+$ mpytool mount ./app :/ -- ln ./pkg :/lib/pkg -- repl        # link as specific name
+$ mpytool mount ./app :/ -- ln ./pkg/ :/lib/ -- repl          # link package contents into /lib/
+$ mpytool mount ./app :/ -- ln ./a.py ./b.py :/lib/ -- repl   # link multiple sources
+```
+
+Links local files or directories into an already mounted VFS as virtual submounts. Works entirely on the PC side — no changes needed on the device. Useful for composing a virtual filesystem from multiple local directories without copying.
+
+Path semantics follow the same trailing `/` rules as `cp`: `ln dir :/lib/` creates `:/lib/dir/...`, `ln dir/ :/lib/` copies contents into `:/lib/...`. Destination must be an absolute device path with `:` prefix.
+
 ### Serial link speed test
 ```
 $ mpytool speedtest
@@ -258,9 +410,9 @@ $ mpytool flash erase vfs --full           # full erase partition
 
 ### OTA firmware update (ESP32)
 ```
-$ mpytool ota firmware.app-bin                    # flash to next OTA partition
-$ mpytool ota firmware.app-bin -- reset --machine          # flash and reboot
-$ mpytool ota firmware.app-bin -- reset --machine -t 30    # flash and reboot with 30s timeout
+$ mpytool flash ota firmware.app-bin                    # flash to next OTA partition
+$ mpytool flash ota firmware.app-bin -- reset --machine          # flash and reboot
+$ mpytool flash ota firmware.app-bin -- reset --machine -t 30    # flash and reboot with 30s timeout
 ```
 
 ### Multiple commands separated by `--`
@@ -388,7 +540,7 @@ For reporting bugs, please include `-ddd` output in the issue.
 
 ## Performance
 
-`mpytool` uses optimized chunked transfer with automatic compression, which allows copying files very quickly. See [README_BENCH.md](README_BENCH.md) for detailed benchmarks.
+`mpytool` uses optimized chunked transfer with automatic compression, which allows copying files very quickly. See [README_bench.md](README_bench.md) for detailed benchmarks.
 
 ### Summary
 

{mpytool-2.2.4 → mpytool-2.3.0}/README.md

@@ -6,17 +6,31 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
 
 ## Features
 
-- **Fast file transfers** - optimized chunked transfer with automatic compression
-- **Skip unchanged files** - compares size + SHA256 hash, re-upload in <1s
-- **Auto-detect serial port** - no need to specify `-p` when only one device connected
-- **Robust REPL handling** - works reliably with USB-UART bridges (CP2102, CH340)
-- **Multiple reset options** - soft, MCU, hardware (RTS), bootloader entry
-- **General-purpose serial terminal** - `repl` and `monitor` work with any serial device
+- **Fast file transfers** - optimized chunked transfer with
+  automatic compression
+- **Skip unchanged files** - compares size + SHA256 hash,
+  re-upload in <1s
+- **Auto-detect serial port** - no need to specify `-p` when only
+  one device connected
+- **Robust REPL handling** - works reliably with USB-UART bridges
+  (CP2102, CH340)
+- **Multiple reset options** - soft, MCU, hardware (RTS),
+  bootloader entry
+- **General-purpose serial terminal** - `repl` and `monitor` work
+  with any serial device
+- **Mount local directory** - VFS mount (read-only or read-write)
+  for development without uploading to flash, with transparent
+  `.mpy` compilation and auto-remount after soft reset
+- **Virtual submounts** - `ln` links files/directories into
+  mounted VFS (PC-side only, no device changes)
 - **Python API** - suitable for IDE integration and automation
-- **Raw-paste mode** - flow-controlled code execution with reduced RAM usage (API)
+- **Raw-paste mode** - flow-controlled code execution with reduced
+  RAM usage (API)
 - **Shell completion** - ZSH and Bash with remote path completion
 - **Network support** - connect over TCP
 
+See [README_mpremote.md](README_mpremote.md) for detailed comparison with mpremote.
+
 ## Installation
 
 ```
@@ -149,8 +163,24 @@ $ mpytool cd :..                  # change to parent directory
 $ mpytool cd :/lib -- ls          # change directory and list files
 ```
 
-### Reset and REPL
+### Module search path (sys.path)
+```
+$ mpytool path                    # show current sys.path
+'', '/lib'
+$ mpytool path : :/lib            # replace entire sys.path
+$ mpytool path -f :/custom        # prepend to sys.path (remove duplicates)
+$ mpytool path -a :/sdcard/lib    # append to sys.path (remove duplicates)
+$ mpytool path -d :/custom        # delete from sys.path
+$ mpytool path -f : :/lib :/extra # prepend multiple paths
+$ mpytool cd :/app -- path -f :   # combine with cd to set working dir
+```
+
+Path semantics: `:` = empty string (CWD) in sys.path, `:/` = root directory. The `-f` and `-a` flags automatically remove duplicates (move existing paths to new position).
+
+### Stop, reset and REPL
 ```
+$ mpytool stop               # stop running program (Ctrl-C)
+$ mpytool stop -- repl       # stop and enter REPL
 $ mpytool reset              # soft reset (Ctrl-D, runs boot.py/main.py)
 $ mpytool reset --raw        # soft reset in raw REPL (clears RAM only)
 $ mpytool reset --machine    # MCU reset (machine.reset, auto-reconnect)
@@ -166,11 +196,18 @@ $ mpytool sleep 2            # sleep for 2 seconds (useful between commands)
 ### Serial terminal and monitor (general purpose)
 ```
 $ mpytool repl                       # auto-detect port, 115200 baud
+REPL (Ctrl+] to exit)
+
+$ mpytool -v repl                    # verbose: shows CWD and sys.path before REPL
+REPL (Ctrl+] to exit)  CWD: /  PATH: : :.frozen :/lib
+
 $ mpytool -p /dev/ttyUSB0 repl       # specify port
 $ mpytool -b 9600 repl               # specify baudrate
 $ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor at 9600 baud
 ```
 
+The `repl` command with `-v` flag displays current working directory (CWD) and `sys.path` before entering REPL, making it easy to see the device state after `mount`, `cd`, or `path` commands.
+
 Both `repl` and `monitor` can be used as general-purpose serial tools - not just for MicroPython devices. Use them to interact with any serial device (Arduino, ESP with custom firmware, GPS modules, etc.). When only one serial port is detected, it is used automatically. Default baudrate is 115200.
 
 ### Execute Python code on device
@@ -185,6 +222,121 @@ $ mpytool run script.py                  # run script (fire-and-forget)
 $ mpytool run script.py -- monitor       # run script and capture output
 ```
 
+### Edit file on device
+```
+$ mpytool edit :boot.py              # edit file (uses $VISUAL or $EDITOR)
+$ mpytool edit :/lib/config.py       # absolute path
+$ mpytool edit --editor vim :main.py # explicit editor
+$ mpytool edit :newfile.py           # create new file if doesn't exist
+```
+
+Downloads file to a temp file, opens in editor, uploads back if changed.
+Editor priority: `--editor` > `$VISUAL` > `$EDITOR` > error.
+
+### Device RTC (real-time clock)
+```
+$ mpytool rtc                        # display current RTC
+2026-02-21 15:30:45
+
+$ mpytool rtc --set                  # set RTC to local PC time
+RTC set to 2026-02-21 15:30:45 (local)
+
+$ mpytool rtc --utc                  # set RTC to UTC time
+RTC set to 2026-02-21 14:30:45 (UTC)
+
+$ mpytool rtc "2026-02-21 14:30:00"  # set RTC to specific datetime
+RTC set to 2026-02-21 14:30:00
+```
+
+Flags: `-s`/`--set` and `-l`/`--local` both set local time, `-u`/`--utc` sets UTC.
+Manual datetime format: `YYYY-MM-DD HH:MM:SS`.
+
+### Mount local directory on device
+```
+$ mpytool mount ./src                       # mount ./src as /remote, auto-start REPL
+Mounted ./src on /remote (readonly)
+Changed CWD to /remote
+REPL (Ctrl+] to exit)
+
+$ mpytool -v mount ./src :/app              # mount as /app instead of /remote (verbose)
+Mounted ./src on /app (readonly)
+Changed CWD to /app
+REPL (Ctrl+] to exit)  CWD: /app  PATH: : :.frozen :/lib
+
+$ mpytool mount -m ./src :/app              # mount with automatic .mpy compilation
+Mounted ./src on /app (readonly, .mpy compilation)
+Changed CWD to /app
+>>> import foo                              # imports /app/foo.mpy (compiled from ./src/foo.py)
+
+$ mpytool mount -w ./workspace :/work       # mount as read-write (can create/modify/delete files)
+Mounted ./workspace on /work (read-write)
+Changed CWD to /work
+>>> f = open('/work/test.txt', 'w'); f.write('hello'); f.close()  # creates local file
+>>> import os; os.mkdir('/work/newdir')     # creates local directory
+
+$ mpytool mount ./src -- exec "import main" # mount and run code
+$ mpytool mount ./src -- monitor            # mount and monitor output
+$ mpytool mount ./app :/app -- mount ./lib :/lib -- repl  # multiple mounts (CWD = /app)
+Mounted ./app on /app (readonly)
+Changed CWD to /app
+Mounted ./lib on /lib (readonly)
+```
+
+Mounts a local directory on the device as a VFS. The device can read,
+import and execute files from the local directory without uploading
+them to flash. Changes to local files are immediately visible on
+the device.
+
+**Memory overhead:** The VFS agent uses ~4.2KB of RAM on the device
+(154 lines of MicroPython code injected during mount).
+
+**By default, mounts are read-only.** Use `-w` / `--writable` flag
+to enable write support — the device can create, modify and delete
+files in the mounted directory. All changes are written directly to
+the local filesystem.
+
+**`-m` / `--mpy` flag:** Enables transparent `.mpy` compilation.
+When the device imports a module, the `.py` file is automatically
+compiled to `.mpy` bytecode on-demand and served from cache
+(`__pycache__/`). Benefits: faster imports, less RAM usage, support
+for `@native`/`@viper` code with `-march`. Boot files (`boot.py`,
+`main.py`) and empty files remain as `.py`. If compilation fails,
+automatically falls back to `.py`. Prebuilt `.mpy` files have
+priority over cache.
+
+The first mount automatically changes CWD to the mount point (mpremote
+compatibility). Subsequent mounts do not change CWD. Use `cd` command
+to change working directory manually if needed. Multiple independent
+(non-nested) mounts are supported.
+
+After mount, mpytool automatically enters REPL (unless `monitor` or
+`repl` follows). In REPL you can import modules from the mounted
+directory, Ctrl+D triggers soft reset with automatic re-mount and CWD
+restoration to the mount point.
+
+**Best for:** Development, testing, prototyping, debugging. For bulk
+file transfers (uploading/downloading many files), use `cp` command
+instead — it's optimized for throughput.
+
+**Security:** Paths are validated to prevent traversal outside mount
+root. Symlinks are followed and checked. Write operations require
+explicit `-w` flag.
+
+See [Mount VFS Comparison](README_mpremote.md#mount-vfs-comparison) for detailed comparison with mpremote.
+
+### Link files into mounted VFS
+```
+$ mpytool mount ./app :/ -- ln ./drivers :/lib/ -- repl       # mount app, link drivers into /lib/
+$ mpytool mount ./app :/ -- ln ./extra.py :/lib/ -- repl      # link single file into /lib/
+$ mpytool mount ./app :/ -- ln ./pkg :/lib/pkg -- repl        # link as specific name
+$ mpytool mount ./app :/ -- ln ./pkg/ :/lib/ -- repl          # link package contents into /lib/
+$ mpytool mount ./app :/ -- ln ./a.py ./b.py :/lib/ -- repl   # link multiple sources
+```
+
+Links local files or directories into an already mounted VFS as virtual submounts. Works entirely on the PC side — no changes needed on the device. Useful for composing a virtual filesystem from multiple local directories without copying.
+
+Path semantics follow the same trailing `/` rules as `cp`: `ln dir :/lib/` creates `:/lib/dir/...`, `ln dir/ :/lib/` copies contents into `:/lib/...`. Destination must be an absolute device path with `:` prefix.
+
 ### Serial link speed test
 ```
 $ mpytool speedtest
@@ -244,9 +396,9 @@ $ mpytool flash erase vfs --full           # full erase partition
 
 ### OTA firmware update (ESP32)
 ```
-$ mpytool ota firmware.app-bin                    # flash to next OTA partition
-$ mpytool ota firmware.app-bin -- reset --machine          # flash and reboot
-$ mpytool ota firmware.app-bin -- reset --machine -t 30    # flash and reboot with 30s timeout
+$ mpytool flash ota firmware.app-bin                    # flash to next OTA partition
+$ mpytool flash ota firmware.app-bin -- reset --machine          # flash and reboot
+$ mpytool flash ota firmware.app-bin -- reset --machine -t 30    # flash and reboot with 30s timeout
 ```
 
 ### Multiple commands separated by `--`
@@ -374,7 +526,7 @@ For reporting bugs, please include `-ddd` output in the issue.
 
 ## Performance
 
-`mpytool` uses optimized chunked transfer with automatic compression, which allows copying files very quickly. See [README_BENCH.md](README_BENCH.md) for detailed benchmarks.
+`mpytool` uses optimized chunked transfer with automatic compression, which allows copying files very quickly. See [README_bench.md](README_bench.md) for detailed benchmarks.
 
 ### Summary
 

{mpytool-2.2.4 → mpytool-2.3.0}/mpytool/__init__.py

@@ -4,5 +4,5 @@ from mpytool.conn import ConnError, Timeout
 from mpytool.conn_serial import ConnSerial
 from mpytool.conn_socket import ConnSocket
 from mpytool.mpy_comm import MpyError, CmdError
-from mpytool.mpy import Mpy
+from mpytool.mpy import Mpy, PathNotFound, FileNotFound, DirNotFound
 from mpytool.logger import SimpleColorLogger