使用cookiecutter创建python项目

涛哥依旧在

已于 2025-09-15 22:16:41 修改

阅读量883

点赞数 28

CC 4.0 BY-SA版权

分类专栏：日常学习 Python 文章标签： python 开发语言

于 2025-09-15 16:41:23 首次发布

26 篇文章

订阅专栏

7 篇文章

订阅专栏

一、关于Python项目结构

Python 项目并没有完全统一的 “固定结构”，但行业内有一些广泛遵循的约定俗成的目录结构（尤其针对可分发的包或大型项目）。同时，确实有工具可以快速生成这些标准化结构，提高开发效率，这在实际开发中非常常见。

对于需要打包、发布或多人协作的项目，典型结构如下：

对于简单脚本或小项目，结构可以简化（例如只有 src/ 目录和几个核心文件）。

今天我们介绍一下最流行的项目模板工具Cookiecutter，支持通过模板快速生成标准化结构，不仅限于 Python。

Cookiecutter 是一个由 Audrey Roy Greenfeld（开源社区活跃开发者）发起并主导开发的开源项目，其核心维护团队包括多位社区贡献者，并非由特定商业公司作为 “发行人” 或 “ publisher ” 进行官方发布。

如果要安装到虚拟化环境下，在虚拟化终端执行“pip install cookiecutter”命令：

运行：cookiecutter https://github.com/audreyr/cookiecutter-pypackage（Python 包标准模板），前提是能访问github。

提示：执行改命令要提前安装了git，在宿主机上安装即可，并将git.exe所在目录添加到了path环境变量中。

如果已经创建过项目的话，cookiecutter会在本地创建缓存模板，这样的话可以直接用本地的，用法有：

cookiecutter C:\Users\yourname\.cookiecutters\cookiecutter-pypackage

或者

cookiecutter cookiecutter-pypackage

系统会自动从默认的缓存路径 ~/.cookiecutters/ 下去寻找名为 cookiecutter-pypackage 的模板。

如果长时间用本地的，模板源有更新了，可以在联网时用下面的命令更新本地模板：

cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage.git --overwrite-if-exists

下载的模板文件默认缓存在本地的如下目录下：

接下来根据模板要求一次输入下面的full_name，可以是作者名称，团队名称，git上的用户名或者昵称，依次输入下面的名称，：

各字段的含义，我列个表：

提示信息	含义	示例回答	重要性
`full_name`	作者/维护者的全名（会写入版权和作者信息）	`Haitao Luo`	⭐⭐⭐⭐⭐
`email`	作者的联系邮箱	`your.email@example.com`	⭐⭐⭐⭐⭐
`github_username`	您的 GitHub 用户名	`your-github-username`	⭐⭐⭐⭐
`project_name`	项目的正式名称（可以包含空格，给人看的）	`My Awesome Project`	⭐⭐⭐⭐⭐
`project_slug`	项目的短标识（用于包名、目录名，电脑看的）	`my_awesome_project`	⭐⭐⭐⭐⭐
`pypi_username`	您在 PyPI 上的用户名（如果打算发布）	`your-pypi-username`	⭐⭐
`project_short_description`	项目的一句话简短描述	`A Python package that does awesome things.`	⭐⭐⭐⭐
`version`	项目的初始版本号	`0.1.0`	⭐⭐⭐
`use_pytest`	是否使用 pytest 作为测试框架	`y` (推荐)	⭐⭐⭐
`use_pypi_deployment_with_travis`	是否配置 Travis CI 自动发布到 PyPI	`n` (除非您明确需要)	⭐
`add_pyup_badge`	是否添加 Pyup 安全更新徽章	`n` (可选)	⭐
`command_line_interface`	是否添加命令行接口（CLI）	`Click` (推荐) 或 `Argparse` 或 `No`	⭐⭐

漏了一个pypi_package_name 就是您的包在“Python应用商店”（PyPI）里的“商品名”，需要独一无二且便于用户查找和安装。

创建结束后可以看到左侧树上有了对应的项目结构，并在windows资源管理器查看：

名称	说明
`src/`	源代码根目录。这是现代 Python 打包（PyPA）推荐的结构。您的实际包（package）就在这里的某个文件夹下。这种结构可以避免无意中导入本地其他文件而非已安装的包。
`tests/`	测试代码目录。存放所有单元测试和集成测试文件。通常与 `src/` 下的模块结构一一对应（例如 `src/mypackage/core.py` 的测试文件是 `tests/test_core.py`）。
`docs/`	项目文档目录。通常使用 Sphinx 或 MkDocs 来构建项目的详细文档。
`.github/`	GitHub 工作流配置。里面通常有 `workflows/` 文件夹，存放 GitHub Actions 的 YAML 配置文件，用于实现CI/CD（持续集成/持续部署），如自动运行测试、自动发布等。

名称	说明
`pyproject.toml`	现代Python项目的核心配置文件。取代了旧的 `setup.py`。它定义了项目构建依赖（如setuptools）、项目元数据（名称、版本、作者）、以及各种工具（如pytest、black、flake8）的配置。这是最重要的文件之一。
`LICENSE`	开源许可证。规定了他人使用您代码的权利和义务。常见的有MIT、Apache 2.0、GPL等。
`README.md`	项目首页文档。这是项目的门面，通常包含项目介绍、安装方法、快速使用示例、贡献指南等。在GitHub和PyPI上会直接显示。
`.gitignore`	Git忽略规则。指定哪些文件或目录不应该被纳入版本控制（如虚拟环境 `venv/`、编译缓存 `__pycache__/`、IDE配置等）。
`MANIFEST.in`	打包附加文件清单。当构建分发包（sdist）时，`pyproject.toml` 可能不会自动包含所有非代码文件（如文档、静态资源）。这个文件用来指明需要额外包含哪些文件。
`.editorconfig`	编辑器配置。帮助在不同编辑器和IDE之间保持代码风格（如缩进、字符集）的一致性。

名称	说明
`CODE_OF_CONDUCT.md`	行为准则。规定了社区交流合作的规范，为所有贡献者创造一个友好的环境。
`CONTRIBUTING.md`	贡献指南。详细说明如何为项目做贡献，如如何提交Issue、如何拉取请求（Pull Request）、代码风格要求等。
`HISTORY.md`	更新日志。记录每个版本的重大变更、新增功能和修复的Bug。
`justfile`	Just命令运行器配置。`just` 是一个类似 `make` 的命令运行工具，用于定义和管理项目常用的命令（如运行测试、构建文档、格式化代码等）。这是一个可选但很方便的工具。