mpytool 2.3.1__tar.gz → 2.3.2__tar.gz

{mpytool-2.3.1 → mpytool-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.3.1
+Version: 2.3.2
 Summary: MPY tool - manage files on devices running MicroPython
 Author-email: Pavel Revak <pavel.revak@gmail.com>
 License-Expression: MIT
@@ -692,6 +692,38 @@ exec bash
 - Support for `--` command separator
 - Works with both relative and absolute paths
 
+## Development
+
+### Running tests
+
+```bash
+# Unit tests (no device needed)
+python -m unittest discover tests/ -v
+
+# Read-only integration tests (safe on production device)
+MPYTOOL_TEST_PORT=/dev/ttyACM0 python -m unittest tests.test_integration -v
+
+# All integration tests (dedicated test device)
+MPYTOOL_TEST_PORT_RW=/dev/ttyACM0 python -m unittest tests.test_integration -v
+
+# CLI tests (no device needed for basic tests)
+python -m unittest tests.test_cli -v
+
+# All CLI tests with device
+MPYTOOL_TEST_PORT_RW=/dev/ttyACM0 python -m unittest tests.test_cli -v
+```
+
+Test categories:
+- **Unit tests** (`test_*.py` except `test_integration.py`, `test_cli.py`) - no device needed
+- **Read-only tests** (`MPYTOOL_TEST_PORT`) - safe on any device, no filesystem changes
+- **All tests** (`MPYTOOL_TEST_PORT_RW`) - includes write and flash operations, use dedicated test device
+
+### Install from source
+
+```bash
+pip install -e .
+```
+
 ## Requirements
 
 Working only with MicroPython boards, not with CircuitPython

{mpytool-2.3.1 → mpytool-2.3.2}/README.md

@@ -678,6 +678,38 @@ exec bash
 - Support for `--` command separator
 - Works with both relative and absolute paths
 
+## Development
+
+### Running tests
+
+```bash
+# Unit tests (no device needed)
+python -m unittest discover tests/ -v
+
+# Read-only integration tests (safe on production device)
+MPYTOOL_TEST_PORT=/dev/ttyACM0 python -m unittest tests.test_integration -v
+
+# All integration tests (dedicated test device)
+MPYTOOL_TEST_PORT_RW=/dev/ttyACM0 python -m unittest tests.test_integration -v
+
+# CLI tests (no device needed for basic tests)
+python -m unittest tests.test_cli -v
+
+# All CLI tests with device
+MPYTOOL_TEST_PORT_RW=/dev/ttyACM0 python -m unittest tests.test_cli -v
+```
+
+Test categories:
+- **Unit tests** (`test_*.py` except `test_integration.py`, `test_cli.py`) - no device needed
+- **Read-only tests** (`MPYTOOL_TEST_PORT`) - safe on any device, no filesystem changes
+- **All tests** (`MPYTOOL_TEST_PORT_RW`) - includes write and flash operations, use dedicated test device
+
+### Install from source
+
+```bash
+pip install -e .
+```
+
 ## Requirements
 
 Working only with MicroPython boards, not with CircuitPython

{mpytool-2.3.1 → mpytool-2.3.2}/mpytool/conn_serial.py

@@ -3,6 +3,7 @@
 import time as _time
 import serial as _serial
 import mpytool.conn as _conn
+import mpytool.utils as _utils
 
 
 class ConnSerial(_conn.Conn):
@@ -11,6 +12,7 @@ class ConnSerial(_conn.Conn):
     def __init__(self, log=None, **serial_config):
         super().__init__(log)
         self._serial_config = serial_config
+        self._port_info = _utils.get_port_info(serial_config.get('port', ''))
         try:
             self._serial = _serial.Serial(**serial_config)
         except _serial.serialutil.SerialException as err:
@@ -20,6 +22,17 @@ class ConnSerial(_conn.Conn):
         # Windows: pyserial has no fd, select() works only with sockets
         if not hasattr(self._serial, 'fd'):
             self._has_data = self._has_data_polling
+        # Debug info about port type
+        if self._log:
+            port = serial_config.get('port', '')
+            if self._port_info and self._port_info.vid:
+                vid = self._port_info.vid
+                pid = self._port_info.pid
+                self._log.info(
+                    "Connected to %s [%04X:%04X %s]",
+                    port, vid, pid, self.port_type)
+            else:
+                self._log.info("Connected to %s [unknown serial port]", port)
 
     def close(self):
         if self._serial:
@@ -74,13 +87,38 @@ class ConnSerial(_conn.Conn):
         except OSError as err:
             raise _conn.ConnError(f"Connection lost: {err}") from err
 
-    def _is_usb_cdc(self):
-        """Check if this is a USB-CDC port (native USB on ESP32-S/C)"""
-        port = self._serial.port or ''
-        return 'ACM' in port or 'usbmodem' in port
+    @property
+    def vid(self):
+        """USB Vendor ID or None if not available"""
+        return self._port_info.vid if self._port_info else None
+
+    @property
+    def pid(self):
+        """USB Product ID or None if not available"""
+        return self._port_info.pid if self._port_info else None
+
+    @property
+    def port_type(self):
+        """Return port type string for debug info"""
+        if self._is_usb_uart():
+            return "USB-UART"
+        if self.vid in _utils._MICROPYTHON_VIDS:
+            return "USB-CDC"
+        if self.vid:
+            return "USB (unknown)"
+        return "unknown"
+
+    def _is_usb_uart(self):
+        """Check if this is a USB-UART bridge (CP210x, CH340, FTDI, etc.)"""
+        return self.vid in _utils._USB_UART_VIDS
 
     def hard_reset(self):
-        """Hardware reset using DTR/RTS signals"""
+        """Hardware reset using DTR/RTS signals (USB-UART only)"""
+        if not self._is_usb_uart():
+            raise _conn.ConnError(
+                f"Hardware reset not supported on {self.port_type}")
+        if self._log:
+            self._log.info("hard_reset: using DTR/RTS")
         self._serial.setDTR(False)  # GPIO0 high (normal boot)
         self._serial.setRTS(True)   # Assert reset
         _time.sleep(0.1)
@@ -117,28 +155,12 @@ class ConnSerial(_conn.Conn):
         raise _conn.ConnError(f"Could not reconnect to {port} within {timeout}s")
 
     def reset_to_bootloader(self):
-        """Reset into bootloader mode (auto-detects USB-CDC vs USB-UART)"""
-        if self._is_usb_cdc():
-            self._reset_to_bootloader_usb_jtag()
-        else:
-            self._reset_to_bootloader_classic()
-
-    def _reset_to_bootloader_usb_jtag(self):
-        """Bootloader reset for USB-JTAG-Serial (esptool sequence)"""
-        self._serial.setRTS(False)
-        self._serial.setDTR(False)
-        _time.sleep(0.1)
-        self._serial.setDTR(True)
-        self._serial.setRTS(True)
-        _time.sleep(0.1)
-        self._serial.setDTR(False)
-        self._serial.setRTS(True)
-        _time.sleep(0.1)
-        self._serial.setDTR(False)
-        self._serial.setRTS(False)
-
-    def _reset_to_bootloader_classic(self):
-        """Bootloader reset for USB-UART (classic DTR/RTS circuit)"""
+        """Reset into bootloader mode (USB-UART only)"""
+        if not self._is_usb_uart():
+            raise _conn.ConnError(
+                f"Bootloader reset not supported on {self.port_type}")
+        if self._log:
+            self._log.info("reset_to_bootloader: using DTR/RTS")
         self._serial.setDTR(False)  # GPIO0 high
         self._serial.setRTS(True)   # Assert reset
         _time.sleep(0.1)

{mpytool-2.3.1 → mpytool-2.3.2}/mpytool/mpytool.py

@@ -57,6 +57,13 @@ def _remote_basename(path):
     return path.rstrip('/').split('/')[-1]
 
 
+def _normalize_path_arg(value):
+    """Argparse type for path arguments - normalize Windows backslashes"""
+    if _sys.platform == 'win32' and value.startswith(':'):
+        return ':' + value[1:].replace('\\', '/')
+    return value
+
+
 def _parse_device_path(path, cmd_name):
     """Parse device path with : prefix, raise ParamsError if missing
 
@@ -65,12 +72,17 @@ def _parse_device_path(path, cmd_name):
         cmd_name: command name for error message
 
     Returns:
-        path without : prefix
+        path without : prefix (normalized on Windows)
     """
     if not path.startswith(':'):
         raise ParamsError(
             f'{cmd_name} requires device path (: prefix): {path}')
-    return path[1:]
+    # Normalize backslashes on Windows (handled by argparse type for most
+    # commands, but _paths doesn't use argparse)
+    result = path[1:]
+    if _sys.platform == 'win32':
+        result = result.replace('\\', '/')
+    return result
 
 
 # Command argument subparsers
@@ -205,7 +217,6 @@ class MpyTool():
                         f"Multiple serial ports found: {ports_str}. "
                         "Use -p to specify one.")
                 port = ports[0]
