Python-Specific Rules - Everything Claude Code

This page extends Common Rules with Python specific content.Applies to: **/*.py, **/*.pyi

Coding Style

Standards

Follow PEP 8 conventions
Use type annotations on all function signatures

Immutability

Prefer immutable data structures:

from dataclasses import dataclass

@dataclass(frozen=True)
class User:
    name: str
    email: str

from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float

Formatting

black

Code formatting

isort

Import sorting

ruff

Linting

Reference

python-patterns

See skill for comprehensive Python idioms and patterns

Testing

Framework

Use pytest as the testing framework.

pytest --cov=src --cov-report=term-missing

Test Organization

Use pytest.mark for test categorization:

import pytest

@pytest.mark.unit
def test_calculate_total():
    assert calculate_total([1, 2, 3]) == 6

@pytest.mark.integration
def test_database_connection():
    db = Database()
    assert db.connect() is True

Reference

python-testing

See skill for detailed pytest patterns and fixtures

Patterns

Protocol (Duck Typing)

from typing import Protocol

class Repository(Protocol):
    def find_by_id(self, id: str) -> dict | None: ...
    def save(self, entity: dict) -> dict: ...

Dataclasses as DTOs

from dataclasses import dataclass

@dataclass
class CreateUserRequest:
    name: str
    email: str
    age: int | None = None

Context Managers & Generators

Context Managers

Use context managers (with statement) for resource management:

with open('file.txt', 'r') as f:
    content = f.read()

# Custom context manager
from contextlib import contextmanager

@contextmanager
def transaction(db):
    try:
        yield db
        db.commit()
    except Exception:
        db.rollback()
        raise

Generators

Use generators for lazy evaluation and memory-efficient iteration:

def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        yield a
        a, b = b, a + b

# Memory-efficient iteration over large datasets
for num in fibonacci(1000000):
    if num > 100:
        break

Reference

python-patterns

See skill for comprehensive patterns including decorators, concurrency, and package organization

Security

Secret Management

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.environ["OPENAI_API_KEY"]  # Raises KeyError if missing

Security Scanning

Use bandit for static security analysis:

bandit -r src/

Reference

django-security

See skill for Django-specific security guidelines (if applicable)

Hooks

PostToolUse Hooks

Configure in ~/.claude/settings.json:

black/ruff: Auto-format .py files after edit

Automatically runs black or ruff formatter on Python files after edits.

{
  "matcher": "Edit",
  "hooks": [{
    "type": "command",
    "command": "node format-python.js"
  }]
}

Example hook:

const { execFileSync } = require('child_process');

let data = '';
process.stdin.on('data', chunk => data += chunk);
process.stdin.on('end', () => {
  const input = JSON.parse(data);
  const filePath = input.tool_input?.file_path || '';
  
  if (/\.py$/.test(filePath)) {
    try {
      execFileSync('ruff', ['format', filePath], { stdio: 'pipe' });
    } catch (e) {}
  }
  
  console.log(data);
});

mypy/pyright: Run type checking after editing .py files

Runs type checker to catch type errors immediately.

mypy src/
# or
pyright src/

Warnings

Warn about print() statements in edited files (use logging module instead)

import logging

logger = logging.getLogger(__name__)

# WRONG: print() in production code
print(f"Processing user {user_id}")

# CORRECT: Use logging
logger.info(f"Processing user {user_id}")

Common Rules

Language-agnostic base rules

Hooks Overview

Complete hook system reference

​Coding Style

​Standards

​Immutability

​Formatting

black

isort

ruff

​Reference

python-patterns

​Testing

​Framework

​Test Organization

​Reference

python-testing

​Patterns

​Protocol (Duck Typing)

​Dataclasses as DTOs

​Context Managers & Generators

​Reference

python-patterns

​Security

​Secret Management

​Security Scanning

​Reference

django-security

​Hooks

​PostToolUse Hooks

​Warnings

​Related

Common Rules

Hooks Overview

Coding Style

Standards

Immutability

Formatting

Reference

Testing

Framework

Test Organization

Reference

Patterns

Protocol (Duck Typing)

Dataclasses as DTOs

Context Managers & Generators

Reference

Security

Secret Management

Security Scanning

Reference

Hooks

PostToolUse Hooks

Warnings

Related