ssh-handler 1.0.0__py3-none-any.whl

ssh_handler/credentials.py

@@ -0,0 +1,144 @@
+"""
+Confidential credential handling.
+
+* ``Secret``        - wraps a password so it never shows up in logs, reprs,
+                      tracebacks, or accidental ``print``/``str`` calls.
+* ``mask``          - redact secrets inside arbitrary strings before logging.
+* ``CredentialStore`` - store/retrieve passwords in the OS credential vault
+                      (Windows Credential Manager / macOS Keychain / Secret
+                      Service) via ``keyring``. Nothing is written in plaintext.
+* ``prompt_password`` - read a password from the terminal without echoing it.
+"""
+
+from __future__ import annotations
+
+import getpass
+from typing import Optional
+
+from .exceptions import CredentialError
+
+try:  # keyring is optional; only needed for the persistent store
+    import keyring
+    _HAS_KEYRING = True
+except Exception:  # pragma: no cover
+    keyring = None
+    _HAS_KEYRING = False
+
+
+_REDACTED = "********"
+
+
+class Secret:
+    """
+    A string-like wrapper that refuses to reveal itself except via ``reveal()``.
+
+    >>> s = Secret("hunter2")
+    >>> print(s)            # ********
+    >>> repr(s)             # "Secret('********')"
+    >>> f"pw={s}"           # "pw=********"
+    >>> s.reveal()          # "hunter2"  (only when you explicitly ask)
+    """
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value: Optional[str]):
+        self._value = value
+
+    def reveal(self) -> Optional[str]:
+        """Return the real secret. Call only at the point of use."""
+        return self._value
+
+    def is_empty(self) -> bool:
+        return self._value is None or self._value == ""
+
+    def __bool__(self) -> bool:
+        return bool(self._value)
+
+    def __str__(self) -> str:
+        return _REDACTED
+
+    def __repr__(self) -> str:
+        return f"Secret('{_REDACTED}')"
+
+    # Avoid leaking through equality / hashing in logs.
+    def __eq__(self, other) -> bool:
+        if isinstance(other, Secret):
+            return self._value == other._value
+        return NotImplemented
+
+    def __hash__(self) -> int:  # so it can live in dataclasses/sets safely
+        return hash(self._value)
+
+
+def coerce_secret(value) -> Optional[Secret]:
+    """Normalize None/str/Secret into a Secret (or None)."""
+    if value is None:
+        return None
+    if isinstance(value, Secret):
+        return value
+    return Secret(str(value))
+
+
+def mask(text: str, *secrets) -> str:
+    """Replace any revealed secret values found in *text* with ``********``."""
+    if not text:
+        return text
+    out = text
+    for sec in secrets:
+        raw = sec.reveal() if isinstance(sec, Secret) else sec
+        if raw:
+            out = out.replace(str(raw), _REDACTED)
+    return out
+
+
+def prompt_password(prompt: str = "Password: ") -> Secret:
+    """Read a password from the terminal without echo. Returns a Secret."""
+    return Secret(getpass.getpass(prompt))
+
+
+class CredentialStore:
+    """
+    Persist passwords in the OS credential vault — never in plaintext files.
+
+    The ``service`` namespaces your app's credentials. ``username`` is the full
+    account identifier; for a domain account use ``"EU\\nkennedy"`` (the store
+    treats it as an opaque key, so domain accounts work transparently).
+    """
+
+    def __init__(self, service: str = "ssh_handler"):
+        if not _HAS_KEYRING:
+            raise CredentialError(
+                "The 'keyring' package is required for CredentialStore. "
+                "Install it with: pip install keyring"
+            )
+        self.service = service
+
+    @staticmethod
+    def available() -> bool:
+        return _HAS_KEYRING
+
+    def set(self, username: str, password) -> None:
+        """Store (or overwrite) a password for *username*."""
+        raw = password.reveal() if isinstance(password, Secret) else password
+        try:
+            keyring.set_password(self.service, username, raw)
+        except Exception as exc:  # pragma: no cover
+            raise CredentialError(f"Could not store credential: {exc}") from exc
+
+    def get(self, username: str) -> Optional[Secret]:
+        """Return the stored password as a Secret, or None if not found."""
+        try:
+            raw = keyring.get_password(self.service, username)
+        except Exception as exc:  # pragma: no cover
+            raise CredentialError(f"Could not read credential: {exc}") from exc
+        return Secret(raw) if raw is not None else None
+
+    def delete(self, username: str) -> bool:
+        """Delete a stored password. Returns False if it was not present."""
+        try:
+            keyring.delete_password(self.service, username)
+            return True
+        except keyring.errors.PasswordDeleteError:  # type: ignore[attr-defined]
+            return False
+        except Exception as exc:  # pragma: no cover
+            raise CredentialError(f"Could not delete credential: {exc}") from exc

