uv 中点号包名的 Windows 可执行文件解析一个回归测试夹具的来龙去脉【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv本文以 uv 仓库中的测试夹具 test/packages/package.name.with.dots 为核心讲解它要验证的那个真实缺陷——当包名包含点号.时uv tool run即uvx在 Windows 上追加可执行文件扩展名时的解析错误并说明该夹具如何与pyproject.toml、PowerShell 入口脚本以及集成测试 crates/uv/tests/tool/tool_run.rs 协同工作形成一条可复现、可断言的回归验证链路。这个测试夹具到底在测什么README 只有一段简短描述但它点出了两个关键事实这是一个验证带点号包名在 Windows 上可执行文件处理的测试包。它用于测试一个 bug 修复uvx在 Windows 上为包名追加可执行文件扩展名时如果包名本身含有.扩展名会被错误地处理。要理解这个缺陷需要先理解uv tool run在 Windows 上的工作方式。它并不会直接把 Python 解释器拉起来执行脚本而是会为工具暴露出一个可执行入口。在 Windows 上一个可执行的工具入口通常是*.exe、*.bat、*.cmd或*.ps1这类带扩展名的文件。问题在于当包名本身带有.例如package.name.with.dots时根据包名推断可执行文件名并加上扩展名这一步会出错——算法很可能把package.name.with.dots最后一段dots当成扩展名去替换从而生成一个不存在的文件名导致找不到入口。这个夹具的价值就是提供一个包名里真的含有多个点、且声明了 Windows 入口脚本的最小可安装包让回归测试能够真实地把这个分支跑出来。夹具的目录结构该夹具是一个完整的、可被 uv 解析并安装的本地 Python 项目结构如下test/packages/package.name.with.dots/ ├── pyproject.toml ├── README.md ├── scripts/ │ └── package.name.with.dots.ps1 # Windows 入口脚本 └── src/ └── package_name_with_dots/ └── __init__.py # 包版本声明其中三个文件各自承担一个职责pyproject.toml声明包名、版本、Python 版本约束以及构建后端并告诉 uv_build 在哪里找入口脚本。scripts/package.name.with.dots.ps1是真正会在 Windows 上被执行的入口脚本。src/package_name_with_dots/__init__.py声明包本身并暴露__version__。注意包名的细节pyproject.toml里写的是name package.name.with.dots带点而导入用的模块目录却写作package_name_with_dots用下划线。这是有意为之的对照——包名distribution name可以含点号而模块名import name用下划线两者并不强制一致正好把名字里有多个点这一变量单独隔离出来。pyproject.toml最小化的可安装声明下面来自 pyproject.toml[project] name package.name.with.dots version 0.1.0 requires-python 3.8 [tool.uv.build-backend.data] scripts scripts [build-system] requires [uv_build0.8.0,0.13] build-backend uv_build几个字段的作用[project] name package.name.with.dots这就是要毒害扩展名解析逻辑的那个包名包含三个点。requires-python 3.8声明最低的 Python 版本约束。[tool.uv.build-backend.data] scripts scripts告诉 uv_build 构建后端入口脚本存放在scripts/目录下。没有这一行后端就无法知道要在 Windows 上生成哪个可执行入口。[build-system]使用 uv 自家的uv_build后端来打 wheelrequires限定了后端版本范围0.8.0,0.13。配合 src/package_name_with_dots/init.py 中的__version__ 0.1.0整个包在构建时就是一个0.1.0版本的本地分发包。入口脚本一个会打印版本的 PowerShell 文件Windows 上真正被执行的入口是 scripts/package.name.with.dots.ps1内容只有两行Write-Host package.name.with.dots version 0.1.0 exit 0它做两件事输出一行包含完整点号包名的字符串然后以状态码0退出。这个脚本是可观测的探针——测试不需要解析复杂的业务逻辑只要确认这行输出被打印出来就说明 uv 成功地在 Windows 上为package.name.with.dots定位到了package.name.with.dots.ps1这个入口并把它跑起来了。如果扩展名解析 bug 存在入口文件名会被算错脚本根本不会被找到测试就会失败。集成测试把缺陷分支真正跑出来夹具不是孤立存在的它被 crates/uv/tests/tool/tool_run.rs 中的回归测试tool_run_windows_dotted_package_name消费。该测试带有#[cfg(windows)]标记意味着它只在 Windows 上编译运行——因为被验证的正是 Windows 专属的扩展名解析行为。测试的核心流程可以概括为三步把夹具从工作区复制到临时目录模拟一个本地包被用户拿去安装的场景let workspace_packages context.workspace_root.join(test).join(packages); let test_package_source workspace_packages.join(package.name.with.dots); let test_package_dest context.temp_dir.child(package.name.with.dots); copy_dir_all(test_package_source, test_package_dest)?;用uv tool run --from 临时包路径 package.name.with.dots触发按包名运行工具的完整链路解析 → 准备 → 安装 → 定位入口 → 执行。通过uv_snapshot!断言运行结果。断言里最关键的几行是exit_code: 0 (success) ----- stdout ----- package.name.with.dots version 0.1.0 ----- stderr ----- Resolved [N] packages in [TIME] Prepared [N] packages in [TIME] Installed [N] packages in [TIME] package-name-with-dots0.1.0 (from file://[TEMP_DIR]/package.name.with.dots)注意最后一行安装摘要里包名被规范化成了package-name-with-dots0.1.0点号被替换为连字符而 stdout 里打印的仍是原始点号包名。这一对照恰好说明规范化发生在依赖求解/展示层而可执行入口的定位仍然要正确地把原始点号名 扩展名拼出来。只要入口定位错了stdout 那行就不会出现exit_code也不会是0。从源码结构看这个分支的位置从源码结构看Windows 上根据名字追加可执行扩展名的通用做法是用std::env::consts::EXE_EXTENSION之类的方式给文件名追加.exe。例如在 crates/uv/src/commands/project/run.rs 中就能看到path.with_extension(...)/with_extension(std::env::consts::EXE_EXTENSION)这类写法。点号包名的缺陷正出在这类按最后一段当作扩展名替换的假设上with_extension语义会把最后一个.之后的内容当成扩展名替换掉于是package.name.with.dots会被错误地改写成package.name.with.exe之类的名字而真正的package.name.with.dots.ps1反而找不到。因此这个回归夹具配合 Windows 测试锁住了带点包名 Windows 扩展名解析这一条最容易回退的路径一旦有人重构入口定位逻辑而忘了点号情况tool_run_windows_dotted_package_name会第一时间报错。如何复现这条验证链路要在本地验证这套逻辑只需按测试的等价步骤操作仓库为只读以下为查看/运行说明非对仓库的修改将 test/packages/package.name.with.dots 整个目录复制到一个临时位置作为一个独立的本地包。在 Windows 上执行uv tool run --from ./package.name.with.dots package.name.with.dots期望看到 stdout 输出package.name.with.dots version 0.1.0且进程退出码为0。若上述命令能稳定打出该行输出即说明 Windows 下点号包名 → 入口扩展名的解析已正确若在旧版本上该命令定位不到入口而失败则正好复现了这个被修复的 bug。小结test/packages/package.name.with.dots 是一个用途单一但目标明确的回归夹具专门验证uv tool run在 Windows 上对含点包名的可执行入口解析。它的pyproject.toml用 uv_build 后端声明了scripts scripts入口目录.ps1脚本充当可观测探针__init__.py提供包版本。真正把它跑起来并断言的是 crates/uv/tests/tool/tool_run.rs 中仅 Windows 编译的tool_run_windows_dotted_package_name它通过复制夹具、执行uv tool run并快照stdout/exit_code来锁住缺陷分支。这类最小可安装包 平台专属回归测试的组合是 uv 在入口定位、可执行文件解析等细节逻辑上防止回退的典型做法。【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考