Format Python Files Check

Automatically formats Python files with Black after every edit operation, enforcing PEP 8 compliant code style across the project.

When to Use This Hook

Attach this hook when you need to:

• Apply consistent Black formatting to every Python file Claude modifies during a session
• Eliminate style inconsistencies in Python codebases without manual formatter invocation
• Ensure all edited .py files comply with your team's Black configuration

Consider alternatives when:

• Your project uses a different formatter like yapf or autopep8 with custom rules
• You prefer formatting only at pre-commit time using the pre-commit framework

Quick Start

Configuration

Copy
name: format-python-files-check
type: hook
trigger: PostToolUse
category: post-tool

Example Trigger

Copy
# Hook triggers after Claude edits a Python file
claude> Edit src/services/user_service.py
# Black runs automatically on the edited file

Example Output

reformatted src/services/user_service.py

All done!
1 file reformatted.

Core Concepts

Format Scope Overview

Aspect	Details
File Extensions	.py only
Matcher	Triggers on Edit tool operations
Formatter	black (must be installed via pip)
Error Handling	Suppressed with 2>/dev/null || true
Config Resolution	Uses nearest pyproject.toml [tool.black] section

Formatting Workflow

Edit Tool Completes
       |
  Check Extension
   /         \
 .py        Other
  |           |
Run Black    Skip
  |
┌─┴──┐
|    |
OK  Fail
|    |
Done Suppress
     Error

Configuration

Parameter	Type	Default	Description
matcher	string	"Edit"	Tool operation that triggers formatting
line_length	number	88	Maximum line length (Black default)
target_version	string	"py310"	Python version target for syntax
suppress_errors	boolean	true	Silently ignore formatter failures
check_only	boolean	false	Report formatting issues without fixing them

Best Practices

1. Install Black in Your Virtual Environment - The hook calls black directly, so it must be available on PATH. Install it in your project's virtualenv with pip install black so it picks up the correct version.

2. Configure in pyproject.toml - Define Black settings in pyproject.toml under [tool.black] so every developer and this hook use identical formatting rules. Avoid relying on command-line flags.

3. Add a check_only Mode for CI - In CI pipelines, run Black with --check to fail on unformatted files rather than silently fixing them. The hook itself should auto-fix during development sessions.

4. Extend to Write Operations - Add a second matcher for the Write tool so newly created Python files are also formatted immediately, not just edited ones.

5. Pair with isort - Black handles code formatting but not import ordering. Add a companion hook that runs isort before Black to keep imports organized and avoid conflicts between the two tools.

Common Issues

1. Black Not Installed - If Black is missing, the hook silently suppresses the error. Developers may not realize files are unformatted. Add a startup check or use pip install black in your project setup script.

2. Line Length Conflicts with Flake8 - Black defaults to 88-character lines while Flake8 defaults to 79. Align both tools by setting max-line-length = 88 in your Flake8 config.

3. Magic Trailing Comma Behavior - Black preserves trailing commas and forces multi-line formatting when they are present. If this surprises your team, document the behavior and decide on a trailing comma convention.