Python Formatter

The Python Formatter beautifies Python code using Black-compatible formatting — the opinionated code style that has become standard for modern Python projects. Black eliminates style debates by having one canonical format. This tool applies the same rules: 88-character line width (Black default, slightly wider than PEP 8 80-char), 4-space indentation (PEP 8), double quotes (Black preference), trailing commas where appropriate, consistent spacing around operators, and f-string handling. Supports Python 3 syntax including type hints, async/await, walrus operator, match statements, and decorators.

Python code style matters because Python has the richest set of formatting options of any popular language — multiple ways to do everything. Without a consistent style, team code becomes hard to read. Black (started 2018, now the de facto standard) eliminates debates by being opinionated. Major projects using Black: FastAPI, Django-Ninja, Poetry, pipx, Pydantic, Hypothesis. This formatter applies the same style without installing Black locally. Perfect for quick cleanups, code reviews, or teams adopting Black.

Black-style formatting (opinionated, based on PEP 8 with some modifications):

Line width: 88 characters (default). Slightly wider than PEP 8 80-char. Configurable.

Indentation: 4 spaces per level (PEP 8).

Quote style: Double quotes "string" preferred (Black decision). Single quotes converted unless single would avoid escapes.

Trailing commas: Added in multi-line collections — makes diffs cleaner:

``python
items = [
"one",
"two",
"three", # <- trailing comma
]
``

Magic trailing comma: If you add trailing comma, Black keeps multi-line. Without it, Black collapses to single line if fits.

Function signatures:

Short fits on one line:
``python
def greet(name: str, greeting: str = "Hello") -> str:
return f"{greeting}, {name}!"
``

Long breaks onto multiple lines:
``python
def process_user_data(
user_id: int,
full_name: str,
email_address: str,
preferences: dict[str, Any],
timezone: str = "UTC",
) -> dict[str, Any]:
pass
``

Imports:

Black does not sort imports (that is isort territory). Preserves order. Groups:

```python
# Standard library
import os
import sys

# Third-party
import requests
from django.db import models

# Local
from .utils import helper
```

F-strings:

``python
name = "Alice"
greeting = f"Hello, {name}!"
``

Formatter preserves f-string contents. Black does not reformat expressions inside f-strings (except spacing).

Type hints:

``python
def calculate(
items: list[dict[str, int]],
threshold: int = 10,
) -> tuple[int, list[str]]:
pass
``

Complex type hints formatted for readability. Union types: Optional[X] and X | None both preserved.

Modern Python features (Black 23+):

- Walrus operator: while chunk := f.read(1024):
- Match statements (Python 3.10+): match command:
- ParamSpec/TypeVarTuple: type hint features.

Comments:

- # line comments preserved in position.
- """docstrings""" preserved — contents not reformatted (Black does not touch docstrings).
- Shebang #! preserved.

Docstrings:

``python
def calculate(x: int, y: int) -> int:
"""
Calculate the sum of two integers.

Args:
x: First integer
y: Second integer

Returns:
The sum x + y
"""
return x + y
``

Black preserves docstring exactly. Tools like docformatter or pydocstyle handle docstring-specific formatting.

What Black does NOT do:

- Sort imports (use isort).
- Remove unused imports (use autoflake, pyflakes, ruff).
- Add missing docstrings.
- Fix type errors (use mypy).
- Fix logic bugs (use pytest, Hypothesis).

Line length:

88 is Black default. PEP 8 says 79. Django uses 119. Google uses 80. Match your project setting.

Black vs autopep8: Black is opinionated (one way). autopep8 is configurable. Black is the modern standard; autopep8 is older alternative. Black wins on consistency, autopep8 on flexibility.

Black vs yapf: yapf (Google) is configurable in complex ways. Black is simpler (fewer knobs). Black has more adoption.

Black vs Ruff format: Ruff is a modern Rust-based linter that also formats (100x faster than Black). Black-compatible output. For large codebases, Ruff is faster.

Python Formatter vs Linter: Formatter fixes style. Linter (Flake8, Ruff, Pylint) fixes semantic issues (unused imports, missing docstrings, errors). Use both.

Python Formatter vs Type Checker: Formatter changes whitespace. Type checker (mypy, pyright, pyre) checks type correctness. Orthogonal — use both.

PEP 8 vs Black: PEP 8 is the Python style guide. Black follows PEP 8 mostly but diverges on line length (88 vs 79), trailing commas, and other details. Black is PEP 8 compliant with modern extensions.