Glossary of Python Code Style: PEP 8, Docstrings, Linters and Formatters

PEP 8, section by section · By the Four Spaces editorial team · Published 2026-11-05

Rows of small oak drawers with brass label holders and pull handles in a library card catalogue — A wooden card catalogue in a public library in Nashua, New Hampshire. Photo: MarkBuckawicki, CC0, via Wikimedia Commons.

Style discussions about Python use a vocabulary of their own. A code review comment mentions a "hanging indent", a formatter talks about the "magic trailing comma", a linter reports a "logical line" problem, and the documentation assumes you know what a "dunder" is. This glossary defines those terms in plain words, with an example where it helps and a note on which tool or document they come from. Each entry has its own anchor, so you can link straight to a definition from a review, a wiki or a contribution guide.

Layout and indentation

Indentation level

One step of indentation that opens a block after a line ending in a colon. PEP 8 asks for 4 spaces per level. Python itself accepts any consistent amount, but mixing tabs and spaces in a way that makes the meaning depend on tab width raises TabError.

Physical line

A line of the source file as your editor shows it, ended by a newline character. Line length limits apply to physical lines.

Logical line

One complete statement, which may span several physical lines when it is continued inside brackets or with a backslash. The Python Language Reference uses this distinction, and pycodestyle runs some checks per physical line and others per logical line.

Continuation line

Any physical line after the first in a logical line. PEP 8 requires that continuation lines be visually distinguishable from the indented block that may follow them.

Implicit line joining

Python's rule that a statement continues across lines while a parenthesis, bracket or brace is open. PEP 8 prefers it to a backslash at the end of the line; wrapping an expression in parentheses is the usual way to split a long condition.

Explicit line joining (backslash continuation)

Ending a line with \ so that the next line continues the statement. PEP 8 accepts it where brackets cannot be used, for instance in long with statements in older Python versions or in assert statements.

Hanging indent

A layout in which the opening bracket ends the first line and the arguments start on the next line, indented one extra level. PEP 8 takes the term from typesetting and adds two conditions: no arguments on the first line, and further indentation to separate the arguments from the body that follows.

result = some_function(
    first_argument,
    second_argument,
)

Visual indent (aligned with the opening delimiter)

A continuation style where wrapped elements line up vertically with the first element after the opening bracket. PEP 8 accepts it alongside the hanging indent. Formatters such as Black do not produce it, because the alignment must be redone whenever the function name changes length.

Maximum line length

PEP 8 limits code lines to 79 characters and flowing text in comments and docstrings to 72. It allows a team to agree on up to 99 characters for code, with comments and docstrings still wrapped at 72. Black's default is 88. Line length is a configuration choice in every tool, so check the project's settings before arguing about it.

Blank lines

PEP 8 surrounds top-level function and class definitions with two blank lines and method definitions inside a class with one. Blank lines inside functions mark logical sections and should be used sparingly.

Trailing whitespace

Spaces or tabs at the end of a line. Invisible in most editors, they create noisy diffs; pycodestyle reports them as W291, or W293 on an otherwise blank line.

Trailing comma

A comma after the last element of a collection, argument list or import list. PEP 8 makes it mandatory for a one-element tuple and recommends it when a list is written one item per line and is expected to grow, so that adding an item changes one line in the diff.

Magic trailing comma

A Black term. When a collection or call already ends with a trailing comma, Black keeps it exploded with one element per line, even if it would fit on one line. The option --skip-magic-trailing-comma turns this off.

Line break before a binary operator

Splitting a long expression so that each continuation line starts with the operator (+, and, or). PEP 8 recommends this style for new code, following mathematical typesetting as described by Donald Knuth, which puts the operator next to its operand. pycodestyle's W503 and W504 flag breaks before and after operators; both are off by default because they contradict each other.

Compound statement on one line

Several statements on one line separated by semicolons, or a body placed after the colon of if, for or while. PEP 8 discourages both; pycodestyle reports them in the E70x codes.

For the rules behind these entries, with examples of each continuation style, see PEP 8 explained section by section.

Naming

