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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-handler
-Version: 1.2.0
+Version: 1.4.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,67 @@ 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 / SSH (port on a *remote* machine)
+`pyserial` only opens a *local* port, so when the serial port is on a remote
+machine, stream it **over SSH** with `serial_stream()` — same live match + save.
+It auto-detects the OS from the device name: `COM*` → Windows (PowerShell
+SerialPort reader), `/dev/tty*` → Linux (`stty` + `cat`).
+
+**Windows COM port on the remote machine** (connect SSH straight to that machine
+— it has sshd from `ssh-handler-setup`):
+
+```python
+cfg = SSHConfig(host="10.232.9.22", domain="CORP", username="myuser",
+                password="pw", host_key_policy="ignore")
+with SSHHandler(cfg, quiet=True) as ssh:
+    ssh.serial_write("COM5", "version", baudrate=115200)      # write a line
+    ssh.serial_stream("COM5", baudrate=115200,                # read it live
+                      on_line=print, match=r"login:|ERROR",
+                      save_to="com5.log", timeout=120)
+```
+
+**Linux device file on a target reached through the jump:**
+
+```python
+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_stream("/dev/ttyUSB0", baudrate=115200,
+                      on_line=print, match=r"login:", save_to="ttyusb0.log")
+```
+
+> Note: on Windows a COM port can't be shared — don't run `serial_write` while a
+> `serial_stream` on the same port is open (`serial_write` opens/writes/closes).
+> If the port is on **your own laptop**, use the local `SerialHandler("COM5")`
+> above instead — no SSH needed.
+
+## 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