writing-python

Writing Python here

Not a general Python style guide. This repo bans things most guides mandate, and the bans are read out of the AST rather than trusted — _output.house_style_violations() fails the build, it does not warn. Everything below is either enforced or measured from the tree as it stands.

The dialect, in one paragraph

Stdlib only. Python 3.8 floor. No typing, no dataclasses, no annotations, no walrus, no from __future__ — banned by AST, because hooks start on every tool call and the import and parse cost is real. %-style formatting; there is not one f-string in the tree. Reach for os.path, json, re, subprocess — not for a dependency.

3.8 also rules out things that read as ordinary today: no X | Y unions, no match, no dict1 | dict2 merge, no list[str]. vermin -t=3.8- catches these; it will not catch the banned imports, which is why the AST lint exists alongside it.

Free functions, structured returns

The measured shape of this codebase is top-level functions by the hundred against a handful of classes, comprehensions everywhere, and global statements you can count on one hand. The ratio is the pattern to keep; the figures are not, so re-derive them rather than trusting a sentence:

grep -rhc '^def ' plugins/audit/scripts plugins/audit/hooks --include='*.py' | paste -sd+ | bc
grep -rn '^class \|^ *global ' plugins/audit/scripts plugins/audit/hooks --include='*.py' | wc -l

• Write a function, not a class. A class here needs a reason you can say out loud — the six that exist are all genuine (a lock, a launcher). Grouping related functions is what a module prefix is for.
• Return a new value; do not mutate an argument. 181 functions return a dict or tuple. A function that edits the caller's dict in place and also returns it is two contracts and the caller will rely on the wrong one.
• No module state. Constants at module level are fine (52 of them, uppercase, frozen tables). Mutable module state that a function writes to is how two callers start disagreeing about the same run. Where a cache is genuinely needed the existing pattern is an explicit _cache/cache=True argument, not a hidden global.
• Comprehensions over accumulate loops when the result is a list or dict and the body is one expression. Past that, a named function reads better than a nested comprehension.
• Push I/O to the edges. A function that takes values and returns values can be tested by a --selftest case with no temp directory and no git init; one that reads a file and prints cannot. Split the read from the decision — decide() taking parsed input is the shape every hook already uses, and it is why their logic has cases at all.