snake_case (lower_case_with_underscores): Lowercase words separated by underscores. PEP 8 uses it for functions, methods, variables and, without underscores where possible, for modules and packages.
CapWords (CamelCase, PascalCase): Words run together, each starting with a capital letter. PEP 8 uses it for class names and type variables, and asks that acronyms be fully capitalised: HTTPServerError, not HttpServerError. Exception classes that are errors end in Error.
mixedCase: Like CapWords but with a lowercase first letter. PEP 8 allows it only where it is already the prevailing style, for backward compatibility; some older standard library modules use it.
UPPER_CASE_WITH_UNDERSCORES: The convention for constants defined at module level, such as MAX_RETRIES. Python does not enforce constancy; the name is a signal to readers and type checkers.
Single leading underscore: A name such as _cache is marked as internal to its module or class. from module import * does not import names that start with an underscore.
Single trailing underscore: Appended to avoid a clash with a keyword or built-in name: class_, type_.
Name mangling (double leading underscore): Inside a class, an attribute named __spam is rewritten by the compiler to _ClassName__spam. PEP 8 suggests it only to avoid clashes with attributes of subclasses, not as a privacy mechanism.
Dunder: Short for "double underscore": names with two leading and two trailing underscores, such as __init__, __len__ or __all__. They have special meaning to the language or the standard library. PEP 8's advice is to use them only as documented and never to invent new ones.
Ambiguous single-character names: PEP 8 asks never to use l, O or I as single-character variable names, because in some fonts they are indistinguishable from the digits one and zero. Linters report this as E741 (variables), E742 (classes) and E743 (functions).
self and cls: The conventional names of the first argument of instance methods and class methods. They are conventions, not keywords, but every tool and reader expects them.

The full set of naming rules, with the reasoning behind them, is in our guide to Python naming conventions.

Comments, strings and docstrings

Block comment: One or more lines starting with # and a single space, indented to the level of the code they describe. Paragraphs inside a block comment are separated by a line containing only #.
Inline comment: A comment on the same line as a statement. PEP 8 asks for at least two spaces before the #, one after it, and sparing use.
Docstring: A string literal that is the first statement of a module, function, class or method. Python stores it in the object's __doc__ attribute, where help() and documentation generators find it. Its conventions are set out in PEP 257.
One-line docstring: A docstring that fits on a single line, with the opening and closing triple quotes on that line. PEP 257 asks that it be a phrase ending in a period that prescribes the effect as a command ("Return the path."), not a description ("Returns the path.").
Summary line: The first line of a multi-line docstring, followed by a blank line and then the details. Tools such as IDEs and documentation indexes often show only this line.
Docstring styles (reST, Google, NumPy): Conventions for documenting parameters, return values and exceptions inside a docstring. PEP 257 does not choose among them; Sphinx reads reStructuredText fields natively and the Google and NumPy styles through its napoleon extension.
String quotes: PEP 8 makes no recommendation between single and double quotes for ordinary strings, beyond picking one and sticking to it. For triple-quoted strings it asks for double quotes, for consistency with PEP 257. Black normalises ordinary strings to double quotes unless told otherwise.

Examples of each docstring style are in our page on Python docstrings and PEP 257.

Imports

Import groups: PEP 8 places imports at the top of the module, after the module docstring and comments, in three groups separated by a blank line: standard library, third-party packages, then local application imports.
Absolute and relative imports: An absolute import names the full package path (from mypackage.sub import tool); an explicit relative import starts with dots (from .sub import tool). PEP 8 recommends absolute imports and accepts explicit relative ones within complex packages.
Wildcard import: from module import *. PEP 8 advises against it because it hides where names come from and confuses readers and tools. Linters report it as F403 and F405 (Pyflakes codes).
__all__: A module-level list of the public names a module exports. PEP 8 places module-level dunders such as __all__ and __version__ after the module docstring and before the imports, except from __future__ imports, which must come first.

Type hints

Type hint (annotation): An expression attached to a parameter, return value or variable that states its expected type: def area(r: float) -> float:. PEP 484 defined the semantics for function annotations, and PEP 526 added variable annotations. Python does not check them at run time; type checkers do.
Annotation spacing: PEP 8 asks for the normal rules for colons (no space before, one after), spaces around the -> arrow, and spaces around = when an annotated argument has a default: def f(sep: str = ","), whereas an unannotated default has none: def f(sep=",").
Type checker: A program that reads annotations and reports inconsistencies without running the code. Mypy, Pyright and Pyre are the best known.
Stub file: A file with the extension .pyi that contains only signatures and annotations for a module, used when the module itself is not annotated or is written in C. Defined in PEP 484.
Gradual typing: The principle that annotated and unannotated code can coexist, with unannotated parts treated as type Any. It is what allows a large codebase to adopt type hints one module at a time.

