1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
#!/usr/bin/env bash
# Validate Python files after Edit/Write/MultiEdit.
# PostToolUse hook: receives tool-call JSON on stdin.
#
# On success: exit 0 silent.
# On failure: emit JSON with hookSpecificOutput.additionalContext so Claude
# sees a structured error in its context, THEN exit 2 to block the tool
# pipeline. stderr still echoes the error for terminal visibility.
#
# Phase 1: syntax — python3 compiles the file. Always available wherever this
# hook can meaningfully run, so it's the floor rather than an optional
# gate: a file that doesn't parse is never worth passing on.
# Phase 2: ruff — lint, when installed. Catches undefined names, unused
# imports, and the rest of the pyflakes set. Absent ruff doesn't block
# the edit, matching how the bash bundle treats shellcheck.
#
# Formatters (black, ruff format) are deliberately NOT enforced here. A project
# picks its own line length and quote style, so blocking on an unconfigured
# default would impose a contested choice. python.md recommends a formatter;
# this hook enforces correctness.
#
# Type checking (mypy, pyright) is also out: it needs the whole package and its
# dependencies resolved, which is a build-scale operation, not a per-keystroke
# one. Run it via `make lint` / `make typecheck`.
#
# Scope: .py and .pyi files, plus extensionless files whose first line is a
# python shebang (the CLI tools that fill a script-heavy repo carry no
# extension).
set -u
# Emit a JSON failure payload and exit 2. Arguments:
# $1 — short failure type (e.g. "PYTHON SYNTAX ERROR")
# $2 — file path
# $3 — tool output (error body)
fail_json() {
local ctx
ctx="$(printf '%s: %s\n\n%s\n\nFix before proceeding.' "$1" "$2" "$3" \
| jq -Rs .)"
cat <<EOF
{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": $ctx}}
EOF
printf '%s: %s\n%s\n' "$1" "$2" "$3" >&2
exit 2
}
f="$(jq -r '.tool_input.file_path // .tool_response.filePath // empty')"
[ -z "$f" ] && exit 0
[ -f "$f" ] || exit 0
# Is this a Python file? By extension, or by shebang when it has no extension.
# Match on the basename, not the full path — a temp/parent dir can carry a dot
# (e.g. my.project/) and misfire the "*.*" extension test.
is_python=0
base="${f##*/}"
case "$base" in
*.py | *.pyi) is_python=1 ;;
*.*) is_python=0 ;; # some other extension — not ours
*)
# No extension: sniff the shebang.
if head -1 "$f" 2>/dev/null | grep -qE '^#!.*\bpython[0-9.]*\b'; then
is_python=1
fi
;;
esac
[ "$is_python" -eq 1 ] || exit 0
# No python3 on this machine — nothing to validate, don't block the edit.
command -v python3 >/dev/null 2>&1 || exit 0
# --- Phase 1: syntax ---
# compile() rather than py_compile so no __pycache__ lands beside the source;
# the hook is a checker and must not leave build artifacts in the tree.
if ! out="$(python3 -c '
import sys
p = sys.argv[1]
with open(p, "rb") as fh:
src = fh.read()
try:
compile(src, p, "exec")
except SyntaxError as e:
print(f"{e.msg} ({p}, line {e.lineno})", file=sys.stderr)
sys.exit(1)
' "$f" 2>&1)"; then
fail_json "PYTHON SYNTAX ERROR" "$f" "$out"
fi
# --- Phase 2: lint (optional) ---
command -v ruff >/dev/null 2>&1 || exit 0
if ! out="$(ruff check "$f" 2>&1)"; then
fail_json "RUFF FAILED" "$f" "$out"
fi
exit 0
|
