coopie
基于 copier 的通用 Python 项目模板。
简介
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
1 maintainer
Metadata
1 maintainer
Release files for coopie 1.0.13
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| coopie-1.0.13.tar.gz | 150.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| coopie-1.0.13-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 160.4 kB
Release files / coopie-1.0.13.tar.gz
| Download URL | coopie-1.0.13.tar.gz |
|---|---|
| Size | 150.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ea419f9c774d7797540ecbdb8922b400733d9f1e14b66e8a1659347f9f6ffcba
|
|
BLAKE2b-256 checksum How to use checksums |
02e252ba91e143b737d9a264ef034b4a5cabf8591cce84a1f4c5685766d8b3e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.13-py3-none-any.whl
| Download URL | coopie-1.0.13-py3-none-any.whl |
|---|---|
| Size | 10.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
50ed9a00832d9142460350c49069add80a652e26ff79a7e6a7c7128995c4f799
|
|
BLAKE2b-256 checksum How to use checksums |
2d35cfc8a961b78fb8b46bb3cc34132526cbf32df92079e5f327155f75792eee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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}
|
Security for coopie 1.0.13
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
