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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-handler
-Version: 1.1.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
@@ -14,22 +14,14 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: paramiko>=3.0
-Provides-Extra: secure
-Requires-Dist: keyring>=23.0; extra == "secure"
-Provides-Extra: scp
-Requires-Dist: scp>=0.14; extra == "scp"
+Requires-Dist: scp>=0.14
+Requires-Dist: pyserial>=3.5
+Requires-Dist: keyring>=23.0
+Requires-Dist: pywinrm>=0.4.3
 Provides-Extra: gui
 Requires-Dist: PyQt5>=5.15; extra == "gui"
-Provides-Extra: winrm
-Requires-Dist: pywinrm>=0.4.3; extra == "winrm"
-Provides-Extra: serial
-Requires-Dist: pyserial>=3.5; extra == "serial"
 Provides-Extra: all
-Requires-Dist: keyring>=23.0; extra == "all"
-Requires-Dist: scp>=0.14; extra == "all"
 Requires-Dist: PyQt5>=5.15; extra == "all"
-Requires-Dist: pywinrm>=0.4.3; extra == "all"
-Requires-Dist: pyserial>=3.5; extra == "all"
 Dynamic: license-file
 
 # ssh-handler
@@ -89,15 +81,17 @@ behind one object that:
 ## Install
 
 ```bash
-pip install ssh-handler                 # core (paramiko only)
-pip install "ssh-handler[secure]"       # + keyring  (OS credential vault)
-pip install "ssh-handler[scp]"          # + scp      (SCP-protocol transfers)
-pip install "ssh-handler[gui]"          # + PyQt5    (the GUI worker)
-pip install "ssh-handler[all]"          # everything
+pip install ssh-handler           # everything: SSH, SFTP, SCP, FTP, serial,
+                                  # credential vault, WinRM bootstrap
+pip install "ssh-handler[gui]"    # also installs PyQt5 for the GUI worker
 ```
 
-`scp`, `keyring`, and `PyQt5` are optional — the core works without them, and
-those features raise a clear, actionable message if you use them without the extra.
+**Batteries included.** A plain `pip install ssh-handler` pulls in `paramiko`,
+`scp`, `pyserial`, `keyring`, and `pywinrm`, so SSH, SFTP/SCP/FTP transfers,
+serial/COM ports, confidential credential storage, and the WinRM bootstrap all
+work out of the box. Only **PyQt5** is optional (`[gui]`), because it's a large
+GUI toolkit you only need when building a GUI — forcing it would bloat headless
+and CI installs.
 
 ## Quick start
 
@@ -137,7 +131,7 @@ with SSHHandler(SSHConfig(host="10.0.0.5", username="root", password="pw")) as s
   with **live regex matching**, a per-line/per-match callback, and **tee to a
   local file**, all built in.
 
-**Serial / COM ports** (`SerialHandler`, needs the `serial` extra)
+**Serial / COM ports** (`SerialHandler`, included by default)
 - `list_serial_ports()`, `open`/`close`, `write` / `write_line`.
 - `iter_lines()` and `stream(...)` — same live streaming + match + save-to-file
   model as SSH, for device consoles.
@@ -298,8 +292,57 @@ To stop a stream from another thread (e.g. a GUI Stop button), pass a
 
 ## Serial / COM ports
 
-Same streaming + match + save model for device serial consoles (needs
-`pip install "ssh-handler[serial]"`).
+Same streaming + match + save model for device serial consoles (included by
+default — no extra install).
+
+### 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