mpytool 2.3.3__tar.gz → 2.3.4__tar.gz

{mpytool-2.3.3/mpytool.egg-info → mpytool-2.3.4}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.3.3
+Version: 2.3.4
 Summary: MPY tool - manage files on devices running MicroPython
-Author-email: Pavel Revak <pavel.revak@gmail.com>
+Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/pavelrevak/mpytool
+Project-URL: Homepage, https://github.com/cortexm/mpytool
 Keywords: MPY,micropython
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -55,7 +55,7 @@ pip3 install mpytool
 ### Installation from git (latest development version)
 
 ```bash
-pip3 install git+https://github.com/pavelrevak/mpytool.git
+pip3 install git+https://github.com/cortexm/mpytool.git
 ```
 
 ### Installation in virtualenv
@@ -254,7 +254,11 @@ RESET soft
 $ mpytool reset --machine    # MCU reset (machine.reset, auto-reconnect)
 RESET machine
 
-$ mpytool reset -- monitor   # reset and monitor output
+$ mpytool reset -- monitor   # reset and monitor until program ends
+RESET soft
+MONITOR (until program ends, -f to follow)
+
+$ mpytool reset -- monitor -f  # reset and monitor continuously
 RESET soft
 MONITOR (Ctrl+C to stop)
 
@@ -275,7 +279,8 @@ 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
+$ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor until program ends
+$ mpytool monitor -f                        # follow output continuously (Ctrl-C to stop)
 ```
 
 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.
@@ -284,24 +289,30 @@ Both `repl` and `monitor` can be used as general-purpose serial tools - not just
 
 ### Execute Python code on device
 ```
-$ mpytool exec "print('Hello!')"
+$ mpytool exec "print('Hello!')"         # execute and stream output
 EXEC: print('Hello!')
 Hello!
 
 $ mpytool exec "import sys; print(sys.version)"
 EXEC: import sys; print(sys.version)
 3.4.0; MicroPython v1.24.0
+
+$ mpytool exec "long_task()" -t 30       # timeout after 30 seconds
+$ mpytool exec "start_server()" -t 0     # fire-and-forget (don't wait)
 ```
 
 ### Run local Python file on device
 ```
-$ mpytool run script.py                  # run script (fire-and-forget)
+$ mpytool run script.py                  # run and stream output
+RUN: script.py (128 bytes)
+Hello from script!
+
+$ mpytool run script.py -t 0             # fire-and-forget (don't wait)
 RUN: script.py (128 bytes)
 
-$ mpytool run script.py -- monitor       # run script and capture output
+$ mpytool run script.py -t 10            # timeout after 10 seconds
 RUN: script.py (128 bytes)
-MONITOR (Ctrl+C to stop)
-Hello from script!
+Done!
 ```
 
 ### Edit file on device
@@ -650,7 +661,7 @@ autoload -Uz compinit && compinit
 **Quick install (or update):**
 ```bash
 mkdir -p ~/.zsh/completions
-curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/_mpytool -o ~/.zsh/completions/_mpytool
+curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/_mpytool -o ~/.zsh/completions/_mpytool
 grep -q '\.zsh/completions' ~/.zshrc || echo 'fpath=(~/.zsh/completions $fpath); autoload -Uz compinit && compinit' >> ~/.zshrc
 exec zsh
 ```
@@ -671,17 +682,17 @@ source ~/.mpytool-completion.bash
 
 **Quick install (Linux system-wide):**
 ```bash
-sudo curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/mpytool.bash -o /etc/bash_completion.d/mpytool && exec bash
+sudo curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/mpytool.bash -o /etc/bash_completion.d/mpytool && exec bash
 ```
 
 **Quick install (macOS Homebrew):**
 ```bash
-curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/mpytool.bash -o /usr/local/etc/bash_completion.d/mpytool && exec bash
+curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/mpytool.bash -o /usr/local/etc/bash_completion.d/mpytool && exec bash
 ```
 
 **Quick install (user directory):**
 ```bash
-curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/mpytool.bash -o ~/.mpytool-completion.bash
+curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/mpytool.bash -o ~/.mpytool-completion.bash
 grep -q 'mpytool-completion' ~/.bashrc || echo 'source ~/.mpytool-completion.bash' >> ~/.bashrc
 exec bash
 ```
@@ -757,4 +768,4 @@ MIT
 ### Support
 
 - Basic support is free over GitHub issues.
-- Professional support is available over email: [Pavel Revak](mailto:pavel.revak@gmail.com?subject=[GitHub]%20mpytool).
+- Professional support is available over email: [Pavel Revak](mailto:pavelrevak@gmail.com?subject=[GitHub]%20mpytool).

mpytool-2.3.3/PKG-INFO → mpytool-2.3.4/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: mpytool
-Version: 2.3.3
-Summary: MPY tool - manage files on devices running MicroPython
-Author-email: Pavel Revak <pavel.revak@gmail.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/pavelrevak/mpytool
-Keywords: MPY,micropython
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyserial>=3.0
-Dynamic: license-file
-
 # mpytool
 
 MPY tool - manage files on devices running MicroPython
@@ -55,7 +41,7 @@ pip3 install mpytool
 ### Installation from git (latest development version)
 
 ```bash
-pip3 install git+https://github.com/pavelrevak/mpytool.git
+pip3 install git+https://github.com/cortexm/mpytool.git
 ```
 
 ### Installation in virtualenv
@@ -254,7 +240,11 @@ RESET soft
 $ mpytool reset --machine    # MCU reset (machine.reset, auto-reconnect)
 RESET machine
 
-$ mpytool reset -- monitor   # reset and monitor output
+$ mpytool reset -- monitor   # reset and monitor until program ends
+RESET soft
+MONITOR (until program ends, -f to follow)
+
+$ mpytool reset -- monitor -f  # reset and monitor continuously
 RESET soft
 MONITOR (Ctrl+C to stop)
 
@@ -275,7 +265,8 @@ 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
+$ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor until program ends
+$ mpytool monitor -f                        # follow output continuously (Ctrl-C to stop)
 ```
 
 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.
@@ -284,24 +275,30 @@ Both `repl` and `monitor` can be used as general-purpose serial tools - not just
 
 ### Execute Python code on device
 ```
-$ mpytool exec "print('Hello!')"
+$ mpytool exec "print('Hello!')"         # execute and stream output
 EXEC: print('Hello!')
 Hello!
 
 $ mpytool exec "import sys; print(sys.version)"
 EXEC: import sys; print(sys.version)
 3.4.0; MicroPython v1.24.0
+
+$ mpytool exec "long_task()" -t 30       # timeout after 30 seconds
+$ mpytool exec "start_server()" -t 0     # fire-and-forget (don't wait)
 ```
 
 ### Run local Python file on device
 ```
-$ mpytool run script.py                  # run script (fire-and-forget)
+$ mpytool run script.py                  # run and stream output
 RUN: script.py (128 bytes)
+Hello from script!
 
-$ mpytool run script.py -- monitor       # run script and capture output
+$ mpytool run script.py -t 0             # fire-and-forget (don't wait)
 RUN: script.py (128 bytes)
-MONITOR (Ctrl+C to stop)
-Hello from script!
+
+$ mpytool run script.py -t 10            # timeout after 10 seconds
+RUN: script.py (128 bytes)
+Done!
 ```
 
 ### Edit file on device
@@ -650,7 +647,7 @@ autoload -Uz compinit && compinit
 **Quick install (or update):**
 ```bash
 mkdir -p ~/.zsh/completions
-curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/_mpytool -o ~/.zsh/completions/_mpytool
+curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/_mpytool -o ~/.zsh/completions/_mpytool
 grep -q '\.zsh/completions' ~/.zshrc || echo 'fpath=(~/.zsh/completions $fpath); autoload -Uz compinit && compinit' >> ~/.zshrc
 exec zsh
 ```
