152 lines
3.6 KiB
Markdown
152 lines
3.6 KiB
Markdown
---
|
|
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
|
|
|
|
```bash
|
|
# Using uv (recommended)
|
|
uv add --dev ruff pyright
|
|
|
|
# Using pip
|
|
pip install ruff pyright
|
|
```
|
|
|
|
### Run Quality Checks
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```python
|
|
# Ruff
|
|
x = 1 # noqa: F841 # Unused variable
|
|
|
|
# Pyright
|
|
x = 1 # type: ignore
|
|
```
|
|
|
|
### Configure Per-Directory
|
|
|
|
```toml
|
|
# 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
|