pypreset

用于通过可配置 YAML 预设搭建 Python 项目的元工具。
支持 Poetry、uv 和 setuptools，可生成 CI 工作流、测试脚手架、类型检查配置等。

mcp-name: io.github.KaiErikNiermann/pypreset

功能

• 基于预设创建项目：从 YAML 配置创建，支持单层继承
• 增强现有项目：添加 CI 工作流、测试、Docker、文档等
• 三种包管理器：Poetry、uv（PEP 621 + hatchling）和 setuptools（PEP 621 + setuptools.build_meta）
• 两种布局风格：src/ 布局和平铺布局
• 类型检查：mypy、pyright、ty 或不使用
• 代码质量：ruff lint 和格式化、radon 复杂度检查、pre-commit 钩子
• Docker 和 devcontainer：生成多阶段 Dockerfile、.dockerignore 和 VS Code devcontainer 配置（Docker 或 Podman）
• 覆盖率集成：支持 Codecov，可配置阈值和忽略模式
• 文档脚手架：MkDocs（Material 主题）或 Sphinx（RTD 主题），可选通过 GitHub Pages 部署
• 多环境测试：使用 tox-uv 后端的 tox 配置
• pyenv / .python-version：为 pyenv 和 uv 生成 .python-version，并在 CI 工作流中使用 python-version-file
• 版本管理：集成 bump-my-version，通过 gh CLI 自动化 GitHub 发布
• 工作流验证：使用 act 在本地测试 GitHub Actions（自动检测、自动安装、试运行和完整运行模式）
• PyPI 元数据管理：读取、设置和检查 pyproject.toml 元数据是否已准备好发布
• 用户默认设置：将配置持久保存到 ~/.config/pypreset/config.yaml
• MCP 服务：通过 Model Context Protocol 向 AI 编码助手提供所有功能

安装

pip install pypreset

# With MCP server support
pip install pypreset[mcp]

快速开始

# Create a CLI tool project with Poetry
pypreset create my-cli --preset cli-tool

# Create a data science project with uv
pypreset create my-analysis --preset data-science --package-manager uv

# Create an empty package with src layout (default)
pypreset create my-package --preset empty-package

# Create a Discord bot
pypreset create my-bot --preset discord-bot

# Create a project with Docker support
pypreset create my-service --preset cli-tool --docker --devcontainer

# Create with .python-version for pyenv/uv
pypreset create my-lib --pyenv --python-version 3.13

# Create with Podman, Codecov, docs, and tox
pypreset create my-project --preset empty-package \
    --container-runtime podman --docker \
    --coverage-tool codecov --coverage-threshold 80 \
    --docs mkdocs --docs-gh-pages \
    --tox

命令

create —— 搭建新项目

pypreset create <name> [OPTIONS]

选项	说明
--preset, -p	要使用的预设（默认：empty-package）
--output, -o	输出目录（默认：.）
--config, -c	自定义预设 YAML 文件
--package-manager	poetry 或 uv
--layout	src 或 flat
--type-checker	mypy、pyright、ty 或 none
--typing	none、basic 或 strict
--python-version	例如，3.12
--testing / --no-testing	启用/禁用测试脚手架
--formatting / --no-formatting	启用/禁用格式化配置
--radon / --no-radon	启用 radon 复杂度检查
--pre-commit / --no-pre-commit	生成 pre-commit 钩子配置
--bump-my-version / --no-bump-my-version	包含 bump-my-version 配置
--extra-package, -e	额外的软件包（可重复指定）
--extra-dev-package, -d	额外的开发软件包（可重复指定）
--docker / --no-docker	生成 Dockerfile 和 .dockerignore
--devcontainer / --no-devcontainer	生成 .devcontainer/ 配置
--container-runtime	docker 或 podman
--coverage-tool	codecov 或 none
--coverage-threshold	最低覆盖率 %（例如，80）
--docs	sphinx、mkdocs 或 none
--docs-gh-pages / --no-docs-gh-pages	生成 GitHub Pages 部署工作流
--tox / --no-tox	生成使用 tox-uv 后端的 tox.ini
--pyenv / --no-pyenv	生成 .python-version，并在 CI 中使用 python-version-file
--git / --no-git	初始化 git 仓库
--install / --no-install	创建后安装依赖
--dry-run	预览将要创建的内容，不实际生成任何文件

