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__)
]

# CORRECT - alphabetical, one per line, no comments
__all__ = [
    "ACLFilterSpec",
    "Chunk",
    "ChunkerInterface",
    "Document",
    "QueryACLContext",
    "Visibility",
]

# WRONG - grouped by category (causes merge conflicts)
__all__ = [
    # Types
    "Chunk",
    "Document",
    # Interfaces
    "ChunkerInterface",
]

No Comments Inside Lists

Comments inside __all__, import groups, or other lists break deterministic ordering and cause merge conflicts. Keep comments outside:

# ACL and schema types exported for public API
__all__ = [
    "ACLFilterSpec",
    "Chunk",
    "Document",
]

When Adding to Shared Files (`init.py`, etc.)

Add new exports in alphabetical position
Never reorder existing exports
Run ruff format immediately after changes
Avoid adding section comments

Why This Matters

Semantic merge tools like mergiraf can automatically resolve conflicts when:

Both branches add items to the same list in alphabetical order
No comments or groupings change the structure
Formatting is consistent (via ruff)

Without these patterns, parallel agents adding exports to the same __init__.py will create conflicts requiring manual resolution.

python-style