ssh-handler 1.2.0__tar.gz → 1.3.0__tar.gz

{ssh_handler-1.2.0 → ssh_handler-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-handler
-Version: 1.2.0
+Version: 1.3.0
 Summary: Extensive SSH/SFTP/SCP/FTP handler built on Paramiko, for test automation, CLIs and PyQt5 tools.
 Author: ssh-handler contributors
 License-Expression: MIT
@@ -295,11 +295,54 @@ To stop a stream from another thread (e.g. a GUI Stop button), pass a
 Same streaming + match + save model for device serial consoles (included by
 default — no extra install).
 
-> **Important — where the COM port physically is.** `pyserial` opens a *local*
-> port, so this runs on the machine the device is **plugged into**. If the device
-> is on your laptop, run it on your laptop. If it's on the remote/RDP machine,
-> either run the script there, or — on Linux targets — stream the device file
-> over SSH instead: `ssh.stream("cat /dev/ttyUSB0", match=..., save_to=...)`.
+### Local serial (device plugged into the machine running the code)
+```python
+from ssh_handler import SerialHandler, list_serial_ports
+print(list_serial_ports())
+with SerialHandler("COM5", baudrate=115200, quiet=True) as ser:
+    ser.write_line("version")
+    ser.stream(on_line=print, match=r"login:", stop_on_match=True, save_to="console.log")
+```
+
+### Serial via RDP / jump host (device on the remote target)
+`pyserial` only opens a *local* port, so when the serial cable is on the remote
+box (reached through your RDP jump), stream it **over SSH** with `serial_stream()`
+— same live match + save, routed through the jump:
+
+```python
+rdp_box = SSHConfig(host="10.232.9.22", domain="CORP", username="myuser", password="pw")
+target  = SSHConfig(host="10.120.1.91", username="root", password="pw",
+                    jump_host=rdp_box, host_key_policy="ignore")
+
+with SSHHandler(target, quiet=True) as ssh:
+    ssh.serial_write("/dev/ttyUSB0", "version")          # write to the device
+    ssh.serial_stream("/dev/ttyUSB0", baudrate=115200,   # read it live
+                      on_line=print, match=r"login:|ERROR",
+                      save_to="device_console.log", timeout=120)
+```
+
+`serial_stream()` sets the line speed with `stty` then streams the device — for
+**Linux targets**. (Windows COM ports on the remote side need a remote helper;
+ask if you need that.)
+
+## File transfer (SFTP / SCP / FTP) via RDP
+
+**SFTP and SCP already work through the jump host** — no special setup. Once you
+pass `jump_host=`, every transfer runs over that tunnel (laptop → RDP → target):
+
+```python
+with SSHHandler(target, quiet=True) as ssh:        # target has jump_host=rdp_box
+    ssh.push("firmware.bin", "/tmp/firmware.bin")  # SFTP, through the jump
+    ssh.pull("/var/log/messages", "messages.log")  # SFTP, through the jump
+    ssh.scp_push("img.tar", "/tmp/img.tar")        # SCP, through the jump
+    print(ssh.read_text("/etc/os-release"))
+```
+
+**FTP via RDP:** FTP is a separate protocol (its data channel can't ride an SSH
+tunnel cleanly), so prefer **SFTP through the jump** as shown above — it does the
+same job better and is already routed via RDP. If you specifically need a real
+FTP *server* on the target, run `FTPHandler` on the RDP machine itself (where it
+can reach that server directly).
 
 ```python
 from ssh_handler import SerialHandler, list_serial_ports