augment -- 为现有项目添加组件

分析 pyproject.toml 以自动检测你的工具，然后生成所选组件。默认以交互模式运行（提示输入无法检测到的值）；使用 --auto 可跳过提示。

pypreset augment [path] [OPTIONS]

可用组件：

标志	组件	生成内容
--test-workflow / --no-test-workflow	测试 CI	GitHub Actions 工作流，在 Python 版本矩阵中运行 pytest
--lint-workflow / --no-lint-workflow	代码检查 CI	用于 ruff、类型检查和复杂度分析的 GitHub Actions 工作流
--dependabot / --no-dependabot	Dependabot	用于自动更新依赖项的 .github/dependabot.yml
--tests / --no-tests	测试目录	包含模板测试文件和 conftest.py 的 tests/
--gitignore / --no-gitignore	Gitignore	Python 专用 .gitignore
--pypi-publish / --no-pypi-publish	PyPI 发布	在发布时通过 OIDC 向 PyPI 发布的 GitHub Actions 工作流
--dockerfile / --no-dockerfile	Docker	多阶段 Dockerfile 和 .dockerignore（支持 Poetry、uv 或 setuptools）
--devcontainer / --no-devcontainer	Devcontainer	带有 VS Code 扩展的 .devcontainer/devcontainer.json
--codecov / --no-codecov	Codecov	codecov.yml 配置
--docs	文档	Sphinx 或 MkDocs 脚手架（--docs sphinx 或 --docs mkdocs）
--tox / --no-tox	tox	使用 tox-uv 后端进行多环境测试的 tox.ini
--readme / --no-readme	README	根据共享模板生成的 README.md（徽章、安装、功能）
--pyenv / --no-pyenv	pyenv	用于 pyenv 和 uv 版本固定的 .python-version 文件

# Interactive mode (prompts for missing values)
pypreset augment ./my-project

# Auto-detect everything, no prompts
pypreset augment --auto

# Generate only specific components
pypreset augment --test-workflow --lint-workflow --gitignore

# Add Docker and devcontainer
pypreset augment --dockerfile --devcontainer

# Add PyPI publish workflow
pypreset augment --pypi-publish

# Add documentation scaffolding
pypreset augment --docs mkdocs

# Generate a README from your project metadata
pypreset augment --readme

# Overwrite existing files
pypreset augment --force

workflow -- 本地工作流验证

使用 act 在本地验证 GitHub Actions 工作流。代理会自动检测是否已安装 act，可在支持的系统上安装，并直接显示所有 act 输出。

# Verify all workflows (dry-run, no containers)
pypreset workflow verify

# Verify a specific workflow file
pypreset workflow verify --workflow .github/workflows/ci.yaml

# Verify a specific job
pypreset workflow verify --job lint

# Full run (executes in containers, requires Docker)
pypreset workflow verify --full-run

# Auto-install act if missing
pypreset workflow verify --auto-install

# Pass extra flags to act
pypreset workflow verify --flag="--secret=GITHUB_TOKEN=xxx"

# Check if act is installed
pypreset workflow check-act

# Install act automatically
pypreset workflow install-act

支持自动安装的目标系统：Arch Linux（pacman）、Ubuntu/Debian（apt）、Fedora（dnf）、使用 Homebrew 的 macOS/Linux。其他系统会显示指向 act 安装页面 的链接。

version -- 发布管理

