pypreset (Kai Erik Niermann)

A meta-tool for scaffolding Python projects with configurable YAML presets.

Supports Poetry, uv, and setuptools, generates CI workflows, testing scaffolds, type checking configs, and more.

Mcp名称：io.ithub。Kimbolenmann/pypreset

特性

• 基于预设的项目创建 来自具有单继承的YAML配置
• 扩大现有项目 使用CI工作流、测试、Docker、文档等
• 三个包管理器：诗歌、uv（PEP 621+孵化器）和setuptools（PEP 621+setuptools.build_meta）
• 两种布局风格: src/ 布局和平面布局
• 类型检查：mypy、pyright、ty或无
• 代码质量：ruff linting/格式化、radon复杂性检查、预提交挂钩
• Docker和devcontainer：生成多级Dockerfiles， .dockerignore，以及VS代码开发容器配置（Docker或Podman）
• 覆盖整合：Codecov支持可配置阈值和忽略模式
• 文件脚手架：MkDocs（Material主题）或Sphinx（RTD主题），可选择GitHub Pages部署
• 多环境测试：带有tox-uv后端的tox配置
• pyenv/.python版本：生成 .python-version 适用于pyenv和uv，带 python-version-file 在CI工作流中
• 版本管理：bump我的版本集成，GitHub发布自动化通过 gh 命令行界面
• 工作流验证：本地GitHub操作测试 act （自动检测、自动安装、干运行和满运行模式）
• PyPI元数据管理：读取、设置和检查的发布准备情况 pyproject.toml 元数据
• 用户默认：持久配置位于 ~/.config/pypreset/config.yaml
• MCP服务器：通过模型上下文协议将所有功能暴露给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  [OPTIONS]

augment --将组件添加到现有项目中

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

pypreset augment [path] [OPTIONS]

可用组件：

# 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 --本地工作流验证

使用以下命令在本地验证GitHub操作工作流 行动。代理自动检测是否 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               # Re-tag and push an existing version
pypreset version rerelease           # 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 --生成徽章标记

读取 pyproject.toml 检测您的项目名称、存储库URL和许可证，然后打印徽章标记，您可以将其粘贴到README中。

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         # 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    # Set a config value

预设

内置预设： empty-package, cli-tool, data-science, discord-bot.

预设是定义元数据、依赖关系、目录结构、测试、格式化等的YAML文件。他们通过以下方式支持单一继承 base: 现场。预设可以通过设置覆盖README模板 metadata.readme_template 按照习俗 .j2 文件名。

自定义预设

将自定义预设文件放入 ~/.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已发布到 MCP注册表 作为 io.github.KaiErikNiermann/pypreset.

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

# 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": []
    }
  }
}

可用工具：

资源: 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

看 贡献.md 用于开发设置和指南。

许可证

麻省理工学院