Article 3: Code Quality Tools

Introduction

Writing code is one thing; writing code that others (including future you) can read, understand, and maintain is another. Through my experience maintaining codebases over years, I've learned that automated quality tools aren't just nice-to-haves—they're essential for sustainable development.

This article covers the modern Python quality toolkit: Ruff for linting, Black for formatting, and mypy for type checking. Together, they catch bugs early, enforce consistency, and make code reviews focus on logic rather than style.

The Quality Toolchain

Tool	Purpose	Speed	Configuration
Ruff	Linting + Import sorting	Very Fast	pyproject.toml
Black	Code formatting	Fast	pyproject.toml
mypy	Static type checking	Moderate	pyproject.toml

Ruff: Modern Python Linter

Why Ruff?

Ruff is a Python linter written in Rust that's 10-100x faster than traditional linters. It replaces Flake8, isort, pyupgrade, and many other tools.

# Install Ruff
pip install ruff

# Run linter
ruff check .

# Fix auto-fixable issues
ruff check --fix .

# Format code (like Black)
ruff format .

Configuration

# pyproject.toml
[tool.ruff]
# Same as Black
line-length = 88
indent-width = 4

# Assume Python 3.11
target-version = "py311"

# Exclude directories
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# Enable these rule sets
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # Pyflakes
    "I",      # isort
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
    "SIM",    # flake8-simplify
]

# Ignore specific rules
ignore = [
    "E501",   # line too long (handled by formatter)
]

# Allow autofix for all enabled rules
fixable = ["ALL"]
unfixable = []

[tool.ruff.lint.isort]
known-first-party = ["task_manager"]

[tool.ruff.format]
# Like Black, use double quotes
quote-style = "double"
indent-style = "space"

Common Ruff Rules

# E: pycodestyle errors
x=1  # E225: missing whitespace around operator
x = 1  # Fixed

# F: Pyflakes
import os  # F401: imported but unused

# B: Bugbear (common bugs)
def func(items=[]):  # B006: mutable default argument
    pass

def func(items=None):  # Fixed
    items = items or []

# UP: pyupgrade (modernize code)
x = dict(a=1)  # UP013: use dict literal
x = {"a": 1}  # Fixed

# SIM: simplify
if x == True:  # SIM901: use 'if x:'
    pass

# I: isort (import sorting)
import os
import sys
from collections import defaultdict

from task_manager import models  # First-party imports last

Running Ruff

# Check all files
ruff check .

# Check specific file
ruff check src/models.py

# Show what would be fixed
ruff check --diff .

# Fix and show changes
ruff check --fix --show-fixes .

# Format code
ruff format .

# Check formatting without changing
ruff format --check .

Black: The Uncompromising Formatter

Philosophy

Black's design philosophy: "You can have any style you want, as long as it's Black." This eliminates all style debates.

# Install Black
pip install black

# Format files
black .

# Check without modifying
black --check .

# Show diff
black --diff .

Configuration

# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py311']
include = '\.pyi?$'
extend-exclude = '''
/(
    \.git
    | \.venv
    | build
    | dist
)/
'''

Black Formatting Examples

# Before Black
def calculate_total(items,tax_rate,discount=0.0,apply_shipping=True):
    subtotal=sum(item['price']*item['quantity'] for item in items)
    tax=subtotal*tax_rate
    total=subtotal+tax-discount
    if apply_shipping:total+=calculate_shipping(items)
    return total

# After Black
def calculate_total(
    items,
    tax_rate,
    discount=0.0,
    apply_shipping=True,
):
    subtotal = sum(item["price"] * item["quantity"] for item in items)
    tax = subtotal * tax_rate
    total = subtotal + tax - discount
    if apply_shipping:
        total += calculate_shipping(items)
    return total

Magic Trailing Comma

Black respects the "magic trailing comma" for multi-line formatting:

# Without trailing comma - Black may collapse to one line
items = [
    "apple",
    "banana",
    "cherry"
]  # May become: items = ["apple", "banana", "cherry"]

# With trailing comma - Black keeps it multi-line
items = [
    "apple",
    "banana",
    "cherry",
]  # Stays multi-line

mypy: Static Type Checking

Why Type Hints?

Type hints catch bugs before runtime and serve as documentation:

# Without types - bug found at runtime
def process_user(user):
    return user.name.upper()  # AttributeError if user is None

# With types - bug found immediately by mypy
def process_user(user: User) -> str:
    return user.name.upper()  # mypy: error if user could be None

Basic Type Hints

from typing import Optional, List, Dict, Union, Any
from collections.abc import Callable

