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:

• Context - What happened and where

• Expected - What was expected instead

• 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

• Keyword-only args - Use * for clarity

• Pathlib - Use Path not string paths

• Context managers - Use with for resources

• 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

• Type hints - Required on all public functions

• Docstrings - Google style, with Args/Returns/Raises

• Black formatting - 100 char line length

• isort imports - Sorted and organized

• Helpful errors - Context + expected + docs link

• Pathlib - Use Path not string paths

• Keyword args - Use * for clarity

• 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