ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

ErisPulse.CLI.utils.package_manager 模块


模块概述

ErisPulse SDK 包管理器

提供包安装、卸载、升级和查询功能


函数列表

create_project_venv(project_dir: Path) -> 'str | None'

在项目目录创建 .venv 虚拟环境

优先使用 uv(uv venv,秒级、无 pip);uv 不可用时回退 python -m venv(自带 pip)。

  • project_dir: 项目目录(.venv 创建于其下)

返回值: 成功时返回 .venv 的 Python 解释器路径;失败返回 None


uv_add(project_dir: Path, packages: 'list[str]') -> bool

在项目目录执行 uv add <packages>(安装依赖并同步写入 pyproject.toml)

uv 会自动创建/使用项目 .venv 并生成 uv.lock——安装与依赖声明 一步完成,天然免疫 uv sync 的未声明包清理。

  • project_dir: 项目目录(须已生成 pyproject.toml)
  • packages: 包名列表

返回值: 是否成功


append_pyproject_dependencies(project_dir: Path, packages: 'list[str]') -> bool

手动向 pyproject.toml 的 project.dependencies 追加依赖(pip 回退路径用)

使用 tomlclass 无损引擎保留文件注释与格式。

  • project_dir: 项目目录
  • packages: 依赖包名列表

返回值: 是否成功(pyproject 不存在 / 解析失败返回 False)


is_uv_project(project_dir: 'Path | None' = None) -> bool

判定目录是否为 uv 管理的项目(三重依据任一命中)

uv.lock 存在 / pyproject 含 [tool.uv] 段 / .venv/pyvenv.cfg 含 uv = 标记行(uv venv 创建时写入)。无 uv 时判定依旧成立—— 联动分支还会要求 uv 可用,两者解耦。

  • project_dir: 项目目录(默认当前目录)

返回值: 是否 uv 项目


resolve_target_python(project_dir: 'Path | None' = None) -> 'tuple[str, PythonSource]'

解析目标 Python 解释器(CLI 各命令统一入口)

优先级:ERISPULSE_PYTHON 环境变量 > UV_PROJECT_ENVIRONMENT(uv 项目 自定义环境路径)> 项目 .venv 内解释器 > UV_PYTHON(仅路径形态)> VIRTUAL_ENV > 当前解释器。

提示 uv 感知:UV_PROJECT_ENVIRONMENT 把项目环境指到非 .venv 路径时, 不感知会把组件装进错误环境(随后 uv tool upgrade 抹掉);UV_PYTHON 的版本说明符形态(如 "3.12")不是路径,跳过。

  • project_dir: 项目目录(默认当前目录);在该目录下探测 .venv 与

    UV_PROJECT_ENVIRONMENT 的相对路径基准

返回值: (解释器路径, 来源)——来源为 :class:PythonSource,用于提示用户

当前操作所作用的环境

build_uv_tool_update_command(uv_cmd: 'list[str]', target_version: 'str | None') -> 'list[str]'

构建 uv tool 通道的 SDK 自更新命令

  • uv_cmd (list[str): ] uv 命令前缀(如 ["uv"])
  • target_version (str | None): 目标版本号;None 表示升级到最新

返回值 (list[str): ] 完整命令列表


_ps_quote(text: str) -> str

转义 PowerShell 单引号字符串中的单引号

  • text (str): 原始文本

返回值 (str): 可安全嵌入 PowerShell 单引号字面量的文本


build_windows_tool_update_script(cmd: 'list[str]', parent_pid: int, msg_done: str, msg_failed: str, press_key: str) -> str

生成 Windows 分离更新用的 PowerShell 脚本文本

脚本流程:等待当前 CLI 进程退出(工具环境文件不再被占用)→ 执行 uv tool 更新命令 → 报告结果 → 自删除 → 等待用户按键,防止新控制台 窗口瞬间关闭导致看不到结果。

  • cmd (list[str): ] 更新命令(如 ["uv", "tool", "upgrade", "ErisPulse"])
  • parent_pid (int): 当前 CLI 进程 PID(脚本等待其退出)
  • msg_done (str): 更新成功提示
  • msg_failed (str): 更新失败提示
  • press_key (str): 退出前按键提示

