py-quality-setup

Name: py-quality-setup
Author: l-mb

github.com/l-mb测试与质量5650 次安装34 周前更新

关于 py-quality-setup

py-quality-setup 是用于按 Engineering Charter 标准配置 Python 项目质量检查的 Claude skill。它设置 Ruff、mypy、basedpyright 和 pytest 工具，并配置相关的 Claude Code 权限与钩子。

主要功能

01配置 Ruff lint 和格式化
02设置 mypy 与 basedpyright
03添加开发依赖
04配置 Claude Code 权限与钩子
05运行初始质量检查

适用场景

01为新 Python 项目配置检查
02为现有代码库添加类型检查
03在旧项目中逐步引入检查

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/l-mb/python-refactoring-skills --skill py-quality-setup

安装后在 Claude Code 中输入/py-quality-setup确认已加载。

详细介绍

Python 质量工具配置

按照 Engineering Charter 标准，为 Python 3.13 项目配置全面的 lint 和类型检查。

目标

配置 ruff 进行 lint 和格式化
配置 mypy 进行严格的类型检查
配置 basedpyright 进行额外的类型分析
确保所有工具的目标版本为 Python 3.13 或更高版本
将工具添加到开发依赖项

必需工具

添加到 [dependency-groups] dev："ruff"、"mypy"、"basedpyright"、"pytest"、"pytest-cov"

ruff：快速的 lint 和格式化工具（基于 Rust，可替代 black、isort、flake8）
mypy：标准 Python 类型检查器
basedpyright：增强版 Pyright 分支，提供额外的类型分析

必需的配置文件

pyproject.toml（规范参考）

本技能提供所有质量工具的规范 pyproject.toml 配置。其他技能会引用此配置。

必须包含以下部分：

[project]
requires-python = ">=3.13"

[dependency-groups]
dev = [
    "pytest>=8.0",
    "pytest-cov>=4.0",
    "ruff>=0.8.0",
    "mypy>=1.0",
    "basedpyright>=1.0",
    "pre-commit>=3.0",
    # Analysis tools (add as needed for py-* skills):
    # "radon", "vulture", "pylint", "bandit", "lizard",
    # "mutmut", "wily", "xenon", "pyupgrade", "coverage",
]

[tool.ruff]
line-length = 100  # or 140 for larger projects
target-version = "py313"
src = ["src"]  # adjust to your source directory

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "W",   # pycodestyle warnings
    "F",   # pyflakes
    "I",   # isort
    "N",   # pep8-naming
    "UP",  # pyupgrade
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
    "SIM", # flake8-simplify
]
ignore = []

[tool.mypy]
python_version = "3.13"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_no_return = true
check_untyped_defs = true

# Add overrides for third-party packages without stubs
# [[tool.mypy.overrides]]
# module = "package_name"
# ignore_missing_imports = true

[tool.basedpyright]
pythonVersion = "3.13"
typeCheckingMode = "standard"  # or "recommended" for stricter
reportMissingTypeStubs = false
reportUnknownMemberType = false
reportUnknownArgumentType = false
reportUnknownVariableType = false

pyrightconfig.json（可选，适用于多包项目）

A. 使用 pyrightconfig.json 配置多包项目时，从 pyproject.toml 中移除 tool.basedpyright 部分

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.*", "venv", ".venv"],
  "pythonVersion": "3.13",
  "typeCheckingMode": "recommended",
  "reportMissingImports": "error",
  "reportMissingTypeStubs": false,
  "reportUnknownMemberType": false,
  "reportUnknownVariableType": false,
  "reportUnknownArgumentType": false,
  "reportMissingParameterType": true,
  "reportUnusedVariable": true,
  "reportImplicitStringConcatenation": true,
  "reportUnnecessaryTypeIgnoreComment": true
}

配置工作流

检查现有配置
- 读取 pyproject.toml
- 检查是否存在开发依赖项
- 确认 Python 版本要求
更新或创建配置
- 如果缺少开发依赖项，则添加
- 添加或更新 [tool.ruff] 部分
- 添加或更新 [tool.mypy] 部分
- 添加或更新 [tool.basedpyright] 部分
- 如有需要，为多包项目创建 pyrightconfig.json

在 venv 中安装工具

# Using uv (recommended):
uv sync                      # Creates venv and installs dev group automatically

# Or manually:
uv venv
source .venv/bin/activate
uv sync --group dev

# Fallback if uv not available:
# python -m venv venv
# source venv/bin/activate
# pip install -e ".[dev]"

验证安装

which ruff mypy basedpyright
ruff --version
mypy --version
basedpyright --version

运行初始检查
```
ruff check .
mypy .
basedpyright .
```

