ssh-handler 1.5.0__tar.gz → 1.6.0__tar.gz

{ssh_handler-1.5.0/ssh_handler.egg-info → ssh_handler-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-handler
-Version: 1.5.0
+Version: 1.6.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

{ssh_handler-1.5.0 → ssh_handler-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ssh-handler"
-version = "1.5.0"
+version = "1.6.0"
 description = "Extensive SSH/SFTP/SCP/FTP handler built on Paramiko, for test automation, CLIs and PyQt5 tools."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -36,9 +36,13 @@ all = ["PyQt5>=5.15"]
 [project.scripts]
 ssh-handler = "ssh_handler.cli:main"
 ssh-handler-setup = "ssh_handler.cli:setup_server_main"
+ssh-handler-docs = "ssh_handler.cli:open_docs"
+
+[project.gui-scripts]
+ssh-handler-gui = "ssh_handler.cli:launch_gui"
 
 [tool.setuptools]
 packages = ["ssh_handler"]
 
 [tool.setuptools.package-data]
-ssh_handler = ["*.ps1", "openssh/*.zip"]
+ssh_handler = ["*.ps1", "*.md", "openssh/*.zip", "assets/*.ico", "assets/*.png"]

ssh_handler-1.6.0/ssh_handler/README.md

@@ -0,0 +1,536 @@
+# ssh-handler
+
+[![PyPI](https://img.shields.io/pypi/v/ssh-handler.svg)](https://pypi.org/project/ssh-handler/)
+[![Python](https://img.shields.io/pypi/pyversions/ssh-handler.svg)](https://pypi.org/project/ssh-handler/)
+
+An extensive **SSH / SFTP / SCP / FTP** automation handler built on
+[Paramiko](https://www.paramiko.org/). One package, three ways to use it:
+
+- **Test-automation framework** — raise-on-error API, pytest fixtures, parallel fleet ops.
+- **Standalone CLI** — `python -m ssh_handler …`, fully argument-driven.
+- **PyQt5 tool** — safe mode + log streaming over Qt signals, runs off the GUI thread.
+
+Passwords are wrapped in a `Secret` and stored in the **OS credential vault** — they
+never appear in logs, reprs, tracebacks, or on disk in plaintext.
+
+```bash
+pip install ssh-handler
+```
+
+---
+
+## Table of contents
+
+- [Why this package](#why-this-package)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [What you can do](#what-you-can-do) — full capability list
+- [Domain / Windows (RDP) hosts](#domain--windows-rdp-hosts)
+- [Confidential credentials](#confidential-credentials)
+- [Performance](#performance)
+- [Error handling: two styles](#error-handling-two-styles)
+- [Result objects](#result-objects)
+- [CLI reference](#cli-reference)
+- [PyQt5 integration](#pyqt5-integration)
+- [Parallel fleet operations](#parallel-fleet-operations)
+- [FTP / FTPS](#ftp--ftps)
+- [API map](#api-map)
+- [Releasing](#releasing)
+
+---
+
+## Why this package
+
+Paramiko is powerful but low-level: you manage clients, transports, channels,
+SFTP sessions, timeouts, retries, host-key policies and error handling yourself,
+and you repeat that boilerplate in every project. `ssh-handler` wraps all of it
+behind one object that:
+
+- auto-selects the right authentication strategy (password, key, agent, empty password),
+- retries connections and transparently reconnects dropped sessions,
+- returns **structured results** for every action instead of raw strings,
+- keeps **passwords confidential** end-to-end,
+- and exposes the same surface whether you're in a test, a CLI, or a GUI.
+
+## Install
+
+```bash
+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
+```
+
+**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
+
+```python
+from ssh_handler import SSHHandler, SSHConfig
+
+with SSHHandler(SSHConfig(host="10.0.0.5", username="root", password="pw")) as ssh:
+    print(ssh.run("uptime").stdout)
+    ssh.run("systemctl restart nginx", check=True)      # raises on non-zero exit
+    ssh.push("local.txt", "/tmp/remote.txt")            # SFTP upload
+    ssh.pull("/etc/nginx", "./backup", recursive=True)  # recursive download
+```
+
+## What you can do
+
+**Connection & session**
+- Connect with password, private key (+ passphrase), SSH agent, auto-discovered
+  keys, or an **empty-password** account — all auto-tried in a smart order.
+- **Auto-retry** connects with backoff; **auto-reconnect** if a session drops.
+- Keepalives, per-command and connection timeouts, optional compression.
+- **Jump host / bastion** chaining (ProxyJump-style) via `SSHConfig(jump_host=…)`.
+- Host-key policy: `auto` / `reject` / `warn`, with an optional `known_hosts` file.
+- Remote-OS awareness (`detect_os()`, `is_windows`) for Linux **and** Windows targets.
+- Raw escape hatch: `ssh.client` and `ssh.transport` expose the underlying Paramiko objects.
+
+**Command execution**
+- `run()` — timeout, `check` (raise on non-zero), PTY allocation, custom environment.
+- `run_many()` — batch with stop-on-error.
+- `sudo()` — runs `sudo -S` and feeds the password on stdin.
+- `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).
+- Listing & metadata: `listdir`, `listdir_attr`, `stat`, `lstat`, `exists`, `isdir`, `walk`.
+- Directories: `mkdir`, `makedirs` (recursive `mkdir -p`), `rmdir`.
+- Files: `remove`, `rename`, `open` (remote file object), `read_text`, `write_text`.
+- Permissions & links: `chmod`, `chown`, `symlink`, `readlink`.
+
+**Other protocols**
+- **FTP / FTPS** via `FTPHandler` (standard-library `ftplib`, no extra dependency):
+  connect, login, TLS, `push`, `pull`, `listdir`, `cwd`, `pwd`, `mkdir`, `rmdir`,
+  `remove`, `rename`, `size`, `exists`.
+
+**Scale & integration**
+- `SSHPool` — run the same command/transfer across many hosts in parallel threads.
+- Safe mode + log callback for GUIs; structured result objects everywhere.
+- Confidential credential storage in the OS vault (`CredentialStore`, `Secret`, `mask`).
+
+## Domain / Windows (RDP) hosts
+
+The Windows machines you normally RDP into can be driven over SSH once **OpenSSH
+Server** is enabled on them:
+
+```powershell
+Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
+Start-Service sshd ; Set-Service -Name sshd -StartupType Automatic
+```
+
+Then log in with your normal domain credentials. **Pass `domain` and `username`
+separately** — never hard-code a single `"DOMAIN\user"` Python string, because a
+backslash escape (e.g. `\n`, `\t`) silently becomes a control character. The
+handler builds the `DOMAIN\user` login string for you:
+
+```python
+from ssh_handler import SSHHandler, SSHConfig, CredentialStore
+
+store = CredentialStore(service="my_test_lab")
+cfg = SSHConfig(
+    host="10.20.30.40",
+    domain="CORP", username="myuser",        # -> login "CORP\myuser"
+    password=store.get("CORP\\myuser"),       # a Secret pulled from the OS vault
+    remote_os="windows",                      # skip the OS probe
+    fast_auth=True,                           # skip key probing -> faster login
+)
+with SSHHandler(cfg) as ssh:
+    print(ssh.run("whoami").stdout)                       # CORP\myuser
+    print(ssh.run("powershell Get-Service sshd").stdout)
+    ssh.push("report.xlsx", "C:/Users/myuser/Desktop/report.xlsx")
+```
+
+Store the password **once** so it never appears in code again:
+
+```python
+from ssh_handler import CredentialStore, prompt_password
+CredentialStore("my_test_lab").set("CORP\\myuser", prompt_password())
+```
+```bash
+# …or from the CLI:
+python -m ssh_handler store-credential --user myuser --domain CORP --service my_test_lab
+```
+
+## RDP-only Windows hosts: auto-enable SSH once (WinRM bootstrap)
+
+A freshly imaged corporate Windows box often has **RDP and WinRM open but no SSH
+server** (port 22 closed). You can't start sshd *over* SSH when SSH is down — but
+if WinRM is reachable, the handler can use it as a one-time bootstrap channel.
+
+Set one flag and connect normally:
+
+```python
+from ssh_handler import SSHHandler, SSHConfig
+
+cfg = SSHConfig(
+    host="10.232.9.22", domain="CORP", username="myuser", password="pw",
+    auto_bootstrap_via_winrm=True,   # if SSH is down but WinRM is up, enable sshd, then retry
+)
+with SSHHandler(cfg) as ssh:         # 1st run: enables sshd over WinRM, then connects
+    print(ssh.run("whoami").stdout)  # every later run: connects straight over SSH
+```
+
+**It's genuinely one-time.** The bootstrap installs the OpenSSH Server capability,
+starts `sshd` with **Automatic** startup, and adds a **persistent** firewall rule —
+so it survives reboots. After the first run, port 22 is already open and the
+handler connects directly over SSH; WinRM is never touched again.
+
+Do it explicitly instead of automatically if you prefer:
+
+```python
+ssh = SSHHandler(cfg)
+ssh.bootstrap_sshd_via_winrm()       # one-time setup
+ssh.connect()
+```
+
+Requirements: `pip install "ssh-handler[winrm]"` (pulls in `pywinrm`; uses NTLM so
+domain creds work without Kerberos), and the account must be a **local
+administrator** on the target. If SSH already works, this code path never runs.
+
+### Set up OpenSSH Server on a machine (bundled installer)
+
+Installing the package also gives you a one-command, **fully offline** setup for
+the local Windows machine. The OpenSSH ZIPs (ARM64 / Win64 / Win32) ship *inside*
+the wheel, so the installer needs **no internet and no Windows Update** — it picks
+the ZIP matching the CPU architecture, self-elevates to Administrator, installs &
+starts OpenSSH Server, and opens the firewall. (This avoids the
+`Add-WindowsCapability` hang common on locked-down corporate networks.)
+
+```powershell
+pip install ssh-handler
+ssh-handler-setup                 # offline install + start sshd + firewall (self-elevates)
+ssh-handler-setup --install-pip   # also (re)install the package as admin
+ssh-handler-setup --force         # reinstall even if sshd already exists
+# equivalent: python -m ssh_handler setup-server
+```
+
+Run it on whichever machine you want to reach over SSH (e.g. the RDP jump box).
+
+When a connection just fails, the error now self-diagnoses — it probes the SSH and
+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).
+
+### 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
+
+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 |
+|-----------|--------------|
+| `Secret` | wraps a password; `str()`/`repr()`/logs show `********`; only `.reveal()` exposes it |
+| `mask()` | redacts secret values from any string (applied automatically to all logging) |
+| `CredentialStore` | stores/reads passwords in the OS vault (Windows Credential Manager / macOS Keychain / Secret Service) via `keyring` — **no plaintext on disk** |
+| `prompt_password()` | hidden terminal input, returns a `Secret` |
+
+Pass a `Secret` (or a plain string, which is wrapped automatically) anywhere a
+password is accepted. It stays redacted across the whole stack.
+
+## Performance
+
+- **`fast_auth`** (default on): when a password is supplied, the slow key/agent
+  probing is skipped — faster logins and no "Too many authentication failures"
+  from the server's `MaxAuthTries`.
+- One SFTP channel is opened lazily and **reused** across operations.
+- SFTP downloads use Paramiko **prefetch** for high throughput.
+- `remote_os="windows"|"linux"` skips the one-time OS-detection probe.
+- `compress=True` for slow/high-latency links; keepalives keep long sessions alive.
+- `SSHPool` parallelizes across hosts with a thread pool.
+
+## Error handling: two styles
+
+**Raise (default)** — best for tests/scripts. Typed exceptions, all subclasses of
+`SSHError`:
+
+```
+SSHConnectionError  SSHAuthenticationError  SSHTimeoutError
+SSHCommandError     SSHTransferError        SSHNotConnectedError
+FTPError            CredentialError
+```
+
+**Safe mode** (`SSHHandler(cfg, safe=True)`) — best for GUIs. Every call returns an
+`OperationResult` instead of raising, so an event loop never dies:
+
+```python
+res = ssh.connect()
+if not res:                 # OperationResult is falsy on failure
+    show_error(res.error)
+else:
+    data = res.value        # or res.unwrap() to re-raise on failure
+```
+
+Override per call with `safe=True` / `safe=False`.
+
+## Result objects
+
+Every action returns structured data, not bare strings:
+
+- **`CommandResult`** — `exit_code`, `stdout`, `stderr`, `duration`, `host`, `.ok`, `.as_dict()`
+- **`TransferResult`** — `size_bytes`, `duration`, `speed_bps`, `human_speed`, `human_size`, `files`
+- **`ShellResult`** — `output`, `matched`, `timed_out`, `duration`
+- **`OperationResult`** — safe-mode wrapper: `bool(res)`, `res.value`, `res.error`, `res.unwrap()`
+
+## 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 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.
+Put `--match`/`--save` *before* the streamed command. After `pip install`, the
+`ssh-handler` and `ssh-handler-setup` console scripts are also available.
+
+## PyQt5 integration
+
+`ssh_handler.pyqt_worker.SSHWorker` is a `QObject` wrapping the handler in **safe
+mode**. Move it to a `QThread`, connect its signals, and drive it from the GUI:
+
+```python
+from PyQt5.QtCore import QThread
+from ssh_handler import SSHConfig
+from ssh_handler.pyqt_worker import SSHWorker
+
+worker = SSHWorker(SSHConfig(host="10.0.0.5", username="root", password=secret))
+thread = QThread(); worker.moveToThread(thread)
+worker.log.connect(text_edit.append)            # live, secret-masked log lines
+worker.command_done.connect(on_command_done)
+worker.progress.connect(progress_bar.setValue)  # bytes_done, bytes_total
+thread.started.connect(lambda: worker.run_command("uptime"))
+thread.start()
+```
+
+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
+
+```python
+from ssh_handler import SSHPool, SSHConfig
+
+configs = [SSHConfig(host=h, username="root", password="pw")
+           for h in ("10.0.0.1", "10.0.0.2", "10.0.0.3")]
+
+with SSHPool(configs, max_workers=8) as pool:
+    for host, res in pool.run("uptime").items():
+        print(host, res.value.stdout.strip() if res else res.error)
+    pool.pull("/var/log/syslog", "logs/{host}_syslog.txt")   # {host} avoids collisions
+```
+
+## FTP / FTPS
+
+```python
+from ssh_handler import FTPHandler, FTPConfig
+
+with FTPHandler(FTPConfig(host="ftp.example.com", username="u",
+                          password="p", use_tls=True)) as ftp:
+    ftp.push("local.txt", "remote.txt")
+    ftp.pull("remote.txt", "copy.txt")
+    print(ftp.listdir("/"))
+```
+
+## API map
+
+```
+ssh_handler/
+  config.py       SSHConfig, FTPConfig
+  credentials.py  Secret, CredentialStore, mask, prompt_password
+  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)
+  pyqt_worker.py  SSHWorker                  (PyQt5, lazy import)
+  results.py      CommandResult, TransferResult, ShellResult, OperationResult
+  exceptions.py   SSHError hierarchy
+examples/examples.py        copy-paste recipes
+tests/test_offline.py       offline checks (no network needed)
+```
+
+## Releasing
+
+Maintainers: use the helper to build and publish a new version.
+
+```bash
+python scripts/release.py 1.0.1            # bump -> build -> twine check -> upload
+python scripts/release.py 1.0.1 --dry-run  # build + check only, no upload
+python scripts/release.py patch            # auto-bump patch/minor/major
+```
+
+The token is read from the `TWINE_PASSWORD` environment variable (username
+`__token__`), never hard-coded. See [`scripts/release.py`](scripts/release.py) and
+the optional [GitHub Actions workflow](.github/workflows/publish.yml) (publishes on
+a `v*` tag). PyPI permanently forbids re-uploading an existing version, so each
+release must use a new version number.
+
+## License
+
+MIT

{ssh_handler-1.5.0 → ssh_handler-1.6.0}/ssh_handler/__init__.py

@@ -22,7 +22,7 @@ dependencies (PyQt5 / scp) don't break the core package.
 
 from __future__ import annotations
 
-__version__ = "1.5.0"
+__version__ = "1.6.0"
 
 from .config import SSHConfig, FTPConfig
 from .core import SSHHandler, ShellSession

{ssh_handler-1.5.0 → ssh_handler-1.6.0}/ssh_handler/cli.py

@@ -33,6 +33,34 @@ def _setup_script_path() -> str:
     return os.path.join(os.path.dirname(__file__), "setup_openssh_server.ps1")
 
 
+DOCS_URL = "https://pypi.org/project/ssh-handler/"
+
+
+def open_docs(argv=None) -> int:
+    """Console entry point (`ssh-handler-docs`): open the rendered docs in a
+    browser, falling back to the README bundled in the package."""
+    import webbrowser
+    try:
+        if webbrowser.open(DOCS_URL):
+            print(f"Opened docs: {DOCS_URL}")
+            return 0
+    except Exception:
+        pass
+    readme = os.path.join(os.path.dirname(__file__), "README.md")
+    if os.path.exists(readme):
+        webbrowser.open("file://" + readme)
+        print(f"Opened bundled README: {readme}")
+    else:
+        print(f"Docs: {DOCS_URL}")
+    return 0
+
+
+def launch_gui(argv=None) -> int:
+    """Console entry point (`ssh-handler-gui`): launch the PyQt5 application."""
+    from .gui_app import main as gui_main
+    return gui_main()
+
+
 def setup_server_main(argv=None) -> int:
     """
     Console entry point (`ssh-handler-setup`): run the bundled PowerShell script

ssh_handler-1.6.0/ssh_handler/gui_app.py

@@ -0,0 +1,402 @@
+"""
+ssh-handler GUI — a PyQt5 application that performs every operation with a
+button and shows commands, results, and live logs in one pane.
+
+Launch:
+    ssh-handler-gui            (console script after `pip install`)
+    python -m ssh_handler.gui_app
+
+Build a standalone .exe with the bundled icon:
+    python scripts/build_exe.py        (uses PyInstaller)
+
+Capabilities exposed: connect (with optional jump host / RDP), run commands,
+SFTP push/pull, serial (COM/device) monitoring with match + save, and live SSH
+log streaming (slog2info / tail -f) with match + save.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import queue
+import threading
+import webbrowser
+
+try:
+    from PyQt5.QtCore import QThread, pyqtSignal, Qt
+    from PyQt5.QtGui import QIcon, QTextCursor, QFont
+    from PyQt5.QtWidgets import (
+        QApplication, QWidget, QMainWindow, QGridLayout, QVBoxLayout, QHBoxLayout,
+        QFormLayout, QLabel, QLineEdit, QPushButton, QPlainTextEdit, QSpinBox,
+        QCheckBox, QTabWidget, QGroupBox, QFileDialog, QComboBox, QStatusBar,
+    )
+except Exception as exc:  # pragma: no cover
+    raise ImportError(
+        "The GUI needs PyQt5. Install it with: pip install \"ssh-handler[gui]\""
+    ) from exc
+
+from .config import SSHConfig
+from .core import SSHHandler
+from .results import OperationResult
+
+ICON_PATH = os.path.join(os.path.dirname(__file__), "assets", "icon.ico")
+DOCS_URL = "https://pypi.org/project/ssh-handler/"
+
+
+# --------------------------------------------------------------------------- #
+# Background worker: one thread owns the SSHHandler; jobs are queued callables.
+# --------------------------------------------------------------------------- #
+class Worker(QThread):
+    log = pyqtSignal(str)
+    status = pyqtSignal(str, bool)        # message, connected?
+    done = pyqtSignal(str, object)        # label, value
+
+    def __init__(self):
+        super().__init__()
+        self._jobs: "queue.Queue" = queue.Queue()
+        self._alive = True
+        self.ssh: SSHHandler | None = None
+        self.stream_stop = threading.Event()
+
+    def run(self):
+        while self._alive:
+            job = self._jobs.get()
+            if job is None:
+                break
+            label, fn = job
+            try:
+                fn()
+            except Exception as exc:                       # never kill the thread
+                self.log.emit(f"[ERROR] {label}: {exc}")
+
+    def submit(self, label, fn):
+        self._jobs.put((label, fn))
+
+    def shutdown(self):
+        self._alive = False
+        self.stream_stop.set()
+        self._jobs.put(None)
+
+    # ---- jobs (run inside the worker thread) ----
+    def do_connect(self, cfg: SSHConfig):
+        def _job():
+            self.ssh = SSHHandler(cfg, log_callback=self.log.emit, safe=True)
+            res = self.ssh.connect()
+            ok = bool(res)
+            if ok:
+                self.status.emit(f"Connected to {cfg.host}", True)
+            else:
+                self.status.emit(f"Connect failed: {getattr(res,'error','')}", False)
+        self.submit("connect", _job)
+
+    def do_disconnect(self):
+        def _job():
+            self.stream_stop.set()
+            if self.ssh:
+                self.ssh.disconnect()
+            self.status.emit("Disconnected", False)
+        self.submit("disconnect", _job)
+
+    def _need(self) -> bool:
+        if not self.ssh or not self.ssh.is_connected:
+            self.log.emit("[ERROR] Not connected. Click Connect first.")
+            return False
+        return True
+
+    def do_run(self, command: str):
+        def _job():
+            if not self._need():
+                return
+            res = self.ssh.run(command)
+            if isinstance(res, OperationResult) and res.success:
+                r = res.value
+                if r.stdout:
+                    self.log.emit(r.stdout.rstrip())
+                if r.stderr:
+                    self.log.emit("[stderr] " + r.stderr.rstrip())
+                self.log.emit(f"[exit {r.exit_code}, {r.duration:.2f}s]")
+        self.submit("run", _job)
+
+    def do_push(self, local, remote, recursive):
+        def _job():
+            if not self._need():
+                return
+            res = self.ssh.push(local, remote, recursive=recursive)
+            if isinstance(res, OperationResult) and res.success:
+                self.log.emit(str(res.value))
+        self.submit("push", _job)
+
+    def do_pull(self, remote, local, recursive):
+        def _job():
+            if not self._need():
+                return
+            res = self.ssh.pull(remote, local, recursive=recursive)
+            if isinstance(res, OperationResult) and res.success:
+                self.log.emit(str(res.value))
+        self.submit("pull", _job)
+
+    def do_serial(self, device, baud, match, save_to):
+        def _job():
+            if not self._need():
+                return
+            self.stream_stop.clear()
+            self.log.emit(f"--- serial {device} @ {baud} (Stop to end) ---")
+            self.ssh.serial_stream(device, baudrate=baud, on_line=self.log.emit,
+                                   match=(match or None), save_to=(save_to or None),
+                                   stop_event=self.stream_stop)
+            self.log.emit("--- serial stopped ---")
+        self.submit("serial", _job)
+
+    def do_stream(self, command, match, save_to):
+        def _job():
+            if not self._need():
+                return
+            self.stream_stop.clear()
+            self.log.emit(f"--- streaming '{command}' (Stop to end) ---")
+            self.ssh.stream(command, on_line=self.log.emit, match=(match or None),
+                            save_to=(save_to or None), stop_event=self.stream_stop)
+            self.log.emit("--- stream stopped ---")
+        self.submit("stream", _job)
+
+    def stop_stream(self):
+        self.stream_stop.set()
+
+
+# --------------------------------------------------------------------------- #
+# Main window
+# --------------------------------------------------------------------------- #
+class MainWindow(QMainWindow):
+    def __init__(self):
+        super().__init__()
+        self.setWindowTitle("ssh-handler — Automotive SSH toolkit")
+        if os.path.exists(ICON_PATH):
+            self.setWindowIcon(QIcon(ICON_PATH))
+        self.resize(900, 680)
+
+        self.worker = Worker()
+        self.worker.log.connect(self._append_log)
+        self.worker.status.connect(self._on_status)
+        self.worker.start()
+
+        central = QWidget()
+        self.setCentralWidget(central)
+        root = QVBoxLayout(central)
+        root.addWidget(self._build_connection_group())
+        root.addWidget(self._build_tabs())
+        root.addWidget(self._build_log_group(), stretch=1)
+        self.setStatusBar(QStatusBar())
+        self.statusBar().showMessage("Not connected")
+
+    # ---- connection panel ----
+    def _build_connection_group(self):
+        g = QGroupBox("Connection")
+        lay = QGridLayout(g)
+        self.host = QLineEdit(); self.host.setPlaceholderText("target host / IP")
+        self.port = QSpinBox(); self.port.setRange(1, 65535); self.port.setValue(22)
+        self.user = QLineEdit()
+        self.domain = QLineEdit(); self.domain.setPlaceholderText("optional domain")
+        self.password = QLineEdit(); self.password.setEchoMode(QLineEdit.Password)
+        self.ignore_hostkey = QCheckBox("Ignore host key (lab)")
+        self.ignore_hostkey.setChecked(True)
+
+        self.use_jump = QCheckBox("Via jump host (RDP machine)")
+        self.jhost = QLineEdit(); self.jhost.setPlaceholderText("jump host / IP")
+        self.juser = QLineEdit(); self.juser.setPlaceholderText("jump user")
+        self.jdomain = QLineEdit(); self.jdomain.setPlaceholderText("jump domain")
+        self.jpass = QLineEdit(); self.jpass.setEchoMode(QLineEdit.Password)
+        self.jpass.setPlaceholderText("jump password")
+
+        self.btn_connect = QPushButton("Connect")
+        self.btn_disconnect = QPushButton("Disconnect")
+        self.btn_disconnect.setEnabled(False)
+        self.btn_connect.clicked.connect(self._connect)
+        self.btn_disconnect.clicked.connect(self._disconnect)
+
+        lay.addWidget(QLabel("Host"), 0, 0); lay.addWidget(self.host, 0, 1)
+        lay.addWidget(QLabel("Port"), 0, 2); lay.addWidget(self.port, 0, 3)
+        lay.addWidget(QLabel("User"), 1, 0); lay.addWidget(self.user, 1, 1)
+        lay.addWidget(QLabel("Domain"), 1, 2); lay.addWidget(self.domain, 1, 3)
+        lay.addWidget(QLabel("Password"), 2, 0); lay.addWidget(self.password, 2, 1)
+        lay.addWidget(self.ignore_hostkey, 2, 2, 1, 2)
+        lay.addWidget(self.use_jump, 3, 0, 1, 4)
+        lay.addWidget(self.jhost, 4, 0, 1, 2); lay.addWidget(self.juser, 4, 2, 1, 2)
+        lay.addWidget(self.jdomain, 5, 0, 1, 2); lay.addWidget(self.jpass, 5, 2, 1, 2)
+        lay.addWidget(self.btn_connect, 6, 0, 1, 2)
+        lay.addWidget(self.btn_disconnect, 6, 2, 1, 2)
+        return g
+
+    # ---- operation tabs ----
+    def _build_tabs(self):
+        tabs = QTabWidget()
+
+        # Command
+        cmd = QWidget(); cl = QHBoxLayout(cmd)
+        self.cmd_in = QLineEdit("uname -a")
+        run_btn = QPushButton("Run")
+        run_btn.clicked.connect(lambda: self.worker.do_run(self.cmd_in.text().strip()))
+        self.cmd_in.returnPressed.connect(run_btn.click)
+        cl.addWidget(QLabel("Command")); cl.addWidget(self.cmd_in, 1); cl.addWidget(run_btn)
+        tabs.addTab(cmd, "Command")
+
+        # Files
+        files = QWidget(); fl = QGridLayout(files)
+        self.local_path = QLineEdit(); self.remote_path = QLineEdit()
+        lb = QPushButton("Browse"); lb.clicked.connect(self._browse_local)
+        self.recursive = QCheckBox("Recursive (folder)")
+        push_btn = QPushButton("Push (upload)")
+        pull_btn = QPushButton("Pull (download)")
+        push_btn.clicked.connect(lambda: self.worker.do_push(
+            self.local_path.text().strip(), self.remote_path.text().strip(),
+            self.recursive.isChecked()))
+        pull_btn.clicked.connect(lambda: self.worker.do_pull(
+            self.remote_path.text().strip(), self.local_path.text().strip(),
+            self.recursive.isChecked()))
+        fl.addWidget(QLabel("Local"), 0, 0); fl.addWidget(self.local_path, 0, 1)
+        fl.addWidget(lb, 0, 2)
+        fl.addWidget(QLabel("Remote"), 1, 0); fl.addWidget(self.remote_path, 1, 1, 1, 2)
+        fl.addWidget(self.recursive, 2, 0)
+        fl.addWidget(push_btn, 2, 1); fl.addWidget(pull_btn, 2, 2)
+        tabs.addTab(files, "Files (SFTP)")
+
+        # Serial
+        ser = QWidget(); sl = QGridLayout(ser)
+        self.ser_dev = QLineEdit("COM5")
+        self.ser_baud = QSpinBox(); self.ser_baud.setRange(300, 4000000)
+        self.ser_baud.setValue(115200)
+        self.ser_match = QLineEdit(); self.ser_match.setPlaceholderText("regex to match (optional)")
+        self.ser_save = QLineEdit(); self.ser_save.setPlaceholderText("save to file (optional)")
+        sb = QPushButton("Browse"); sb.clicked.connect(lambda: self._browse_save(self.ser_save))
+        ser_start = QPushButton("Start"); ser_stop = QPushButton("Stop")
+        ser_start.clicked.connect(lambda: self.worker.do_serial(
+            self.ser_dev.text().strip(), self.ser_baud.value(),
+            self.ser_match.text().strip(), self.ser_save.text().strip()))
+        ser_stop.clicked.connect(self.worker.stop_stream)
+        sl.addWidget(QLabel("Device"), 0, 0); sl.addWidget(self.ser_dev, 0, 1)
+        sl.addWidget(QLabel("Baud"), 0, 2); sl.addWidget(self.ser_baud, 0, 3)
+        sl.addWidget(QLabel("Match"), 1, 0); sl.addWidget(self.ser_match, 1, 1, 1, 3)
+        sl.addWidget(QLabel("Save"), 2, 0); sl.addWidget(self.ser_save, 2, 1, 1, 2)
+        sl.addWidget(sb, 2, 3)
+        sl.addWidget(ser_start, 3, 1); sl.addWidget(ser_stop, 3, 2)
+        tabs.addTab(ser, "Serial")
+
+        # Log stream
+        strm = QWidget(); stl = QGridLayout(strm)
+        self.strm_cmd = QLineEdit("slog2info -w")
+        self.strm_match = QLineEdit(); self.strm_match.setPlaceholderText("regex to match (optional)")
+        self.strm_save = QLineEdit(); self.strm_save.setPlaceholderText("save to file (optional)")
+        stb = QPushButton("Browse"); stb.clicked.connect(lambda: self._browse_save(self.strm_save))
+        strm_start = QPushButton("Start"); strm_stop = QPushButton("Stop")
+        strm_start.clicked.connect(lambda: self.worker.do_stream(
+            self.strm_cmd.text().strip(), self.strm_match.text().strip(),
+            self.strm_save.text().strip()))
+        strm_stop.clicked.connect(self.worker.stop_stream)
+        stl.addWidget(QLabel("Command"), 0, 0); stl.addWidget(self.strm_cmd, 0, 1, 1, 3)
+        stl.addWidget(QLabel("Match"), 1, 0); stl.addWidget(self.strm_match, 1, 1, 1, 3)
+        stl.addWidget(QLabel("Save"), 2, 0); stl.addWidget(self.strm_save, 2, 1, 1, 2)
+        stl.addWidget(stb, 2, 3)
+        stl.addWidget(strm_start, 3, 1); stl.addWidget(strm_stop, 3, 2)
+        tabs.addTab(strm, "Log stream")
+
+        return tabs
+
+    # ---- log pane ----
+    def _build_log_group(self):
+        g = QGroupBox("Log")
+        lay = QVBoxLayout(g)
+        self.log_view = QPlainTextEdit(); self.log_view.setReadOnly(True)
+        self.log_view.setFont(QFont("Consolas", 9))
+        self.log_view.setMaximumBlockCount(20000)
+        row = QHBoxLayout()
+        clear = QPushButton("Clear"); clear.clicked.connect(self.log_view.clear)
+        savelog = QPushButton("Save log…"); savelog.clicked.connect(self._save_log)
+        docs = QPushButton("Help / Docs"); docs.clicked.connect(lambda: webbrowser.open(DOCS_URL))
+        row.addWidget(clear); row.addWidget(savelog); row.addStretch(1); row.addWidget(docs)
+        lay.addWidget(self.log_view, 1); lay.addLayout(row)
+        return g
+
+    # ---- actions ----
+    def _build_config(self) -> SSHConfig:
+        policy = "ignore" if self.ignore_hostkey.isChecked() else "auto"
+        jump = None
+        if self.use_jump.isChecked() and self.jhost.text().strip():
+            jump = SSHConfig(host=self.jhost.text().strip(),
+                             username=self.juser.text().strip() or None,
+                             domain=self.jdomain.text().strip() or None,
+                             password=self.jpass.text(), host_key_policy=policy)
+        return SSHConfig(
+            host=self.host.text().strip(), port=self.port.value(),
+            username=self.user.text().strip() or None,
+            domain=self.domain.text().strip() or None,
+            password=self.password.text(), jump_host=jump,
+            host_key_policy=policy,
+        )
+
+    def _connect(self):
+        if not self.host.text().strip():
+            self._append_log("[ERROR] Enter a host first.")
+            return
+        self._append_log(f"Connecting to {self.host.text().strip()}…")
+        self.worker.do_connect(self._build_config())
+
+    def _disconnect(self):
+        self.worker.do_disconnect()
+
+    def _on_status(self, msg, connected):
+        self.statusBar().showMessage(msg)
+        self._append_log(msg)
+        self.btn_connect.setEnabled(not connected)
+        self.btn_disconnect.setEnabled(connected)
+
+    def _append_log(self, text):
+        self.log_view.appendPlainText(text)
+        self.log_view.moveCursor(QTextCursor.End)
+
+    def _browse_local(self):
+        path, _ = QFileDialog.getOpenFileName(self, "Choose local file")
+        if path:
+            self.local_path.setText(path)
+
+    def _browse_save(self, target):
+        path, _ = QFileDialog.getSaveFileName(self, "Save to file")
+        if path:
+            target.setText(path)
+
+    def _save_log(self):
+        path, _ = QFileDialog.getSaveFileName(self, "Save log", "session.log")
+        if path:
+            with open(path, "w", encoding="utf-8") as fh:
+                fh.write(self.log_view.toPlainText())
+            self._append_log(f"Log saved to {path}")
+
+    def closeEvent(self, event):
+        self.worker.shutdown()
+        self.worker.wait(2000)
+        super().closeEvent(event)
+
+
+def _maybe_open_docs_first_run():
+    """Open the docs in a browser the first time the app is launched."""
+    try:
+        flag_dir = os.path.join(os.path.expanduser("~"), ".ssh-handler")
+        flag = os.path.join(flag_dir, "docs-opened")
+        if not os.path.exists(flag):
+            os.makedirs(flag_dir, exist_ok=True)
+            webbrowser.open(DOCS_URL)
+            with open(flag, "w") as fh:
+                fh.write("1")
+    except Exception:
+        pass
+
+
+def main():
+    app = QApplication(sys.argv)
+    if os.path.exists(ICON_PATH):
+        app.setWindowIcon(QIcon(ICON_PATH))
+    _maybe_open_docs_first_run()
+    win = MainWindow()
+    win.show()
+    return app.exec_()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{ssh_handler-1.5.0 → ssh_handler-1.6.0/ssh_handler.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-handler
-Version: 1.5.0
+Version: 1.6.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

{ssh_handler-1.5.0 → ssh_handler-1.6.0}/ssh_handler.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE
 README.md
 pyproject.toml
+ssh_handler/README.md
 ssh_handler/__init__.py
 ssh_handler/__main__.py
 ssh_handler/cli.py
@@ -9,6 +10,7 @@ ssh_handler/core.py
 ssh_handler/credentials.py
 ssh_handler/exceptions.py
 ssh_handler/ftp.py
+ssh_handler/gui_app.py
 ssh_handler/pool.py
 ssh_handler/pyqt_worker.py
 ssh_handler/results.py
@@ -21,6 +23,8 @@ ssh_handler.egg-info/dependency_links.txt
 ssh_handler.egg-info/entry_points.txt
 ssh_handler.egg-info/requires.txt
 ssh_handler.egg-info/top_level.txt
+ssh_handler/assets/icon.ico
+ssh_handler/assets/icon.png
 ssh_handler/openssh/OpenSSH-ARM64.zip
 ssh_handler/openssh/OpenSSH-Win32.zip
 ssh_handler/openssh/OpenSSH-Win64.zip

{ssh_handler-1.5.0 → ssh_handler-1.6.0}/ssh_handler.egg-info/entry_points.txt

@@ -1,3 +1,7 @@
 [console_scripts]
 ssh-handler = ssh_handler.cli:main
+ssh-handler-docs = ssh_handler.cli:open_docs
 ssh-handler-setup = ssh_handler.cli:setup_server_main
+
+[gui_scripts]
+ssh-handler-gui = ssh_handler.cli:launch_gui