ssh_handler/exceptions.py

@@ -0,0 +1,49 @@
+"""Exception hierarchy for ssh_handler. Catch SSHError for everything."""
+
+from __future__ import annotations
+
+
+class SSHError(Exception):
+    """Base class for all errors raised by this package."""
+
+
+class SSHConnectionError(SSHError):
+    """Network / TCP / DNS level failure establishing a connection."""
+
+
+class SSHAuthenticationError(SSHError):
+    """Every configured authentication strategy was rejected."""
+
+
+class SSHTimeoutError(SSHError):
+    """An operation exceeded its allotted time."""
+
+
+class SSHCommandError(SSHError):
+    """A remote command exited non-zero while check=True."""
+
+    def __init__(self, command: str, result):
+        self.command = command
+        self.result = result
+        stderr = getattr(result, "stderr", "") or ""
+        exit_code = getattr(result, "exit_code", "?")
+        super().__init__(
+            f"Command failed (exit={exit_code}): {command!r}\n"
+            f"stderr: {stderr.strip()[:500]}"
+        )
+
+
+class SSHTransferError(SSHError):
+    """An SFTP/SCP upload or download failed."""
+
+
+class SSHNotConnectedError(SSHError):
+    """An operation was attempted before connecting (auto_reconnect off)."""
+
+
+class FTPError(SSHError):
+    """An FTP/FTPS operation failed."""
+
+
+class CredentialError(SSHError):
+    """A credential could not be stored or retrieved."""

ssh_handler/ftp.py

