WinPython 3.13.12.0dot 发行版包清单深度解析:dot Flavor 极简构成与 changelog 自动生成机制
WinPython 3.13.12.0dot 发行版包清单深度解析:dot Flavor 极简构成与 changelog 自动生成机制
WinPython 是一个面向 Windows 平台的免费 Python 发行版(64 位版通常内置预编译的科学计算包),其构建系统在产出发行目录的同时,会由 wppm(WinPython Package Manager)自动生成一份随版本归档的 Markdown 包索引——即 changelogs 目录下形如 WinPythondot-64bit-3.13.12.0.md 的清单文件。本文以这份 3.13.12.0dot 清单为主体,逐段解读 dot 极简 Flavor 的完整构成(Tools / Python packages / WheelHouse 三部分)、每个包的来源与分组逻辑,并深入构建管线源码,说明这份 changelog 是如何被自动生成的,以及如何用 wppm 自行复现与对比包索引。读完本文,你将能读懂任意一份 WinPython changelog,并理解 dot 与 slim 等 Flavor 的差异及包清单的生成原理。
一、dot Flavor:WinPython 的极简发行形态
WinPython 按 "Flavor"(口味/变体)区分不同的预置软件组合,每种 Flavor 决定了一份发行版装哪些包、带哪些工具目录。dot 是其中面向最小化场景的变体——只包含 Python 解释器与一组维护发行版自身所需的构建/包管理工具,不含科学计算栈。
在 winpython_builds.toml 中可以看到 dot Flavor 的定义:
[flavors.dot]
requirements = "dot_requirements.txt"
source_dirs = "packages.win-amd64"
toolsdirs = "bdTools\\Tools.dot"
三个键的含义如下(路径均相对构建目录解析,参见 build_winpython_meta.py 中 UNDER_BASEDIR 与 UNDER_ROOT 的划分):
| 键 | 取值 | 作用 |
|---|---|---|
requirements |
dot_requirements.txt |
该 Flavor 的包安装清单,列出要 pip 安装的包 |
source_dirs |
packages.win-amd64 |
预构建 wheel 的本地源目录(供离线安装回退) |
toolsdirs |
bdTools\Tools.dot |
随发行版附带的工具(Toolkit)目录 |
同一组配置还衍生出 dotf(自由线程版 Python 的 dot,见 winpython_builds.toml);而 slim / slimf 则在 dot 之上追加了更丰富的工具目录(tools64_pandoc_alone)。在构建配置中,一个 Python 版本对应一个 <a href="https://link.gitcode.com/i/15ad3b1029f083630aaa9db7cbecb7e2" target="_blank">pythons."3XX"] 块,builds 列表声明该版本要产出哪些 Flavor;例如 [pythons."313" 声明 builds = ["dot", "slim"],说明 Python 3.13 系列会同时产出 dot 与 slim 两种变体。
本地构建时通过批处理入口选择具体目标(见 generate_a_winpython_distropy_meta.bat):
cd /D %~dp0
call "C:\WinPdev\WPy64-31190\python-3.11.9.amd64\python.exe" %~dp0\build_winpython_meta.py %*
典型用法(winpython_builds.toml 文件头部注释中有完整说明):
generate_a_winpython_distropy_meta.bat winpython_builds.toml 315:slim :: 只构建 3.15 的 slim
generate_a_winpython_distropy_meta.bat winpython_builds.toml 315 :: 构建 3.15 的全部 Flavor
generate_a_winpython_distropy_meta.bat winpython_builds.toml --dry-run :: 只打印构建命令,不执行
--dry-run 会调用 build_winpython_meta.py 中的 run_build 打印完整的底层命令,其中就包含 --flavor、--requirements、--bytecode、--only-binary 等参数。这里的 3.13.12.0dot 正是该配置体系下已发布的正式版产物(版本号中无 b1 之类的 release level 后缀)。
二、3.13.12.0dot 完整包清单(原文档全量继承)
changelog 文件 WinPythondot-64bit-3.13.12.0.md 由三部分组成:Tools、Python packages、WheelHouse packages。以下清单为该版本的全部内容。
2.1 Tools(工具)
| Name | Version | Description |
|---|---|---|
| Python | 3.13.12 | Python programming language with standard library |
Tools 段列出的不是第三方工具链,而是发行版自身的核心运行时——Python 3.13.12 解释器及其标准库。该段由 wppm 在扫描发行目录时通过 utils.get_installed_tools() 收集(见 wppm/wppm.py),因此它在 dot 清单中只有 Python 一项,与 dot Flavor 的极简定位一致。
2.2 Python packages(预装包)
| Name | Version | Description |
|---|---|---|
| build | 1.4.0 | A simple, correct Python build frontend |
| colorama | 0.4.6 | Cross-platform colored terminal text. |
| packaging | 26.0 | Core utilities for Python packages |
| pip | 26.0.1 | The PyPA recommended tool for installing Python packages. |
| pyproject-hooks | 1.2.0 | Wrappers to call pyproject.toml-based build backend hooks. |
| setuptools | 82.0.0 | Easily download, build, install, upgrade, and uninstall Python packages |
| sqlite-bro | 0.13.1 | a graphic SQLite Client in 1 Python file |
| sv-ttk | 2.6.0 | A gorgeous theme for Tkinter, based on Windows 11's UI |
| wheel | 0.46.3 | Command line tool for manipulating wheel files |
| wppm | 17.2.20250823 | WinPython Package Management |
2.3 WheelHouse packages(预置 wheel 仓库)
| Name | Version | Description |
|---|---|---|
| (空) |
WheelHouse 段为空,说明该 dot 发行版没有附带 wheelhouse\included.wheels 离线 wheel 目录。从 wppm 的索引生成逻辑可以印证这一点:wheelhouse_list 只有在 my_wheeldir(默认 wheelhouse/included.wheels)目录存在时才会被填充(见 wppm/wppm.py),目录不存在则保持空表——这正是"预置科学计算包离线仓库"这一能力在 dot Flavor 中被刻意省略的体现。若需离线安装包,用户可自行用 wppm 的 wheelhouse 功能构建本地仓库。
三、包清单的分组逻辑:mandatory 与 dot requirements
这份 10 个包的清单并非随机拼凑,而是由两类需求文件叠加(pip 依赖解析)得到的,理解其分组有助于判断每个包"为什么会在里面"。
3.1 每个发行版都强制的包(mandatory)
mandatory_requirements.txt 的内容如下:
# the mandatory
pip
setuptools
#not Wheel
wppm
这 3 个包(pip、setuptools、wppm)是所有 Flavor 构建的公共底线,由 build_winpython_meta.py 在构建时以 --mandatory-req 参数传给底层构建流程——pip 与 setuptools 保证发行版开箱即具备安装能力,wppm 则保证包管理能力。因此 3.13.12.0dot 清单中 pip 26.0.1、setuptools 82.0.0、wppm 17.2.20250823 三者的出现是强制性的,而不是依赖带入的。
3.2 dot Flavor 自己的包清单
dot_requirements.txt 是 dot 区别于其他 Flavor 的核心:
# the essential
sqlite_bro
setuptools
wheel
build
##msvc_runtime
# end of requirements.txt
- sqlite_bro:单文件实现的图形化 SQLite 客户端(以 Tkinter 为界面),适合数据查看与调试;
- setuptools / wheel / build:构成一套完整的"打包三件套"——setuptools 负责构建后端,wheel 负责操作
.whl文件,build 则是 PyPA 推荐的、从源码构建 wheel/sdist 的前端入口(python -m build)。这与 WinPython 让发行版自带构建能力的定位直接相关; ##msvc_runtime被注释掉,说明该版本不额外强制 MSVC 运行时包(按需由包自身携带)。
3.3 由依赖解析带入的包
清单中还有 4 个包是上述直接声明包的传递依赖,可从仓库元数据确认其来源:
- packaging 26.0:wppm 的运行时依赖——pyproject.toml 中
dependencies = <a href="https://link.gitcode.com/i/3c3736b83bee8bd3f09c2d665543a05e" target="_blank">"packaging"],wppm 的版本解析、PEP 440 比较都依赖它(例如 [wppm/diff.py 中find_previous_version就用version.parse做版本排序); - colorama 0.4.6 与 pyproject-hooks 1.2.0:build 包(1.4.0)的依赖,分别提供跨平台彩色终端输出与基于 pyproject.toml 的构建后端钩子调用封装;
- sv-ttk 2.6.0:sqlite-bro 的依赖,为 Tkinter 应用提供基于 Windows 11 UI 风格的主题。
由此可以画出一条清晰的依赖链:dot 的 10 个包 = 3 个 mandatory(pip/setuptools/wppm)+ 4 个 dot 声明(sqlite_bro/setuptools/wheel/build,setuptools 重复)+ 4 个传递依赖(packaging/colorama/pyproject-hooks/sv-ttk),且所有版本均满足 constraints.txt 中列出的最低版本约束(如 wppm>=17.2.20250823、setuptools>=80.9.0、sqlite_bro>=0.13.1、sv-ttk>=2.6.0、wheel>=0.45.1、packaging>=25.0)。
四、这份 changelog 是怎么生成的:构建管线第 7 步
changelog 不是人工维护的清单,而是 WinPython 构建流程的自动产物。在 winpython/build_winpython.py 中,构建脚本以"Step 7: generate changelog"明确完成了这一工作:
changelog_version = f"{winpyver2}{args.release_level}"
mdn = f"WinPython{args.flavor}-{args.arch}bit-{changelog_version}.md"
out = f"WinPython{args.flavor}-{args.arch}bit-{changelog_version}_History.md"
changelog_dir = log_dir.parent / "changelogs"
关键机制有三点:
- 命名规则:文件名由
WinPython+{flavor}+-{arch}bit-+{version}拼接。3.13.12.0dot 对应 flavor=dot、arch=64、version=3.13.12.0,与本仓库 changelogs 目录中的实际文件名完全一致; - release level 必须并入版本名:源码注释(winpython/build_winpython.py)解释了原因——一个 b1 预览版与它最终演变成的正式版共享同一个
winpyver2(如 3.15.0.5),若不在文件名中区分 level,预览版的包清单就会覆盖正式版的文件;3.15.0.5b1是合法的 PEP 440 版本号,可以按预期参与排序; - 实际生成由 wppm 完成:构建脚本以子进程方式执行
wppm.Distribution().generate_package_index_markdown()(winpython/build_winpython.py),生成的 Markdown 先写到构建输出目录,再shutil.copyfile归档到 changelogs 目录。
generate_package_index_markdown 的实现位于 wppm/wppm.py:它先调用 get_package_index_data 汇总"distribution 元信息 + tools + packages + wheelhouse"四类数据,再通过 render_markdown_for_list 将每组渲染成 Name | Version | Description 表格(wppm/wppm.py),并按名称字母序排序、为每个包自动生成指向 PyPI 的 https://pypi.org/project/{name} 链接。此外,索引中的 distribution 元信息会读取环境变量 WINPYVER2 / WINPYFLAVOR / WINPYVER(wppm/wppm.py)——构建脚本在调用前显式 set 了这三个变量,这正是 changelog 标题能写出 "WinPython 3.13.12.0dot" 与 64bit 标识的原因。
4.1 旁边的 _History 文件做什么
同名 _History.md 文件(diff 结果)则由 wppm/diff.py 的 compare_package_indexes 生成,对比当前版本与同 Flavor 的前一版本,逐段输出包的新增/移除/升级。构建脚本刻意不将 History 文件复制进 changelogs 归档(winpython/build_winpython.py 注释说明):包索引用于长期归档,而"距上一版的变化"是给构建者即时看的,Flavor 之间变化频繁,发布意义不大;读者需要对比时,可自行用 wppm -diff <a>.md <b>.md 选择任意两个索引。
五、用 wppm 自行复现与对比包索引
wppm 既是 WinPython 发行版内的包管理器,也提供了生成/对比包索引的 CLI。根据 wppm/main.py(python -m wppm 即调用 wppm.wppm.main())与 pyproject.toml 中的 console script 定义,常用命令如下:
# 为当前 Python 发行版重新生成包索引 Markdown(对应 changelog 的 Tools/Packages/WheelHouse 三表)
python -m wppm -markdown
# 以 JSON 形式输出同一份索引数据(便于程序化消费)
python -m wppm -json
# 对比两份包索引,输出差异报告
wppm -diff changelogs/WinPythondot-64bit-3.13.12.0.md changelogs/WinPythondot-64bit-3.13.11.0.md
其中 -diff 的更多用法(按 section 对比、按配对对比、按版本号从 changelogs 目录检索等)在 wppm/diff.py 的 print_usage 中有完整说明。-markdown 与 -json 分支位于 wppm/wppm.py,-json 直接打印 get_package_index_data 的字典结构(含 distribution 元信息、tools、packages、wheelhouse 四键)。
六、小结
WinPython 3.13.12.0dot 是一份目标明确的极简发行版:Python 3.13.12 解释器 + 10 个经过精心挑选的包(3 个 mandatory + 4 个 dot 声明 + 4 个依赖),无 wheelhouse 预置仓库。其 changelog 由构建管线第 7 步调用 wppm 自动生成,命名、归档与 _History 对比都遵循一套可复现的规则。理解这份清单的生成机制后,你可以通过 python -m wppm -markdown 在任何 WinPython 发行版上随时重建自己的包索引,也可以用 wppm -diff 横向对比任意两个版本的包构成,用于升级评估或镜像维护。