企业官网建设流程全解析

• 开发工具
• 构建工具
• CLI
• 包管理器

WinPython 3.8.6.0dot 是面向 Windows 平台的免费 Python 发行版 WinPython 在 64 位架构下的一种 "dot" 风味（flavor）构建，其随附的包索引文档（WinPythondot-64bit-3.8.6.0.md）精确记录了该版本内置的每一个 Python 包及其版本号。本文将以这份索引为主体，逐项解析各包的用途与版本演进，并结合当前仓库的源码（winpython_builds.toml、winpython/build_winpython.py、wppm/wppm.py、wppm/diff.py）揭示这类 Markdown 包清单与_History变更记录究竟是如何在构建流水线中被自动生成的，帮助读者既读懂一份 changelog，也理解其背后的发行版构建与发布链路。

一、背景：什么是 WinPython 的 "dot" 风味

WinPython 仓库采用"Python 版本 × 风味（flavor）"的二维矩阵来组织本地构建。构建配置集中在仓库根目录的 winpython_builds.toml 中，其中[flavors.dot]一节即定义了 dot 风味的构成：

[flavors.dot] requirements = "dot_requirements.txt" source_dirs = "packages.win-amd64" toolsdirs = "bdTools\\Tools.dot"

从源码结构看，winpython_builds.toml的注释说明了各字段的派生关系：requirements指向该风味专属的依赖清单，source_dirs指向存放 Python 官方安装包/zip 的本地目录，toolsdirs指向随发行版捆绑的外部工具目录；而 build_winpython_meta.py 中的expand_builds()会把[pythons."3XX"]与[flavors.xxx]两两组合展开成具体的构建任务，并推导出basedir、requirements、toolsdirs等路径。

changelogs/目录中同版本号下并存多个风味文件，如WinPython-64bit-3.8.6.0.md、WinPythoncod-64bit-3.8.6.0.md、WinPythondot-32bit-3.8.6.0.md与本文主题的WinPythondot-64bit-3.8.6.0.md，正体现了"同一 Python 版本、不同风味与位宽"的矩阵发布方式。

二、3.8.6.0dot 内置的 Python 包清单

包索引文档的 "Python packages" 一节列出了该发行版出厂时内置的全部 Python 包，共 7 项，如下表所示（名称、版本、描述均完整继承自原文档）：

这些包可以按职责划分为四类：

• 解释器本体：Python 3.8.6，即 CPython 3.8 系列的 3.8.6 维护版本，自带标准库。
• 运行时依赖：msvc_runtime 14.27.29016.1，负责把 Microsoft Visual C++ 运行时 DLL 安装到sys.prefix与Scripts目录，为需要原生 C 运行时的扩展包提供支撑。
• 包管理基础设施：pip 20.2.4（安装 Python 包的官方工具）、setuptools 50.3.2（构建/升级/卸载包）、wheel 0.35.1（wheel 内置包格式），三者构成 Python 打包生态的核心底座。
• 发行版专属工具与桌面应用：winpython 3.0.20201028（WinPython 发行版工具集，内含 WPPM——WinPython Package Manager）、sqlite_bro 0.9.1（单文件实现的图形化 SQLite 客户端）。

与当前 dot 依赖清单的呼应

将这份出厂清单与仓库根目录的 dot_requirements.txt 对照，可以看到 dot 风味的"精华"依赖集合正是围绕上述包组织起来的：

# the essential sqlite_bro setuptools wheel build ##msvc_runtime # end of requirements.txt

值得注意的是：3.8.6.0dot 出厂包含msvc_runtime，而在当前仓库的dot_requirements.txt中该行以##注释形式存在，说明 dot 风味的依赖集合随版本演进发生过调整——这正是 changelog 存在的价值：逐版本追踪这类内置组成的变化。

三、从 3.8.5.0dot 到 3.8.6.0dot 的升级记录

配套的 WinPythondot-64bit-3.8.6.0_History.md 记录了相对上一版本 3.8.5.0dot 的所有升级，共 5 项：

升级内容呈现明显的节奏特征：解释器从 3.8.5 升到 3.8.6（3.8 系列的常规维护版本推进）；pip 由 20.2.2 升至 20.2.4，setuptools 由 49.6.0 升至 50.3.2，属于打包工具链的同步跟进；winpython工具包从 3.0.20200808 更新至 3.0.20201028，时间戳式版本号对应构建日期 2020-10-28，说明随发行版内置的 WPPM 工具在该周期内有功能更新。

四、包索引 Markdown 的源码级生成原理

这份 changelog 并非手工编写，而是构建流水线的自动产物。winpython/build_winpython.py 的 Step 7 "generate changelog" 展示了完整调用链：

cmd = ["set", f"WINPYVER2={winpyver2}&", "set", f"WINPYFLAVOR={args.flavor}&", "set", f"WINPYVER={winpyver2}{args.flavor}{args.release_level}&", str(target_python), "-X", "utf8", "-c" , ( "from wppm import wppm;" "result = wppm.Distribution().generate_package_index_markdown();" f"open(r'{winpydirbase.parent / mdn}', 'w', encoding='utf-8').write(result)" )]

其核心是 wppm/wppm.py 中Distribution.generate_package_index_markdown()，该方法：