Tools and process

PEP: Python Enhancement Proposal: a design document for the Python community, numbered and published on peps.python.org. PEP 8 (style) and PEP 257 (docstrings) are "Process" or "Informational" documents, not language features.
The Zen of Python: Tim Peters's short list of aphorisms about Python's design, published as PEP 20 and printed by import this. "Readability counts" is the line most often quoted in style discussions.
"A Foolish Consistency…": The title of PEP 8's opening section, borrowed from Emerson. It says that consistency within a function or module matters more than consistency with the guide, and lists cases where breaking a rule is the right choice.
Linter: A program that analyses source code and reports problems without changing it: style violations, likely bugs, unused names, excessive complexity. pycodestyle, Pyflakes, flake8, pylint and Ruff are linters.
Formatter: A program that rewrites source code into a consistent layout. Black and ruff format are opinionated formatters with few options; autopep8 fixes only what pycodestyle reports; isort sorts imports.
Idempotent formatting: Running a formatter twice gives the same result as running it once. Black and ruff format are designed this way, which is what makes them safe to run in a pre-commit hook or a CI job: a second pass changes nothing.
AST equivalence: An abstract syntax tree (AST) is the parsed structure of a program. In its default safe mode, Black checks that the code before and after formatting is semantically equivalent by comparing their ASTs, as a guarantee that formatting did not change behaviour.
pycodestyle: The reference checker for the mechanical parts of PEP 8, maintained by the PyCQA. It was originally called pep8 and was renamed to stop people confusing the tool with the document.
Pyflakes: A checker for logical errors rather than style: unused imports, undefined names, redefined functions. Its codes start with F.
flake8: A wrapper that runs pycodestyle, Pyflakes and the McCabe complexity checker (code C901) with one configuration, and accepts plugins.
Ruff: A linter and formatter written in Rust that reimplements rules from pycodestyle, Pyflakes, isort and many flake8 plugins, largely under their original codes, and offers a formatter designed as a drop-in replacement for Black.
Error code: The identifier attached to each finding, such as E501 or F401. The letter prefix identifies the family or the original tool (E and W for pycodestyle, F for Pyflakes, C9 for McCabe). Our reference to pycodestyle error codes explains each family.
noqa: "No quality assurance": a comment that silences findings on one line. # noqa: E501 silences one code; a bare # noqa silences everything on the line and is best avoided.
pre-commit hook: A script that Git runs before recording a commit. The pre-commit framework manages such hooks from a .pre-commit-config.yaml file, commonly to run a formatter and a linter on changed files.
pyproject.toml: The project configuration file introduced by PEP 518. Many tools, including Black, Ruff, isort, mypy and pytest, read their settings from its [tool.…] tables.
EditorConfig: A small .editorconfig file read by most editors to set indentation, line endings and final newlines per file type, so that code is written correctly before any tool runs.

The numbers, in one table

The main numeric values in PEP 8, plus Black's default line length, with where each is stated. Reuse is free with a link to this page.

Rule	Value	Source
Spaces per indentation level	4	PEP 8, "Indentation"
Maximum length of a code line	79 characters	PEP 8, "Maximum Line Length"
Maximum length of comments and docstrings	72 characters	PEP 8, "Maximum Line Length"
Upper limit a team may agree on for code	99 characters	PEP 8, "Maximum Line Length"
Blank lines around top-level functions and classes	2	PEP 8, "Blank Lines"
Blank lines around methods in a class	1	PEP 8, "Blank Lines"
Spaces before an inline comment	at least 2	PEP 8, "Inline Comments"
Groups of imports	3	PEP 8, "Imports"
Black's default line length	88 characters	Black documentation, "The Black code style"

Sources

Guido van Rossum, Barry Warsaw and Alyssa Coghlan, PEP 8 – Style Guide for Python Code, consulted 5 November 2026.
David Goodger and Guido van Rossum, PEP 257 – Docstring Conventions.
Black documentation, "The Black code style" (line length, magic trailing comma, string normalisation, AST safety checks).
PEP 20 (The Zen of Python), PEP 484 (type hints), PEP 526 (variable annotations), PEP 518 (pyproject.toml); pycodestyle, Pyflakes, flake8 and Ruff documentation.