-                self.verbose(f"Using {port}", level=2)
             if port:
                 self._conn = _mpytool.ConnSerial(
                     port=port, baudrate=self._baudrate, log=self._log)
@@ -727,32 +738,22 @@ class MpyTool():
         elif mode == 'rts':
             try:
                 self.mpy.hard_reset()
-                if reconnect:
-                    self.verbose(
-                        "  reconnecting...", 1, color='yellow')
-                    _time.sleep(1.0)  # Wait for device to boot
-                    self.mpy._conn.reconnect()
-                    self.verbose("  connected", 1, color='green')
-            except NotImplementedError:
-                raise _mpytool.MpyError(
-                    "Hardware reset not available (serial only)")
-            except (_mpytool.ConnError, OSError) as err:
-                self.verbose(
-                    f"  reconnect failed: {err}", 1, color='red')
-                raise _mpytool.ConnError(
-                    f"Reconnect failed: {err}")
+            except (NotImplementedError, _mpytool.ConnError) as err:
+                raise _mpytool.MpyError(f"Hardware reset failed: {err}")
+            # USB stays connected, just wait for device to boot
+            if reconnect:
+                _time.sleep(0.5)
         elif mode == 'boot':
             self.mpy.machine_bootloader()
         elif mode == 'dtr-boot':
             try:
                 self.mpy.reset_to_bootloader()