@@ -671,17 +668,17 @@ source ~/.mpytool-completion.bash
 
 **Quick install (Linux system-wide):**
 ```bash
-sudo curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/mpytool.bash -o /etc/bash_completion.d/mpytool && exec bash
+sudo curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/mpytool.bash -o /etc/bash_completion.d/mpytool && exec bash
 ```
 
 **Quick install (macOS Homebrew):**
 ```bash
-curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/mpytool.bash -o /usr/local/etc/bash_completion.d/mpytool && exec bash
+curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/mpytool.bash -o /usr/local/etc/bash_completion.d/mpytool && exec bash
 ```
 
 **Quick install (user directory):**
 ```bash
-curl -fsSL https://raw.githubusercontent.com/pavelrevak/mpytool/main/completions/mpytool.bash -o ~/.mpytool-completion.bash
+curl -fsSL https://raw.githubusercontent.com/cortexm/mpytool/main/completions/mpytool.bash -o ~/.mpytool-completion.bash
 grep -q 'mpytool-completion' ~/.bashrc || echo 'source ~/.mpytool-completion.bash' >> ~/.bashrc
 exec bash
 ```
@@ -757,4 +754,4 @@ MIT
 ### Support
 
 - Basic support is free over GitHub issues.
-- Professional support is available over email: [Pavel Revak](mailto:pavel.revak@gmail.com?subject=[GitHub]%20mpytool).
+- Professional support is available over email: [Pavel Revak](mailto:pavelrevak@gmail.com?subject=[GitHub]%20mpytool).

{mpytool-2.3.3 → mpytool-2.3.4}/mpytool/__init__.py

@@ -3,6 +3,6 @@
 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_comm import MpyComm, MpyError, CmdError
 from mpytool.mpy import Mpy, PathNotFound, FileNotFound, DirNotFound
 from mpytool.logger import SimpleColorLogger

{mpytool-2.3.3 → mpytool-2.3.4}/mpytool/conn_serial.py

@@ -22,14 +22,11 @@ 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
+        # Debug info about port
         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)
+            desc = _utils._port_description(self._port_info)
+            self._log.info("Connected to %s [%s]", port, desc)
         else:
             self._log.info("Connected to %s [unknown serial port]", port)
 

{mpytool-2.3.3 → mpytool-2.3.4}/mpytool/mount.py

@@ -179,7 +179,7 @@ CMD_MAX = CMD_READLINE
 _ESCAPE_BYTE = bytes([ESCAPE])
 
 _SOFT_REBOOT = b'soft reboot'
-_REPL_PROMPT = b'>>> '
+from mpytool.mpy_comm import REPL_PROMPT as _REPL_PROMPT
 _REBOOT_BUF_MAX = 256
 _REBOOT_BUF_KEEP = 64
 _LISTDIR_LIMIT = 1000  # max entries returned by CMD_LISTDIR

{mpytool-2.3.3 → mpytool-2.3.4}/mpytool/mpy_comm.py

@@ -1,5 +1,6 @@
 """MicroPython tool: MPY communication"""
 
+import io as _io
 import re as _re
 import time as _time
 
@@ -13,6 +14,10 @@ CTRL_C = b'\x03'  # Interrupt
 CTRL_D = b'\x04'  # Execute / Soft reset / End raw-paste
 CTRL_E = b'\x05'  # Paste mode
 
+# REPL prompt
+REPL_PROMPT = b'>>> '
+REPL_PROMPT_LINE = b'\r\n' + REPL_PROMPT
+
 # Raw-paste mode
 RAW_PASTE_ENTER = CTRL_E + b'A' + CTRL_A  # Enter raw-paste mode sequence
 RAW_PASTE_ACK = b'\x01'  # Flow control ACK
