// Configure and use automated code quality tools (ruff, mypy, pre-commit) for scientific Python projects. Covers linting rules, type checking configuration, formatting, and CI integration.
[HINT] 下载包含 SKILL.md 和所有相关文件的完整技能目录
| name | code-quality-tools |
| description | Configure and use automated code quality tools (ruff, mypy, pre-commit) for scientific Python projects. Covers linting rules, type checking configuration, formatting, and CI integration. |
| metadata | {"assets":["assets/pre-commit-config.yaml","assets/pyproject-ruff-mypy.toml"],"references":["references/common-issues.md","references/configuration-patterns.md","references/type-hints.md"]} |
Master the essential code quality tools that keep scientific Python projects maintainable, consistent, and error-free. Learn how to configure ruff for lightning-fast linting and formatting, mypy for static type checking, and pre-commit hooks for automated quality gates. These tools help catch bugs early, enforce consistent style across teams, and make code reviews focus on logic rather than formatting.
Key Tools:
# Using uv (recommended for scientific projects)
uv add --dev ruff mypy pre-commit
# Or install into the active virtual environment
uv pip install ruff mypy pre-commit
# Initialize pre-commit
pre-commit install
# Check code (linting)
ruff check .
# Fix auto-fixable issues
ruff check --fix .
# Format code
ruff format .
# Check and format together
ruff check --fix . && ruff format .
# Type check entire project
mypy src/
# Type check with strict mode
mypy --strict src/
# Type check specific file
mypy src/mymodule/analysis.py
# Generate type coverage report
mypy --html-report mypy-report src/
# Run all hooks on all files
pre-commit run --all-files
# Run hooks on staged files only
pre-commit run
# Update hook versions
pre-commit autoupdate
# Skip hooks temporarily (not recommended)
git commit --no-verify
Need to enforce code style and catch common errors?
YES → Use Ruff (linting + formatting)
NO → Skip to type checking
Want to catch type-related bugs before runtime?
YES → Add MyPy
NO → Ruff alone is sufficient
Need to ensure checks run automatically?
YES → Set up pre-commit hooks
NO → Run tools manually (not recommended for teams)
Working with legacy code without type hints?
YES → Start with Ruff only, add MyPy gradually
NO → Use both Ruff and MyPy from the start
Use this skill to establish or improve code quality practices in scientific Python projects:
Ruff is a blazingly fast Python linter and formatter written in Rust that replaces multiple tools you might be using today.
What Ruff Replaces:
Why Ruff for Scientific Python:
Ruff is 10-100x faster than traditional tools, which matters when you have large codebases with thousands of lines of numerical code. Instead of managing multiple configuration files and tool versions, you get a single tool that handles everything. Ruff can auto-fix most issues automatically, saving time during development. It includes NumPy-aware docstring checking, understanding the conventions used throughout the scientific Python ecosystem. Best of all, it's compatible with existing black and flake8 configurations, making migration straightforward.
Example:
# Before ruff format
import sys
import os
import numpy as np
def calculate_mean(data):
return np.mean(data)
# After ruff format
import os
import sys
import numpy as np
def calculate_mean(data):
return np.mean(data)
Ruff automatically organizes imports (standard library, third party, local) and applies consistent formatting.
MyPy analyzes type hints to catch errors before your code ever runs. This is especially valuable in scientific computing where dimension mismatches and type errors can lead to subtle bugs in numerical calculations.
Example of what MyPy catches:
import numpy as np
from numpy.typing import NDArray
def calculate_mean(data: NDArray[np.float64]) -> float:
"""Calculate mean of array."""
return float(np.mean(data))
# MyPy catches this error at type-check time:
result: int = calculate_mean(np.array([1.0, 2.0, 3.0]))
# Error: Incompatible types (expression has type "float", variable has type "int")
Benefits for Scientific Code:
Type hints catch dimension mismatches in array operations before you run expensive computations. They validate function signatures, ensuring you pass the right types to numerical functions. Type hints serve as documentation, making it clear what types functions expect and return. They prevent None-related bugs that can crash long-running simulations. Modern IDEs use type hints to provide better autocomplete and inline documentation.
Pre-commit runs checks automatically before each commit, ensuring code quality standards are maintained without manual intervention.
Workflow:
git commitThis ensures that code quality issues are caught immediately, before they enter the codebase.
See assets/pyproject-ruff-mypy.toml for complete Ruff and MyPy configuration examples.
See assets/pre-commit-config.yaml for pre-commit hook configuration.
See references/configuration-patterns.md for detailed patterns including:
See references/type-hints.md for type hint patterns including:
See references/common-issues.md for solutions to:
pyproject.toml with tool configurations.pre-commit-config.yamlpre-commit install to enable git hookspre-commit run --all-files to check existing codeuv run or in project automationuv run workflows for common quality checksruff check --fix before committingruff format before committing# type: ignore without reason)--no-verifypre-commit autoupdate)Code quality tools are essential for maintaining scientific Python projects. Ruff provides fast, comprehensive linting and formatting. MyPy catches type errors before runtime. Pre-commit automates quality checks in your workflow.
Key takeaways:
Start with ruff for immediate impact as it replaces multiple tools with a single fast solution. Add mypy gradually as you add type hints to catch bugs early. Use pre-commit to enforce standards automatically without manual intervention. Integrate with uv for reproducible development environments. Configure tools in pyproject.toml for centralized management. Run quality checks in CI/CD to maintain standards across the team.
Next steps:
Set up ruff and pre-commit in your project today. Add type hints to new functions you write. Gradually increase mypy strictness as your codebase matures. Share configurations with your team for consistency. Integrate quality checks into your development workflow.
Quality tools save time by catching errors early and maintaining consistency across your scientific codebase. They make code reviews more productive by automating style discussions, allowing reviewers to focus on scientific correctness and algorithmic choices rather than formatting details.