/python-standards

name: python-standards
description: "Python code quality standards covering PEP 8, Black formatting, type hints, Google-style docstrings, and error handling. Use when writing or reviewing Python code. TRIGGER when: python, formatting, type hints, docstrings, PEP 8, black, isort. DO NOT TRIGGER when: non-Python files, markdown, config, shell scripts."
allowed-tools: [Read]

Python Standards Skill

Python code quality standards for autonomous-dev project.

When This Activates

• Writing Python code
• Code formatting
• Type hints
• Docstrings
• Keywords: "python", "format", "type", "docstring"

---

Code Style (PEP 8 + Black)

| Setting | Value | |---------|-------| | Line length | 100 characters | | Indentation | 4 spaces (no tabs) | | Quotes | Double quotes | | Imports | Sorted with isort |

black --line-length=100 src/ tests/
isort --profile=black --line-length=100 src/ tests/

---

Type Hints (Required)

**Rule:** All public functions must have type hints on parameters and return.

def process_file(
    input_path: Path,
    output_path: Optional[Path] = None,
    *,
    max_lines: int = 1000
) -> Dict[str, any]:
    """Type hints on all parameters and return."""
    pass

---

Docstrings (Google Style)

**Rule:** All public functions/classes need docstrings with Args, Returns, Raises.

def process_data(data: List[Dict], *, batch_size: int = 32) -> ProcessResult:
    """Process data with validation.

    Args:
        data: Input data as list of dicts
        batch_size: Items per batch (default: 32)

    Returns:
        ProcessResult with items and metrics

    Raises:
        ValueError: If data is empty
    """

---

Error Handling

**Rule:** Error messages must include context + expected + docs link.

# ✅ GOOD
raise FileNotFoundError(
    f"Config file not found: {path}\n"
    f"Expected: YAML with keys: model, data\n"
    f"See: docs/guides/configuration.md"
)

# ❌ BAD
raise FileNotFoundError("File not found")

Exception Hierarchy

Define a project-level exception hierarchy for structured error handling:

class AppError(Exception):
    """Base exception for the application."""
    pass

class ConfigError(AppError):
    """Configuration loading or validation error."""
    pass

class ValidationError(AppError):
    """Input or data validation error."""
    pass

class ExternalServiceError(AppError):
    """Error communicating with external service."""
    pass

**When to use custom vs built-in exceptions:**

• Use **built-in** (`ValueError`, `TypeError`, `FileNotFoundError`) for standard programming errors
• Use **custom** exceptions when callers need to catch specific application-level failures
• Always inherit from a project base exception for catch-all handling

Error Message Format

Every error message should follow this three-part format:

1. **Context** - What happened and where 2. **Expected** - What was expected instead 3. **Docs link** - Where to find more information

raise ValidationError(
    f"Invalid config key '{key}' in {config_path}\n"
    f"Expected one of: {', '.join(valid_keys)}\n"
    f"See: docs/configuration.md#valid-keys"
)

Graceful Degradation

When a non-critical operation fails, log and continue rather than crashing:

try:
    optional_result = enhance_with_cache(data)
except CacheError:
    logging.warning("Cache unavailable, proceeding without cache")
    optional_result = None

---

Naming Conventions

| Type | Convention | Example | |------|------------|---------| | Classes | PascalCase | `ModelTrainer` | | Functions | snake_case | `train_model()` | | Constants | UPPER_SNAKE | `MAX_LENGTH` | | Private | _underscore | `_helper()` |

---

Best Practices

1. **Keyword-only args** - Use `*` for clarity 2. **Pathlib** - Use `Path` not string paths 3. **Context managers** - Use `with` for resources 4. **Dataclasses** - For configuration objects

# Keyword-only args
def train(data: List, *, learning_rate: float = 1e-4):
    pass

# Pathlib
config = Path("config.yaml").read_text()

---

Code Quality Commands

flake8 src/ --max-line-length=100       # Linting
mypy src/[project_name]/                # Type checking
pytest --cov=src --cov-fail-under=80    # Coverage

---

Key Takeaways

1. **Type hints** - Required on all public functions 2. **Docstrings** - Google style, with Args/Returns/Raises 3. **Black formatting** - 100 char line length 4. **isort imports** - Sorted and organized 5. **Helpful errors** - Context + expected + docs link 6. **Pathlib** - Use Path not string paths 7. **Keyword args** - Use `*` for clarity 8. **Dataclasses** - For configuration objects

---

Related Skills

• **testing-guide** - Testing patterns and TDD methodology
• **error-handling-patterns** - Error handling best practices

---

Hard Rules

**FORBIDDEN**:

• Public functions without type hints on parameters and return values
• Bare `except:` or `except Exception:` without re-raising or specific handling
• Mutable default arguments (`def f(items=[])`)
• Using `os.path` when `pathlib.Path` is available

**REQUIRED**:

• All public APIs MUST have Google-style docstrings with Args/Returns/Raises
• All code MUST pass black formatting (100 char line length)
• Imports MUST be sorted with isort (profile=black)
• Keyword-only arguments MUST be used for functions with 2+ optional parameters