remote-cmd-manager 2.2.0__tar.gz → 2.4.0__tar.gz

{remote_cmd_manager-2.2.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.2.0
+Version: 2.4.0
 Summary: Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more.
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT
@@ -18,6 +18,9 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: System :: Networking
 Classifier: Environment :: Console
@@ -86,27 +89,30 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.2.0 Release Highlights
+## v2.4.0 Release Highlights
 
-v2.2.0 bounds batch-execution resource usage, makes concurrent SQLite writers safe, tightens
-retry classification, and hardens the release pipeline. See the
+v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging
+handler resources, with default behavior and public result schemas unchanged. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### Resource & Reliability
+### Bounded Batch Output
 
-- Internal batch pools are now created lazily per host, capped at one connection, and closed as soon as that host (including all retries) finishes; batch-wide live internal connections are bounded by `max_concurrency` instead of retaining one idle connection per host until the batch ends.
-- SQLite writes now use `BEGIN IMMEDIATE` with a configurable `busy_timeout` (default 5000 ms), and the initial `journal_mode=WAL` switch is retried; concurrent `remote-cmd` processes writing the same `hosts.db` no longer fail with `database is locked` or lose updates. Schema and `db_version` are unchanged.
-- Pool closure raises the new `PoolClosedError` (still catchable as `RuntimeError`); retry classification is corrected so bare `RuntimeError` is retryable again (v2.0 behavior) while pool closure remains non-retryable. Typed permanent and transient errors are unchanged.
+- `BatchExecutor` / `AsyncBatchExecutor` accept an optional `max_output_bytes` (default `None`): `None` keeps full `stdout`/`stderr`, while a positive value caps each host's retained streams and appends a `[output truncated: N bytes omitted]` marker.
+- Truncation is deterministic and UTF-8 byte-boundary safe, applies to `stdout` and `stderr` independently, and never changes command success/failure or exit codes.
+- The cap bounds the retained `BatchResult`; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.
 
-### Release Engineering
+### Reliability
 
-- Publish workflow: artifact actions aligned, run-scoped artifact names, duplicate version publication now fails instead of being skipped, `twine check` validates distributions, and the release tag is verified against the package version. Trusted Publishing and the GitHub Release → PyPI flow are unchanged.
-- CI documentation drift detection: `docs/api` is regenerated and compared on relevant changes, failing when tracked generated docs are stale (`pdoc` pinned to `15.0.4` on Python 3.12).
-- Release metadata validation: a lightweight gate checks the single-source version, the `pyproject.toml` dynamic-version attribute, `[Unreleased]` and matching `[x.y.z]` CHANGELOG headings, and (on release) that the git tag matches the package version.
+- `setup_logging` now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
+- Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).
+
+### Compatibility
+
+- Default behavior is unchanged (`max_output_bytes=None` retains full output) and the public `BatchResult` / `BatchHostResult` schemas are unchanged.
 
 ## Table of Contents
 