pypreset version release --bump patch     # 0.1.0 -> 0.1.1
pypreset version release --bump minor     # 0.1.0 -> 0.2.0
pypreset version release --bump major     # 0.1.0 -> 1.0.0
pypreset version release-version 2.0.0    # Explicit version
pypreset version rerun <ver>              # Re-tag and push an existing version
pypreset version rerelease <ver>          # Delete and recreate a GitHub release

需要安装并完成身份验证的 gh CLI。

metadata -- PyPI 元数据管理

pypreset metadata show                                   # Display current metadata
pypreset metadata set --description "My cool package"    # Set description
pypreset metadata set --github-owner myuser              # Auto-generate URLs
pypreset metadata set --license MIT --keyword python     # Set license and keywords
pypreset metadata check                                  # Check publish-readiness

badges -- 生成徽章 Markdown

读取 pyproject.toml 以检测项目名称、仓库 URL 和许可证，然后输出可粘贴到 README 中的徽章 Markdown。

pypreset badges                  # Badges for current directory
pypreset badges ./my-project     # Badges for a specific project

其他命令

pypreset list-presets              # List all available presets
pypreset show-preset <name>        # Show full preset details
pypreset validate [path]           # Validate project structure
pypreset analyze [path]            # Detect and display project tooling
pypreset config show               # Show current user defaults
pypreset config init               # Create default config file
pypreset config set <key> <value>  # Set a config value

预设

内置预设：empty-package、cli-tool、data-science、discord-bot。

预设是用于定义元数据、依赖项、目录结构、测试、格式设置等内容的 YAML 文件。它们支持通过 base: 字段进行单层继承。预设可以通过将 metadata.readme_template 设置为自定义 .j2 文件名来覆盖 README 模板。

自定义预设

将自定义预设文件放在 ~/.config/pypreset/presets/ 中，或直接传入文件：

pypreset create my-project --config ./my-preset.yaml

同名的用户预设优先于内置预设。

用户配置

持久化默认值存储在 ~/.config/pypreset/config.yaml 中，并作为优先级最低的一层应用（预设和 CLI 标志会覆盖这些默认值）。

pypreset config init                    # Create with defaults
pypreset config set layout flat         # Set default layout
pypreset config set type_checker ty     # Set default type checker
pypreset config show                    # View current config

MCP 服务

pypreset 已作为 io.github.KaiErikNiermann/pypreset 发布到 MCP Registry。

通过注册表安装（推荐）：

# Claude Code
claude mcp add pypreset -- uvx --from "pypreset[mcp]" pypreset-mcp

# Or add manually to ~/.claude/settings.json

{
  "mcpServers": {
    "pypreset": {
      "command": "uvx",
      "args": ["--from", "pypreset[mcp]", "pypreset-mcp"]
    }
  }
}

或在本地安装：

pip install pypreset[mcp]

{
  "mcpServers": {
    "pypreset": {
      "command": "pypreset-mcp",
      "args": []
    }
  }
}

可用工具：

工具	描述
create_project	使用预设创建新项目，并可选择覆盖配置
augment_project	为现有项目添加 CI 工作流、测试、Docker、文档等
validate_project	检查项目目录的结构是否正确
verify_workflow	使用 act 在本地验证 GitHub Actions 工作流
list_presets	列出所有可用预设及其描述
show_preset	显示指定预设的完整 YAML 配置
get_user_config	读取当前用户级默认配置
set_user_config	更新用户级默认配置
set_project_metadata	在 pyproject.toml 中设置或更新 PyPI 元数据
generate_badges	根据项目元数据生成徽章 Markdown 链接

资源：preset://list、config://user、template://list

提示词：create-project、augment-project

开发

所有任务都使用 Justfile：

just install     # Install dependencies
just test        # Run tests
just test-cov    # Tests with coverage
just lint        # Ruff check
just format      # Ruff format
just typecheck   # Pyright
just radon       # Cyclomatic complexity check
just check       # lint + typecheck + radon + test
just all         # format + lint-fix + typecheck + radon + test

开发环境设置和指南请参阅 CONTRIBUTING.md。

许可证

MIT