ssh-handler 1.0.0__py3-none-any.whl

ssh_handler/results.py

@@ -0,0 +1,127 @@
+"""Rich, structured result objects returned by every action."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+
+
+def _human_size(num: float) -> str:
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if abs(num) < 1024.0:
+            return f"{num:.1f}{unit}"
+        num /= 1024.0
+    return f"{num:.1f}PB"
+
+
+@dataclass
+class CommandResult:
+    """Result of a remote command execution."""
+
+    command: str
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration: float
+    host: str = ""
+    started_at: float = field(default_factory=time.time)
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+    def __str__(self) -> str:
+        return (
+            f"<CommandResult host={self.host} exit={self.exit_code} "
+            f"ok={self.ok} dur={self.duration:.2f}s cmd={self.command!r}>"
+        )
+
+
+@dataclass
+class TransferResult:
+    """Result of a file/dir transfer (push/pull via SFTP or SCP)."""
+
+    source: str
+    dest: str
+    direction: str           # "push" or "pull"
+    protocol: str            # "sftp" or "scp"
+    size_bytes: int
+    duration: float
+    files: int = 1
+
+    @property
+    def speed_bps(self) -> float:
+        return self.size_bytes / self.duration if self.duration > 0 else 0.0
+
+    @property
+    def human_speed(self) -> str:
+        return f"{_human_size(self.speed_bps)}/s"
+
+    @property
+    def human_size(self) -> str:
+        return _human_size(self.size_bytes)
+
+    def as_dict(self) -> dict:
+        d = asdict(self)
+        d.update(speed_bps=self.speed_bps, human_speed=self.human_speed)
+        return d
+
+    def __str__(self) -> str:
+        return (
+            f"<TransferResult {self.direction}/{self.protocol} "
+            f"{self.source} -> {self.dest} {self.human_size} "
+            f"in {self.duration:.2f}s ({self.human_speed}), files={self.files}>"
+        )
+
+
+@dataclass
+class ShellResult:
+    """Result of an interactive shell read/expect operation."""
+
+    output: str
+    matched: Optional[str]
+    timed_out: bool
+    duration: float
+
+    def __bool__(self) -> bool:
+        return not self.timed_out
+
+    def __str__(self) -> str:
+        return (
+            f"<ShellResult matched={self.matched!r} "
+            f"timed_out={self.timed_out} dur={self.duration:.2f}s>"
+        )
+
+
+@dataclass
+class OperationResult:
+    """
+    Returned by safe-mode operations. Wraps a value or an error so GUI handlers
+    never have to try/except. Falsy on failure.
+    """
+
+    success: bool
+    action: str = ""
+    value: object = None
+    error: Optional[Exception] = None
+
+    def __bool__(self) -> bool:
+        return self.success
+
+    def unwrap(self):
+        """Return value on success, else re-raise the captured error."""
+        if self.success:
+            return self.value
+        raise self.error if self.error else RuntimeError(f"{self.action} failed")
+
+    def __str__(self) -> str:
+        if self.success:
+            return f"<OperationResult {self.action} ok value={self.value!r}>"
+        return f"<OperationResult {self.action} error={self.error!r}>"

ssh_handler-1.0.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: ssh-handler
+Version: 1.0.0
+Summary: Extensive SSH/SFTP/SCP/FTP handler built on Paramiko, for test automation, CLIs and PyQt5 tools.
+Author: Naveen
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+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"
+Provides-Extra: gui
+Requires-Dist: PyQt5>=5.15; extra == "gui"
+Provides-Extra: all
+Requires-Dist: keyring>=23.0; extra == "all"
+Requires-Dist: scp>=0.14; extra == "all"
+Requires-Dist: PyQt5>=5.15; extra == "all"
+
+# ssh_handler
+
+An extensive **SSH / SFTP / SCP / FTP** handler built on [Paramiko](https://www.paramiko.org/),
+packaged so the *same* code works in three places:
+
+- a **test-automation framework** (raise-on-error, pytest fixtures, parallel fleet ops),
+- a **standalone CLI** (`python -m ssh_handler …`, argument-driven),
+- a **PyQt5 tool** (safe mode + log streaming via Qt signals, 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.
+
+## Install
+
+```bash
+pip install -e .                 # core (paramiko)
+pip install -e ".[all]"          # + keyring, scp, PyQt5
+# or just the pieces you need:
+pip install -e ".[secure]"       # keyring  (confidential password storage)
+pip install -e ".[scp]"          # scp      (SCP-protocol transfers)
+pip install -e ".[gui]"          # PyQt5    (the worker)
+```
+
+## 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
+```
+
+## Connecting to your RDP / Windows hosts (domain login `EU\nkennedy`)
+
+Those Windows machines need **OpenSSH Server** enabled (Settings → Optional Features →
+"OpenSSH Server", or `Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0`).
+Then you log in with your normal domain credentials.
+
+**Pass `domain` and `username` separately** — never hard-code `"EU\nkennedy"` as a Python
+string, because `\n` becomes a newline. The handler builds `EU\nkennedy` for you:
+
+```python
+from ssh_handler import SSHHandler, SSHConfig, CredentialStore
+
+store = CredentialStore(service="my_test_lab")
+cfg = SSHConfig(
+    host="10.20.30.40",
+    domain="EU", username="nkennedy",
+    password=store.get("EU\\nkennedy"),   # 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)                    # EU\nkennedy
+    print(ssh.run("powershell Get-Service sshd").stdout)
+    ssh.push("report.xlsx", "C:/Users/nkennedy/Desktop/report.xlsx")
+```
+
+Store the password **once** so it's never typed or committed again:
+
+```python
+CredentialStore("my_test_lab").set("EU\\nkennedy", prompt_password())
+# or from the CLI:
+python -m ssh_handler store-credential --user nkennedy --domain EU --service my_test_lab
+```
+
+## Confidential credentials
+
+| Mechanism | What it does |
+|-----------|--------------|
+| `Secret`  | wraps a password; `str()`/`repr()`/logs show `********`; only `.reveal()` exposes it |
+| `mask()`  | redacts secret values from any log line (applied automatically to all logging) |
+| `CredentialStore` | stores/reads passwords in Windows Credential Manager (or macOS Keychain / Secret Service) via `keyring` — **no plaintext on disk** |
+| `prompt_password()` | hidden terminal input |
+
+## Speed
+
+- **`fast_auth`** (default on): when a password is supplied, 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.
+- **`SSHPool`** runs the same command/transfer across many hosts in parallel threads.
+- `remote_os="windows"|"linux"` skips the one-time OS-detection probe.
+- `compress=True` for slow/high-latency links; keepalives keep long sessions alive.
+
+## What's covered (Paramiko parity, plus extras)
+
+- **Exec**: `run` (timeout, `check`, pty, env), `run_many`, `sudo` (password via stdin)
+- **Interactive shell**: `open_shell()` → `ShellSession` with `send` / `read_until` / `read_available`
+- **SFTP**: `listdir`, `listdir_attr`, `stat`, `lstat`, `exists`, `isdir`, `mkdir`, `makedirs`,
+  `rmdir`, `remove`, `rename`, `chmod`, `chown`, `symlink`, `readlink`, `open`,
+  `read_text`, `write_text`, `walk`, and `push`/`pull` (recursive, progress, stats)
+- **SCP**: `scp_push` / `scp_pull` (needs the `scp` extra)
+- **FTP/FTPS**: `FTPHandler` (stdlib `ftplib`, no extra dependency)
+- **Jump host / bastion**: `SSHConfig(jump_host=…)` (ProxyJump-style)
+- **Escape hatch**: `ssh.client` and `ssh.transport` expose the raw Paramiko objects
+
+## 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`, `files`
+- `ShellResult` — `output`, `matched`, `timed_out`, `duration`
+- `OperationResult` — safe-mode wrapper: `bool(res)`, `res.value`, `res.error`, `res.unwrap()`
+
+## Two error-handling styles
+
+- **Raise (default)** — for tests/scripts. Typed exceptions: `SSHConnectionError`,
+  `SSHAuthenticationError`, `SSHTimeoutError`, `SSHCommandError`, `SSHTransferError`,
+  `FTPError`, `CredentialError` — all subclasses of `SSHError`. **Auto-retry** on connect
+  and **auto-reconnect** on dropped sessions are built in.
+- **Safe mode** (`SSHHandler(cfg, safe=True)`) — for GUIs. Every call returns an
+  `OperationResult` instead of raising, so the event loop never dies. Override per call
+  with `safe=True/False`.
+
+## CLI
+
+```bash
+python -m ssh_handler run   --host H --user U --domain EU 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 --use-stored uptime   # vault password
+```
+Password options: `--password` (hidden prompt), `--use-stored` (OS vault), `--key FILE`.
+Add `--json` for machine-readable output.
+
+## PyQt5
+
+`ssh_handler.pyqt_worker.SSHWorker` is a `QObject` wrapping the handler in **safe mode**.
+`moveToThread()` it, connect its signals (`log`, `connected`, `command_done`,
+`transfer_done`, `progress`, `error`, `finished`), and drive it from the GUI — see recipe
+in [examples/examples.py](examples/examples.py).
+
+## Project layout
+
+```
+ssh_handler/
+  config.py       SSHConfig, FTPConfig
+  credentials.py  Secret, CredentialStore, mask, prompt_password
+  core.py         SSHHandler, ShellSession  (SSH + SFTP + SCP)
+  ftp.py          FTPHandler (FTP/FTPS)
+  pool.py         SSHPool (parallel multi-host)
+  cli.py          argparse entry point  (python -m ssh_handler)
+  pyqt_worker.py  SSHWorker (PyQt5, lazy import)
+  results.py      CommandResult, TransferResult, ShellResult, OperationResult
+  exceptions.py   SSHError hierarchy
+examples/examples.py
+tests/test_offline.py     (no network needed)
+```
+
+## Tests
+
+`tests/test_offline.py` validates secret masking, domain-login building, fast-auth
+kwargs, recursive-mkdir logic, transfer math, and both error-handling modes — all offline.
+
+```bash
+python tests/test_offline.py
+```

ssh_handler-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ssh_handler/__init__.py,sha256=ZY-5qIgixXRCKs_AcONVIFegIOPYX3ImCZK-CyKHg5M,1737
+ssh_handler/__main__.py,sha256=y-JCII5ssoxfEktEawpfYKBz-CCgxob8Q3b0AK76Lqo,122
+ssh_handler/cli.py,sha256=AXG8u2hmRQXG2BsShwC_XFrHXPXf83CoE26DS-JOIrc,5926
+ssh_handler/config.py,sha256=ElXOX-Al_o8PVv_i8cZponb1cdd1nkDBlwJjbV3g_oI,3982
+ssh_handler/core.py,sha256=wGyr22I3MeuGXvBx4hi9Sv9Bm9ZLdwvpD1zPMB0VCCc,33491
+ssh_handler/credentials.py,sha256=dhdun4U4lhngjbvT_Udv2Xpf9_NCmnB9Nk-S4ucOlNY,4848
+ssh_handler/exceptions.py,sha256=O2Ksw1r0mTQkqd_w36KYwuL6me_bKFFXFJ9o8WO6Ul0,1319
+ssh_handler/ftp.py,sha256=TOEJ3qHlo49A7rxf5iSunlr0zZGgxRpzbt27unHKWjA,7346
+ssh_handler/pool.py,sha256=L7_dN75GYZYGedS3DHumgNmc6rYxJeIDmJ6r03QjxNk,3822
+ssh_handler/pyqt_worker.py,sha256=FE1KiTC34fJTQxzVwo5CvKbb_j7FJes2f-aMgX3auXg,3636
+ssh_handler/results.py,sha256=BRZ10UmIvuaLwOC1YSdDarNKJ7rz0jcOmm_5mVNi_8k,3262
+ssh_handler-1.0.0.dist-info/METADATA,sha256=BCILCNpa6XbORrY2sMqRScUT988prMxHtg78Lov3q0U,7998
+ssh_handler-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ssh_handler-1.0.0.dist-info/entry_points.txt,sha256=AuXs00bXUYsd1ABut1If8dnWB7S8U9ZaWpsPClAHf2A,53
+ssh_handler-1.0.0.dist-info/top_level.txt,sha256=QQ4IFeUXYOGWDo2uNzt6PEzQU_jZIBSONnD8oh5fvNg,12
+ssh_handler-1.0.0.dist-info/RECORD,,

ssh_handler-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ssh_handler-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ssh-handler = ssh_handler.cli:main

ssh_handler-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ssh_handler