sshkit 0.1.0__py3-none-any.whl

sshkit/__init__.py

@@ -0,0 +1,19 @@
+"""安全的 SSH 客户端工具."""
+
+from .client import (
+    CommandResult,
+    SshClient,
+    SshError,
+    SshErrorKind,
+    SshLoopHandler,
+)
+
+__all__ = [
+    "CommandResult",
+    "SshClient",
+    "SshError",
+    "SshErrorKind",
+    "SshLoopHandler",
+]
+
+__version__ = "0.1.0"

sshkit/client.py

@@ -0,0 +1,498 @@
+import socket
+import threading
+import time
+from dataclasses import dataclass
+from enum import Enum
+from math import isfinite
+from typing import Dict, Optional
+
+import paramiko
+
+
+# =========================
+# SSH 错误类型定义
+# =========================
+class SshErrorKind(Enum):
+    NOT_CONNECTED = "not_connected"
+    CONNECTION = "connection"
+    AUTHENTICATION = "authentication"
+    KEY_LOAD = "key_load"
+    HOST_KEY = "host_key"
+    TIMEOUT = "timeout"
+    TRANSPORT = "transport"
+
+
+# =========================
+# SSH 统一异常定义
+# 使用 kind 区分错误类型,避免定义过多异常子类
+# =========================
+class SshError(Exception):
+    def __init__(
+        self,
+        kind: SshErrorKind,
+        message: str,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message)
+        self.kind = kind
+        self.message = message
+        self.cause = cause
+
+    def __str__(self) -> str:
+        return self.message
+
+    def title_text(self) -> str:
+        if self.kind == SshErrorKind.AUTHENTICATION:
+            return "SSH 认证失败"
+        if self.kind == SshErrorKind.KEY_LOAD:
+            return "SSH 私钥加载失败"
+        if self.kind == SshErrorKind.HOST_KEY:
+            return "SSH 主机密钥校验失败"
+        if self.kind == SshErrorKind.CONNECTION:
+            return "SSH 连接失败"
+        if self.kind == SshErrorKind.NOT_CONNECTED:
+            return "SSH 尚未连接"
+        if self.kind == SshErrorKind.TIMEOUT:
+            return "SSH 操作超时"
+        if self.kind == SshErrorKind.TRANSPORT:
+            return "SSH 传输异常"
+        return "SSH 未知异常"
+
+    def build_alert_message(self, host_name: str, ip: str, port: int) -> str:
+        return f"{self.title_text()}: ({host_name} {ip}:{port}), 错误: {self}"
+
+
+# =========================
+# 命令执行结果
+# =========================
+@dataclass(frozen=True)
+class CommandResult:
+    exit_status: int
+    stdout_text: str
+    stderr_text: str
+
+
+# =========================
+# 循环处理器基类
+# handler 自己保存首次运行状态和上一轮错误
+# run 和 on_error 统一签名
+# =========================
+class SshLoopHandler:
+    def __init__(self) -> None:
+        self.is_first_run = True
+        self.last_error: Optional[Exception] = None
+
+    def run(self, ssh_client: "SshClient") -> None:
+        raise NotImplementedError("子类必须实现 run 方法")
+
+    def on_error(self, ssh_client: "SshClient") -> None:
+        raise NotImplementedError("子类必须实现 on_error 方法")
+
+
+class _RejectUnknownHostKeyPolicy(paramiko.RejectPolicy):
+    def missing_host_key(self, client, hostname, key) -> None:
+        raise SshError(
+            kind=SshErrorKind.HOST_KEY,
+            message=f"SSH 主机密钥未在 known_hosts 中找到: {hostname}",
+        )
+
+
+class SshClient:
+    def __init__(
+        self,
+        hostname: str,
+        ip: str,
+        port: int,
+        username: str,
+        password: Optional[str] = None,
+        key_path: Optional[str] = None,
+        connect_timeout_seconds: float = 3.0,
+        keepalive_interval_seconds: int = 15,
+        key_passphrase: Optional[str] = None,
+        known_hosts_path: Optional[str] = None,
+    ) -> None:
+        if password is None and key_path is None:
+            raise ValueError("必须提供 password 或 key_path")
+        if password is not None and key_path is not None:
+            raise ValueError("password 和 key_path 只能提供一个")
+        if not 1 <= port <= 65535:
+            raise ValueError("port 必须在 1 到 65535 之间")
+        if not isfinite(connect_timeout_seconds) or connect_timeout_seconds <= 0:
+            raise ValueError("connect_timeout_seconds 必须大于 0")
+        if not isfinite(keepalive_interval_seconds) or keepalive_interval_seconds < 0:
+            raise ValueError("keepalive_interval_seconds 不能小于 0")
+
+        self.hostname = hostname
+        self.ip = ip
+        self.port = port
+        self._username = username
+        self._password = password
+        self._key_path = key_path
+        self._key_passphrase = key_passphrase
+        self._known_hosts_path = known_hosts_path
+        self._connect_timeout_seconds = connect_timeout_seconds
+        self._keepalive_interval_seconds = keepalive_interval_seconds
+        self._client: Optional[paramiko.SSHClient] = None
+
+    def __enter__(self) -> "SshClient":
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    # =========================
+    # 连接状态检查
+    # 这里只做轻量检查,不保证下一次操作一定成功
+    # =========================
+    def is_connected(self) -> bool:
+        if self._client is None:
+            return False
+        transport = self._client.get_transport()
+        return transport is not None and transport.is_active()
+
+    # =========================
+    # 建立 SSH 连接
+    # 这里只负责建立连接,不负责重试策略
+    # =========================
+    def connect(self) -> None:
+        if self.is_connected():
+            return
+        if self._client is not None:
+            self._close_quietly(self._client)
+            self._client = None
+
+        client = paramiko.SSHClient()
+        client.set_missing_host_key_policy(_RejectUnknownHostKeyPolicy())
+        connect_kwargs = {
+            "hostname": self.ip,
+            "port": self.port,
+            "username": self._username,
+            "timeout": self._connect_timeout_seconds,
+            "auth_timeout": self._connect_timeout_seconds,
+            "banner_timeout": self._connect_timeout_seconds,
+            "allow_agent": False,
+            "look_for_keys": False,
+        }
+
+        try:
+            try:
+                client.load_system_host_keys()
+                if self._known_hosts_path is not None:
+                    client.load_host_keys(self._known_hosts_path)
+            except (OSError, UnicodeError) as exc:
+                raise SshError(
+                    kind=SshErrorKind.CONNECTION,
+                    message=f"SSH known_hosts 配置失败: {exc}",
+                    cause=exc,
+                ) from exc
+            except paramiko.hostkeys.InvalidHostKey as exc:
+                raise SshError(
+                    kind=SshErrorKind.HOST_KEY,
+                    message=f"SSH known_hosts 内容无效: {exc}",
+                    cause=exc,
+                ) from exc
+
+            if self._key_path is not None:
+                connect_kwargs["pkey"] = self._load_private_key(
+                    self._key_path,
+                    self._key_passphrase,
+                )
+            else:
+                connect_kwargs["password"] = self._password
+
+            client.connect(**connect_kwargs)
+            transport = client.get_transport()
+            if transport is not None:
+                transport.set_keepalive(self._keepalive_interval_seconds)
+            self._client = client
+
+        except paramiko.AuthenticationException as exc:
+            self._close_quietly(client)
+            raise SshError(
+                kind=SshErrorKind.AUTHENTICATION,
+                message=f"SSH 认证失败: {exc}",
+                cause=exc,
+            ) from exc
+        except paramiko.BadHostKeyException as exc:
+            self._close_quietly(client)
+            raise SshError(
+                kind=SshErrorKind.HOST_KEY,
+                message=f"SSH 主机密钥校验失败: {exc}",
+                cause=exc,
+            ) from exc
+        except SshError:
+            self._close_quietly(client)
+            raise
+        except socket.timeout as exc:
+            self._close_quietly(client)
+            raise SshError(
+                kind=SshErrorKind.TIMEOUT,
+                message=f"SSH 连接超时: {exc}",
+                cause=exc,
+            ) from exc
+        except (socket.error, paramiko.SSHException) as exc:
+            self._close_quietly(client)
+            raise SshError(
+                kind=SshErrorKind.CONNECTION,
+                message=f"SSH 连接失败: {exc}",
+                cause=exc,
+            ) from exc
+
+    # =========================
+    # 关闭 SSH 连接
+    # 保持幂等,允许重复调用
+    # =========================
+    def close(self) -> None:
+        if self._client is not None:
+            self._close_quietly(self._client)
+            self._client = None
+
+    # =========================
+    # 执行远端命令
+    # 不自动连接,不自动重试,不自动关闭 SSH client
+    # =========================
+    def execute(
+        self,
+        command: str,
+        env: Optional[Dict[str, str]] = None,
+        timeout_seconds: Optional[float] = None,
+    ) -> CommandResult:
+        if (
+            timeout_seconds is not None
+            and (not isfinite(timeout_seconds) or timeout_seconds <= 0)
+        ):
+            raise ValueError("timeout_seconds 必须大于 0")
+        if self._client is None or not self.is_connected():
+            raise SshError(
+                kind=SshErrorKind.NOT_CONNECTED,
+                message="SSH 连接尚未建立或已失活,请由上层决定是否重连",
+            )
+
+        stdin = None
+        channel = None
+        timeout_timer = None
+        timed_out = threading.Event()
+        deadline = (
+            time.monotonic() + timeout_seconds
+            if timeout_seconds is not None
+            else None
+        )
+
+        try:
+            transport = self._client.get_transport()
+            if transport is None or not transport.is_active():
+                raise SshError(
+                    kind=SshErrorKind.NOT_CONNECTED,
+                    message="SSH 连接尚未建立或已失活,请由上层决定是否重连",
+                )
+
+            open_timeout = (
+                max(0.0, deadline - time.monotonic())
+                if deadline is not None
+                else None
+            )
+            if deadline is not None:
+                timeout_timer = threading.Timer(
+                    open_timeout,
+                    self._abort_client_on_timeout,
+                    args=(self._client, timed_out),
+                )
+                timeout_timer.daemon = True
+                timeout_timer.start()
+
+            channel = transport.open_session(timeout=open_timeout)
+            remaining_timeout = (
+                max(0.0, deadline - time.monotonic())
+                if deadline is not None
+                else None
+            )
+            if timed_out.is_set() or self._deadline_expired(deadline):
+                raise self._command_timeout(command)
+
+            channel.settimeout(remaining_timeout)
+            if env:
+                channel.update_environment(env)
+            channel.exec_command(command)
+            stdin = channel.makefile_stdin("wb", -1)
+            self._close_quietly(stdin)
+
+            stdout_chunks = bytearray()
+            stderr_chunks = bytearray()
+            while True:
+                for stdout_read_attempt in range(16):
+                    if not channel.recv_ready():
+                        break
+                    stdout_chunks.extend(channel.recv(65536))
+                    if timed_out.is_set() or self._deadline_expired(deadline):
+                        raise self._command_timeout(command)
+
+                for stderr_read_attempt in range(16):
+                    if not channel.recv_stderr_ready():
+                        break
+                    stderr_chunks.extend(channel.recv_stderr(65536))
+                    if timed_out.is_set() or self._deadline_expired(deadline):
+                        raise self._command_timeout(command)
+
+                if timed_out.is_set():
+                    raise self._command_timeout(command)
+
+                if channel.exit_status_ready() or channel.closed:
+                    continue_reading = channel.recv_ready() or channel.recv_stderr_ready()
+                    if not continue_reading:
+                        break
+
+                if timed_out.is_set() or self._deadline_expired(deadline):
+                    raise self._command_timeout(command)
+                time.sleep(0.01)
+
+            if timed_out.is_set() or self._deadline_expired(deadline):
+                raise self._command_timeout(command)
+
+            exit_status = channel.recv_exit_status()
+            if exit_status < 0:
+                raise SshError(
+                    kind=SshErrorKind.TRANSPORT,
+                    message="SSH 命令未返回有效退出状态",
+                )
+            return CommandResult(
+                exit_status=exit_status,
+                stdout_text=bytes(stdout_chunks).decode("utf-8", errors="replace"),
+                stderr_text=bytes(stderr_chunks).decode("utf-8", errors="replace"),
+            )
+
+        except socket.timeout as exc:
+            raise SshError(
+                kind=SshErrorKind.TIMEOUT,
+                message=f"SSH 命令执行超时: {exc}",
+                cause=exc,
+            ) from exc
+        except (socket.error, EOFError, paramiko.SSHException) as exc:
+            if timed_out.is_set() or self._deadline_expired(deadline):
+                raise self._command_timeout(command, exc) from exc
+            raise SshError(
+                kind=SshErrorKind.TRANSPORT,
+                message=f"SSH 传输异常: {exc}",
+                cause=exc,
+            ) from exc
+        finally:
+            if timeout_timer is not None:
+                timeout_timer.cancel()
+            self._close_quietly(channel)
+            self._close_quietly(stdin)
+
+    # =========================
+    # 循环运行入口
+    # handler 自己保存首次运行状态和最近一次错误
+    # =========================
+    def loop_run(
+        self,
+        handler: SshLoopHandler,
+        interval_seconds: float,
+    ) -> None:
+        if not isfinite(interval_seconds):
+            raise ValueError("interval_seconds 必须是有限数值")
+
+        while True:
+            try:
+                if not self.is_connected():
+                    self.connect()
+                handler.run(self)
+                handler.last_error = None
+            except Exception as exc:
+                handler.last_error = exc
+                if isinstance(exc, SshError) and self._should_reset_connection(exc):
+                    self.close()
+                try:
+                    handler.on_error(self)
+                except Exception:
+                    pass
+            finally:
+                handler.is_first_run = False
+
+            if interval_seconds <= 0:
+                break
+            time.sleep(interval_seconds)
+
+    @staticmethod
+    def _deadline_expired(deadline: Optional[float]) -> bool:
+        return deadline is not None and time.monotonic() >= deadline
+
+    @staticmethod
+    def _command_timeout(
+        command: str,
+        cause: Optional[Exception] = None,
+    ) -> SshError:
+        return SshError(
+            kind=SshErrorKind.TIMEOUT,
+            message=f"SSH 命令执行超时: {command}",
+            cause=cause,
+        )
+
+    @staticmethod
+    def _abort_client_on_timeout(
+        client: paramiko.SSHClient,
+        timed_out: threading.Event,
+    ) -> None:
+        timed_out.set()
+        SshClient._close_quietly(client)
+
+    @staticmethod
+    def _close_quietly(resource) -> None:
+        if resource is None:
+            return
+        try:
+            resource.close()
+        except Exception:
+            pass
+
+    # =========================
+    # 判断哪些错误需要重置连接
+    # =========================
+    @staticmethod
+    def _should_reset_connection(exc: SshError) -> bool:
+        return exc.kind in {
+            SshErrorKind.CONNECTION,
+            SshErrorKind.NOT_CONNECTED,
+            SshErrorKind.TIMEOUT,
+            SshErrorKind.TRANSPORT,
+        }
+
+    # =========================
+    # 加载私钥
+    # 依次尝试常见私钥格式
+    # =========================
+    @staticmethod
+    def _load_private_key(
+        key_path: str,
+        key_passphrase: Optional[str] = None,
+    ):
+        key_loaders = [
+            paramiko.Ed25519Key.from_private_key_file,
+            paramiko.RSAKey.from_private_key_file,
+            paramiko.ECDSAKey.from_private_key_file,
+        ]
+        last_error: Optional[Exception] = None
+        password_error: Optional[Exception] = None
+
+        for key_loader in key_loaders:
+            try:
+                return key_loader(key_path, password=key_passphrase)
+            except (FileNotFoundError, PermissionError, OSError) as exc:
+                raise SshError(
+                    kind=SshErrorKind.KEY_LOAD,
+                    message=f"无法读取私钥文件: {key_path}: {exc}",
+                    cause=exc,
+                ) from exc
+            except (paramiko.SSHException, ValueError) as exc:
+                last_error = exc
+                if isinstance(exc, paramiko.PasswordRequiredException):
+                    password_error = exc
+
+        if password_error is not None:
+            last_error = password_error
+        raise SshError(
+            kind=SshErrorKind.KEY_LOAD,
+            message=f"无法加载私钥文件: {key_path}",
+            cause=last_error,
+        ) from last_error

sshkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: sshkit
+Version: 0.1.0
+Summary: 安全的 SSH 客户端工具
+Author: yanguangshaonian
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yanguangshaonian/sshkit
+Project-URL: Repository, https://github.com/yanguangshaonian/sshkit
+Project-URL: Issues, https://github.com/yanguangshaonian/sshkit/issues
+Keywords: ssh,paramiko,remote-command
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paramiko>=3.4
+Dynamic: license-file
+
+# sshkit
+
+一个基于 Paramiko 的 SSH 客户端工具,提供安全的主机密钥校验,远程命令执行,统一异常和循环处理能力.
+
+## 安装
+
+```bash
+python -m pip install sshkit
+```
+
+## 快速使用
+
+SSH 主机密钥默认使用 `RejectPolicy` 校验.连接前,请确保目标主机已存在于系统 `known_hosts` 或指定的文件中.
+
+```python
+from sshkit import SshClient, SshError
+
+client = SshClient(
+	hostname="trade.example.com",
+	ip="192.0.2.10",
+	port=22,
+	username="deploy",
+	key_path="/home/deploy/.ssh/id_ed25519",
+	known_hosts_path="/home/deploy/.ssh/known_hosts",
+)
+
+try:
+	client.connect()
+	result = client.execute("uname -a", timeout_seconds=5.0)
+	print(result.exit_status)
+	print(result.stdout_text)
+finally:
+	client.close()
+```
+
+也可以使用上下文管理器:
+
+```python
+from sshkit import SshClient
+
+with SshClient(
+	hostname="trade.example.com",
+	ip="192.0.2.10",
+	port=22,
+	username="deploy",
+	password="password",
+	known_hosts_path="/home/deploy/.ssh/known_hosts",
+) as client:
+	result = client.execute("hostname", timeout_seconds=5.0)
+```
+
+`password` 和 `key_path` 必须二选一.加密私钥可以通过 `key_passphrase` 传入 passphrase.程序不会自动使用 `ssh-agent` 或本地默认私钥.
+
+## 错误处理
+
+连接和命令错误统一使用 `SshError`,通过 `SshError.kind` 区分错误类型:
+
+```python
+from sshkit import SshError, SshErrorKind
+
+try:
+	client.connect()
+except SshError as error:
+	if error.kind == SshErrorKind.AUTHENTICATION:
+		print("认证失败")
+	elif error.kind == SshErrorKind.HOST_KEY:
+		print("主机密钥校验失败")
+```
+
+## 开发
+
+```bash
+python -m pip install -e .
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+## 发布到 PyPI
+
+项目提供了交互式发布脚本.它会读取项目元数据并提示发布目标,然后检查工具,清理旧产物,运行测试,构建 wheel/sdist,执行 `twine check`,最后上传到选定的仓库.
+
+不要把 PyPI token 写入代码,配置文件或 git.需要认证时,脚本会交给 `twine` 处理.
+
+直接运行并交互选择目标:
+
+```bash
+./publish.sh
+```
+
+也可以直接指定目标:
+
+```bash
+./publish.sh testpypi
+./publish.sh pypi
+```
+
+只构建和校验,不上传:
+
+```bash
+./publish.sh testpypi --dry-run
+```
+
+跳过测试或保留构建产物:
+
+```bash
+./publish.sh testpypi --skip-tests
+./publish.sh testpypi --keep-artifacts
+```
+
+发布流程默认会在退出时清理 `build`、`dist`、`*.egg-info`、`__pycache__`、`.pytest_cache` 和 `*.pyc`. 只清理这些临时文件而不发布:
+
+```bash
+./publish.sh --clean-only
+```
+
+`--keep-build` 仍可作为 `--keep-artifacts` 的兼容别名. 使用 `--keep-artifacts` 时, 发布产物和构建缓存会保留, 便于排查问题.
+
+建议先上传 TestPyPI,再验证安装流程:
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ \
+	--no-deps sshkit==0.1.0
+```
+
+上面的 TestPyPI 安装命令只安装测试仓库中的 `sshkit`.运行库代码前,请确保依赖已经从正式 PyPI 安装:
+
+```bash
+python -m pip install "paramiko>=3.4"
+```
+
+确认 TestPyPI 安装正常后,再执行:
+
+```bash
+./publish.sh pypi
+```
+
+## 许可证
+
+MIT License,详见 [LICENSE](LICENSE).

sshkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sshkit/__init__.py,sha256=8ZOZ5Q6q8b1BR14zb2w2W4_b0IUKqJ9yvlnTpDVaeno,282
+sshkit/client.py,sha256=ZFzmnGx9TG-ua8u6Q_Ex-CI5ROSvOmwdrlxke55MuVw,17303
+sshkit-0.1.0.dist-info/licenses/LICENSE,sha256=-ApOjGox8M1XgXG_tzt5mUo6YmMqh2MMgK74j7xurew,1073
+sshkit-0.1.0.dist-info/METADATA,sha256=pXzXi_296Pp_W518FSE93ImOWSoDpCkwfkVBYBKBjy4,4115
+sshkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sshkit-0.1.0.dist-info/top_level.txt,sha256=46JFXNG8deH1ilYn--xOG_NpohkP03jyJzKmmxEs_Fk,7
+sshkit-0.1.0.dist-info/RECORD,,

sshkit-0.1.0.dist-info/WHEEL

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

sshkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yanguangshaonian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sshkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sshkit