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

# 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.)

1. Add new exports in alphabetical position
2. Never reorder existing exports
3. Run ruff format immediately after changes
4. 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.