# Code Formatting and Linting Standards in TheAlgorithms/Python: A Complete Developer Guide

> Discover the code formatting and linting standards in TheAlgorithms/Python. Learn how Ruff, Black, and Mypy ensure uniform style and quality for all contributions.

- Repository: [The Algorithms/Python](https://github.com/TheAlgorithms/Python)
- Tags: best-practices
- Published: 2026-02-24

---

**TheAlgorithms/Python enforces a comprehensive code formatting and linting pipeline using pre-commit hooks, Ruff, Black, Mypy, and additional specialized tools to ensure all contributions maintain uniform style, type safety, and documentation quality.**

Maintaining consistency across thousands of algorithmic implementations requires rigorous automation. The repository implements a multi-layered quality assurance system defined in [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml), [`.pre-commit-config.yaml`](https://github.com/TheAlgorithms/Python/blob/main/.pre-commit-config.yaml), and [`CONTRIBUTING.md`](https://github.com/TheAlgorithms/Python/blob/main/CONTRIBUTING.md) that validates every pull request against strict formatting, linting, and type-checking standards before merging.

## Python Version Requirements

All code in the repository must target **Python 3.14 or newer**. This requirement is explicitly declared in [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) at line 6 within the `requires-python = ">=3.14"` configuration, ensuring contributors utilize the latest language features and type hinting capabilities while maintaining compatibility across the codebase.

## Code Formatting Standards

### Black and Ruff Format

The repository recommends **Black** for code formatting while automatically enforcing **Ruff's formatter** via pre-commit hooks. According to [`CONTRIBUTING.md`](https://github.com/TheAlgorithms/Python/blob/main/CONTRIBUTING.md) at lines 86-94, contributors should run `black .` locally, though the `ruff-format` hook in [`.pre-commit-config.yaml`](https://github.com/TheAlgorithms/Python/blob/main/.pre-commit-config.yaml) automatically applies compatible formatting during the commit process. This dual approach ensures consistent 4-space indentation, line breaking, and trailing newline handling across all Python files.

### Automated Refactoring with Auto-Walrus

The pipeline includes **auto-walrus**, a specialized tool enabled in [`.pre-commit-config.yaml`](https://github.com/TheAlgorithms/Python/blob/main/.pre-commit-config.yaml) at lines 16-20, which automatically replaces manual assignment patterns with the walrus operator (`:=`) where semantically appropriate. This optimization reduces line count and improves performance without manual intervention.

## Linting and Static Analysis Configuration

### Ruff Lint Rules

**Ruff** serves as the primary linter, configured extensively in [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) at lines 51-88. The selected rule set includes:

- **Flake8-builtins** (A): Prevents shadowing of Python built-ins
- **Bugbear** (B): Detects likely bugs and design problems
- **Isort** (I): Enforces standardized import ordering at line 73
- **McCabe complexity**: Cyclomatic complexity is capped at **17** as defined at lines 53-55
- **Per-file ignores**: Specific exemptions for test files and build scripts

### Type Checking with Mypy

Static type analysis runs via **Mypy** with flags `--ignore-missing-imports` and `--install-types` configured at [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) lines 52-60. The pre-commit hook validates that all public functions include proper type annotations, ensuring type safety across the algorithmic implementations.

### Spell Checking with Codespell

Documentation and code comments undergo spell-checking via **Codespell**, configured at [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) lines 64-66 with a custom ignore-words list. This prevents typos in user-facing docstrings and internal comments from reaching the main branch.

## Mandatory Contribution Standards

### File Naming Conventions

All filenames must use **snake_case** formatting (e.g., [`module_name.py`](https://github.com/TheAlgorithms/Python/blob/main/module_name.py), [`algorithm_test.py`](https://github.com/TheAlgorithms/Python/blob/main/algorithm_test.py)). The custom validation script [`scripts/validate_filenames.py`](https://github.com/TheAlgorithms/Python/blob/main/scripts/validate_filenames.py) enforces these rules along with restrictions against new top-level folders, as documented in [`CONTRIBUTING.md`](https://github.com/TheAlgorithms/Python/blob/main/CONTRIBUTING.md) at lines 77-80.

### Documentation and Type Hint Requirements

Every public function must include:
- **Python type hints** for all parameters and return values
- **Docstrings** with descriptive text and executable doctests

These requirements are explicitly mandated in [`CONTRIBUTING.md`](https://github.com/TheAlgorithms/Python/blob/main/CONTRIBUTING.md) at lines 55-66 and verified through the test suite, ensuring all algorithms are properly documented and demonstrably correct via example executions.

### Whitespace and Line Length Controls

The pre-commit pipeline enforces strict whitespace discipline through standard hooks defined in [`.pre-commit-config.yaml`](https://github.com/TheAlgorithms/Python/blob/main/.pre-commit-config.yaml) at lines 8-14:

- `trailing-whitespace`: Removes end-of-line spaces
- `end-of-file-fixer`: Ensures single final newlines
- **Ruff-controlled line length**: Default length limits apply without explicit override in the current configuration

## Example Compliant Implementation

The following implementation satisfies all enforced formatting and linting standards:

```python
from __future__ import annotations

def fibonacci(n: int) -> list[int]:
    """
    Return a list containing the first *n* Fibonacci numbers.

    >>> fibonacci(5)
    [0, 1, 1, 2, 3]
    """
    if n < 0:
        raise ValueError("n must be non-negative")
    a, b = 0, 1
    result: list[int] = []
    while len(result) < n:
        result.append(a)
        a, b = b, a + b
    return result

```

This example demonstrates **snake_case** naming, complete **type hints**, **docstring formatting** with doctests, **Black-compatible** indentation, and **Ruff-compliant** import structure. Running `pre-commit run --all-files` validates these standards locally before submission.

## Summary

- **Python 3.14+** is mandatory per [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) line 6
- **Ruff and Black** handle formatting and linting through automated pre-commit hooks
- **Mypy** enforces type safety with configured ignore patterns for missing imports
- **Complexity limits** cap cyclomatic complexity at 17 via McCabe rules
- **Snake_case filenames** are enforced by [`scripts/validate_filenames.py`](https://github.com/TheAlgorithms/Python/blob/main/scripts/validate_filenames.py)
- **Docstrings and type hints** are required for all public functions per [`CONTRIBUTING.md`](https://github.com/TheAlgorithms/Python/blob/main/CONTRIBUTING.md)

## Frequently Asked Questions

### What pre-commit hooks are mandatory for TheAlgorithms/Python contributions?

The pipeline requires hooks for **ruff-check**, **ruff-format**, **mypy**, **codespell**, **auto-walrus**, **trailing-whitespace**, and **end-of-file-fixer**. These are defined in [`.pre-commit-config.yaml`](https://github.com/TheAlgorithms/Python/blob/main/.pre-commit-config.yaml) and execute automatically when running `pre-commit install` locally.

### How does the repository handle import ordering?

**Ruff's isort implementation** (rule `I`) manages import sorting, configured in [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) at line 73. The linter automatically reorganizes imports into standard library, third-party, and local application groupings without manual intervention.

### Why is Python 3.14 required specifically?

The `requires-python = ">=3.14"` setting in [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) ensures compatibility with the latest type hinting syntax and standard library features. This requirement allows the codebase to leverage modern Python capabilities while maintaining consistency across all 1500+ algorithm implementations.

### What happens if my code exceeds the complexity limit of 17?

Ruff's **McCabe** complexity checker, configured at [`pyproject.toml`](https://github.com/TheAlgorithms/Python/blob/main/pyproject.toml) lines 53-55, will reject code exceeding the cyclomatic complexity threshold of 17. Contributors must refactor complex functions into smaller, more manageable units to satisfy this linting rule and improve code maintainability.