返回值 (str): PowerShell 脚本文本


warn_if_uv_isolated() -> bool

检测当前是否处于 uv 无项目的隔离运行上下文并输出警告

uv run 在无 pyproject.toml 的目录执行时,命令运行于一次性 隔离环境——其中安装的包不会持久化。通过 UV 环境变量识别 uv 上下文,结合 cwd 项目文件缺失判定隔离场景。

返回值: 是否处于隔离场景(True = 已输出警告)


is_uv_tool_env() -> bool

检测当前解释器是否位于 uv tool install 创建的工具环境中

uv tool 环境位于 uv 数据目录下的 uv/tools/<包名>/(Linux: ~/.local/share/uv/tools,Windows: %APPDATA%\uv\tools), 通过 sys.prefix 路径特征识别,不依赖任何环境变量—— uv tool 的入口 shim 执行时不会设置 UV 变量。

返回值 (bool): 当前 epsdk 运行于 uv tool 环境时返回 True


warn_if_uv_tool_env_without_project() -> bool

检测「uv tool 环境运行 + 无项目环境」场景并输出提示

uv tool install ErisPulse 后,epsdk 运行于全局工具环境;若用户 未在项目内(无 .venv 且未激活 VIRTUAL_ENV),组件安装目标会 落到工具环境自身——升级 SDK 时 uv tool upgrade 会将其抹掉。 检测到该场景时提示在项目内操作。

返回值 (bool): 处于该场景时返回 True(已输出提示)


类列表

class PackageManager

ErisPulse包管理器

提供包安装、卸载、升级和查询功能

提示

  1. 支持本地和远程包管理
  2. 包含1小时缓存机制

方法列表

_sanitize_proxy_url(url: str) -> str(staticmethod)

对代理URL中的密码进行脱敏处理

  • url (str): 原始代理URL

返回值 (str): 密码被替换为 *** 的脱敏URL


__init__(python_executable: 'str | None' = None)

初始化包管理器,设置缓存、查找器、代理与 uv 相关状态

  • python_executable (str | None): 显式指定目标 Python 解释器

    (如项目 .venv 内的解释器)。指定后查找器与安装/卸载目标环境 全部指向该解释器;None 时按 _get_target_python() 自动解析


_parse_size(size_str: str) -> float(staticmethod)

将带单位的尺寸字符串解析为字节数

  • size_str (str): 尺寸字符串,如 "10MB"

返回值 (float): 对应的字节数,无法解析时返回 0


_get_system_proxy() -> dict[str, str] | None

获取系统代理配置,优先读取环境变量,其次读取Windows注册表

返回值 (Optional[Dict[str, str): ]] 代理配置字典,无代理时返回 None


_parse_windows_proxy(proxy_server: str) -> dict[str, str](staticmethod)

解析Windows注册表中的代理服务器字符串为协议到URL的映射

  • proxy_server (str): Windows代理服务器字符串

返回值 (Dict[str, str): ] 协议到代理URL的映射


_get_proxy_for_url(url: str) -> str | None

根据URL的协议获取对应的代理地址

  • url (str): 目标URL

返回值 (Optional[str): ] 对应的代理URL,无匹配代理时返回 None


_build_subprocess_env() -> dict[str, str]

构建子进程环境变量,未设置时注入系统代理配置

返回值 (Dict[str, str): ] 包含代理配置的环境变量字典


_http_get(url: str, timeout: int = 15) -> str | None

发起HTTP GET请求并返回响应文本,自动应用系统代理

  • url (str): 请求URL
  • timeout (int): 超时时间(秒) (默认: 15)

返回值 (Optional[str): ] 响应文本,请求失败时返回 None


_fetch_remote_packages_sync(url: str) -> dict | None

同步获取并解析远程包列表JSON

  • url (str): 远程包列表URL

返回值 (Optional[dict): ] 解析后的包列表字典,失败时返回 None


async _fetch_remote_packages(url: str) -> dict | None

异步获取远程包列表

  • url (str): 远程包列表URL