-            except NotImplementedError:
-                raise _mpytool.MpyError(
-                    "DTR boot not available (serial only)")
+            except (NotImplementedError, _mpytool.ConnError) as err:
+                raise _mpytool.MpyError(f"Bootloader reset failed: {err}")
 
     @command('ls', 'List files and directories on device.')
     @argument('path', nargs='?', default=':', metavar='remote',
-        help='device path (default: CWD)')
+        type=_normalize_path_arg, help='device path (default: CWD)')
     def _dispatch_ls(self, commands, is_last_group):
         args = _make_parser(self._dispatch_ls).parse_args(commands[:1])
         del commands[:1]
@@ -776,7 +777,7 @@ class MpyTool():
 
     @command('tree', 'Show directory tree on device.')
     @argument('path', nargs='?', default=':', metavar='remote',
-        help='device path (default: CWD)')
+        type=_normalize_path_arg, help='device path (default: CWD)')
     def _dispatch_tree(self, commands, is_last_group):
         args = _make_parser(self._dispatch_tree).parse_args(commands[:1])
         del commands[:1]
@@ -790,7 +791,7 @@ class MpyTool():
 
     @command('cat', 'Print file content from device to stdout.')
     @argument('paths', nargs='+', metavar='remote',
-        help='device path(s) to print')
+        type=_normalize_path_arg, help='device path(s) to print')
     def _dispatch_cat(self, commands, is_last_group):
         args = _make_parser(self._dispatch_cat).parse_args(commands)
         commands.clear()
