86 lines | 3.8 KB
Raw

Python (PEP 8) — Claude Code rules

Write Python that follows PEP 8 (style) and PEP 257 (docstrings). PEP 8's own guidance applies: code is read more often than written, and consistency within a module or function matters most. Know when to be inconsistent — don't break backward compatibility just to comply.

Run a formatter (e.g. black or ruff format) and a linter (ruff / flake8) so layout is enforced mechanically, not by hand. These rules describe the target; the formatter gets you there.

Layout

  • 4 spaces per indentation level. Spaces, never tabs (tabs only to stay consistent with already-tab-indented code).
  • Limit lines to 79 characters (72 for docstrings and comments). Teams may agree on up to 99 for code, but keep comments/docstrings at 72.
  • Two blank lines around top-level function and class definitions; one blank line between methods inside a class. Blank lines sparingly inside functions to separate logical sections.
  • No trailing whitespace.
  • Break long expressions before a binary operator, not after.

Whitespace in expressions

  • No spaces just inside (), [], {}, and none before ,, ;, : or a call/index bracket: spam(ham[1], {eggs: 2}).
  • Surround binary operators with a single space (=, ==, <, +=, and, or, not, is).
  • No spaces around = for keyword args / unannotated defaults (f(real, imag=0.0)), but add them when an annotation is present (def f(sep: str = "")).
  • In slices treat : as a binary operator with even spacing (ham[lower:upper]).

Naming

  • Functions, variables, methods, modules: snake_case. Modules/packages stay short and all-lowercase.
  • Classes, type variables, exceptions: CapWords (exceptions end in Error).
  • Constants (module level): UPPER_CASE_WITH_UNDERSCORES.
  • _single_leading_underscore for non-public/internal; __double_leading only to invoke name mangling; trailing_underscore_ to dodge a keyword (e.g. class_). Never name anything l, O, or I.
  • First method args are self (instance) and cls (class).

Imports

  • One import per line (import os then import sys); from x import a, b is fine.
  • Imports at the top of the file, after the module docstring, before globals.
  • Group as (1) standard library, (2) third-party, (3) local, one blank line between groups. Prefer absolute imports. No wildcard from x import *.

Docstrings & comments (PEP 257)

  • Docstrings for every public module, function, class, and method (including __init__). Always """triple double quotes""" (r"""...""" if it needs backslashes).
  • One-liner: text and closing """ on the same line, imperative mood ("Return the path", not "Returns the path"), ends with a period.
  • Multi-line: summary line, blank line, then the body; closing """ on its own line. Blank line after a class docstring before its methods.
  • Block comments at code indent, each line # then text, complete sentences. Inline comments: at least two spaces before #, used sparingly.

Comparisons

  • Compare to None with is / is not, never ==. Use is not x, not not ... is.
  • Don't compare booleans with ==; write if greeting: not if greeting == True.
  • Use isinstance(obj, int), not type(obj) is int.
  • Lean on truthiness for empty sequences: if not seq: / if seq:.

Type hints (PEP 484, optional)

  • Annotate with def f(x: int) -> str:; import constructs from typing.
  • Use Optional[T] (or T | None) when None is allowed.
  • Hints are static-analysis only — not enforced at runtime.

Don't

  • Don't mix tabs and spaces, or exceed the line limit without team agreement.
  • Don't use a bare except:; catch specific exceptions and keep try blocks small.
  • Don't bind a lambda to a name — use def.
  • Don't write comments that contradict the code; update or delete them.