# Basic types
name: str = "Alice"
age: int = 30
price: float = 19.99
is_active: bool = True

# Collections
names: list[str] = ["Alice", "Bob"]
scores: dict[str, int] = {"Alice": 100, "Bob": 95}
coordinates: tuple[float, float] = (1.0, 2.0)

# Optional (can be None)
middle_name: Optional[str] = None  # Same as str | None

# Union types
result: Union[int, str] = 42  # Same as int | str in Python 3.10+

# Callable
handler: Callable[[int, str], bool] = some_function

# Any (escape hatch - use sparingly)
data: Any = get_external_data()

Type Hints in Functions

from dataclasses import dataclass
from typing import Optional

@dataclass
class Task:
    id: int
    title: str
    completed: bool = False

def create_task(title: str, id: Optional[int] = None) -> Task:
    """Create a new task with the given title."""
    return Task(
        id=id or generate_id(),
        title=title,
    )

def find_task(tasks: list[Task], task_id: int) -> Optional[Task]:
    """Find a task by ID, returns None if not found."""
    for task in tasks:
        if task.id == task_id:
            return task
    return None

def complete_tasks(tasks: list[Task]) -> list[Task]:
    """Mark all tasks as completed."""
    return [Task(t.id, t.title, completed=True) for t in tasks]

Configuration