@@ -802,7 +803,7 @@ class MpyTool():
 
     @command('mkdir', 'Create directory (with parents if needed).')
     @argument('paths', nargs='+', metavar='remote',
-        help='device path(s) to create')
+        type=_normalize_path_arg, help='device path(s) to create')
     def _dispatch_mkdir(self, commands, is_last_group):
         args = _make_parser(self._dispatch_mkdir).parse_args(commands)
         commands.clear()
@@ -813,7 +814,7 @@ class MpyTool():
 
     @command('rm', 'Delete files/dirs. Use :path/ for contents only.')
     @argument('paths', nargs='+', metavar='remote',
-        help='device path(s) to delete')
+        type=_normalize_path_arg, help='device path(s) to delete')
     def _dispatch_rm(self, commands, is_last_group):
         args = _make_parser(self._dispatch_rm).parse_args(commands)
         commands.clear()
@@ -828,7 +829,8 @@ class MpyTool():
         print(cwd)
 
     @command('cd', 'Change current working directory on device.')
-    @argument('path', metavar='remote', help='device path')
+    @argument('path', metavar='remote', type=_normalize_path_arg,
+        help='device path')
     def _dispatch_cd(self, commands, is_last_group):
         args = _make_parser(self._dispatch_cd).parse_args([commands.pop(0)])
         path = _parse_device_path(args.path, 'cd')
@@ -844,7 +846,7 @@ class MpyTool():
     @option('-d', '--delete', action='store_const', const='delete',
         dest='mode', help='delete from sys.path')
     @argument('paths', nargs='*', metavar='remote',
-        help='paths to add/remove (: prefix required)')
+        type=_normalize_path_arg, help='paths to add/remove (: prefix required)')
     def _dispatch_path(self, commands, is_last_group):
         args = _make_parser(self._dispatch_path).parse_args(commands)
         commands.clear()
@@ -984,7 +986,8 @@ class MpyTool():
 
     @command('edit', 'Edit file on device in local editor.')
     @option('--editor', metavar='CMD', help='editor command')
-    @argument('path', metavar='remote', help='device file to edit (: prefix)')
+    @argument('path', metavar='remote', type=_normalize_path_arg,
+        help='device file to edit (: prefix)')
     def _dispatch_edit(self, commands, is_last_group):
         args = _make_parser(self._dispatch_edit).parse_args(commands)
         commands.clear()
@@ -1115,14 +1118,14 @@ class MpyTool():
     @option('-Z', '--no-compress', dest='no_compress', action='store_true',
         help='disable compression')
     @argument('paths', nargs='*', metavar='local_or_remote',
-        help='source(s) and dest (: prefix for device)')
+        type=_normalize_path_arg, help='source(s) and dest (: prefix for device)')
     def _dispatch_cp(self, commands, is_last_group):
         self.cmd_cp(commands)
         commands.clear()
 
     @command('mv', 'Move or rename files on device.')
     @argument('paths', nargs='+', metavar='remote',
-        help='source(s) and destination (all with : prefix)')
+        type=_normalize_path_arg, help='source(s) and destination (all with : prefix)')
     def _dispatch_mv(self, commands, is_last_group):
         args = _make_parser(self._dispatch_mv).parse_args(commands)
         commands.clear()
@@ -1177,7 +1180,7 @@ class MpyTool():
         help='compile .py to .mpy on-the-fly')
     @option('-w', '--writable', action='store_true', help='mount as writable')
     @argument('paths', nargs='*', metavar='local_and_remote',
-        help='local_dir [:mount_point] (default: /remote)')
+        type=_normalize_path_arg, help='local_dir [:mount_point] (default: /remote)')
     def _dispatch_mount(self, commands, is_last_group):
         if not commands:
             self._list_mounts()
@@ -1219,7 +1222,7 @@ class MpyTool():
 
     @command('ln', 'Link local file/directory into mounted VFS.')
     @argument('paths', nargs='+', metavar='local_and_remote',
-        help='local source(s) and device destination')
+        type=_normalize_path_arg, help='local source(s) and device destination')
     def _dispatch_ln(self, commands, is_last_group):
         args = _make_parser(self._dispatch_ln).parse_args(commands)
         commands.clear()
