mpytool 2.3.6__tar.gz → 2.5.0__tar.gz

{mpytool-2.3.6 → mpytool-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.3.6
+Version: 2.5.0
 Summary: MPY tool - manage files on devices running MicroPython
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -31,6 +31,11 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
   (CP2102, CH340)
 - **Multiple reset options** - soft, MCU, hardware (RTS),
   bootloader entry
+- **Wipe device** - erase the whole filesystem and machine-reset
+  for a clean slate (handy at the start of automated tests)
+- **Deploy projects** - `sync` uploads a whole project to the device
+  using a `.mpyproject` config file (deploy map, excludes, `.mpy`
+  compilation)
 - **General-purpose serial terminal** - `repl` and `monitor` work
   with any serial device
 - **Mount local directory** - VFS mount (read-only or read-write)
@@ -42,7 +47,7 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
 - **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
+- **Network support** - connect over TCP with optional SSL/TLS
 - **Full Unicode support** - handles Unicode in file names and content
 
 See [README_mpremote.md](README_mpremote.md) for detailed comparison with mpremote.
@@ -166,6 +171,47 @@ Requires `mpy-cross` in PATH (`pip install mpy-cross`). If mpy-cross version dif
 from device, automatically uses `-b` flag to target the correct bytecode version.
 If `mpy-cross` is not found, falls back to uploading `.py` with a warning.
 
+### Deploy project (sync)
+
+`sync` uploads a whole project to the device based on a `.mpyproject`
+configuration file. It is the command-line counterpart of the deploy feature in
+the [Sublime Text plugin](https://github.com/cortexm/mpytool-sublime) and shares
+the same `.mpyproject` format. Unlike the plugin it is non-interactive: when more
+than one device is connected, pass `-p` to pick the port.
+
+```
+$ mpytool sync                  # deploy project in CWD (.mpyproject searched upward)
+$ mpytool sync ~/projects/blink # deploy a project in another directory
+$ mpytool -p /dev/ttyACM0 sync  # pick port explicitly (multiple devices)
+$ mpytool sync -- reset -- monitor   # deploy, then reset and watch output
+```
+
+The `.mpyproject` file (JSON, trailing commas tolerated) describes what to upload:
+
+```json
+{
+    "name": "blink",
+    "compile": true,
+    "deploy": {
+        "": ["./"],
+        "/lib/": ["../shared/utils.py"],
+        "/main.py": "src/main_dev.py"
+    },
+    "exclude": ["*.bak", "tests"]
+}
+```
+
+- `deploy` maps a device destination to its source(s), relative to the project
+  root. A key of `""` or one ending in `/` is a **directory** (value is a list of
+  sources); any other key is a **rename** (value is a single source file).
+  Defaults to `{"": ["./"]}` (whole project to root) when omitted.
+- `compile: true` compiles `.py` to `.mpy` (same as `cp -m`).
+- `exclude` adds ignore patterns on top of the defaults (`__pycache__`, `*.pyc`,
+  dotfiles). Combined with global `-e` patterns.
+
+The connection fields (`port`, `address`) used by the Sublime plugin are ignored
+by the CLI — use the global `-p` / `-a` options instead.
+
 ### Move/rename on device
 ```
 $ mpytool mv :/old.py :/new.py      # rename file
@@ -270,6 +316,30 @@ $ mpytool sleep 2            # sleep for 2 seconds (useful between commands)
 SLEEP 2.0s
 ```
 
+### Wipe device (erase all files + machine reset)
+```
+$ mpytool wipe               # delete everything from / then machine.reset()
+WIPE
+  rm /boot.py
+  rm /main.py
+  rm /lib
+  reset
+
+$ mpytool wipe -- ls         # wipe, reconnect, then list (now empty)
+WIPE
+  rm /main.py
+  reset, reconnected
+LS:
+```
+
+`wipe` erases the whole filesystem (recursive delete of `/`) and then does a
+full `machine.reset()` — a soft reset would leave open sockets, WiFi and
+mounted VFS alive, so machine reset is used for a true clean slate. It **never
+prompts** (mpytool has no interactive mode); `-y`/`--yes` is accepted as a
+no-op. When `wipe` is the last command it just resets and exits; when more
+commands follow it reconnects first (use `-t SECONDS` for the reconnect
+timeout). See [README_API.md](README_API.md) for `Mpy.wipe()`.
+
 ### Serial terminal and monitor (general purpose)
 ```
 $ mpytool repl                       # auto-detect port, 115200 baud
@@ -537,8 +607,12 @@ TREE: /
 
 ### Connect over network (TCP, default port 23)
 ```
-$ mpytool -a 192.168.1.100 ls
-$ mpytool -a 192.168.1.100:8266 tree
+$ mpytool -a 192.168.1.100 ls                          # plain TCP
+$ mpytool -a 192.168.1.100:8266 tree                   # custom port
+$ mpytool -a 192.168.1.100:8023 --ssl ls               # SSL/TLS connection
+$ mpytool -a 192.168.1.100:8023 --ssl-ca ca.pem ls     # SSL with custom CA
+$ mpytool -a 192.168.1.100:8023 --ssl-no-hostname ls   # SSL, skip hostname check
+$ mpytool -a 192.168.1.100:8023 --ssl-no-verify ls     # SSL, skip all verification
 ```
 
 ### Set baudrate (default 115200)

{mpytool-2.3.6 → mpytool-2.5.0}/README.md

@@ -16,6 +16,11 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
   (CP2102, CH340)
 - **Multiple reset options** - soft, MCU, hardware (RTS),
   bootloader entry
+- **Wipe device** - erase the whole filesystem and machine-reset
+  for a clean slate (handy at the start of automated tests)
+- **Deploy projects** - `sync` uploads a whole project to the device
+  using a `.mpyproject` config file (deploy map, excludes, `.mpy`
+  compilation)
 - **General-purpose serial terminal** - `repl` and `monitor` work
   with any serial device
 - **Mount local directory** - VFS mount (read-only or read-write)
@@ -27,7 +32,7 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
 - **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
+- **Network support** - connect over TCP with optional SSL/TLS
 - **Full Unicode support** - handles Unicode in file names and content
 
 See [README_mpremote.md](README_mpremote.md) for detailed comparison with mpremote.
@@ -151,6 +156,47 @@ Requires `mpy-cross` in PATH (`pip install mpy-cross`). If mpy-cross version dif
 from device, automatically uses `-b` flag to target the correct bytecode version.
 If `mpy-cross` is not found, falls back to uploading `.py` with a warning.
 
+### Deploy project (sync)
+
+`sync` uploads a whole project to the device based on a `.mpyproject`
+configuration file. It is the command-line counterpart of the deploy feature in
+the [Sublime Text plugin](https://github.com/cortexm/mpytool-sublime) and shares
+the same `.mpyproject` format. Unlike the plugin it is non-interactive: when more
+than one device is connected, pass `-p` to pick the port.
+
+```
+$ mpytool sync                  # deploy project in CWD (.mpyproject searched upward)
+$ mpytool sync ~/projects/blink # deploy a project in another directory
+$ mpytool -p /dev/ttyACM0 sync  # pick port explicitly (multiple devices)
+$ mpytool sync -- reset -- monitor   # deploy, then reset and watch output
+```
+
+The `.mpyproject` file (JSON, trailing commas tolerated) describes what to upload:
+
+```json
+{
+    "name": "blink",
+    "compile": true,
+    "deploy": {
+        "": ["./"],
+        "/lib/": ["../shared/utils.py"],
+        "/main.py": "src/main_dev.py"
+    },
+    "exclude": ["*.bak", "tests"]
+}
+```
+
+- `deploy` maps a device destination to its source(s), relative to the project
+  root. A key of `""` or one ending in `/` is a **directory** (value is a list of
+  sources); any other key is a **rename** (value is a single source file).
+  Defaults to `{"": ["./"]}` (whole project to root) when omitted.
+- `compile: true` compiles `.py` to `.mpy` (same as `cp -m`).
+- `exclude` adds ignore patterns on top of the defaults (`__pycache__`, `*.pyc`,
+  dotfiles). Combined with global `-e` patterns.
+
+The connection fields (`port`, `address`) used by the Sublime plugin are ignored
+by the CLI — use the global `-p` / `-a` options instead.
+
 ### Move/rename on device
 ```
 $ mpytool mv :/old.py :/new.py      # rename file
@@ -255,6 +301,30 @@ $ mpytool sleep 2            # sleep for 2 seconds (useful between commands)
 SLEEP 2.0s
 ```
 
+### Wipe device (erase all files + machine reset)
+```
+$ mpytool wipe               # delete everything from / then machine.reset()
+WIPE
+  rm /boot.py
+  rm /main.py
+  rm /lib
+  reset
+
+$ mpytool wipe -- ls         # wipe, reconnect, then list (now empty)
+WIPE
+  rm /main.py
+  reset, reconnected
+LS:
+```
+
+`wipe` erases the whole filesystem (recursive delete of `/`) and then does a
+full `machine.reset()` — a soft reset would leave open sockets, WiFi and
+mounted VFS alive, so machine reset is used for a true clean slate. It **never
+prompts** (mpytool has no interactive mode); `-y`/`--yes` is accepted as a
+no-op. When `wipe` is the last command it just resets and exits; when more
+commands follow it reconnects first (use `-t SECONDS` for the reconnect
+timeout). See [README_API.md](README_API.md) for `Mpy.wipe()`.
+
 ### Serial terminal and monitor (general purpose)
 ```
 $ mpytool repl                       # auto-detect port, 115200 baud
@@ -522,8 +592,12 @@ TREE: /
 
 ### Connect over network (TCP, default port 23)
 ```
-$ mpytool -a 192.168.1.100 ls
-$ mpytool -a 192.168.1.100:8266 tree
+$ mpytool -a 192.168.1.100 ls                          # plain TCP
+$ mpytool -a 192.168.1.100:8266 tree                   # custom port
+$ mpytool -a 192.168.1.100:8023 --ssl ls               # SSL/TLS connection
+$ mpytool -a 192.168.1.100:8023 --ssl-ca ca.pem ls     # SSL with custom CA
+$ mpytool -a 192.168.1.100:8023 --ssl-no-hostname ls   # SSL, skip hostname check
+$ mpytool -a 192.168.1.100:8023 --ssl-no-verify ls     # SSL, skip all verification
 ```
 
 ### Set baudrate (default 115200)

{mpytool-2.3.6 → mpytool-2.5.0}/README_API.md

@@ -107,25 +107,44 @@ conn.reconnect(timeout=5)   # Reconnect after device reset (USB-CDC)
 
 ### ConnSocket
 
-TCP socket connection for network-connected devices.
+TCP socket connection for network-connected devices with optional SSL/TLS.
 
 ```python
-mpytool.ConnSocket(address, log=None)
+mpytool.ConnSocket(address, log=None, ssl=False, ssl_verify=True,
+    ssl_ca=None, ssl_check_hostname=True)
 ```
 
 **Parameters:**
 - `address` (str): Host address with optional port (e.g., `192.168.1.100` or `192.168.1.100:8266`)
 - `log`: Optional logger instance
+- `ssl` (bool): Enable SSL/TLS encryption (default: `False`)
+- `ssl_verify` (bool): Verify server certificate (default: `True`). Set to `False` for self-signed certs.
+- `ssl_ca` (str): Path to CA certificate file for custom certificate authorities
+- `ssl_check_hostname` (bool): Verify hostname matches certificate (default: `True`). Set to `False` when one cert is shared across multiple hosts.
 
 Default port is 23 if not specified.
 
-**Example:**
+**Examples:**
 ```python
+# Plain TCP
 conn = mpytool.ConnSocket(address='192.168.1.100:8266')
+
+# SSL with system CA
+conn = mpytool.ConnSocket(address='server:8023', ssl=True)
+
+# SSL with custom CA
+conn = mpytool.ConnSocket(address='server:8023', ssl=True, ssl_ca='ca.pem')
+
+# SSL, verify cert but skip hostname check
+conn = mpytool.ConnSocket(address='192.168.1.100:8023',
+    ssl=True, ssl_ca='ca.pem', ssl_check_hostname=False)
+
+# SSL without any verification (insecure)
+conn = mpytool.ConnSocket(address='server:8023', ssl=True, ssl_verify=False)
 ```
 
 **Raises:**
-- `ConnError`: If unable to connect
+- `ConnError`: If unable to connect or SSL handshake fails
 
 ### Common Connection Methods
 
@@ -873,7 +892,7 @@ Soft reset in raw REPL mode (clears RAM only, doesn't run boot.py/main.py).
 mpy.soft_reset_raw()
 ```
 
-#### machine_reset(reconnect=True)
+#### machine_reset(reconnect=True, timeout=None)
 
 MCU reset using `machine.reset()`.
 
@@ -883,6 +902,7 @@ mpy.machine_reset(reconnect=True)
 
 **Parameters:**
 - `reconnect` (bool): If True, attempt to reconnect after reset (for USB-CDC ports)
+- `timeout` (int): Reconnect timeout in seconds (None = default)
 
 #### hard_reset()
 
@@ -895,6 +915,34 @@ mpy.hard_reset()
 **Raises:**
 - `NotImplementedError`: If connection doesn't support hardware reset
 
+#### wipe(reconnect=True, timeout=None, on_delete=None)
+
+Erase all files from the filesystem root, then `machine.reset()` the device.
+
+Recursively deletes every entry in `/`, then performs a full machine reset so
+runtime state (open sockets, WiFi, mounted VFS) is dropped too — a soft reset
+would leave those alive. Intended for a clean slate, e.g. at the start of
+integration tests.
+
+```python
+# Clean slate at the start of a test
+mpy.wipe()
+
+# Wipe without waiting to reconnect
+mpy.wipe(reconnect=False)
+
+# Show what gets removed
+mpy.wipe(on_delete=lambda path: print(f"removing {path}"))
+```
+
+**Parameters:**
+- `reconnect` (bool): If True, wait for the device to come back after reset
+- `timeout` (int): Reconnect timeout in seconds (None = default)
+- `on_delete` (callable): Optional `callback(path)` invoked before each delete
+
+**Returns:**
+- `bool`: True if reconnected after reset, False otherwise
+
 ### Flash/Partition Methods
 
 #### partitions()

{mpytool-2.3.6 → mpytool-2.5.0}/completions/_mpytool

@@ -133,6 +133,10 @@ _mpytool() {
         '--port[serial port]:port:_mpytool_ports' \
         '-a[network address]:address:' \
         '--address[network address]:address:' \
+        '--ssl[use SSL/TLS]' \
+        '--ssl-no-verify[disable SSL certificate verification]' \
+        '--ssl-ca[CA certificate file]:file:_files' \
+        '--ssl-no-hostname[disable SSL hostname verification]' \
         '-b[baud rate]:baud:(9600 19200 38400 57600 115200 230400 460800 921600)' \
         '--baud[baud rate]:baud:(9600 19200 38400 57600 115200 230400 460800 921600)' \
         '-d[debug level]' \
@@ -265,6 +269,13 @@ _mpytool() {
                         fi
                     fi
                     ;;
+                sync)
+                    # Optional local project directory, -- anytime
+                    if [[ $pos -eq 2 ]]; then
+                        _files -/
+                    fi
+                    compadd -- '--'
+                    ;;
                 exec)
                     # 1 code string, -- after it
                     [[ $nargs -ge 1 ]] && compadd -- '--'

{mpytool-2.3.6 → mpytool-2.5.0}/completions/mpytool.bash

@@ -170,6 +170,10 @@ _mpytool() {
         -a|--address)
             return
             ;;
+        --ssl-ca)
+            COMPREPLY=($(compgen -f -- "$cur"))
+            return
+            ;;
     esac
 
     # At command position
@@ -268,6 +272,13 @@ _mpytool() {
                 fi
             fi
             ;;
+        sync)
+            # Optional local project directory, -- for chaining
+            if [[ $pos -eq 2 ]]; then
+                COMPREPLY=($(compgen -d -- "$cur"))
+            fi
+            [[ -z "$cur" || "--" == "$cur"* ]] && COMPREPLY+=("--")
+            ;;
         exec)
             # 1 code string, -- after it
             [[ $nargs -ge 1 && ( -z "$cur" || "--" == "$cur"* ) ]] && COMPREPLY+=("--")

mpytool-2.5.0/mpytool/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2.5.0'
+__version_tuple__ = version_tuple = (2, 5, 0)
+
+__commit_id__ = commit_id = 'ga70fd9bfe'

{mpytool-2.3.6 → mpytool-2.5.0}/mpytool/conn.py

@@ -208,6 +208,13 @@ class Conn():
     def close(self):
         """Close connection"""
 
+    def discard_output(self):
+        """Discard buffered output not yet transmitted (no-op by default).
+
+        Serial connections override this; needed before closing a port with
+        undeliverable queued data, otherwise close() blocks waiting to drain.
+        """
+
     def hard_reset(self):
         """Hardware reset (only available on serial connections)"""
         raise NotImplementedError("Hardware reset not available on this connection")

{mpytool-2.3.6 → mpytool-2.5.0}/mpytool/conn_serial.py

@@ -46,6 +46,19 @@ class ConnSerial(_conn.Conn):
     def __del__(self):
         self.close()
 
+    def discard_output(self):
+        """Discard kernel TX buffer (data written but not yet transmitted).
+
+        Without this, closing the port blocks while the kernel waits to drain
+        output the device never consumed (e.g. keystrokes sent to a device not
+        reading its USB-CDC, after leaving the REPL).
+        """
+        if self._serial:
+            try:
+                self._serial.reset_output_buffer()
+            except OSError:
+                pass
+
     @property
     def fd(self):
         return self._serial.fd if self._serial else None

{mpytool-2.3.6 → mpytool-2.5.0}/mpytool/conn_socket.py

@@ -1,11 +1,14 @@
 """MicroPython tool: socket connector"""
 
 import socket as _socket
+import ssl as _ssl
 import mpytool.conn as _conn
 
 
 class ConnSocket(_conn.Conn):
-    def __init__(self, address, log=None):
+    def __init__(
+            self, address, log=None, ssl=False, ssl_verify=True,
+            ssl_ca=None, ssl_check_hostname=True):
         super().__init__(log)
         self._socket = None
         sock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
@@ -16,14 +19,31 @@ class ConnSocket(_conn.Conn):
         else:
             host = address
             port = 23
+        proto = "ssl" if ssl else "tcp"
         if log:
-            log.info(f"Connecting to: {host}:{port}")
+            log.info(f"Connecting to: {host}:{port} [{proto}]")
         try:
             sock.connect((host, port))
         except _socket.timeout as err:
+            sock.close()
             raise _conn.ConnError(f"Timeout connecting to {host}:{port}") from err
         except _socket.error as err:
+            sock.close()
             raise _conn.ConnError(f"Cannot connect to {host}:{port}: {err}") from err
+        if ssl:
+            try:
+                context = _ssl.create_default_context()
+                if not ssl_verify:
+                    context.check_hostname = False
+                    context.verify_mode = _ssl.CERT_NONE
+                elif not ssl_check_hostname:
+                    context.check_hostname = False
+                if ssl_ca:
+                    context.load_verify_locations(ssl_ca)
+                sock = context.wrap_socket(sock, server_hostname=host)
+            except (_ssl.SSLError, OSError) as err:
+                sock.close()
+                raise _conn.ConnError(f"SSL error: {err}") from err
         sock.settimeout(None)
         sock.setblocking(False)
         self._socket = sock
@@ -51,8 +71,12 @@ class ConnSocket(_conn.Conn):
             if data:
                 self._log.debug("RX: %r", data)
                 return data
-        except BlockingIOError:
+            # recv() returned b'' = peer closed connection
+            raise _conn.ConnError("Connection closed")
+        except (BlockingIOError, _ssl.SSLWantReadError):
             pass
+        except _conn.ConnError:
+            raise
         except OSError as err:
             raise _conn.ConnError(f"Connection lost: {err}") from err
         return None
@@ -64,5 +88,7 @@ class ConnSocket(_conn.Conn):
         self._log.debug("TX: %r", data)
         try:
             return self._socket.send(data)
+        except _ssl.SSLWantWriteError:
+            return 0
         except OSError as err:
             raise _conn.ConnError(f"Connection lost: {err}") from err

{mpytool-2.3.6 → mpytool-2.5.0}/mpytool/mpy.py

@@ -1329,6 +1329,29 @@ def _mt_pfind(label):
             return True
         return False
 
+    def wipe(self, reconnect=True, timeout=None, on_delete=None):
+        """Erase all files from filesystem root, then machine-reset device
+
+        Deletes every entry in '/' recursively, then performs a full
+        machine.reset() so runtime state (open sockets, WiFi, mounted VFS,
+        etc.) is dropped too - a soft reset would leave those alive. Intended
+        for a clean slate, e.g. at the start of integration tests.
+
+        Arguments:
+            reconnect: if True, wait for the device to come back after reset
+            timeout: reconnect timeout in seconds (None = default)
+            on_delete: optional callback(path) invoked before each delete
+
+        Returns:
+            True if reconnected after reset, False otherwise
+        """
+        for name, _ in self.ls('/'):
+            path = '/' + name
+            if on_delete is not None:
+                on_delete(path)
+            self.delete(path)
+        return self.machine_reset(reconnect=reconnect, timeout=timeout)
+
     def machine_bootloader(self):
         """Enter bootloader using machine.bootloader()