# pyproject.toml
[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_ignores = true
disallow_untyped_defs = true
disallow_incomplete_defs = true

# Per-module overrides
[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

[[tool.mypy.overrides]]
module = "third_party_lib.*"
ignore_missing_imports = true

Running mypy

# Install mypy
pip install mypy

# Check all files
mypy src/

# Check specific file
mypy src/models.py

# With config file
mypy --config-file pyproject.toml src/

# Show error codes
mypy --show-error-codes src/

Common mypy Errors and Fixes

# error: Incompatible return value type (expected "str", got "Optional[str]")
def get_name(user: Optional[User]) -> str:
    if user is None:
        return "Anonymous"  # Handle None case
    return user.name

# error: Item "None" of "Optional[Task]" has no attribute "title"
def print_task(task: Optional[Task]) -> None:
    if task is not None:  # Narrow the type first
        print(task.title)

# error: Argument 1 to "process" has incompatible type "str"; expected "int"
def process(value: int) -> int:
    return value * 2

process(42)  # OK
process("42")  # Error! Use: process(int("42"))

# error: Missing return statement
def maybe_find(items: list[str], target: str) -> Optional[str]:
    for item in items:
        if item == target:
            return item
    return None  # Must explicitly return None

Advanced Type Patterns

from typing import TypeVar, Generic, Protocol

# TypeVar for generic functions
T = TypeVar("T")

def first(items: list[T]) -> Optional[T]:
    """Return first item or None if empty."""
    return items[0] if items else None

# Generic classes
class Repository(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []
    
    def add(self, item: T) -> None:
        self._items.append(item)
    
    def get_all(self) -> list[T]:
        return self._items.copy()

# Protocols (structural subtyping)
class Printable(Protocol):
    def to_string(self) -> str: ...

def print_item(item: Printable) -> None:
    print(item.to_string())

# Any class with to_string() method works
class Task:
    def to_string(self) -> str:
        return f"Task: {self.title}"

print_item(Task())  # OK - Task has to_string()

Integrating All Tools

Combined Configuration

# pyproject.toml - Complete quality tool configuration

[project]
name = "task-manager"
version = "0.1.0"
requires-python = ">=3.11"

[tool.ruff]
line-length = 88
target-version = "py311"
exclude = [".git", ".venv", "__pycache__", "build", "dist"]

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM"]
ignore = ["E501"]

[tool.ruff.lint.isort]
known-first-party = ["task_manager"]

[tool.black]
line-length = 88
target-version = ["py311"]

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
disallow_untyped_defs = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

Quality Check Script

#!/bin/bash
# scripts/quality.sh

set -e

echo "🔍 Running code quality checks..."

echo ""
echo "1️⃣  Ruff (linting)..."
ruff check src tests

echo ""
echo "2️⃣  Black (formatting)..."
black --check src tests

echo ""
echo "3️⃣  mypy (type checking)..."
mypy src

echo ""
echo "✅ All quality checks passed!"

Makefile Integration

# Makefile
.PHONY: lint format typecheck quality

lint:
	ruff check src tests

format:
	ruff format src tests
	ruff check --fix src tests

typecheck:
	mypy src

quality: lint typecheck
	@echo "All quality checks passed!"

fix:
	ruff format src tests
	ruff check --fix src tests

Pre-commit Integration

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies:
          - types-requests  # Type stubs for requests

VS Code Integration

// .vscode/settings.json
{
    // Python interpreter
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    
    // Formatting with Black
    "editor.formatOnSave": true,
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter"
    },
    
    // Linting with Ruff
    "ruff.lint.run": "onSave",
    "ruff.organizeImports": true,
    
    // Type checking with Pylance (uses mypy config)
    "python.analysis.typeCheckingMode": "basic",
    
    // Show problems in editor
    "python.analysis.diagnosticMode": "workspace"
}

Practical Exercise

Exercise 1: Fix Code Quality Issues

Create a file with intentional issues and fix them:

# src/task_manager/example_bad.py (before)
import os
import sys
from typing import List,Dict
import json

def processData(data:Dict,verbose=True)->List:
    result=[]
    for key,value in data.items():
        if verbose==True:
            print(f"Processing {key}")
        if value!=None:
            result.append(value)
    return result

class taskManager:
    def __init__(self):
        self.tasks=[]
    
    def add_task(self,title):
        self.tasks.append({"title":title,"done":False})
    
    def get_tasks(self):
        return self.tasks

Run the quality tools:

# Check issues
ruff check src/task_manager/example_bad.py
mypy src/task_manager/example_bad.py

# Fix formatting
ruff format src/task_manager/example_bad.py
ruff check --fix src/task_manager/example_bad.py

# src/task_manager/example_fixed.py (after)
from typing import Any


def process_data(data: dict[str, Any], verbose: bool = True) -> list[Any]:
    result: list[Any] = []
    for key, value in data.items():
        if verbose:
            print(f"Processing {key}")
        if value is not None:
            result.append(value)
    return result


class TaskManager:
    def __init__(self) -> None:
        self.tasks: list[dict[str, Any]] = []

    def add_task(self, title: str) -> None:
        self.tasks.append({"title": title, "done": False})

    def get_tasks(self) -> list[dict[str, Any]]:
        return self.tasks

Exercise 2: Add Type Hints to Existing Code

# Before: No type hints
def calculate_statistics(numbers):
    if not numbers:
        return None
    
    total = sum(numbers)
    count = len(numbers)
    average = total / count
    
    sorted_nums = sorted(numbers)
    mid = count // 2
    if count % 2 == 0:
        median = (sorted_nums[mid - 1] + sorted_nums[mid]) / 2
    else:
        median = sorted_nums[mid]
    
    return {
        "count": count,
        "sum": total,
        "average": average,
        "median": median,
        "min": min(numbers),
        "max": max(numbers),
    }

# After: With type hints
from typing import TypedDict


class Statistics(TypedDict):
    count: int
    sum: float
    average: float
    median: float
    min: float
    max: float


def calculate_statistics(numbers: list[float]) -> Statistics | None:
    if not numbers:
        return None

    total = sum(numbers)
    count = len(numbers)
    average = total / count

    sorted_nums = sorted(numbers)
    mid = count // 2
    if count % 2 == 0:
        median = (sorted_nums[mid - 1] + sorted_nums[mid]) / 2
    else:
        median = sorted_nums[mid]

    return {
        "count": count,
        "sum": total,
        "average": average,
        "median": median,
        "min": min(numbers),
        "max": max(numbers),
    }

Exercise 3: Configure Tools for a Project

# Create complete configuration
cat >> pyproject.toml << 'EOF'

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM"]

[tool.ruff.lint.isort]
known-first-party = ["task_manager"]

[tool.black]
line-length = 88
target-version = ["py311"]

[tool.mypy]
python_version = "3.11"
strict = true
EOF

# Run all checks
ruff check src tests
black --check src tests
mypy src

Quality Tools Comparison

Aspect	Ruff	Black	mypy
Purpose	Linting + formatting	Formatting only	Type checking
Speed	Very fast (Rust)	Fast	Moderate
Configuration	Extensive	Minimal	Extensive
Auto-fix	Yes	Yes (formatting)	No
When to run	Every save	Every save	Pre-commit/CI

Key Takeaways

1. Use all three tools together - They complement each other

2. Configure once, forget it - pyproject.toml centralizes settings

3. Format on save - Let the tools work automatically

4. Type hints are documentation - They help you and others understand code

5. Integrate with pre-commit - Catch issues before they're committed

What's Next?

Quality tools enforce style consistency, but writing truly clean code requires deeper principles. In Article 4: Clean Code Principles, we'll explore naming conventions, function design, and foundational design patterns that make code readable and maintainable.

---

This article is part of the Software Engineering 101 series.