@@ -1525,7 +1528,7 @@ def main():
     log = SimpleColorLogger(args.debug + 1, verbose_level=args.verbose)
     if args.port and args.address:
         log.error("You can select only serial port or network address")
-        return
+        _sys.exit(1)
     # Determine compression setting: None=auto, True=force, False=disable
     compress = None
     if args.no_compress:
@@ -1543,9 +1546,11 @@ def main():
         _run_commands(mpy_tool, command_groups, with_progress=with_progress)
     except (_mpytool.MpyError, _mpytool.ConnError, _mpytool.Timeout) as err:
         log.error(err)
+        _sys.exit(1)
     except KeyboardInterrupt:
         # Clear partial progress line and show clean message
         log.verbose('Interrupted', level=0, overwrite=True)
+        _sys.exit(130)  # 128 + SIGINT(2)
 
 
 if __name__ == '__main__':

mpytool-2.3.2/mpytool/utils.py

@@ -0,0 +1,136 @@
+"""Utility functions for mpytool"""
+
+import sys as _sys
+
+from serial.tools.list_ports import comports as _comports
+
+
+# Known USB Vendor IDs for MicroPython devices
+# Native USB-CDC (direct USB connection to microcontroller)
+VID_RASPBERRY_PI = 0x2E8A  # RP2040/RP2350 (Pico)
+VID_ESPRESSIF = 0x303A     # ESP32-S2/S3/C3/C6 USB-JTAG-Serial
+VID_MICROPYTHON = 0xF055   # Official MicroPython (pyboard, STM32)
+
+# USB-UART bridge chips (external USB-to-serial converter)
+VID_SILICON_LABS = 0x10C4  # CP210x
+VID_QINHENG = 0x1A86       # CH340/CH341
+VID_FTDI = 0x0403          # FT232/FT2232
+VID_PROLIFIC = 0x067B      # PL2303
+
+# Priority groups for port sorting (lower = higher priority)
+_MICROPYTHON_VIDS = {VID_RASPBERRY_PI, VID_ESPRESSIF, VID_MICROPYTHON}
+_USB_UART_VIDS = {VID_SILICON_LABS, VID_QINHENG, VID_FTDI, VID_PROLIFIC}
+
+
+def is_remote_path(path: str) -> bool:
+    """Check if path is remote (starts with :)"""
+    return path.startswith(":")
+
+
+def parse_remote_path(path: str) -> str:
+    """Parse remote path, strip leading :
+
+    Args:
+        path: path with : prefix
+
+    Returns:
+        path without : prefix (empty string for ':' means CWD)
+    """
+    if not is_remote_path(path):
+        raise ValueError(f"Not a remote path: {path}")
+    return path[1:]
+
+
+def split_commands(args: list[str], separator: str = "--") -> list[list[str]]:
+    """Split command arguments by separator
+
+    Args:
+        args: list of arguments
+        separator: separator string (default: --)
+
+    Returns:
+        list of command groups
+
+    Example:
+        split_commands(["cp", "a", ":/", "--", "reset"])
+        => [["cp", "a", ":/"], ["reset"]]
+    """
+    if separator not in args:
+        return [args] if args else []
+
+    groups = []
+    current = []
+    for arg in args:
+        if arg == separator:
+            if current:
+                groups.append(current)
+                current = []
+        else:
+            current.append(arg)
+    if current:
+        groups.append(current)
+    return groups
+
+
+def format_size(size):
+    """Format size in bytes to human readable format (like ls -h)"""
+    if size < 1024:
+        return f"{int(size)}B"
+    for unit in ('K', 'M', 'G', 'T'):
+        size /= 1024
+        if size < 10:
+            return f"{size:.2f}{unit}"
+        if size < 100:
+            return f"{size:.1f}{unit}"
+        if size < 1024 or unit == 'T':
+            return f"{size:.0f}{unit}"
+    return f"{size:.0f}T"
+
+
+def _port_sort_key(port_info):
+    """Sort key for serial ports - prioritize known MicroPython VIDs"""
+    vid = port_info.vid
+    if vid is None:
+        return (3, port_info.device)  # Unknown - lowest priority
+    if vid in _MICROPYTHON_VIDS:
+        return (0, port_info.device)  # Native MicroPython USB - highest
+    if vid in _USB_UART_VIDS:
+        return (1, port_info.device)  # USB-UART bridges - second
+    return (2, port_info.device)      # Other USB devices - third
+
+
+def detect_serial_ports() -> list[str]:
+    """Detect available serial ports for MicroPython devices
+
+    Returns:
+        list of port paths sorted by likelihood of being MicroPython device
+        (known MicroPython VIDs first, then USB-UART bridges, then others)
+    """
+    ports = []
+    for p in _comports():
+        # Skip non-USB devices (Bluetooth, debug console, etc.)
+        if p.vid is None:
+            continue
+        # macOS: prefer cu.* over tty.* (doesn't wait for DCD signal)
+        if _sys.platform == "darwin" and p.device.startswith("/dev/tty."):
+            continue
+        ports.append(p)
+    # Sort by priority (known MicroPython VIDs first)
+    ports.sort(key=_port_sort_key)
+    return [p.device for p in ports]
+
+
+def get_port_info(port: str):
+    """Get USB info for a serial port
+
+    Args:
+        port: port path (e.g. /dev/ttyACM0, COM3)
+
+    Returns:
+        ListPortInfo object with vid, pid, manufacturer, product, etc.
+        or None if port not found
+    """
+    for p in _comports():
+        if p.device == port:
+            return p
+    return None

