AI导哈

Python项目脚手架工具

PyPreset是一个基于YAML预设配置的Python项目脚手架工具，支持多种包管理器和项目布局，可生成CI工作流、测试框架、类型检查配置等，提升开发效率。

  • by KaiErikNiermann
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 KaiErikNiermann/pypreset

使用说明

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 <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 启用氡复杂性检查
--pre-commit / --no-pre-commit 生成预提交钩子配置
--bump-my-version / --no-bump-my-version 包括bump我的版本配置
--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.ini 带有tox-uv后端
--pyenv / --no-pyenv 生成 .python-version 和使用 python-version-file 在CI
--git / --no-git 初始化git存储库
--install / --no-install 创建后运行依赖项安装
--dry-run 预览在不生成任何内容的情况下创建的内容

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

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

pypreset augment [path] [OPTIONS]

可用组件：

标志 组件 它生成什么
--test-workflow / --no-test-workflow 测试CI 跨Python版本矩阵运行pytest的GitHub操作工作流
--lint-workflow / --no-lint-workflow Lint CI GitHub Actions工作流，用于ruff、类型检查和复杂性分析
--dependabot / --no-dependabot Dependabot .github/dependabot.yml 用于自动更新依赖关系
--tests / --no-tests 测试目录 tests/ 使用模板测试文件和 conftest.py
--gitignore / --no-gitignore Gitignore 特定于Python .gitignore
--pypi-publish / --no-pypi-publish PyPI发布 发布时基于OIDC向PyPI发布的GitHub操作工作流
--dockerfile / --no-dockerfile Docker 多阶段 Dockerfile 和 .dockerignore （诗歌、uv或setuptools感知）
--devcontainer / --no-devcontainer Devcontainer .devcontainer/devcontainer.json 带有VS代码扩展名
--codecov / --no-codecov Codecov codecov.yml 配置
--docs 文档 Sphinx或MkDocs脚手架(--docs sphinx 或 --docs mkdocs)
--tox / --no-tox 毒素 tox.ini 使用tox-uv后端进行多环境测试
--readme / --no-readme 自述文件 README.md 从共享模板生成（徽章、安装、功能）
--pyenv / --no-pyenv pyenv .python-version pyenv和uv版本固定文件 
# 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 <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 --生成徽章标记

读取 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 <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: 现场。预设可以通过设置覆盖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": []
    }
  }
}

可用工具：

工具 说明
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 在中设置或更新PyPI元数据 pyproject.toml
generate_badges 从项目元数据生成徽章标记链接

资源: 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 用于开发设置和指南。

许可证

麻省理工学院

相关 MCP