1. 调用get_package_index_data()收集三类数据：发行版身份（名称、版本、Python 版本、位宽、发布级别）、Tools 工具列表、Python 包列表；
2. 用render_markdown_for_list()将每个列表渲染为Name | Version | Description三列 Markdown 表格——这正是 changelog 中表格的精确格式来源（见 wppm/wppm.py）：

   md += "Name | Version | Description\n" md += "-----|---------|------------\n"

3. 包名在渲染时按(名称小写, 版本)排序，保证清单输出稳定可读。

包列表的数据来自get_installed_packages()，它通过pip list --format=full枚举目标解释器的已装包，再经Package类标准化为(name, version, summary)三元组。而发行版身份中的"version": my_winpyver2 + my_flavor（见 wppm/wppm.py）恰好解释了文档标题 "WinPython 3.8.6.0dot" 的构成：3.8.6.0（winpyver2）拼接风味后缀dot。

Tools 节为何为空

原文档中 "Tools" 表格没有任何条目。对照当前仓库 wppm/utils.py 的get_installed_tools()实现，Tools 节会尝试登记 Python 解释器以及检测到的外部工具（如root/n/node.exe对应的 Node.js、root/t/pandoc.exe对应的 Pandoc、root/t/VSCode/Code.exe对应的 VSCode）。可以推断，3.8.6.0dot 发布时该节未登记任何外部工具，即这一构建没有捆绑 Node.js、Pandoc、VSCode 等独立可执行工具，属于纯 Python 包 + 解释器的精简形态；而当前生成逻辑的 Tools 节内容会随目标发行版实际捆绑的工具动态变化。

五、_History变更记录如何自动生成

配套的_History.md同样由流水线自动产出。在 winpython/build_winpython.py 中，构建脚本调用wppm.diff.compare_package_indexes()，而该函数定义于 wppm/diff.py：

• 以目标版本号（如3.8.6.0）为参数，在changelogs/目录中按WinPython{dot}-{64}bit-{version}.md命名模式（见changelog_versions()，wppm/diff.py）扫描同风味的所有历史索引；
• find_previous_version()用 PEP 440 版本解析找出小于当前版本的最大版本（即 3.8.5.0dot），从而自动定位"上一版"；
• compare_markdown_sections()逐节对比两份索引的 Markdown 表格，把版本有变化的包写成旧版本 → 新版本的升级条目，并统一输出为 "History of changes for WinPython-64bit ..." 标题与* * *结尾的格式——与_History.md的版式完全吻合。

值得注意的设计细节：源码注释（wppm/diff.py）指出，比较是有方向的——每行升级都按 "old → new" 书写，若把两份索引的先后顺序弄反，所有升级都会被误读为降级；而wppm -diff命令行工具允许用户以文件模式或版本模式比较任意两个发行版索引。

六、实战：用 WPPM 解读与比较发行版

随发行版内置的winpython包（3.0.20201028）携带 WPPM（WinPython Package Manager），可用于复查与解读这类索引背后的真实环境：

:: 列出目标发行版中匹配的已装包 wppm -ls wppm -ls sqlite :: 生成当前安装的 Markdown 摘要（与 changelog 同格式） wppm -md :: 比较任意两个包索引文件（无需连续版本，方向任意） wppm -diff WinPythondot-64bit-3.8.6.0.md WinPythondot-64bit-3.8.5.0.md :: 按版本号模式比较（从 changelogs 目录读取） python -m wppm.diff 3.8.6.0 3.8.5.0 changelogs dot 64

其中-diff的文件模式不涉及任何发行版，直接读取两份 Markdown 索引逐节对比；-md则与构建脚本 Step 7 使用同一套generate_package_index_markdown()渲染逻辑，因此用户在任何已装 WinPython 上都能复现出与 changelog 同构的包清单（见 wppm/wppm.py 中参数定义与说明）。

七、版本命名与构建目录约定

版本号3.8.6.0dot的解析逻辑贯穿构建链路：在 build_winpython_meta.py 中，目标目录被构造成bd{target}\bu{flavor}\WPy{arch}-{release}{release}{level}形式；而在 winpython/build_winpython.py 中，winpyver2由目录名解析为点分版本（如3.8.6.0），再拼接args.flavor得到3.8.6.0dot，最终写入 Markdown 的版本字段。构建脚本还会把生成的索引复制到仓库的changelogs/目录归档（winpython/build_winpython.py），这正是本仓库changelogs/下数百份历史索引的来源。

结语

一份看似简单的WinPythondot-64bit-3.8.6.0.md，实际上是 WinPython 构建流水线的"档案快照"：它记录了 dot 风味在 3.8.6.0 时刻的精确软件组成（CPython 3.8.6 + 打包工具链 + WPPM + sqlite_bro），而_History.md则通过wppm/diff的版本化比较自动沉淀了与上一版的差异。理解这两份文件的生成原理后，读者不仅会读 changelog，更能借助 wppm/wppm.py 与 wppm/diff.py 在任意已安装发行版上复现包清单、比对任意两个版本，从而把"发行说明"转化为自己排查环境与选择版本的实用工具。

• 开发工具
• 构建工具
• CLI
• 包管理器