---

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

Recommended Workflow

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