Code Quality Tools

Code Quality Tools for Scientific Python

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:

• Ruff: Ultra-fast Python linter and formatter (replaces flake8, black, isort, and more)
• MyPy: Static type checker for Python
• Pre-commit: Git hook framework for automated checks

Quick Reference Card

Installation & Setup

# 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

Essential Ruff Commands

# 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 .

Essential MyPy Commands

# 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/

Essential Pre-commit Commands

# 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

Quick Decision Tree

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

When to Use This Skill

Use this skill to establish or improve code quality practices in scientific Python projects:

• Starting a new scientific Python project and want to establish code quality standards from day one
• Maintaining existing research code that needs consistency and error prevention
• Collaborating with multiple contributors who need automated style enforcement
• Preparing code for publication or package distribution
• Catching bugs early through static type checking before runtime
• Automating code reviews to focus on logic rather than style
• Integrating with CI/CD for automated quality checks
• Migrating from older tools like black, flake8, or isort to modern alternatives

Core Concepts

1. Ruff: The All-in-One Linter and Formatter

Ruff is a blazingly fast Python linter and formatter written in Rust that replaces multiple tools you might be using today.

What Ruff Replaces:

• flake8 (linting)
• black (formatting)
• isort (import sorting)
• pyupgrade (syntax modernization)
• pydocstyle (docstring linting)
• And 50+ other tools

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.

2. MyPy: Static Type Checking

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.

3. Pre-commit: Automated Quality Gates

Pre-commit runs checks automatically before each commit, ensuring code quality standards are maintained without manual intervention.

Workflow:

1. Developer runs git commit
2. Pre-commit automatically runs ruff, mypy, and other checks
3. If checks fail, commit is blocked
4. Developer fixes issues and commits again
5. Once all checks pass, commit succeeds

This ensures that code quality issues are caught immediately, before they enter the codebase.

Configuration

See assets/pyproject-ruff-mypy.toml for complete Ruff and MyPy configuration examples.

See assets/pre-commit-config.yaml for pre-commit hook configuration.

Configuration Patterns

See references/configuration-patterns.md for detailed patterns including:

• Basic Ruff configuration
• MyPy configuration for scientific Python
• Pre-commit configuration
• Ruff rule selection for scientific Python
• Fixing common Ruff warnings

Type Hints

See references/type-hints.md for type hint patterns including:

• Gradual type hint adoption
• NumPy array type hints
• Handling optional and union types

Common Issues and Solutions

See references/common-issues.md for solutions to:

• Ruff and Black formatting conflicts
• MyPy can't find imports
• Pre-commit hooks too slow
• Too many Ruff errors on legacy code
• Type hints break at runtime
• MyPy errors in test files
• Ruff conflicts with project style
• Pre-commit fails in CI

Best Practices Checklist