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小时缓存机制
方法列表
_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),供各安装场景复用。
策略:
- 优先使用 uv(自动识别独立二进制或 python -m uv),
并通过
--python显式指定目标解释器,确保安装到用户期望的环境 (特别是 epsdk 经 pipx 全局安装、用户包需装到项目 venv 的场景); - 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)。
策略:
- 优先使用 uv(自动识别独立二进制或 python -m uv);
通过
--python显式指定目标解释器,确保安装到用户期望的环境 (特别是 epsdk 经 pipx 全局安装、用户包需装到项目 venv 的场景)。 install 子命令复用 :meth:_build_install_command构建完整命令。 - 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_project_link_active() -> bool
内部方法 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 键渲染。