@@ -121,7 +126,7 @@ class MpyComm():
             if attempt >= 4:
                 self._conn.write(b'\x18')
             try:
-                self._conn.read_until(b'\r\n>>> ', timeout=0.2)
+                self._conn.read_until(REPL_PROMPT_LINE, timeout=0.2)
                 self._repl_mode = False
                 return True
             except _conn.Timeout:
@@ -149,7 +154,7 @@ class MpyComm():
             return
         self._log.info('EXIT RAW REPL')
         self._conn.write(CTRL_B)
-        self._conn.read_until(b'\r\n>>> ')
+        self._conn.read_until(REPL_PROMPT_LINE)
         self._repl_mode = False
 
     def soft_reset(self):
@@ -176,16 +181,64 @@ class MpyComm():
         self._repl_mode = None
         self._raw_paste_supported = None
 
-    def exec(self, command, timeout=None):
+    def monitor(self, stream=False, follow=False):
+        """Monitor device output in normal REPL mode.
+
+        Reads device output until REPL prompt (>>>) is detected,
+        or indefinitely if follow=True.
+
+        Arguments:
+            stream: False = return bytes, True = yield chunks,
+                file-like object = write chunks to it and return b''
+            follow: if True, don't stop at REPL prompt
+
+        Returns:
+            bytes result, generator, or b'' (when stream is file-like)
+        """
+        self.exit_raw_repl()
+        if stream is True:
+            return self._monitor_chunks(follow)
+        if stream:
+            return self._monitor_to(stream, follow)
+        return b''.join(self._monitor_chunks(follow))
+
+    def _monitor_chunks(self, follow):
+        """Yield output chunks until REPL prompt (or forever if follow)."""
+        prompt_len = len(REPL_PROMPT_LINE)
+        tail = b''
+        while True:
+            data = self._conn.read(timeout=0.1)
+            if data is None:
+                continue
+            yield data
+            if not follow:
+                # Keep enough bytes so prompt split across chunks is found
+                tail = tail[-(prompt_len - 1):] + data
+                if REPL_PROMPT_LINE in tail:
+                    return
+
+    def _monitor_to(self, out, follow):
+        """Write monitor output to file-like object."""
+        text_mode = isinstance(out, _io.TextIOBase)
+        for chunk in self._monitor_chunks(follow):
+            out.write(
+                chunk.decode('utf-8', 'backslashreplace')
+                if text_mode else chunk)
+            out.flush()
+        return b''
+
+    def exec(self, command, timeout=None, stream=False):
         """Execute command
 
         Arguments:
             command: command to execute
             timeout: maximum waiting time for result (None = wait forever),
                 0 = submit only (send code, don't wait for output)
+            stream: False = return bytes, True = yield chunks,
+                file-like object = write chunks to it and return b''
 
         Returns:
-            command STDOUT result
+            bytes result, generator, or b'' (when stream is file-like)
 
         Raises:
             CmdError when command return error
@@ -199,6 +252,10 @@ class MpyComm():
         if timeout == 0:
             self._repl_mode = False
             return b''
+        if stream is True:
+            return self._exec_stream_result(command, timeout)
+        if stream:
+            return self._exec_stream_to(command, timeout, stream)
         result = self._conn.read_until(CTRL_D, timeout)
         if result:
             self._log.info('RES: %s', bytes(result))
@@ -280,6 +337,65 @@ class MpyComm():
             if byte == CTRL_D:
                 break
 
+    def _read_stdout_chunks(self, timeout):
+        """Read stdout chunks until CTRL_D marker.
+
+        Yields (chunk, is_last) tuples. Timeout is total wall time.
+        """
+        start_time = _time.time()
+        while True:
+            if timeout is not None:
+                remaining = timeout - (_time.time() - start_time)
+                if remaining <= 0:
+                    raise _conn.Timeout("Execution timeout")
+            self._conn._read_to_buffer(wait_timeout=0.001)
+            idx = self._conn._buffer.find(CTRL_D)
+            if idx != -1:
+                chunk = bytes(self._conn._buffer[:idx])
+                del self._conn._buffer[:idx + len(CTRL_D)]
+                if chunk:
+                    yield chunk
+                return
+            if self._conn._buffer:
+                yield bytes(self._conn._buffer)
+                self._conn._buffer.clear()
+
+    def _check_stderr(self, command, result, timeout, start_time):
+        """Read stderr and raise CmdError if non-empty."""
+        if result:
+            self._log.info('RES: %s', bytes(result))
+        err_timeout = 5 if timeout is None else max(
+            1, timeout - (_time.time() - start_time))
+        err = self._conn.read_until(CTRL_D + b'>', err_timeout)
+        if err:
+            raise CmdError(command, bytes(result), err)
+
+    def _exec_stream_result(self, command, timeout):
+        """Read execution result as streaming generator."""
+        start_time = _time.time()
+        result = bytearray()
+        for chunk in self._read_stdout_chunks(timeout):
+            result.extend(chunk)
+            yield chunk
+        self._check_stderr(command, result, timeout, start_time)
+
+    def _exec_stream_to(self, command, timeout, out):
+        """Read execution result, writing chunks to file-like object.
+
+        Supports both binary and text streams (io.TextIOBase).
+        """
+        start_time = _time.time()
+        result = bytearray()
+        text_mode = isinstance(out, _io.TextIOBase)
+        for chunk in self._read_stdout_chunks(timeout):
+            result.extend(chunk)
+            out.write(
+                chunk.decode('utf-8', 'backslashreplace')
+                if text_mode else chunk)
+            out.flush()
+        self._check_stderr(command, result, timeout, start_time)
+        return b''
+
     def _read_execution_result(self, command, timeout):
         """Read and parse execution result."""
         result = self._conn.read_until(CTRL_D, timeout)
@@ -290,15 +406,17 @@ class MpyComm():
             raise CmdError(command.decode('utf-8', errors='replace'), result, err)
         return result
 
-    def exec_raw_paste(self, command, timeout=5):
+    def exec_raw_paste(self, command, timeout=5, stream=False):
         """Execute code via raw-paste mode (flow-controlled, less RAM).
 
         Arguments:
             command: code to execute (str or bytes)
             timeout: max wait time (0 = submit only, don't wait for output)
+            stream: False = return bytes, True = yield chunks,
+                file-like object = write chunks to it and return b''
 
         Returns:
-            command STDOUT result
+            bytes result, generator, or b'' (when stream is file-like)
 
         Raises:
             CmdError: command execution error
@@ -338,26 +456,32 @@ class MpyComm():
             self._repl_mode = False
             return b''
 
+        if stream is True:
+            return self._exec_stream_result(command, timeout)
+        if stream:
+            return self._exec_stream_to(command, timeout, stream)
         return self._read_execution_result(command, timeout)
 
-    def try_raw_paste(self, command, timeout=5):
+    def try_raw_paste(self, command, timeout=5, stream=False):
         """Try raw-paste mode, fall back to regular exec if not supported.
 
         Arguments:
             command: command to execute
             timeout: maximum waiting time for result
+            stream: False = return bytes, True = yield chunks,
+                file-like object = write chunks to it and return b''
 
         Returns:
-            command STDOUT result
+            bytes result, generator, or b'' (when stream is file-like)
         """
         # If we know raw-paste is not supported, skip it
         if self._raw_paste_supported is False:
-            return self.exec(command, timeout)
+            return self.exec(command, timeout, stream=stream)
 
         try:
-            return self.exec_raw_paste(command, timeout)
+            return self.exec_raw_paste(command, timeout, stream=stream)
         except MpyError as e:
             if "not supported" in str(e):
                 self._log.info("Raw-paste not supported, using regular exec")
-                return self.exec(command, timeout)
+                return self.exec(command, timeout, stream=stream)
             raise