coopie

基于 copier 的通用 Python 项目模板。

Python License

简介

coopie 是一个 copier 模板仓库，用于生成符合现代 Python 工程实践的项目骨架。提供 coopie CLI 封装 copier copy/recopy 命令，简化模板调用。模板内置：

构建工具链：hatchling + uv + ruff + pyrefly + pytest + coverage
Python 版本：3.8 ~ 3.14（可配置最低/最高版本）
代码质量：pre-commit 钩子 + ruff lint/format，可配置覆盖率阈值
CI/CD：GitHub Actions（lint + typecheck + 多版本测试 + 自动发布到 PyPI）
文档：Sphinx + ReadTheDocs（中文 zh_CN）
多版本测试：tox + tox-uv
项目类型：library / cli / gui（PySide2/PySide6）/ web（FastAPI）
项目结构：src layout + py.typed 类型标记

使用方式

前置要求

Python ≥ 3.8
uv ≥ 0.5（推荐）

使用 coopie CLI（推荐）

# 安装 coopie CLI（自动安装 copier 依赖）
uvx coopie init my-project

# 或 pip 安装后使用
pip install coopie
coopie init my-project

coopie init 默认使用 Gitee 国内源，可用 --url 切换：

# 使用 GitHub 源
coopie init my-project --url https://github.com/gookeryoung/coopie.git

# 指定模板版本
coopie init my-project --vcs-ref v0.8.0

# 使用默认参数跳过交互（CI/脚本化场景）
coopie init my-project --defaults

# 信任模板源，跳过 copier 的模板执行安全确认（仅用于可信模板）
coopie init my-project --trust

coopie 默认不自动 trust 模板源：模板含 Jinja/任务时 copier 会请求确认。确认模板来源可信后再加 --trust，避免静默执行第三方模板中的代码。

使用 copier 原生命令（备选）

# 国内用户推荐 Gitee 源（访问稳定）
uvx copier copy --trust https://gitee.com/gooker_young/coopie.git my-project

# 国外用户可使用 GitHub 源
uvx copier copy --trust https://github.com/gookeryoung/coopie.git my-project

--trust 用于信任模板仓库以执行渲染。如需指定模板版本，附加 --vcs-ref v0.8.0。

执行后 copier 会交互式询问项目名称、包名、Python 版本范围、项目类型（library/cli/gui/web）等参数，并在 my-project/ 目录生成完整工程骨架。

模板参数速览

参数	类型	默认值	说明
`project_name`	str	`my-project`	项目名称（用于 README/文档标题）
`package_name`	str	由 `project_name` 派生	Python 包名（小写+下划线）
`description`	str	`A Python project.`	项目简短描述
`author_name` / `author_email`	str	空	作者信息
`min_python_version` / `max_python_version`	str	`3.8` / `3.14`	Python 版本范围
`license`	str	`MIT`	许可证（MIT/Apache-2.0/GPL-3.0/None）
`project_type`	str	`library`	项目类型（library/cli/gui/web）
`use_docs`	bool	`true`	是否包含 Sphinx 文档配置
`use_docker`	bool	`false`	是否包含 Dockerfile
`use_cicd`	bool	`true`	是否包含 GitHub Actions CI/CD
`use_tox`	bool	`true`	是否包含 tox 多版本测试
`use_domestic_mirrors`	bool	`true`	是否预置国内镜像源（pip/uv 华为云源、apt 华为云）
`coverage_fail_under`	int	`95`	覆盖率阈值（百分比）

完整参数说明见 copier.yml。

更新已有项目

当模板版本升级后，在已生成的项目目录中执行：

# 使用 coopie CLI（推荐）
coopie update

# 信任模板源时
coopie update --trust

# 或使用 copier 原生命令
uvx copier update --trust

coopie update 调用 copier recopy，基于 .copier-answers.yml 中记录的答案重新渲染模板。模板源来自该文件里的 _src_path，因此默认不自动 trust——确认来源可信后再加 --trust。

模板开发

本仓库自身即 copier 模板，开发流程如下：

# 安装开发依赖（lint + test + docs 工具链）
uv sync --extra dev

# 校验代码
uv run ruff check
uv run ruff format --check

# 类型检查
uv run pyrefly check

# 运行测试
uv run pytest

# 本地构建文档
make doc

# 渲染验证（不写入磁盘）
uvx copier copy --trust --defaults --vcs-ref HEAD . /tmp/preview-lib

Make 快捷命令

make sync      # 安装开发依赖
make lint      # ruff 检查
make typecheck # pyrefly 类型检查
make test      # 运行测试
make cov       # 测试 + HTML 覆盖率报告
make check     # 全套门禁 (lint + typecheck + typecheck-ci + cov)
make doc       # 构建 Sphinx 文档
make build     # 构建 Python 包
make bump PART=patch  # 版本号 bump（创建 git tag，供 copier --vcs-ref 引用）
make push      # 推送到所有远程仓库

目录结构

coopie/
├── copier.yml              # Copier 模板配置（参数定义与渲染规则）
├── template/               # 模板内容（Jinja 渲染源，所有文件均参与渲染）
│   ├── src/{{ package_name }}/
│   ├── tests/
│   ├── pyproject.toml      # 模板内的 pyproject.toml（含 Jinja 表达式）
│   ├── README.md           # 模板内的 README（含 Jinja 表达式）
│   └── ...
├── src/coopie/             # coopie CLI 包（封装 copier copy/recopy）
│   ├── __init__.py
│   ├── cli.py              # Typer CLI 入口（init/update 命令）
│   └── py.typed
├── tests/                  # coopie CLI 测试
├── docs/                   # 本仓库的 Sphinx 文档
└── pyproject.toml          # 本仓库元数据与工具配置

文档

文档由 Sphinx 构建，托管在 ReadTheDocs：

make doc

许可证

MIT

Metadata

Release files for coopie 1.0.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coopie 1.0.10
File	Size	Uploaded
coopie-1.0.10.tar.gz	152.4 kB	Oct 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for coopie 1.0.10
File	Interpreter	ABI	Platform	Reset
coopie-1.0.10-py3-none-any.whl 9.9 kB Oct 12, 2026	Python 3	none	any	Details

Total release size: 162.3 kB

Release files / coopie-1.0.10.tar.gz

Download URL	coopie-1.0.10.tar.gz
Size	152.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`aec9ae4413c725e86459748b2ecd34c9367572947f47f7123fbb56a791defe28`
BLAKE2b-256 checksum How to use checksums	`684da0a35562a78057bf74de99640d9fb626ae729ae397f0b8e9b561272fbb46`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / coopie-1.0.10-py3-none-any.whl

Download URL	coopie-1.0.10-py3-none-any.whl
Size	9.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2441bd3cc1dc0e341a497e89383ba7b259ed45c985e512f2d73fa3d721d68c02`
BLAKE2b-256 checksum How to use checksums	`6e33facf5a7cf186c044268074c059c99a64f7eaa6674fb06d578d89d4bcb042`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`