文章目录
- cookiecutter-pypackage：Python 包项目模板
cookiecutter-pypackage：Python 包项目模板
audreyfeldroy/cookiecutter-pypackage 是一个基于 Cookiecutter 的 Python 包项目模板，目前累计 4,579 个 Star：
这个模板的目标是为 Python 开发者提供一个可直接投入生产的项目起点。它基于 Cookiecutter 构建，通过交互式命令行引导用户填写项目基本信息，随后生成一个包含完整工具链和自动化流程的代码仓库。
模板内置的开发工具覆盖了包管理的各个环节。包管理使用 uv，它在处理依赖的同时自动维护虚拟环境，省去了手动激活和切换的步骤。代码格式化与静态检查由 ruff 负责，ruff 将原本需要多个工具分别完成的任务合并为一条命令。类型检查选用 ty，默认启用所有规则，并提供 watch 模式方便开发时实时反馈。测试框架采用 pytest，配置覆盖 Python 3.12、3.13 和 3.14 三个版本。命令行接口基于 Typer 实现，模板中已包含入口点定义和__main__.py文件。文档系统由 Zensical 和 mkdocstrings 组成，前者负责站点渲染，后者从 docstring 中提取接口说明，整体自动部署到 GitHub Pages。
CI/CD 部分基于 GitHub Actions 实现，包含四个工作流。CI 工作流在每次 Push 和 Pull Request 时触发，依次执行格式化检查、类型校验和多版本单元测试。发布工作流在推送v*标签时启动，完成构建后通过 Sigstore 生成签名证明，再经由 Trusted Publishers 机制将包发布到 PyPI，整个过程不需要手动管理 token。文档工作流监听 main 分支的变更，自动构建并重新部署到 GitHub Pages。Dependabot 每周检查一次 Action 依赖，生成更新 PR。安全方面，所有 GitHub Actions 均通过 SHA 值固定版本，权限按最小化原则分配，不保留持久凭证。
快速上手需要先安装 uv，然后执行：
uvx cookiecutter-pypackage命令会依次询问包名、GitHub 用户名等配置项。填写完成后，当前目录下会生成一个完整的项目结构。将项目推送到 GitHub 后，按照官方教程启用 Pages 并配置 PyPI Trusted Publisher 即可完成发布准备。
对于不使用 uvx 的环境，也可以手动创建虚拟环境并安装 cookiecutter：
uv venvsource.venv/bin/activate uv pipinstallcookiecutter cookiecutter gh:audreyfeldroy/cookiecutter-pypackage项目文档覆盖从生成到发布的完整链路，包括逐步教程、项目结构说明、GitHub Actions 配置与安全加固说明、每个提示项的含义解释，以及常见问题的排查方法。文档站点托管在 GitHub Pages 上，随代码仓库同步更新。
该模板由 Audrey M. Roy Greenfeld 创建和维护，采用 MIT 协议开源。它的配置较为固定，适合希望减少项目初始化工作量的开发者。如果默认方案不适合特定场景，可以查看社区 fork 中的各类变体，或基于 Cookiecutter 从零创建自定义模板。
中的各类变体，或基于 Cookiecutter 从零创建自定义模板。