@@ -0,0 +1,186 @@
+"""
+Plain FTP / FTPS handler (separate protocol from SSH/SFTP), built on the
+standard-library ``ftplib`` so it needs no extra dependency. Mirrors the
+push/pull/listing surface of SSHHandler and returns the same result objects.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import logging
+from ftplib import FTP, FTP_TLS, error_perm, all_errors
+from typing import Callable, Optional
+
+from .config import FTPConfig
+from .credentials import Secret, mask
+from .results import TransferResult, OperationResult
+from .exceptions import FTPError
+
+
+class FTPHandler:
+    """
+    >>> 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")
+    """
+
+    def __init__(self, config: FTPConfig, *,
+                 log_callback: Optional[Callable[[str], None]] = None,
+                 logger: Optional[logging.Logger] = None, safe: bool = False):
+        self.config = config
+        self._safe_default = safe
+        self._log_callback = log_callback
+        self.log = logger or logging.getLogger(f"ftp_handler.{config.host}")
+        if not self.log.handlers:
+            h = logging.StreamHandler()
+            h.setFormatter(logging.Formatter("%(asctime)s [%(levelname)s] %(message)s"))
+            self.log.addHandler(h)
+            self.log.setLevel(logging.INFO)
+        self._ftp: Optional[FTP] = None
+
+    def _emit(self, level, msg):
+        msg = mask(msg, self.config.password)
+        self.log.log(level, msg)
+        if self._log_callback:
+            try:
+                self._log_callback(f"[{logging.getLevelName(level)}] {msg}")
+            except Exception:
+                pass
+
+    def _guard(self, action, fn, *a, safe=None, **k):
+        use_safe = self._safe_default if safe is None else safe
+        if not use_safe:
+            return fn(*a, **k)
+        try:
+            return OperationResult(True, action, value=fn(*a, **k))
+        except Exception as exc:
+            self._emit(logging.ERROR, f"{action} failed: {exc}")
+            return OperationResult(False, action, error=exc)
+
+    # --- connection ---
+    def connect(self, *, safe=None):
+        return self._guard("connect", self._connect, safe=safe)
+
+    def _connect(self):
+        cfg = self.config
+        pw = cfg.password.reveal() if isinstance(cfg.password, Secret) else cfg.password
+        try:
+            self._ftp = FTP_TLS() if cfg.use_tls else FTP()
+            self._ftp.encoding = cfg.encoding
+            self._ftp.connect(cfg.host, cfg.port, timeout=cfg.timeout)
+            self._ftp.login(cfg.username, pw or "")
+            if cfg.use_tls:
+                self._ftp.prot_p()  # encrypt the data channel too
+            self._ftp.set_pasv(cfg.passive)
+            self._emit(logging.INFO, f"Connected to ftp://{cfg.username}@{cfg.host}.")
+        except all_errors as exc:
+            raise FTPError(f"FTP connect/login failed for {cfg.host}: {exc}") from exc
+        return self
+
+    def disconnect(self):
+        if self._ftp is not None:
+            try:
+                self._ftp.quit()
+            except Exception:
+                try:
+                    self._ftp.close()
+                except Exception:
+                    pass
+            self._emit(logging.INFO, f"Disconnected from {self.config.host}.")
+            self._ftp = None
+
+    close = disconnect
+
+    def _require(self) -> FTP:
+        if self._ftp is None:
+            raise FTPError("Not connected. Call connect() first.")
+        return self._ftp
+
+    # --- operations ---
+    def listdir(self, path: str = ".", *, safe=None):
+        return self._guard("listdir", lambda: self._require().nlst(path), safe=safe)
+
+    def cwd(self, path: str, *, safe=None):
+        return self._guard("cwd", lambda: self._require().cwd(path), safe=safe)
+
+    def pwd(self, *, safe=None):
+        return self._guard("pwd", lambda: self._require().pwd(), safe=safe)
+
+    def mkdir(self, path: str, *, safe=None):
+        return self._guard("mkdir", lambda: self._require().mkd(path), safe=safe)
+
+    def remove(self, path: str, *, safe=None):
+        return self._guard("remove", lambda: self._require().delete(path), safe=safe)
+
+    def rmdir(self, path: str, *, safe=None):
+        return self._guard("rmdir", lambda: self._require().rmd(path), safe=safe)
+
+    def rename(self, old: str, new: str, *, safe=None):
+        return self._guard("rename", lambda: self._require().rename(old, new), safe=safe)
+
+    def size(self, path: str, *, safe=None):
+        return self._guard("size", lambda: self._require().size(path), safe=safe)
+
+    def exists(self, path: str, *, safe=None):
+        def _do():
+            try:
+                self._require().size(path)
+                return True
+            except error_perm:
+                # size() fails on dirs; fall back to a listing probe.
+                try:
+                    return path in self._require().nlst(os.path.dirname(path) or ".")
+                except all_errors:
+                    return False
+        return self._guard("exists", _do, safe=safe)
+
+    def push(self, local_path: str, remote_path: str, *, callback=None, safe=None):
+        """Upload a single file (STOR)."""
+        def _do():
+            lp = os.path.expanduser(local_path)
+            if not os.path.isfile(lp):
+                raise FTPError(f"Local file not found: {lp}")
+            start = time.time()
+            self._emit(logging.INFO, f"PUSH {lp} -> {remote_path}")
+            try:
+                with open(lp, "rb") as fh:
+                    self._require().storbinary(f"STOR {remote_path}", fh,
+                                               callback=callback)
+            except all_errors as exc:
+                raise FTPError(f"FTP upload failed: {exc}") from exc
+            return TransferResult(lp, remote_path, "push", "ftp",
+                                  os.path.getsize(lp), time.time() - start)
+        return self._guard("push", _do, safe=safe)
+
+    def pull(self, remote_path: str, local_path: str, *, callback=None, safe=None):
+        """Download a single file (RETR)."""
+        def _do():
+            lp = os.path.expanduser(local_path)
+            parent = os.path.dirname(lp)
+            if parent and not os.path.exists(parent):
+                os.makedirs(parent, exist_ok=True)
+            start = time.time()
+            self._emit(logging.INFO, f"PULL {remote_path} -> {lp}")
+            try:
+                with open(lp, "wb") as fh:
+                    def _cb(data):
+                        fh.write(data)
+                        if callback:
+                            callback(len(data))
+                    self._require().retrbinary(f"RETR {remote_path}", _cb)
+            except all_errors as exc:
+                raise FTPError(f"FTP download failed: {exc}") from exc
+            return TransferResult(remote_path, lp, "pull", "ftp",
+                                  os.path.getsize(lp), time.time() - start)
+        return self._guard("pull", _do, safe=safe)
+
+    def __enter__(self):
+        r = self.connect()
+        if isinstance(r, OperationResult) and not r.success:
+            raise r.error or FTPError("connect failed")
+        return self
+
+    def __exit__(self, *exc):
+        self.disconnect()

ssh_handler/pool.py

@@ -0,0 +1,103 @@
+"""
+Run the same operation across many hosts in parallel — useful for test labs
+and fleet operations where speed matters. Each host gets its own SSHHandler.
+"""
+
+from __future__ import annotations
+
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Callable, Optional, Sequence
+
+from .config import SSHConfig
+from .core import SSHHandler
+from .results import OperationResult
+
+
+class SSHPool:
+    """
+    >>> pool = SSHPool([cfg1, cfg2, cfg3], max_workers=8)
+    >>> results = pool.run("uptime")        # {host: OperationResult}
+    >>> pool.push("a.bin", "/tmp/a.bin")
+    >>> pool.close()
+    """
+
+    def __init__(self, configs: Sequence[SSHConfig], *, max_workers: int = 10,
+                 log_callback: Optional[Callable[[str], None]] = None):
+        self.handlers = {
+            cfg.host: SSHHandler(cfg, log_callback=log_callback, safe=True)
+            for cfg in configs
+        }
+        self.max_workers = max_workers
+
+    def _fanout(self, method: str, *args, **kwargs) -> dict:
+        results: dict[str, OperationResult] = {}
+        with ThreadPoolExecutor(max_workers=self.max_workers) as ex:
+            futures = {}
+            for host, handler in self.handlers.items():
+                # ensure each worker is connected first
+                def _job(h=handler):
+                    if not h.is_connected:
+                        c = h.connect()
+                        if isinstance(c, OperationResult) and not c.success:
+                            return c
+                    return getattr(h, method)(*args, **kwargs)
+                futures[ex.submit(_job)] = host
+            for fut in as_completed(futures):
+                host = futures[fut]
+                try:
+                    results[host] = fut.result()
+                except Exception as exc:  # pragma: no cover
+                    results[host] = OperationResult(False, method, error=exc)
+        return results
+
+    def connect(self) -> dict:
+        return self._fanout_connect()
+
+    def _fanout_connect(self) -> dict:
+        results = {}
+        with ThreadPoolExecutor(max_workers=self.max_workers) as ex:
+            futures = {ex.submit(h.connect): host
+                       for host, h in self.handlers.items()}
+            for fut in as_completed(futures):
+                results[futures[fut]] = fut.result()
+        return results
+
+    def run(self, command: str, **kwargs) -> dict:
+        return self._fanout("run", command, **kwargs)
+
+    def push(self, local_path: str, remote_path: str, **kwargs) -> dict:
+        return self._fanout("push", local_path, remote_path, **kwargs)
+
+    def pull(self, remote_path: str, local_path_template: str, **kwargs) -> dict:
+        """
+        Pull from every host. ``local_path_template`` may contain ``{host}`` so
+        downloads don't collide, e.g. ``"logs/{host}_syslog.txt"``.
+        """
+        results = {}
+        with ThreadPoolExecutor(max_workers=self.max_workers) as ex:
+            futures = {}
+            for host, handler in self.handlers.items():
+                local = local_path_template.format(host=host)
+
+                def _job(h=handler, l=local):
+                    if not h.is_connected:
+                        c = h.connect()
+                        if isinstance(c, OperationResult) and not c.success:
+                            return c
+                    return h.pull(remote_path, l, **kwargs)
+                futures[ex.submit(_job)] = host
+            for fut in as_completed(futures):
+                results[futures[fut]] = fut.result()
+        return results
+
+    def close(self) -> None:
+        for h in self.handlers.values():
+            h.disconnect()
+
+    def __enter__(self):
+        self.connect()
+        return self
+
+    def __exit__(self, *exc):
+        self.close()

ssh_handler/pyqt_worker.py

@@ -0,0 +1,94 @@
+"""
+PyQt5 integration helpers.
+
+Import is guarded so the rest of the package works even where PyQt5 is absent
+(e.g. on a headless CI runner). Import names from here only inside your GUI.
+
+A worker that runs SSH work off the GUI thread, streams log lines to a signal,
+and never lets an SSH error crash the event loop (the handler runs in safe
+mode, so failures come back as OperationResult).
+
+Usage sketch::
+
+    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", domain="EU",
+                                 username="nkennedy", password=secret))
+    thread = QThread()
+    worker.moveToThread(thread)
+    worker.log.connect(text_edit.append)
+    worker.command_done.connect(on_done)
+    thread.started.connect(lambda: worker.run_command("uptime"))
+    thread.start()
+"""
+
+from __future__ import annotations
+
+try:
+    from PyQt5.QtCore import QObject, pyqtSignal
+except Exception as exc:  # pragma: no cover
+    raise ImportError(
+        "ssh_handler.pyqt_worker requires PyQt5. Install it with: pip install PyQt5"
+    ) from exc
+
+from .config import SSHConfig
+from .core import SSHHandler
+from .results import OperationResult
+
+
+class SSHWorker(QObject):
+    """A QObject wrapper around SSHHandler (safe mode) for use in a QThread."""
+
+    log = pyqtSignal(str)                 # every log line (already secret-masked)
+    connected = pyqtSignal(bool)          # connect() finished
+    command_done = pyqtSignal(object)     # CommandResult or Exception
+    transfer_done = pyqtSignal(object)    # TransferResult or Exception
+    progress = pyqtSignal(int, int)       # bytes_done, bytes_total
+    error = pyqtSignal(str)               # human-readable error
+    finished = pyqtSignal()               # work item complete
+
+    def __init__(self, config: SSHConfig, parent=None):
+        super().__init__(parent)
+        self.ssh = SSHHandler(config, log_callback=self.log.emit, safe=True)
+
+    def _resolve(self, res: OperationResult):
+        """Emit error if an OperationResult failed; return its value or None."""
+        if isinstance(res, OperationResult):
+            if not res.success:
+                self.error.emit(str(res.error))
+                return None
+            return res.value
+        return res
+
+    # --- slots (call via signals/queued connection) ---
+    def connect_host(self):
+        res = self.ssh.connect()
+        ok = bool(res)
+        if not ok and isinstance(res, OperationResult):
+            self.error.emit(str(res.error))
+        self.connected.emit(ok)
+        self.finished.emit()
+
+    def run_command(self, command: str, timeout: float = None):
+        res = self.ssh.run(command, timeout=timeout)
+        value = self._resolve(res)
+        self.command_done.emit(value if value is not None else res)
+        self.finished.emit()
+
+    def push(self, local_path: str, remote_path: str, recursive: bool = False):
+        res = self.ssh.push(local_path, remote_path, recursive=recursive,
+                            callback=lambda done, total: self.progress.emit(done, total))
+        self.transfer_done.emit(self._resolve(res))
+        self.finished.emit()
+
+    def pull(self, remote_path: str, local_path: str, recursive: bool = False):
+        res = self.ssh.pull(remote_path, local_path, recursive=recursive,
+                            callback=lambda done, total: self.progress.emit(done, total))
+        self.transfer_done.emit(self._resolve(res))
+        self.finished.emit()
+
+    def disconnect_host(self):
+        self.ssh.disconnect()
+        self.finished.emit()