Dignified Python - Python 3.13+ Coding Standards

Write explicit, predictable code that fails fast at proper boundaries.

Quick Reference - Check Before Coding

CRITICAL RULES (Top 6)

1. Exception Handling - NEVER for Control Flow 🔴

ALWAYS use LBYL (Look Before You Leap), NEVER EAFP

# ✅ CORRECT: Check before acting
if key in mapping:
    value = mapping[key]
else:
    handle_missing_key()

# ❌ WRONG: Using exceptions for control flow
try:
    value = mapping[key]
except KeyError:
    handle_missing_key()

Details: See references/core-standards.md#exception-handling for complete patterns

2. Type Annotations - Python 3.13+ Syntax Only 🔴

FORBIDDEN: from __future__ import annotations

# ✅ CORRECT: Modern Python 3.13+ syntax
def process(items: list[str]) -> dict[str, int]: ...
def find_user(id: int) -> User | None: ...

# ❌ WRONG: Legacy syntax
from typing import List, Dict, Optional
def process(items: List[str]) -> Dict[str, int]: ...

Details: See references/core-standards.md#type-annotations for all patterns

3. Path Operations - Check Exists First 🔴

# ✅ CORRECT: Check exists first
if path.exists():
    resolved = path.resolve()

# ❌ WRONG: Using exceptions
try:
    resolved = path.resolve()
except OSError:
    pass

Details: See references/core-standards.md#path-operations

4. Dependency Injection - ABC Not Protocol 🔴

# ✅ CORRECT: Use ABC
from abc import ABC, abstractmethod

class MyOps(ABC):
    @abstractmethod
    def operation(self) -> None: ...

# ❌ WRONG: Using Protocol
from typing import Protocol

Details: See references/core-standards.md#dependency-injection

5. Imports - Module-Level and Absolute 🔴

ALL imports must be at module level unless preventing circular imports

# ✅ CORRECT: Module-level, absolute imports
from erk.config import load_config
from pathlib import Path
import click

# ❌ WRONG: Inline imports (unless for circular import prevention)
def my_function():
    from erk.config import load_config  # WRONG unless circular import
    return load_config()

# ❌ WRONG: Relative imports
from .config import load_config

Exception: Inline imports are ONLY acceptable when preventing circular imports. Always document why:

def create_context():
    # Inline import to avoid circular dependency with tests
    from tests.fakes.gitops import FakeGitOps
    return FakeGitOps()

Details: See references/core-standards.md#imports

6. No Silent Fallback Behavior 🔴

# ❌ WRONG: Silent fallback
try:
    result = primary_method()
except:
    result = fallback_method()  # Untested, brittle

# ✅ CORRECT: Let error bubble up
result = primary_method()

Details: See references/core-standards.md#anti-patterns

When to Load References

Load references/core-standards.md when:

• Writing exception handling code (LBYL patterns)
• Working with type annotations (Python 3.13+ syntax)
• Implementing path operations (exists() checks)
• Creating ABC interfaces (dependency injection)
• Organizing imports (absolute imports, module-level)
• Working with CLI code (Click patterns)
• Using dataclasses and immutability
• Avoiding anti-patterns (silent fallback, exception swallowing)
• Implementing @property or __len__ (performance expectations)

Load references/code-smells-dagster.md when:

• Designing function APIs (default parameters, keyword arguments)
• Managing parameter complexity (parameter anxiety, invalid combinations)
• Refactoring large functions/classes (god classes, local variables)
• Working with context managers (assignment patterns)
• Using repr() programmatically (string representation abuse)
• Passing context objects (context coupling)
• Dealing with error boundaries (early validation)

Load references/patterns-reference.md when:

• Developing CLI commands with Click
• Working with file I/O and pathlib
• Implementing dataclasses and frozen structures
• Managing subprocess operations
• Reducing code nesting (early returns, helper functions)

Progressive Disclosure Guide

This skill uses a three-level loading system:

1. This file (SKILL.md): Core rules and navigation (~350 lines)
2. Reference files: Detailed patterns and examples (loaded as needed)
3. Quick lookup: Use the tables above to find what you need

Claude loads reference files only when needed based on the current task. The reference files contain:

• core-standards.md: Foundational Python patterns from this skill
• code-smells-dagster.md: Production-tested anti-patterns from Dagster Labs
• patterns-reference.md: Common implementation patterns and examples

Philosophy

Write dignified Python code that:

• Fails fast at proper boundaries (not deep in the stack)
• Makes invalid states unrepresentable (use the type system)
• Expresses intent clearly (LBYL over EAFP)
• Minimizes cognitive load (explicit over implicit)
• Enables confident refactoring (test what you build)

Default stances:

• Let exceptions bubble up (handle at boundaries only)
• Break APIs and migrate immediately (no unnecessary backwards compatibility)
• Check conditions proactively (LBYL)
• Use modern Python 3.13+ syntax

Quick Decision Tree

About to write Python code?

1. Using try/except?

   • Can you use LBYL instead? → Do that
   • Is this an error boundary? → OK to handle
   • Otherwise → Let it bubble

2. Using type hints?

   • Use list[str], str | None, not List, Optional
   • NO from __future__ import annotations

3. Working with paths?

   • Check .exists() before .resolve()
   • Use pathlib.Path, not os.path

4. Writing CLI code?

   • Use click.echo(), not print()
   • Exit with raise SystemExit(1)

5. Too many parameters?

   • See references/code-smells-dagster.md#parameter-anxiety

6. Class getting large?

   • See references/code-smells-dagster.md#god-classes

Checklist Before Writing Code

Before writing try/except:

• Can I check the condition proactively? (LBYL)
• Is this at an error boundary? (CLI/API level)
• Am I adding meaningful context or just hiding the error?

Before using type hints:

• Am I using Python 3.13+ syntax? (list, dict, |)
• Have I removed all typing imports except essentials?

Before path operations:

• Did I check .exists() before .resolve()?
• Am I using pathlib.Path?
• Did I specify encoding="utf-8"?

Before adding backwards compatibility:

• Did the user explicitly request it?
• Is this a public API?
• Default: Break and migrate immediately

Common Patterns Summary

References

• Core Standards: references/core-standards.md - Detailed LBYL patterns, type annotations, imports
• Code Smells: references/code-smells-dagster.md - Production-tested anti-patterns
• Pattern Reference: references/patterns-reference.md - CLI, file I/O, dataclasses
• Python 3.13 docs: https://docs.python.org/3.13/