配置 Claude Code 权限

编写 .claude/settings.local.json，使所有 py-* 技能都能在无需权限提示的情况下运行。如果文件已存在，将新条目合并到现有的 allow 列表中，不要移除用户条目。

{
  "permissions": {
    "allow": [
      "Bash(ruff *)",
      "Bash(mypy *)",
      "Bash(basedpyright *)",
      "Bash(pytest *)",
      "Bash(vulture *)",
      "Bash(pylint *)",
      "Bash(radon *)",
      "Bash(lizard *)",
      "Bash(wily *)",
      "Bash(bandit *)",
      "Bash(mutmut *)",
      "Bash(pyupgrade *)",
      "Bash(scc *)",
      "Bash(pre-commit *)",
      "Bash(uv *)",
      "Bash(pip *)",
      "Bash(python3 *)",
      "Bash(python *)",
      "Bash(source *)",
      "Bash(which *)",
      "Bash(mkdir *)",
      "Bash(chmod *)",
      "Bash(ls *)",
      "Bash(ln *)",
      "Bash(git add *)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Bash(git log *)",
      "Bash(git ls-files *)",
      "Bash(git checkout *)",
      "Bash(git branch *)",
      "Bash(git commit *)"
    ],
    "deny": []
  }
}

合并逻辑：读取现有文件并解析 JSON，合并 allow 列表中的条目，然后写回。必要时创建 .claude/ 目录。

安装 Stop hook lint 门禁

为 lint 门禁脚本创建符号链接，使 Claude Code 在将结果返回给用户之前，对已修改的文件运行完整的 lint 套件（ruff、mypy、basedpyright）。如果任何 lint 工具报告错误，Claude 将无法停止，必须先修复错误。
```
mkdir -p ~/.claude/hooks
ln -sf ~/.claude/skills/py-git-hooks/lint-gate.py ~/.claude/hooks/lint-gate.py
```
在 ~/.claude/settings.json 中配置 Stop hook（如果已有 hooks，则合并）：
```
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/lint-gate.py"
          }
        ]
      }
    ]
  }
}
```
配置 git hooks（如有要求）
- 设置运行 lint 工具的 pre-commit hook
- 参见 py-git-hooks 技能

工具专属说明

Ruff

速度最快的 Python lint 工具（基于 Rust）
可替代：black、isort、flake8 及许多插件
自动修复：ruff check --fix .
格式化：ruff format .

Mypy

标准 Python 类型检查器
严格模式可捕获大多数类型错误
谨慎使用 # type: ignore[error-code]
为没有存根的包添加覆盖配置

Basedpyright

功能更丰富的 Pyright 分支
能捕获一些 mypy 未发现的错误
比 Pyright 更易配置
可与 mypy 配合使用

常见调整

单体仓库/多包项目：

使用带有 extraPaths 的 pyrightconfig.json
在 mypy 中设置 namespace_packages = true

旧版代码库：

从较宽松的 mypy 设置开始（strict = false）
逐步启用严格检查
按模块使用 mypy 覆盖配置

没有存根的第三方包：

[[tool.mypy.overrides]]
module = "package_name"
ignore_missing_imports = true

验证清单

示例

示例：新项目设置

1. Create venv: uv venv && source .venv/bin/activate
2. Create pyproject.toml with [project], [tool.ruff], [tool.mypy], [tool.basedpyright]
3. Install: uv pip install -e ".[dev]"
4. Verify: ruff --version && mypy --version && basedpyright --version
5. Run initial checks: ruff check . && mypy . && basedpyright .
6. Fix issues or add ignores for false positives

示例：为现有项目添加质量工具

1. Activate venv: source .venv/bin/activate
2. Update pyproject.toml:
   - Add ruff, mypy, basedpyright to [project.optional-dependencies] dev
   - Add [tool.ruff], [tool.mypy], [tool.basedpyright] sections
3. Install: uv pip install -e ".[dev]"
4. Run checks: ruff check . (expect many errors initially)
5. Auto-fix: ruff check --fix . && ruff format .
6. Run type checkers: mypy . && basedpyright .
7. Add [[tool.mypy.overrides]] for third-party packages without stubs
8. Iterate until all checks pass

示例：逐步改造旧代码库

1. Start with minimal ruff rules: select = ["E", "F"]
2. Start mypy non-strict: strict = false
3. Fix errors incrementally, expand rules over time
4. Add per-module mypy overrides for problematic modules
5. Eventually enable strict mode project-wide

基本信息

作者: l-mb
仓库: l-mb/python-refactoring-skills
分类: 测试与质量
安装次数: 50
GitHub Stars: 56

报告问题