{mpytool-2.3.1 → mpytool-2.3.2}/mpytool.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.3.1
+Version: 2.3.2
 Summary: MPY tool - manage files on devices running MicroPython
 Author-email: Pavel Revak <pavel.revak@gmail.com>
 License-Expression: MIT
@@ -692,6 +692,38 @@ exec bash
 - Support for `--` command separator
 - Works with both relative and absolute paths
 
+## Development
+
+### Running tests
+
+```bash
+# Unit tests (no device needed)
+python -m unittest discover tests/ -v
+
+# Read-only integration tests (safe on production device)
+MPYTOOL_TEST_PORT=/dev/ttyACM0 python -m unittest tests.test_integration -v
+
+# All integration tests (dedicated test device)
+MPYTOOL_TEST_PORT_RW=/dev/ttyACM0 python -m unittest tests.test_integration -v
+
+# CLI tests (no device needed for basic tests)
+python -m unittest tests.test_cli -v
+
+# All CLI tests with device
+MPYTOOL_TEST_PORT_RW=/dev/ttyACM0 python -m unittest tests.test_cli -v
+```
+
+Test categories:
+- **Unit tests** (`test_*.py` except `test_integration.py`, `test_cli.py`) - no device needed
+- **Read-only tests** (`MPYTOOL_TEST_PORT`) - safe on any device, no filesystem changes
+- **All tests** (`MPYTOOL_TEST_PORT_RW`) - includes write and flash operations, use dedicated test device
+
+### Install from source
+
+```bash
+pip install -e .
+```
+
 ## Requirements
 
 Working only with MicroPython boards, not with CircuitPython

{mpytool-2.3.1 → mpytool-2.3.2}/mpytool.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ mpytool.egg-info/dependency_links.txt
 mpytool.egg-info/entry_points.txt
 mpytool.egg-info/requires.txt
 mpytool.egg-info/top_level.txt
+tests/test_cli.py
 tests/test_cmd_cp.py
 tests/test_errors.py
 tests/test_integration.py

{mpytool-2.3.1 → mpytool-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mpytool"
-version = "2.3.1"
+version = "2.3.2"
 description = "MPY tool - manage files on devices running MicroPython"
 readme = "README.md"
 license = "MIT"