-- [v2.2.0 Release Highlights](#v220-release-highlights)
+- [v2.4.0 Release Highlights](#v240-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -254,7 +260,7 @@ with SSHClient(config) as client:
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
-| **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
+| **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |

{remote_cmd_manager-2.2.0 → remote_cmd_manager-2.4.0}/README.md

@@ -36,27 +36,30 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.2.0 Release Highlights
+## v2.4.0 Release Highlights
 
-v2.2.0 bounds batch-execution resource usage, makes concurrent SQLite writers safe, tightens
-retry classification, and hardens the release pipeline. See the
+v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging
+handler resources, with default behavior and public result schemas unchanged. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### Resource & Reliability
+### Bounded Batch Output
 
-- Internal batch pools are now created lazily per host, capped at one connection, and closed as soon as that host (including all retries) finishes; batch-wide live internal connections are bounded by `max_concurrency` instead of retaining one idle connection per host until the batch ends.
-- SQLite writes now use `BEGIN IMMEDIATE` with a configurable `busy_timeout` (default 5000 ms), and the initial `journal_mode=WAL` switch is retried; concurrent `remote-cmd` processes writing the same `hosts.db` no longer fail with `database is locked` or lose updates. Schema and `db_version` are unchanged.
-- Pool closure raises the new `PoolClosedError` (still catchable as `RuntimeError`); retry classification is corrected so bare `RuntimeError` is retryable again (v2.0 behavior) while pool closure remains non-retryable. Typed permanent and transient errors are unchanged.
+- `BatchExecutor` / `AsyncBatchExecutor` accept an optional `max_output_bytes` (default `None`): `None` keeps full `stdout`/`stderr`, while a positive value caps each host's retained streams and appends a `[output truncated: N bytes omitted]` marker.
+- Truncation is deterministic and UTF-8 byte-boundary safe, applies to `stdout` and `stderr` independently, and never changes command success/failure or exit codes.
+- The cap bounds the retained `BatchResult`; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.
 
-### Release Engineering
+### Reliability
 
-- Publish workflow: artifact actions aligned, run-scoped artifact names, duplicate version publication now fails instead of being skipped, `twine check` validates distributions, and the release tag is verified against the package version. Trusted Publishing and the GitHub Release → PyPI flow are unchanged.
-- CI documentation drift detection: `docs/api` is regenerated and compared on relevant changes, failing when tracked generated docs are stale (`pdoc` pinned to `15.0.4` on Python 3.12).
-- Release metadata validation: a lightweight gate checks the single-source version, the `pyproject.toml` dynamic-version attribute, `[Unreleased]` and matching `[x.y.z]` CHANGELOG headings, and (on release) that the git tag matches the package version.
+- `setup_logging` now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
+- Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).
+
+### Compatibility
+
+- Default behavior is unchanged (`max_output_bytes=None` retains full output) and the public `BatchResult` / `BatchHostResult` schemas are unchanged.
 
 ## Table of Contents
 
-- [v2.2.0 Release Highlights](#v220-release-highlights)
+- [v2.4.0 Release Highlights](#v240-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -204,7 +207,7 @@ with SSHClient(config) as client:
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
-| **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
+| **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |

{remote_cmd_manager-2.2.0 → remote_cmd_manager-2.4.0}/pyproject.toml

@@ -22,6 +22,9 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: System :: Systems Administration",
     "Topic :: System :: Networking",
     "Environment :: Console",

{remote_cmd_manager-2.2.0 → remote_cmd_manager-2.4.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.2.0（单一真相源见 remote_cmd._version）
+Version: 2.4.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 

{remote_cmd_manager-2.2.0 → remote_cmd_manager-2.4.0}/remote_cmd/_version.py

@@ -9,4 +9,4 @@
 - ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
 """
 
-__version__ = "2.2.0"
+__version__ = "2.4.0"

{remote_cmd_manager-2.2.0 → remote_cmd_manager-2.4.0}/remote_cmd/core/async_ssh_client.py

@@ -14,9 +14,12 @@
 - 密码、密钥等敏感信息不入日志（沿用项目 SensitiveDataFilter 规范）。
 """
 
+import asyncio
+import contextlib
 import logging
 import shlex
 import stat
+from collections.abc import Awaitable, Callable, Sequence
 from pathlib import Path
 from typing import Any, Optional
 
@@ -34,6 +37,7 @@ from remote_cmd.utils.exceptions import (
     SSHConnectionError,
     SSHFileTransferError,
     SSHTimeoutError,
+    ValidationError,
 )
 
 logger = logging.getLogger(__name__)
@@ -286,45 +290,169 @@ class AsyncSSHClient:
     # ------------------------------------------------------------------
     # SFTP / 文件传输
     # ------------------------------------------------------------------
-    async def _get_sftp(self) -> asyncssh.SFTPClient:
+    async def _get_sftp(self, timeout: Optional[float] = None) -> asyncssh.SFTPClient:
+        """获取 SFTP 客户端（延迟初始化）。
+
+        v2.3：打开 SFTP channel 本身也受有效超时约束，避免握手阶段永久挂起。
+        """
         conn = await self._get_conn()
         if self._sftp is None:
+            effective = self._effective_sftp_timeout(timeout)
             try:
-                self._sftp = await conn.start_sftp_client()
+                self._sftp = await asyncio.wait_for(conn.start_sftp_client(), timeout=effective)
+            except asyncio.TimeoutError as e:
+                raise SSHFileTransferError(
+                    f"failed to open SFTP channel: timed out after {effective:g} seconds"
+                ) from e
             except (OSError, asyncssh.Error) as e:
                 raise SSHFileTransferError(f"failed to open SFTP channel: {e}") from e
         return self._sftp
 
-    async def upload_file(self, local_path: str, remote_path: str) -> None:
-        """异步上传本地文件到远程服务器。"""
-        sftp = await self._get_sftp()
+    def _effective_sftp_timeout(self, timeout: Optional[float]) -> float:
+        """返回 SFTP 操作的有效 inactivity 超时（秒）。
+
+        显式 timeout 优先，否则回退到 ``ConnectionConfig.timeout``。
+        """
+        if timeout is not None:
+            if timeout <= 0:
+                raise ValidationError(f"timeout must be > 0, got: {timeout}")
+            return timeout
+        return self.config.timeout
+
+    def _discard_sftp(self) -> None:
+        """关闭并丢弃缓存的 SFTP 会话（超时后防止复用可能失步的会话）。"""
+        sftp, self._sftp = self._sftp, None
+        if sftp is not None:
+            with contextlib.suppress(Exception):
+                sftp.exit()
+
+    async def _run_sftp_operation(
+        self,
+        operation: Callable[[Callable[..., None]], Awaitable[Any]],
+        timeout: Optional[float],
+        description: str,
+    ) -> Any:
+        """运行 SFTP 操作并施加 inactivity（静默）超时。
+
+        asyncssh 的 SFTP API 没有原生超时参数，因此使用 watchdog：
+        ``operation`` 收到一个 progress 回调（传给 ``put``/``get`` 的
+        ``progress_handler``），每次有数据进展就刷新时间戳；超过有效超时
+        没有任何进展则取消操作、丢弃失步的 SFTP 会话并抛出
+        ``SSHFileTransferError``。只要数据持续流动，长时间传输不会被打断。
+        """
+        effective = self._effective_sftp_timeout(timeout)
+        loop = asyncio.get_running_loop()
+        last_activity = loop.time()
+
+        def _mark_progress(*_args: Any) -> None:
+            nonlocal last_activity
+            last_activity = loop.time()
+
+        task = asyncio.ensure_future(operation(_mark_progress))
+        interval = min(0.5, max(effective / 10.0, 0.01))
+        cancelled: Optional[asyncio.CancelledError] = None
+        try:
+            while True:
+                done, _pending = await asyncio.wait({task}, timeout=interval)
+                if task in done:
+                    return task.result()
+                if loop.time() - last_activity >= effective:
+                    break
+        except asyncio.CancelledError as exc:
+            # 外层取消：记录后统一走清理路径（不在此处 await，避免
+            # 取消事件再次进入本处理器）
+            cancelled = exc
+
+        # 统一清理：立即丢弃可能失步的 SFTP 会话；取消并等待子任务收尾。
+        # shield 确保清理期间到达的再次取消只打断"等待"本身，而不会
+        # 把清理过程转换成超时错误或被整体吞掉。
+        self._discard_sftp()
+        task.cancel()
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            if not task.cancelled():
+                # 清理期间外层再次取消：保留取消语义
+                raise
+        except Exception:  # noqa: BLE001 - 子任务失败不应掩盖超时/取消语义
+            pass
+
+        if cancelled is not None:
+            raise cancelled
+        raise SSHFileTransferError(
+            f"{description} timed out after {effective:g} seconds of inactivity"
+        )
+
+    async def upload_file(
+        self,
+        local_path: str,
+        remote_path: str,
+        timeout: Optional[float] = None,
+    ) -> None:
+        """异步上传本地文件到远程服务器。
+
+        Args:
+            local_path: 本地文件路径
+            remote_path: 远程目标路径
+            timeout: inactivity 超时（秒）；None 表示使用
+                ``ConnectionConfig.timeout``。静默超过该时长即中止
+        """
+        sftp = await self._get_sftp(timeout)
         local_file = Path(local_path)
         if not local_file.exists():
             raise SSHFileTransferError(f"Local file not found: {local_path}")
         logger.info(f"uploading file: {local_path} -> {remote_path}")
+
+        async def _operation(progress: Callable[..., None]) -> None:
+            await sftp.put(str(local_file), remote_path, progress_handler=progress)
+
         try:
-            await sftp.put(str(local_file), remote_path)
+            await self._run_sftp_operation(_operation, timeout, "file upload")
         except (OSError, asyncssh.Error) as e:
             raise SSHFileTransferError(f"file upload failed: {e}") from e
         logger.info("file upload finished")
 
-    async def download_file(self, remote_path: str, local_path: str) -> None:
-        """异步从远程服务器下载文件到本地。"""
-        sftp = await self._get_sftp()
+    async def download_file(
+        self,
+        remote_path: str,
+        local_path: str,
+        timeout: Optional[float] = None,
+    ) -> None:
+        """异步从远程服务器下载文件。
+
+        Args:
+            remote_path: 远程文件路径
+            local_path: 本地目标路径
+            timeout: inactivity 超时（秒）；None 表示使用
+                ``ConnectionConfig.timeout``。静默超过该时长即中止
+        """
+        sftp = await self._get_sftp(timeout)
         local_file = Path(local_path)
         local_file.parent.mkdir(parents=True, exist_ok=True)
         logger.info(f"downloading file: {remote_path} -> {local_path}")
+
+        async def _operation(progress: Callable[..., None]) -> None:
+            await sftp.get(remote_path, str(local_file), progress_handler=progress)
+
         try:
-            await sftp.get(remote_path, str(local_file))
+            await self._run_sftp_operation(_operation, timeout, "file download")
         except (OSError, asyncssh.Error) as e:
             raise SSHFileTransferError(f"file download failed: {e}") from e
         logger.info("file download finished")
 
-    async def list_remote_directory(self, remote_path: str = ".") -> list[RemoteFileEntry]:
+    async def list_remote_directory(
+        self,
+        remote_path: str = ".",
+        timeout: Optional[float] = None,
+    ) -> list[RemoteFileEntry]:
         """异步列出远程目录内容（结构与同步 SSHClient 一致）。"""
-        sftp = await self._get_sftp()
+        sftp = await self._get_sftp(timeout)
+
+        async def _operation(_progress: Callable[..., None]) -> Sequence[Any]:
+            return await sftp.readdir(remote_path)
+
         try:
-            names = await sftp.readdir(remote_path)
+            names = await self._run_sftp_operation(_operation, timeout, "list remote directory")
         except (OSError, asyncssh.Error) as e:
             raise SSHFileTransferError(f"failed to list remote directory: {e}") from e