Google Python Style + mandatory docstrings

Sources: https://google.github.io/styleguide/pyguide.html · https://peps.python.org/pep-0008/

Audit: script first, read code only where needed. Review only: report findings, don't edit unless the user explicitly asks. In legacy code with its own config (pyproject.toml [tool.ruff], .pylintrc, setup.cfg), report deviations from Google style once, then follow the project config.

Scope

Check the files/directories the user names, otherwise the whole repo. Skip .git/, .venv/, venv/, build/, dist/, __pycache__/, site-packages/, node_modules/, vendor/, migrations and generated files (# Generated by, DO NOT EDIT, *_pb2.py).

Audit steps

1. Run (no pipe; output is capped): bash <skill-dir>/scripts/check.sh <project-root> [hitsPerRule=8]
   • Uses ruff (preferred) or pylint if installed, then grep/awk heuristics ## ID count SEV | desc + samples file:line:code.
   • No linter installed: the script says so. Tell the user that pip install ruff makes the check more precise, then continue with heuristics and manual review. Never install anything yourself.
2. Heuristic hits: spot-check samples, drop false positives (list below). Bulk formatting hits (line length, quotes) = one root cause: report once, suggest a formatter (ruff format, pyink, black --line-length 80).
3. Review ★ rules manually in ≤5 representative files (largest/core modules).
4. Report (format below). Fix order: docstring/type gaps on public API → MUST rules → SHOULD.

Rules (ID → script; ★ manual)

Language

• P4 no bare except:; ★ catch Exception only to re-raise or at an isolation boundary; keep try bodies small; custom exceptions end in Error
• ★ assert only for internal invariants, never to validate public arguments
• P5 no mutable default arguments ([], {}, list(), dict(), set()); use None
• P6 no wildcard imports · P7 no relative imports (use the full package path) · ★ import x / from pkg import module for modules and packages only, not classes/functions (exempt: typing, collections.abc, typing_extensions)
• P8 is None / is not None, never == None; no == True/False; ★ implicit false for sequences (if not items:)
• ★ no mutable global state; module constants are fine · ★ avoid power features (metaclasses, __del__, reflection hacks)
• P11 avoid @staticmethod (write a module function) · ★ @classmethod only for named constructors
• P15 files/sockets via with (not bare x = open(...))
• P12 logging with %-placeholders: logger.info('Got %s', x), not f-strings
• ★ if __name__ == '__main__': guard, logic in main() · ★ functions ≤ ~40 lines (guideline)
• ★ type hints on all public functions/methods (project rule); X | None / Optional[X] for nullable

Style

• P1 no tabs; 4 spaces · P2 ≤80 columns (except long imports, URLs, # pylint: disable lines)
• P3 no backslash continuation; use implicit joining inside ()
• P10 one statement per line (no ;) · P9 one import per line (except typing names)
• ★ imports grouped __future__ → stdlib → third-party → local, each lexicographically sorted
• ★ 2 blank lines between top-level definitions, 1 between methods
• ★ consistent quote character per file; """ for docstrings
• P13 TODO format: # TODO: <link> - <text> (legacy # TODO(<user>): <text> accepted)

Naming

• module_name, package_name, ClassName, ExceptionName, function_name, method_name, GLOBAL_CONSTANT, local_var, param_name; leading _ for internal
• ★ no single-char names outside short scopes (i, j, k, e, f, v ok); ★ no __double_leading names (name mangling); no dashes in module names

Docstrings (project rule: stricter than the Guide)

• D1 module docstring at the top of every file (summary line + description)
• D2 every class and every public function/method has a docstring (_private and __dunder__ exempt unless non-trivial); ★ @override methods may skip it if behavior is unchanged
• ★ summary line ≤80 chars, ends with ., then blank line, then body
• ★ sections in order Args: → Returns:/Yields: → Raises:; Args: lists every parameter as name: Description. (indent 4, continuation +4); no section for None returns
• ★ class docstring describes the instance; public attributes in Attributes:; @property docstring reads like an attribute ("The Bigtable path.")
• ★ consistent mood per file: descriptive ("Fetches rows.") or imperative ("Fetch rows.")

Template:

def fetch_rows(table: Table, keys: Sequence[str]) -> dict[str, Row]:
    """Fetches rows from a table.

    Args:
        table: The table to read from.
        keys: Row keys to fetch. Missing keys are skipped.

    Returns:
        A dict mapping each found key to its row.

    Raises:
        IOError: If the table cannot be read.
    """

False positives to drop

P2 in long string literals that can't be split, or in URLs inside docstrings · P3 inside string literals · P5 when the default is never mutated (still mention as info) · P8 in SQLAlchemy/pandas expressions (col == None builds a query) · P11 when a framework requires it · D2 in tests (test_* functions need no docstring) · anything in generated code.

Report

In the user's language, grouped by file:

path/to/file.py:line - error|warning|info - <ID> <rule> - <why it is a problem> (https://google.github.io/styleguide/pyguide.html#<section>)

• MUST = error, SHOULD = warning, style hints = info.
• Every finding has a concrete location; mark uncertain ones as "possible".
• Bulk hits with one root cause: report once with count and 2-3 sample locations.
• End with a summary: findings per severity, then the 3 most important things to fix first.
• Do not change code. Apply fixes only when the user explicitly asks for it.