python-style

Python Style Best Practices Skill

This skill automatically activates when writing Python code to ensure consistency with PEP standards, type hints, and modern Python idioms.

Core Standards

• PEP 8: Naming conventions, imports, line length
• Type Hints: Modern syntax (list[str] not List[str], X | None not Optional[X])
• Docstrings: Google style with Args, Returns, Raises sections
• Imports: stdlib → third-party → local, alphabetically sorted

Naming Conventions

# Classes: PascalCase
class UserAccount:
    pass

# Functions/variables: snake_case
def calculate_total():
    user_name = "john"

# Constants: SCREAMING_SNAKE_CASE
MAX_RETRY_COUNT = 3

# Private: single underscore prefix
def _internal_helper():
    pass

Type Hints (Python 3.10+)

# Use built-in generics
def process(items: list[str]) -> dict[str, int]:
    pass

# Use | for Optional/Union
def find_user(id: str) -> User | None:
    pass

# TypedDict for structured dicts
class UserData(TypedDict):
    id: str
    name: str

Function Length Guidelines

• < 30 lines: Ideal
• 30-50 lines: Review for refactoring
• > 50 lines: Must be broken down

Anti-Patterns to Avoid

• Missing type hints
• Bare except: clauses
• Magic numbers/strings without constants
• Non-expressive variable names (d, temp, x)
• Vague function names (process, handle, do_stuff)

Merge-Friendly Patterns (for Parallel Development)

When multiple agents modify the same module, follow these patterns to enable automatic merge resolution by semantic merge tools (mergiraf).

Always Run Ruff Before Commit

uv run ruff format .
uv run ruff check --fix .

This ensures imports are consistently ordered, enabling clean merges.

__all__ Must Be Alphabetical

Enable RUF022 in ruff to enforce this automatically:

[tool.ruff.lint]
select = [
    # ... other rules
    "RUF022", # unsorted-dunder-all (enforces alphabetical __all__)
]