remote-cmd-manager 1.2.3__tar.gz → 2.0.0__tar.gz

{remote_cmd_manager-1.2.3/remote_cmd_manager.egg-info → remote_cmd_manager-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 1.2.3
+Version: 2.0.0
 Summary: SSH 远程服务器管理工具 / Python SSH remote server management tool
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT

{remote_cmd_manager-1.2.3 → remote_cmd_manager-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "remote_cmd_manager"
-version = "1.2.3"
+dynamic = ["version"]
 description = "SSH 远程服务器管理工具 / Python SSH remote server management tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -63,6 +63,9 @@ Download = "https://pypi.org/project/remote_cmd_manager/"
 [project.scripts]
 remote-cmd = "remote_cmd.cli.main:main"
 
+[tool.setuptools.dynamic]
+version = { attr = "remote_cmd._version.__version__" }
+
 [tool.setuptools.packages.find]
 include = ["remote_cmd*"]
 

{remote_cmd_manager-1.2.3 → remote_cmd_manager-2.0.0}/remote_cmd/__init__.py

@@ -52,7 +52,9 @@ Version: 1.2.3
 License: MIT
 """
 
-__version__ = "1.2.3"
+# 版本号单一真相源（见 remote_cmd._version）
+from remote_cmd._version import __version__
+
 __author__ = "Vae-Scrooge"
 __email__ = "vae-scrooge@example.com"
 __license__ = "MIT"

remote_cmd_manager-2.0.0/remote_cmd/_version.py

@@ -0,0 +1,12 @@
+"""
+版本号单一真相源（无任何 import，纯常量）
+
+供 ``remote_cmd/__init__.py`` 与 ``pyproject.toml`` 的 setuptools 动态版本读取。
+
+设计约定：
+- 本模块不 import 任何东西，无副作用——setuptools 通过 ``attr`` 解析版本时
+  不会触发 ``remote_cmd`` 包级 import（避免干净构建环境缺依赖时 ImportError）。
+- ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
+"""
+
+__version__ = "2.0.0"

{remote_cmd_manager-1.2.3 → remote_cmd_manager-2.0.0}/remote_cmd/cli/main.py

@@ -18,6 +18,7 @@ Main commands:
 
 import getpass
 import os
+from pathlib import Path
 from typing import Any, Optional
 
 import click
@@ -77,7 +78,12 @@ def _build_service(config_file: str, storage_backend: Optional[str] = None) -> H
 )
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose output mode")
 @click.pass_context
-def cli(ctx, config: Optional[str], hosts_file_override: Optional[str], verbose: bool):
+def cli(
+    ctx: click.Context,
+    config: Optional[str],
+    hosts_file_override: Optional[str],
+    verbose: bool,
+) -> None:
     """
     Remote CMD - SSH remote server management tool
 
@@ -115,7 +121,7 @@ def cli(ctx, config: Optional[str], hosts_file_override: Optional[str], verbose:
 
 
 @cli.group()
-def host():
+def host() -> None:
     """
     Host management command group
 
@@ -141,7 +147,7 @@ def host():
 @click.option("--description", "-d", default="", help="Host description")
 @click.pass_context
 def host_add(
-    ctx,
+    ctx: click.Context,
     name: str,
     hostname: str,
     username: str,
@@ -149,7 +155,7 @@ def host_add(
     key: Optional[str],
     tag: tuple,
     description: str,
-):
+) -> None:
     """
     Add a new host
 
@@ -207,7 +213,7 @@ def host_add(
 @host.command("list")
 @click.option("--tag", "-t", help="Filter hosts by tag")
 @click.pass_context
-def host_list(ctx, tag: Optional[str]):
+def host_list(ctx: click.Context, tag: Optional[str]) -> None:
     """List all hosts"""
     service: HostService = ctx.obj["service"]
     hosts = service.list_hosts(tag=tag)
@@ -233,7 +239,7 @@ def host_list(ctx, tag: Optional[str]):
 @click.argument("name", required=True)
 @click.confirmation_option(prompt="Are you sure you want to remove this host?")
 @click.pass_context
-def host_remove(ctx, name: str):
+def host_remove(ctx: click.Context, name: str) -> None:
     """Remove a host"""
     service: HostService = ctx.obj["service"]
 
@@ -250,7 +256,7 @@ def host_remove(ctx, name: str):
 @host.command("show")
 @click.argument("name", required=True)
 @click.pass_context
-def host_show(ctx, name: str):
+def host_show(ctx: click.Context, name: str) -> None:
     """Show host details"""
     service: HostService = ctx.obj["service"]
 
@@ -272,8 +278,6 @@ def host_show(ctx, name: str):
         click.echo(f"  Auth:       {auth_type}")
         if host.key_filename:
             # Sanitize key path: show only the filename, not full path
-            from pathlib import Path
-
             key_name = Path(host.key_filename).name
             click.echo(f"  Key file:   {key_name}")
         tags_str = ", ".join(host.tags) if host.tags else "-"
@@ -290,7 +294,7 @@ def host_show(ctx, name: str):
 @host.command("test")
 @click.argument("name", required=True)
 @click.pass_context
-def host_test(ctx, name: str):
+def host_test(ctx: click.Context, name: str) -> None:
     """Test host connection"""
     service: HostService = ctx.obj["service"]
 
@@ -307,7 +311,7 @@ def host_test(ctx, name: str):
 @click.argument("host_name", required=True)
 @click.argument("command", required=True)
 @click.pass_context
-def run(ctx, host_name: str, command: str):
+def run(ctx: click.Context, host_name: str, command: str) -> None:
     """
     Execute a command on a remote host
 
@@ -340,7 +344,7 @@ def run(ctx, host_name: str, command: str):
 @click.argument("local_path", required=True)
 @click.argument("remote_path", required=True)
 @click.pass_context
-def upload(ctx, host_name: str, local_path: str, remote_path: str):
+def upload(ctx: click.Context, host_name: str, local_path: str, remote_path: str) -> None:
     """
     Upload a file to a remote host
 
@@ -366,7 +370,7 @@ def upload(ctx, host_name: str, local_path: str, remote_path: str):
 @click.argument("local_path", required=True)
 @click.argument("remote_path", required=True)
 @click.pass_context
-def download(ctx, host_name: str, local_path: str, remote_path: str):
+def download(ctx: click.Context, host_name: str, local_path: str, remote_path: str) -> None:
     """
     Download a file from a remote host
 
@@ -398,8 +402,8 @@ def download(ctx, host_name: str, local_path: str, remote_path: str):
 @click.option("--show-failures", is_flag=True, help="Show only failed hosts")
 @click.pass_context
 def batch_run(
-    ctx,
-    host_names: tuple,
+    ctx: click.Context,
+    host_names: tuple[str, ...],
     command: str,
     concurrency: int,
     timeout: int,
@@ -407,7 +411,7 @@ def batch_run(
     retry_delay: float,
     use_async: bool,
     show_failures: bool,
-):
+) -> None:
     """
     Execute a command on multiple hosts in batch
 
@@ -443,7 +447,7 @@ def batch_run(
         show_percent=True,
     ) as bar:
 
-        def progress(_completed, _total, _host_name):
+        def progress(_completed: int, _total: int, _host_name: str) -> None:
             bar.update(1)
 
         result = executor.execute(
@@ -488,7 +492,7 @@ def batch_run(
         ctx.exit(1)
 
 
-def main():
+def main() -> None:
     """CLI entry point"""
     cli()
 

{remote_cmd_manager-1.2.3 → remote_cmd_manager-2.0.0}/remote_cmd/core/async_connection_pool.py

@@ -20,6 +20,12 @@ from typing import Any, Optional
 
 from remote_cmd.core.async_ssh_client import AsyncSSHClient
 from remote_cmd.core.ssh_client import ConnectionConfig
+from remote_cmd.service._pool_policy import (
+    ConnectionMeta,
+    idle_expired,
+    lifetime_expired,
+    should_close,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -55,6 +61,9 @@ class AsyncConnectionPool:
         self._semaphore = asyncio.Semaphore(max_connections)
         self._lock = asyncio.Lock()
 
+        # 生命周期状态：close_all() 后置 True，禁止再借用/归还
+        self._closed = False
+
         # 指标
         self._total_created = 0
         self._total_reconnects = 0
@@ -65,7 +74,7 @@ class AsyncConnectionPool:
         self._monitor_task: Optional[asyncio.Task[None]] = None
 
         # 连接元数据（副表，避免侵入 AsyncSSHClient 私有属性）
-        self._meta: dict[int, dict[str, Any]] = {}
+        self._meta: dict[int, ConnectionMeta] = {}
 
     # ------------------------------------------------------------------
     # 指标
@@ -98,7 +107,10 @@ class AsyncConnectionPool:
 
         Raises:
             SSHConnectionError: 创建连接失败
+            RuntimeError: 连接池已关闭（close_all 之后）
         """
+        if self._closed:
+            raise RuntimeError("connection pool is closed")
         await self._semaphore.acquire()
         try:
             # 优先复用空闲连接
@@ -119,9 +131,15 @@ class AsyncConnectionPool:
         """归还连接到池中（如已断开/超时则关闭）。"""
         if conn is None:
             return
+        # 池已关闭：不把连接放回空闲队列（避免游离连接），直接关闭并释放槽位
+        if self._closed:
+            await self._close_connection(conn)
+            self._semaphore.release()
+            self._total_released += 1
+            return
         meta = self._meta.get(id(conn))
         if meta is not None:
-            meta["last_used"] = time.time()
+            meta.last_used = time.time()
 
         if not conn.is_connected():
             await self._close_connection(conn)
@@ -129,10 +147,7 @@ class AsyncConnectionPool:
             return
 
         # 生命周期 / 空闲超时则关闭
-        if meta and (
-            time.time() - meta["created_at"] > self._max_lifetime
-            or time.time() - meta["last_used"] > self._idle_timeout
-        ):
+        if meta and should_close(meta, self._max_lifetime, self._idle_timeout, True):
             await self._close_connection(conn)
             self._semaphore.release()
             return
@@ -162,18 +177,18 @@ class AsyncConnectionPool:
             raise
         self._connections.append(client)
         now = time.time()
-        self._meta[id(client)] = {
-            "created_at": now,
-            "last_used": now,
-            "conn_id": uuid.uuid4().hex,
-        }
+        self._meta[id(client)] = ConnectionMeta(
+            created_at=now,
+            last_used=now,
+            conn_id=uuid.uuid4().hex,
+        )
         self._total_created += 1
         return client
 
     def _touch(self, conn: AsyncSSHClient) -> None:
         meta = self._meta.get(id(conn))
         if meta is not None:
-            meta["last_used"] = time.time()
+            meta.last_used = time.time()
 
     async def _check_connection(self, conn: AsyncSSHClient) -> bool:
         if not conn.is_connected():
@@ -181,14 +196,12 @@ class AsyncConnectionPool:
         meta = self._meta.get(id(conn))
         if meta is None:
             return True
-        age = time.time() - meta["created_at"]
-        if age > self._max_lifetime:
-            logger.debug("connection %s exceeded max lifetime", meta.get("conn_id", "?")[:8])
+        if lifetime_expired(meta.created_at, self._max_lifetime):
+            logger.debug("connection %s exceeded max lifetime", meta.conn_id[:8])
             return False
         # 连接刚使用过（空闲未超时）则信任其状态，避免频繁探活开销
         # （与 SyncConnectionPool._check_connection 保持一致）
-        idle = time.time() - meta["last_used"]
-        if idle < self._idle_timeout:
+        if not idle_expired(meta.last_used, self._idle_timeout):
             return True
         # 空闲较久才触发轻量探活：发出一个无害命令
         try:
@@ -239,15 +252,10 @@ class AsyncConnectionPool:
         keep: list[AsyncSSHClient] = []
         for conn in snapshot:
             meta = self._meta.get(id(conn))
-            if meta is None:
+            if should_close(meta, self._max_lifetime, self._idle_timeout, conn.is_connected(), now):
                 await self._close_connection(conn)
                 continue
-            age = now - meta["created_at"]
-            idle = now - meta["last_used"]
-            if age < self._max_lifetime and idle < self._idle_timeout and conn.is_connected():
-                keep.append(conn)
-            else:
-                await self._close_connection(conn)
+            keep.append(conn)
         # 将存活连接放回同一队列对象
         async with self._lock:
             for conn in keep:
@@ -275,6 +283,7 @@ class AsyncConnectionPool:
 
     async def close_all(self) -> None:
         """关闭池中所有连接并停止监控。"""
+        self._closed = True
         self.stop_monitor()
         for conn in list(self._connections):
             await self._close_connection(conn)

{remote_cmd_manager-1.2.3 → remote_cmd_manager-2.0.0}/remote_cmd/core/async_ssh_client.py

@@ -22,7 +22,7 @@ from typing import Any, Optional
 
 import asyncssh
 
-from remote_cmd.core.ssh_client import CommandResult, ConnectionConfig
+from remote_cmd.core.ssh_client import CommandResult, ConnectionConfig, RemoteFileEntry
 from remote_cmd.utils.exceptions import (
     SSHCommandError,
     SSHConnectionError,
@@ -195,7 +195,8 @@ class AsyncSSHClient:
                 + "; "
             )
         full_command = f"{env_str}cd ~ && {command}"
-        logger.debug(f"executing command: {command}")
+        # 安全：不记录命令全文（可能含敏感参数），仅记录执行事件
+        logger.debug("executing remote command")
         try:
             result = await conn.run(
                 full_command,
@@ -204,7 +205,7 @@ class AsyncSSHClient:
                 env={k: str(v) for k, v in (environment or {}).items()},
             )
         except (OSError, asyncssh.Error) as e:
-            raise SSHCommandError(f"command execution failed '{command}': {e}") from e
+            raise SSHCommandError(f"command execution failed: {e}") from e
 
         stdout_data = (
             result.stdout
@@ -242,14 +243,16 @@ class AsyncSSHClient:
                 timeout=timeout,
             )
         except (OSError, asyncssh.Error) as e:
-            raise SSHCommandError(f"sudo command execution failed '{command}': {e}") from e
+            raise SSHCommandError(f"sudo command execution failed: {e}") from e
 
         try:
             proc.stdin.write(password + "\n")
             proc.stdin.write_eof()
-            result = await proc.wait()
+            # 与 execute 的 conn.run(timeout=...) 语义对齐：timeout 覆盖整个命令执行
+            # wall-clock，避免挂起的 sudo（如等待密码）无限等待
+            result = await proc.wait(timeout=timeout)
         except (OSError, asyncssh.Error) as e:
-            raise SSHCommandError(f"sudo command execution failed '{command}': {e}") from e
+            raise SSHCommandError(f"sudo command execution failed: {e}") from e
 
         stdout_data = (
             result.stdout
@@ -305,7 +308,7 @@ class AsyncSSHClient:
             raise SSHFileTransferError(f"file download failed: {e}") from e
         logger.info("file download finished")
 
-    async def list_remote_directory(self, remote_path: str = ".") -> list[dict[str, Any]]:
+    async def list_remote_directory(self, remote_path: str = ".") -> list[RemoteFileEntry]:
         """异步列出远程目录内容（结构与同步 SSHClient 一致）。"""
         sftp = await self._get_sftp()
         try:
@@ -313,18 +316,20 @@ class AsyncSSHClient:
         except (OSError, asyncssh.Error) as e:
             raise SSHFileTransferError(f"failed to list remote directory: {e}") from e
 
-        entries: list[dict[str, Any]] = []
+        entries: list[RemoteFileEntry] = []
         for entry in names:
             attrs = entry.attrs
             mode = attrs.permissions if hasattr(attrs, "permissions") else None
+            raw_size = attrs.size if hasattr(attrs, "size") else None
+            raw_mtime = attrs.mtime if hasattr(attrs, "mtime") else 0
             entries.append(
-                {
-                    "name": entry.filename,
-                    "size": attrs.size if hasattr(attrs, "size") else 0,
-                    "mode": oct(int(mode))[-3:] if mode else "000",
-                    "mtime": attrs.mtime if hasattr(attrs, "mtime") else 0,
-                    "is_dir": bool(mode & stat.S_IFDIR) if mode else False,
-                }
+                RemoteFileEntry(
+                    name=str(entry.filename),
+                    size=raw_size if raw_size is not None else 0,
+                    mode=oct(int(mode))[-3:] if mode else "000",
+                    mtime=raw_mtime,
+                    is_dir=bool(mode & stat.S_IFDIR) if mode else False,
+                )
             )
         return entries
 

{remote_cmd_manager-1.2.3 → remote_cmd_manager-2.0.0}/remote_cmd/core/host.py

@@ -9,7 +9,8 @@
 - 与连接配置的转换
 """
 
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
 from typing import Any, Optional
 
 from remote_cmd.core.ssh_client import ConnectionConfig
@@ -49,11 +50,11 @@ class Host:
     port: int = 22
     password: Optional[str] = None
     key_filename: Optional[str] = None
-    tags: Optional[list[str]] = None
+    tags: list[str] = field(default_factory=list)
     description: str = ""
 
     def __post_init__(self):
-        """初始化后处理：设置默认标签列表"""
+        """初始化后处理：归一化外部传入的 None 标签（兼容旧数据）"""
         if self.tags is None:
             self.tags = []
 
@@ -124,8 +125,6 @@ class Host:
             )
         # 脱敏密钥路径：仅显示文件名
         if data.get("key_filename"):
-            from pathlib import Path
-
             data["key_filename"] = Path(data["key_filename"]).name
         return data
 

{remote_cmd_manager-1.2.3 → remote_cmd_manager-2.0.0}/remote_cmd/core/ssh_client.py

@@ -137,6 +137,28 @@ class CommandResult:
         return f"{status} [{self.exit_code}] {self.command}"
 
 
+@dataclass
+class RemoteFileEntry:
+    """
+    远程文件/目录条目信息
+
+    描述远程目录中的单个条目（文件或目录），替代弱类型的字典返回。
+
+    Attributes:
+        name: 文件/目录名
+        size: 文件大小（字节）
+        mode: 权限模式（八进制字符串）
+        mtime: 修改时间戳
+        is_dir: 是否为目录
+    """
+
+    name: str
+    size: int
+    mode: str
+    mtime: Any
+    is_dir: bool
+
+
 # ============================================================================
 # SSH 客户端类
 # ============================================================================
@@ -166,7 +188,7 @@ class SSHClient:
         ...     print(result.stdout)
     """
 
-    def __init__(self, config: ConnectionConfig):
+    def __init__(self, config: ConnectionConfig) -> None:
         """
         初始化 SSH 客户端
 
@@ -375,7 +397,8 @@ class SSHClient:
             raise SSHConnectionError("not connected, call connect() first")
 
         try:
-            logger.debug(f"executing command: {command}")
+            # 安全：不记录命令全文（可能含敏感参数），仅记录执行事件
+            logger.debug("executing remote command")
 
             # 构建环境变量设置命令
             # 安全：对 value 做 shlex.quote 转义，防止包含 shell 元字符
@@ -408,7 +431,7 @@ class SSHClient:
             return result
 
         except (paramiko.SSHException, OSError) as e:
-            raise SSHCommandError(f"command execution failed '{command}': {e}") from e
+            raise SSHCommandError(f"command execution failed: {e}") from e
 
     def execute_sudo(
         self,
@@ -464,7 +487,7 @@ class SSHClient:
                 exit_code=exit_code,
             )
         except (paramiko.SSHException, OSError) as e:
-            raise SSHCommandError(f"sudo command execution failed '{command}': {e}") from e
+            raise SSHCommandError(f"sudo command execution failed: {e}") from e
 
     # ========================================================================
     # 文件传输方法
@@ -532,7 +555,7 @@ class SSHClient:
         except (paramiko.SSHException, OSError) as e:
             raise SSHFileTransferError(f"file download failed: {e}") from e
 
-    def list_remote_directory(self, remote_path: str = ".") -> list[dict[str, Any]]:
+    def list_remote_directory(self, remote_path: str = ".") -> list[RemoteFileEntry]:
         """
         列出远程目录内容
 
@@ -540,12 +563,7 @@ class SSHClient:
             remote_path: 远程目录路径，默认为当前目录
 
         Returns:
-            List[Dict[str, Any]]: 目录项信息列表，每个字典包含：
-                - name: 文件/目录名
-                - size: 文件大小（字节）
-                - mode: 权限模式（八进制字符串）
-                - mtime: 修改时间戳
-                - is_dir: 是否为目录
+            List[RemoteFileEntry]: 目录项信息列表
 
         Raises:
             SSHFileTransferError: 列出目录失败时抛出
@@ -554,22 +572,22 @@ class SSHClient:
         Example:
             >>> entries = client.list_remote_directory("/home/user")
             >>> for entry in entries:
-            ...     print(f"{entry['name']}: {entry['size']} bytes")
+            ...     print(f"{entry.name}: {entry.size} bytes")
         """
         sftp = self._get_sftp()
 
         try:
-            entries = []
+            entries: list[RemoteFileEntry] = []
             for entry in sftp.listdir_attr(remote_path):
                 mode = entry.st_mode if entry.st_mode is not None else 0
                 entries.append(
-                    {
-                        "name": entry.filename,
-                        "size": entry.st_size,
-                        "mode": oct(mode)[-3:] if mode else "000",
-                        "mtime": entry.st_mtime,
-                        "is_dir": bool(mode & stat.S_IFDIR) if mode else False,
-                    }
+                    RemoteFileEntry(
+                        name=entry.filename,
+                        size=entry.st_size,
+                        mode=oct(mode)[-3:] if mode else "000",
+                        mtime=entry.st_mtime,
+                        is_dir=bool(mode & stat.S_IFDIR) if mode else False,
+                    )
                 )
             return entries
         except (paramiko.SSHException, OSError) as e:
@@ -579,7 +597,7 @@ class SSHClient:
         """创建远程目录（支持递归创建）"""
         sftp = self._get_sftp()
 
-        def _makedirs(sftp_client, remote_path):
+        def _makedirs(sftp_client: paramiko.SFTPClient, remote_path: str) -> None:
             if remote_path == "/":
                 return
             try:
@@ -607,9 +625,9 @@ class SSHClient:
         """删除远程目录"""
         sftp = self._get_sftp()
 
-        def _rm_recursive(sftp_client, remote_path):
+        def _rm_recursive(sftp_client: paramiko.SFTPClient, remote_path: str) -> None:
             """递归删除目录内容，先收集后删除以避免不一致状态"""
-            entries = []
+            entries: list[tuple[str, bool]] = []
             try:
                 for entry in sftp_client.listdir_attr(remote_path):
                     entries.append((entry.filename, bool(entry.st_mode & stat.S_IFDIR)))