WinPython 3.13.12.0dot 发行版包清单深度解析:dot Flavor 极简构成与 changelog 自动生成机制

原创2026-10-16 23:48:462,293 阅读
文章标签:包管理器开发工具CLI构建工具

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"

关键机制有三点:

  1. 命名规则:文件名由 WinPython + {flavor} + -{arch}bit- + {version} 拼接。3.13.12.0dot 对应 flavor=dot、arch=64、version=3.13.12.0,与本仓库 changelogs 目录中的实际文件名完全一致;
  2. release level 必须并入版本名:源码注释(winpython/build_winpython.py)解释了原因——一个 b1 预览版与它最终演变成的正式版共享同一个 winpyver2(如 3.15.0.5),若不在文件名中区分 level,预览版的包清单就会覆盖正式版的文件;3.15.0.5b1 是合法的 PEP 440 版本号,可以按预期参与排序;
  3. 实际生成由 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 横向对比任意两个版本的包构成,用于升级评估或镜像维护。

登录后查看全文
winpython