python-best-practices

Files (1)

• SKILL.md

SKILL.md (first lines)

# Python Best Practices

This skill provides comprehensive guidance for writing clean, maintainable, and testable Python code, especially when working with AI-assisted development.

## Code Style and Formatting

### 1. PEP 8 Compliance
```python
# Use 4 spaces for indentation
def calculate_total(items):
    total = 0
    for item in items:
        total += item.value
    return total

# Line length: max 79 characters (soft), 88 (hard)
long_variable_name = "this_is_acceptable"  # 27 chars
acceptable_but_longer = "this_name_is_still_within_limits"  # 36 chars

# Import order: standard library → third party → local
import os  # standard library
import tempfile  # standard library
import openai  # third party
from .local_module import local_function  # local
```

### 2. Type Hints
```python
from typing import List, Dict, Optional, TypedDict, Union
from datetime import datetime

def process_data(
    items: List[Dict[str, Union[str, int]]],
    timestamp: Optional[datetime] = None
) -> List[str]:
    """Process data items and return results."""
    results = []
    for item in items:
        processed = str(item.get("value", 0))
        results.append(processed)

    return results

# TypedDict for structured data
class UserProfile(TypedDict):
    name: str
    age: int
    email: Optional[str]
```

### 3. Docstrings
```python
def complex_function(param1: str, param2: int) -> bool:
    """
    Perform complex calculation on input parameters.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        bool: True if calculation succeeds, False otherwise

    Raises:
        ValueError: If param2 is negative

    Examples:
        >>> complex_function("test", 5)
        True
    """
    if param2 < 0:
        raise ValueError("param2 must be non-negative")

    return True
```

## Error Handling

### 1. Specific Exceptions
```python
class ValidationError(Exception):
    """Raised when input validation fails."""
    pass

class APIError(Exception):
    """Raised when API calls fail."""
    def __init__(self, message: str, status_code: int):
        super().__init__(message)
        self.status_code = status_code

def validate_input(data: dict) -> dict:
    if not isinstance(data, dict):
        raise ValidationError("Input must be a dictionary")

    if not data.get("required_field"):
        raise ValidationError("required_field is missing")

    return data
```

### 2. Context Managers
```python
from contextlib import contextmanager

@contextmanager
def database_connection():
    """Context manager for database connections."""
    conn = create_connection()

    try:
        yield conn
    finally:
        conn.close()

# Usage
with database_connection() as conn:
    result = conn.execute("SELECT * FROM users")
```

From yasinnerten/temporal-openai-agents-sdk, Apache-2.0.

More from yasinnerten/temporal-openai-agents-sdk