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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-handler
-Version: 1.0.9
+Version: 1.2.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,19 +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: 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"
 Dynamic: license-file
 
 # ssh-handler
@@ -86,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
 
@@ -127,6 +124,18 @@ with SSHHandler(SSHConfig(host="10.0.0.5", username="root", password="pw")) as s
 - `open_shell()` — a persistent interactive `ShellSession` with `send` /
   `read_until` (send-expect) / `read_available`.
 
+**Continuous / streaming output (logs)**
+- `iter_lines(cmd)` — generator yielding a never-ending command's output **line
+  by line, live** (`slog2info -w`, `tail -f`, `journalctl -f`, `dmesg -w`).
+- `stream(cmd, on_line=, match=, save_to=, stop_on_match=, stop_event=)` — stream
+  with **live regex matching**, a per-line/per-match callback, and **tee to a
+  local file**, all built in.
+
+**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.
+
 **File operations (SFTP) — full Paramiko parity**
 - Transfers: `push` / `pull` (single file **or** recursive directory, with progress
   callbacks and transfer statistics), plus `scp_push` / `scp_pull` (SCP protocol).
@@ -247,6 +256,71 @@ When a connection just fails, the error now self-diagnoses — it probes the SSH
 RDP ports and tells you *why* (e.g. "Port 22 is closed but RDP (3389) is open … no
 SSH server listening"). Call `ssh.diagnose()` for a pre-flight reachability check.
 
+## Continuous logs & live pattern matching
+
+Stream a long-running remote command and react to lines as they arrive — match a
+pattern, save to a file, or stop when something appears. Works through the jump
+host too.
+
+```python
+from ssh_handler import SSHHandler, SSHConfig
+
+with SSHHandler(SSHConfig(host="10.120.1.91", username="root", password="pw",
+                          jump_host=rdp_box), quiet=True) as ssh:
+
+    # (a) simplest: iterate lines live
+    for line in ssh.iter_lines("slog2info -w"):
+        print(line)
+        if "FATAL" in line:
+            break
+
+    # (b) full: match + tee to a local file + callback, stop on a pattern
+    result = ssh.stream(
+        "tail -f /var/log/messages",
+        on_line=print,                 # called for every line
+        match=r"error|fail",           # regex; matching lines collected
+        on_match=lambda l: print("HIT:", l),
+        save_to="device.log",          # tee every line to this local file
+        stop_on_match=False,           # set True to stop at the first match
+        timeout=60,                    # optional overall time limit
+    )
+    print(result["lines"], "lines,", len(result["matches"]), "matched")
+```
+
+To stop a stream from another thread (e.g. a GUI Stop button), pass a
+`threading.Event` as `stop_event=` and `.set()` it.
+
+## Serial / COM ports
+
+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=...)`.
+
+```python
+from ssh_handler import SerialHandler, list_serial_ports
+
+print(list_serial_ports())            # [{'device':'COM5','description':...}, ...]
+
+with SerialHandler("COM5", baudrate=115200, quiet=True) as ser:
+    ser.write_line("version")                       # send a command
+    res = ser.stream(
+        on_line=print,
+        match=r"login:",                            # wait for the login prompt
+        stop_on_match=True,
+        save_to="serial_console.log",               # tee to file
+        timeout=120,
+    )
+    print("matched:", res["matched"])
+```
+
+`write_line(..., eol="\r\n")` for consoles that need CRLF. Everything returns the
+same `OperationResult` in safe mode and raises `SerialError` otherwise.
+
 ## Confidential credentials
 
 | Mechanism | What it does |
@@ -306,17 +380,29 @@ Every action returns structured data, not bare strings:
 ## CLI reference
 
 ```bash
-python -m ssh_handler run   --host H --user U --domain CORP uptime
-python -m ssh_handler push  --host H --user U ./build /tmp/build --recursive
-python -m ssh_handler pull  --host H --user U /var/log ./logs --recursive
-python -m ssh_handler info  --host H --user U --json
+python -m ssh_handler run    --host H --user U --domain CORP uptime
+python -m ssh_handler push   --host H --user U ./build /tmp/build --recursive
+python -m ssh_handler pull   --host H --user U /var/log ./logs --recursive
+python -m ssh_handler info   --host H --user U --json
 python -m ssh_handler store-credential --user U --domain CORP --service my_test_lab
+
+# continuous logs over SSH, with live matching + save:
+python -m ssh_handler stream --host H --user U --match "error|fail" \
+                             --save run.log -- slog2info -w
+
+# serial / COM ports:
+python -m ssh_handler list-serial
+python -m ssh_handler serial-monitor --port COM5 --baud 115200 \
+                             --match "login:" --stop-on-match --save console.log
+
+# install OpenSSH Server on THIS Windows machine (offline, self-elevates):
+ssh-handler-setup
 ```
 
 Password options: `--password` (hidden prompt), `--use-stored` (read from the OS
 vault), `--key FILE` (private key). Add `--json` for machine-readable output.
-After `pip install`, a `ssh-handler` console script is also available
-(`ssh-handler run --host …`).
+Put `--match`/`--save` *before* the streamed command. After `pip install`, the
+`ssh-handler` and `ssh-handler-setup` console scripts are also available.
 
 ## PyQt5 integration
 
@@ -337,8 +423,22 @@ thread.started.connect(lambda: worker.run_command("uptime"))
 thread.start()
 ```
 
-Signals: `log`, `connected`, `command_done`, `transfer_done`, `progress`, `error`,
-`finished`. The import is lazy, so the rest of the package works where PyQt5 isn't installed.
+Signals: `log`, `connected`, `command_done`, `transfer_done`, `progress`,
+`stream_line`, `stream_match`, `stream_done`, `error`, `finished`. The import is
+lazy, so the rest of the package works where PyQt5 isn't installed.
+
+**Streaming logs into the GUI** — drive `start_stream` in the worker thread and
+wire the per-line signals to your widgets; `stop_stream()` ends it cleanly:
+
+```python
+worker.stream_line.connect(log_view.append)         # every live line
+worker.stream_match.connect(lambda l: alerts.append(l))   # only matching lines
+thread.started.connect(lambda: worker.start_stream("slog2info -w",
+                                                    match="error|fail",
+                                                    save_to="device.log"))
+# later, from a Stop button:
+worker.stop_stream()
+```
 
 ## Parallel fleet operations
 
@@ -372,8 +472,9 @@ with FTPHandler(FTPConfig(host="ftp.example.com", username="u",
 ssh_handler/
   config.py       SSHConfig, FTPConfig
   credentials.py  Secret, CredentialStore, mask, prompt_password
-  core.py         SSHHandler, ShellSession   (SSH + SFTP + SCP + diagnose)
+  core.py         SSHHandler, ShellSession   (SSH + SFTP + SCP + stream + diagnose)
   ftp.py          FTPHandler                 (FTP / FTPS)
+  serial_handler.py   SerialHandler, list_serial_ports   (serial / COM ports)
   winrm_bootstrap.py  enable_openssh_via_winrm   (one-time sshd enable over WinRM)
   pool.py         SSHPool                    (parallel multi-host)
   cli.py          argparse entry point       (python -m ssh_handler / ssh-handler)