返回值 (Optional[dict): ] 解析后的包列表字典,失败时返回 None


async get_remote_packages(force_refresh: bool = False) -> dict

获取远程包列表,带缓存机制

  • force_refresh (bool): 是否强制刷新缓存 (默认: False)

返回值 (dict): 包含 modules 和 adapters 信息的字典


get_installed_packages() -> dict[str, dict[str, dict[str, str]]]

获取已安装的模块和适配器信息

返回值 (Dict[str, Dict[str, Dict[str, str): ]] 包含 modules 和 adapters 信息的字典


_is_module_enabled(module_name: str) -> bool

检查指定模块是否已启用

  • module_name (str): 模块名称

返回值 (bool): 模块已启用返回 True,无法判断时默认返回 True


_normalize_name(name: str) -> str

将名称标准化为小写并去除首尾空白

  • name (str): 原始名称

返回值 (str): 标准化后的名称


async _find_package_by_alias(alias: str) -> str | None

通过别名查找实际的包名,依次匹配已安装包和远程包

  • alias (str): 别名或包名

返回值 (Optional[str): ] 实际的包名,未找到时返回 None


_find_installed_package_by_name(name: str) -> str | None

在已安装的模块和适配器中按名称查找实际包名

  • name (str): 包名或别名

返回值 (Optional[str): ] 已安装的实际包名,未找到时返回 None


async check_package_updates() -> dict[str, tuple[str, str]]

检查已安装包的可用更新

返回值 (Dict[str, Tuple[str, str): ]] 包名到(当前版本, 最新版本)的映射


_get_pypi_version_sync(package_name: str) -> str | None

同步从PyPI获取指定包的最新版本号

  • package_name (str): 包名

返回值 (Optional[str): ] 最新版本号,失败时返回 None


async _get_pypi_package_version(package_name: str, force_refresh: bool = False) -> str | None

异步获取指定包的PyPI最新版本,带缓存机制

  • package_name (str): 包名
  • force_refresh (bool): 是否强制刷新缓存 (默认: False)

返回值 (Optional[str): ] 最新版本号,失败时返回 None


_is_uv_disabled() -> bool

是否禁用 uv:CLI --no-uv 优先,其次环境变量 ERISPULSE_NO_UV


_detect_uv() -> list[str] | None

检测可用的 uv 命令。

优先使用 PATH 上的独立 uv 二进制(用户可能是全局安装, 而非作为 pip 包安装在当前环境),其次回退到 python -m uv。

返回值 (Optional[List[str): ]] 形如 ["uv"] 或 [python, "-m", "uv"] 的命令前缀;未找到返回 None


_get_uv_command() -> list[str] | None

返回应使用的 uv 命令前缀。

当通过 --no-uv 禁用或 uv 不可用时返回 None。

返回值 (Optional[List[str): ]] uv 命令前缀或 None


_get_target_python() -> str

返回应当作为安装目标的 Python 解释器路径。

若用户激活了虚拟环境 (VIRTUAL_ENV) 但 epsdk 自身运行在别处 (例如通过 pipx 全局安装),则返回该虚拟环境的 Python, 以确保包安装到用户期望的环境中而非全局。

返回值 (str): 目标 Python 解释器路径


_execute_backend(base_cmd: list[str], args: list[str], description: str, backend: str) -> bool

使用指定的后端 (uv/pip) 执行命令并实时输出到当前终端。

  • base_cmd (List[str): ] 后端命令前缀,如 ["uv", "pip"] 或 [python, "-m", "pip"]
  • args (List[str): ] 传递给后端的子命令与参数
  • description (str): 展示给用户的操作描述
  • backend (str): 后端名称 (uv/pip),用于展示与错误提示

返回值 (bool): 执行成功返回 True


_build_install_command(package_spec: str, upgrade: bool = True) -> tuple[list[str], str]

构建安装命令(uv 优先,回退 pip),供各安装场景复用。

策略:

  1. 优先使用 uv(自动识别独立二进制或 python -m uv), 并通过 --python 显式指定目标解释器,确保安装到用户期望的环境 (特别是 epsdk 经 pipx 全局安装、用户包需装到项目 venv 的场景);
  2. uv 不可用时回退到 pip,目标 Python 解析为当前虚拟环境的解释器, 避免安装到全局环境。
  • package_spec (str): 包描述,如 "ErisPulse==1.0.0"
  • upgrade (bool): 是否添加 --upgrade 参数 (默认: True)

返回值 (Tuple[List[str): , str]] (完整安装命令列表, 后端名称 uv/pip)


_run_pip_command_with_output(args: list[str], description: str) -> bool

执行 pip 类操作 (install/uninstall)。

策略:

  1. 优先使用 uv(自动识别独立二进制或 python -m uv); 通过 --python 显式指定目标解释器,确保安装到用户期望的环境 (特别是 epsdk 经 pipx 全局安装、用户包需装到项目 venv 的场景)。 install 子命令复用 :meth:_build_install_command 构建完整命令。
  2. uv 不可用或执行失败时,回退到 pip, 并将目标 Python 解析为当前虚拟环境的解释器, 避免安装到全局环境。
  • args (List[str): ] pip 子命令与参数,如 ["install", "--upgrade", pkg]
  • description (str): 展示给用户的操作描述

返回值 (bool): 执行成功返回 True


_run_uv_project_command(cmd: 'list[str]', description: str) -> bool

执行 uv 项目级命令(uv add / uv remove),写入 pyproject 并刷新 uv.lock

与 uv pip 通道的差异:uv add/remove 操作项目环境(按 cwd 的 pyproject/uv.lock),不支持 --python 目标模型;这也是它能把依赖 写回 lock、免疫 uv sync exact 清理的原因。

  • cmd (uv): 子命令与参数(如 ["add", "pkg"] / ["remove", "pkg"])
  • description (str): 展示给用户的操作描述

返回值 (bool): 执行成功返回 True(失败由调用方回退 uv pip/pip 通道)


_is_plain_package_spec(spec: str) -> bool(staticmethod)

判定包描述是否为「纯包名形态」(可安全转为 uv add/remove)

pip 形态(-e 本地路径、-r 需求文件、URL/VCS、含空格的 extra 语法) 仍走 uv pip/pip 通道——uv add 只接受 PEP 508 名称形态。

内部方法


内部方法 uv 项目安装联动是否生效:uv 项目 + uv 可用 + 未禁用(--no-uv / 环境变量)


_ensure_pip_available(target_python: str) -> bool

确保目标 Python 环境可用 pip

uv 创建的 venv 默认不含 pip(uv 自身可装包)。当 uv 不可用或执行失败需 回退到 pip 时,必须先检测 pip 是否可用,否则会出现 “No module named pip” 的错误。这里通过 python -m ensurepip 自举安装。

  • target_python (str): 目标 Python 解释器路径

返回值 (bool): pip 可用返回 True,无法 bootstrap 返回 False


_version_key(version: str) -> tuple

将版本号解析为可比较的元组键

委托 :func:ErisPulse.runtime.version.version_key(框架内唯一实现)。

  • version (str): 版本号字符串

返回值 (tuple): 逐段可比较的比较键元组


_compare_versions(version1: str, version2: str) -> int

比较两个版本号的大小

委托 :func:ErisPulse.runtime.version.compare_versions(框架内唯一实现)。

  • version1 (str): 第一个版本号
  • version2 (str): 第二个版本号

返回值 (int): version1 大于/等于/小于 version2 时分别返回 1/0/-1


_check_sdk_compatibility(min_sdk_version: str) -> tuple[bool, str]

检查当前SDK版本是否满足最低版本要求

  • min_sdk_version (str): 所需的最低SDK版本

返回值 (Tuple[bool, str): ] (是否兼容, 提示信息)


async _get_package_info(package_name: str) -> dict[str, Any] | None

从远程包列表中获取指定包的详细信息

  • package_name (str): 包名

返回值 (Optional[Dict[str, Any): ]] 包信息字典,未找到时返回 None


install_package(package_names: list[str], upgrade: bool = False, pre: bool = False, extra_pip_args: list[str] | None = None) -> bool

安装一个或多个包,支持别名映射、未验证包确认和SDK兼容性检查

  • package_names (List[str): ] 待安装的包名或别名列表
  • upgrade (bool): 是否升级已安装的包 (默认: False)
  • pre (bool): 是否允许预发布版本 (默认: False)
  • extra_pip_args (Optional[List[str): ]] 附加的pip参数 (默认: None)

返回值 (bool): 全部安装成功返回 True


install_direct(pip_args: list[str], description: str = 'pip install') -> bool

直接使用给定参数执行pip安装

  • pip_args (List[str): ] pip install 的参数列表
  • description (str): 展示给用户的操作描述 (默认: "pip install")

返回值 (bool): 执行成功返回 True


uninstall_package(package_names: list[str], skip_confirm: bool = False) -> bool

卸载一个或多个包,支持别名映射和确认提示

  • package_names (List[str): ] 待卸载的包名或别名列表
  • skip_confirm (bool): 是否跳过确认提示 (默认: False)

返回值 (bool): 全部卸载成功返回 True


upgrade_all() -> bool

检查并升级所有有可用更新的ErisPulse包

返回值 (bool): 全部升级成功返回 True


upgrade_package(package_names: list[str], pre: bool = False) -> bool

升级指定包到最新版本

  • package_names (List[str): ] 待升级的包名或别名列表
  • pre (bool): 是否允许预发布版本 (默认: False)

返回值 (bool): 全部升级成功返回 True


search_package(query: str) -> dict[str, list[dict[str, str]]]

在已安装和远程包中搜索匹配查询的包

  • query (str): 搜索关键词

返回值 (Dict[str, List[Dict[str, str): ]] 包含 installed 和 remote 匹配结果的字典


get_installed_version() -> str

获取已安装的ErisPulse SDK版本号

返回值 (str): SDK版本号,无法获取时返回 "unknown"


_get_pypi_versions_sync() -> list[dict[str, Any]]

同步从PyPI获取ErisPulse的所有可用版本,按版本号降序排列

返回值 (List[Dict[str, Any): ]] 版本信息列表,失败时返回空列表


async get_pypi_versions() -> list[dict[str, Any]]

异步获取ErisPulse在PyPI上的所有可用版本

返回值 (List[Dict[str, Any): ]] 版本信息列表,失败时返回空列表


_is_pre_release(version: str) -> bool

判断版本号是否为预发布版本

与 :meth:_version_key 共用同一解析口径(:func:ErisPulse.runtime.version.parse_version)。 当版本号含预发布段 (dev/alpha/beta/rc/c/pre) 时返回 True。 post 版本 (1.0.post1) 与本地版本 (1.0+local) 不视为预发布版本

  • version (str): 版本号字符串

返回值 (bool): 是预发布版本时返回 True


_spawn_windows_tool_update(cmd: 'list[str]', target_version: 'str | None', current_version: str) -> bool

Windows 下以分离进程执行 uv tool 自更新

当前 CLI 进程就运行在待替换的工具环境内,Windows 不允许删除运行中 的 exe——更新必须等本进程退出后进行。此方法生成 PowerShell 脚本 (等待本进程 → 执行更新 → 报告结果),以新控制台窗口分离启动后立 即返回;调用方随后正常退出 CLI,脚本接管更新。

  • cmd (list[str): ] uv tool 更新命令
  • target_version (str | None): 目标版本号(None 表示最新)
  • current_version (str): 当前已安装版本号

返回值 (bool): 更新进程启动成功返回 True(结果以新窗口输出为准)


update_self(target_version: str | None = None, force: bool = False) -> bool

更新ErisPulse SDK到指定版本或最新版本

  • target_version (Optional[str): ] 目标版本号,为空则更新到最新版本 (默认: None)
  • force (bool): 是否强制更新到当前已安装的目标版本 (默认: False)

返回值 (bool): 更新成功返回 True


class PythonSource(str, Enum)

解释器解析来源(resolve_target_python 的返回标签)

取代此前的中文魔法字符串("项目 .venv" 等)——字符串比较曾是 i18n 体系外的暗契约,任何一侧改字即静默失效;展示文案经 cli.python.source.* i18n 键渲染。