python-code-quality

basher83 的头像作者 basher83

使用ruff和pyright的Python代码质量工具。在设置linting、格式化、类型检查、配置ruff或pyright或建立代码质量标准时使用。

📖 中文导读:使用ruff和pyright的Python代码质量工具。在设置linting、格式化、类型检查、配置ruff或pyright或建立代码质量标准时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: python-code-quality description: > Python code quality tooling with ruff and pyright. Use when setting up linting, formatting, type checking, configuring ruff or pyright, or establishing code quality standards.

Python Code Quality with Ruff and Pyright

Modern Python code quality tooling using ruff (linting + formatting) and pyright (type checking).

Quick Start

Install Tools

# Using uv (recommended)
uv add --dev ruff pyright

# Using pip
pip install ruff pyright

Run Quality Checks

# Format and lint with ruff
ruff check --fix .
ruff format .

# Type check with pyright
pyright

When to Use This Skill

Use this skill when:

  • Setting up linting and formatting for a Python project
  • Configuring type checking
  • Establishing code quality standards for a team
  • Integrating quality checks into pre-commit or CI/CD
  • Migrating from black/flake8/mypy to ruff/pyright

Ruff: All-in-One Linter and Formatter

Ruff combines the functionality of flake8, black, isort, and more:

Benefits:

  • 10-100x faster than alternatives
  • Drop-in replacement for black, flake8, isort
  • Single tool configuration
  • Auto-fix for many violations

Configuration: See reference/ruff-configuration.md

Pyright: Fast Type Checker

Pyright provides static type checking for Python:

Benefits:

  • Faster than mypy
  • Better editor integration (VS Code, etc.)
  • Incremental type checking
  • Configurable strictness

Configuration: See reference/pyright-configuration.md

  1. Pre-commit Hooks - Run quality checks before each commit

    • See: patterns/pre-commit-integration.md
  2. CI/CD Quality Gates - Block merges on quality failures

    • See: patterns/ci-cd-quality-gates.md
  3. Editor Integration - Real-time feedback while coding

    • See: workflows/quality-workflow.md

Configuration Templates

Generic starter configs in examples/:

  • pyrightconfig-starter.json - Minimal type checking
  • pyrightconfig-strict.json - Strict type checking
  • ruff-minimal.toml - Basic linting + formatting
  • ruff-comprehensive.toml - Full-featured config

Helper Tools

  • tools/python_formatter.py - Batch format Python files
  • tools/python_ruff_checker.py - Check code quality

Ruff vs Alternatives

Feature Ruff Black + Flake8 + isort
Speed ⚡⚡⚡ ⚡
Configuration Single file Multiple files
Auto-fix ✅ Partial
Formatting ✅ Black only
Import sorting ✅ isort only

Pyright vs mypy

Feature Pyright mypy
Speed ⚡⚡⚡ ⚡⚡
VS Code integration Native Extension
Configuration JSON INI/TOML
Incremental checking ✅ ✅

Common Patterns

Ignore Specific Lines

# Ruff
x = 1  # noqa: F841  # Unused variable

# Pyright
x = 1  # type: ignore

Configure Per-Directory

# ruff.toml
[tool.ruff]
exclude = ["migrations/", "scripts/"]

[tool.ruff.lint]
select = ["E", "F", "W"]

Next Steps

  1. Choose config template from examples/
  2. Set up pre-commit hooks: patterns/pre-commit-integration.md
  3. Add CI/CD quality gates: patterns/ci-cd-quality-gates.md
  4. Configure editor integration: workflows/quality-workflow.md

Reference Documentation

  • reference/ruff-configuration.md - Complete ruff configuration guide
  • reference/ruff-linting-settings.md - Linting rule categories
  • reference/ruff-formatting-settings.md - Formatting options
  • reference/pyright-configuration.md - Pyright setup and configuration