该检查清单聚焦发布前终态验证，涵盖代码质量、依赖、文档及分发兼容性，按源码层、构建层、分发层分层组织，支持自动化、防错提示与向后兼容。
在将 Python 项目正式发布前，需系统性验证代码质量、依赖完整性、文档可用性及分发兼容性。以下是构建该检查清单的核心设计思路：
一、明确检查维度与边界
检查清单不应覆盖开发全流程，而应聚焦于“发布动作触发前”的终态确认。其范围限定为可验证、可自动化、与分发强相关的项，排除主观性高或需人工长期评审的内容（如算法优劣、架构合理性）。每个条目必须对应一个明确的判定标准，例如“pyproject.toml 中存在 [project] 段且 version 字段非空”而非“项目配置合理”。
1、识别发布目标类型：确定是发布为 PyPI 包、Docker 镜像、CLI 工具还是内部 wheel 文件，不同目标决定检查重点。
2、区分强制项与建议项：强制项缺失即阻断发布（如缺少 LICENSE 文件），建议项仅提示风险（如未配置 pre-commit 钩子）。
立即学习“Python免费学习笔记（深入）”；
3、剔除环境相关检查：不验证 CI/CD 环境变量或本地 IDE 设置，仅检查项目内嵌资产（如配置文件、元数据）。
二、分层组织检查项结构
按软件交付生命周期中信息沉淀的物理位置与逻辑层级划分检查组，确保无遗漏且易于定位问题来源。底层为源码级事实，上层为元数据与契约声明，顶层为外部可观察行为。
1、源码层：检查 Python 语法合法性、PEP 8 合规性、类型注解完整性（若启用 mypy）、无未处理的 TODO/FIXME 注释。
2、构建层：验证 pyproject.toml 或 setup.py 是否定义了正确的 build-backend、requires-build、project.dependencies 和 project.optional-dependencies。
3、分发层：确认 MANIFEST.in 存在且覆盖了非 Python 资源（如 README.md、static/ 目录）、wheel 构建后能通过 auditwheel 或 delv 检查 ABI 兼容性（如适用）。
三、支持可执行性与自动化集成
每项检查必须能映射到一条可脚本化命令或 API 调用，避免依赖人工肉眼比对。设计时预设其运行上下文为干净的临时虚拟环境，并要求所有工具依赖声明在项目自身配置中可解析。
1、为每个检查项指定唯一标识符（如 CHECK-PY-001），便于日志追踪与 CI 报告聚合。
2、提供默认阈值与可覆盖参数：例如代码行覆盖率检查默认要求 ≥80%，但允许在配置中设为 75% 或禁用。
3、输出格式统一为机器可读的 JSON 或符合 pytest 的 xunit XML，支持直接接入 GitHub Actions 或 Jenkins 的质量门禁。
四、内置防错与上下文感知机制
检查清单需主动识别常见误操作场景并给出针对性反馈，而非仅返回失败状态。例如当检测到 git 未提交暂存区变更时，应指出“未提交文件：setup.py、CHANGELOG.md”，而非仅提示“版本控制状态异常”。
1、检测当前分支是否为预期发布分支（如 main 或 stable），若非则强制中断并提示切换分支。
2、校验版本号格式是否匹配所选发布策略（如 PEP 440 规范），若发现 “v1.2.3” 或 “1.2.3-beta” 等非法格式，立即输出标准化建议格式。
3、扫描项目根目录是否存在 .pypirc 或 PYPI_TOKEN 环境变量，若缺失且检查项涉及上传操作，则跳过上传验证但标记为警告。
五、保持向后兼容与最小侵入原则
检查清单本身不得修改项目文件，也不得引入运行时依赖。所有验证逻辑应通过只读方式访问文件系统或调用标准库接口完成，避免因检查过程导致项目状态意外变更。
1、不自动格式化代码或重写配置文件，仅报告差异位置与合规建议。
2、对已弃用但尚被支持的字段（如 setup.py 中的 long_description_content_type），标注弃用等级与替代方案路径，但不视为错误。
3、当检测到 pyproject.toml 与 setup.py 并存时，优先采用 pyproject.toml 并警告移除 setup.py，而非报冲突错误。
