Python Expert

# Python Expert Guidelines

**A comprehensive guide for AI agents writing and reviewing Python code**, organized by priority and impact.

---

## Table of Contents

### Correctness — **CRITICAL**
1. [Avoid Mutable Default Arguments](#avoid-mutable-default-arguments)
2. [Proper Error Handling](#proper-error-handling)

### Type Safety — **HIGH**
3. [Use Type Hints](#use-type-hints)
4. [Use Dataclasses](#use-dataclasses)

### Performance — **HIGH**
5. [Use List Comprehensions](#use-list-comprehensions)
6. [Use Context Managers](#use-context-managers)

### Style — **MEDIUM**
7. [Follow PEP 8 Style Guide](#follow-pep-8-style-guide)
8. [Write Docstrings](#write-docstrings)

---

## Correctness

### Avoid Mutable Default Arguments

**Impact: CRITICAL** | **Category: correctness** | **Tags:** bugs, defaults, mutable, gotcha

Mutable default arguments (like lists or dicts) are shared across all calls to the function.

#### Why This Matters

Because the default value is evaluated only once at function definition time, subsequent calls will persist changes made to the default object, leading to extremely subtle and frustrating bugs.

#### ❌ Incorrect

```python
def add_item(item, items=[]):  # BUG: [] is shared!
    items.append(item)
    return items

print(add_item("a"))  # ['a']
print(add_item("b"))  # ['a', 'b'] - Unexpected!
```

#### ✅ Correct

```python
def add_item(item: str, items: list[str] | None = None) -> list[str]:
    """Add an item to a list, creating a new list if none provided.
    
    Args:
        item: The item to add
        items: Optional existing list to add to
        
    Returns:
        The list with the new item added
    """
    if items is None:
        items = []
    items.append(item)
    return items
```

---

### Proper Error Handling

**Impact: CRITICAL** | **Category: correctness** | **Tags:** errors, exceptions, reliability

Always handle errors explicitly. Don't use bare except clauses or ignore errors silently.

#### ❌ Incorrect

```python
try:
    result = risky_operation()
except:
    pass  # Silent failure!
```

#### ✅ Correct

```python
try:
    config = json.loads(config_file.read())
except json.JSONDecodeError as e:
    logger.error(f"Invalid JSON in config file: {e}")
    config = get_default_config()
except FileNotFoundError:
    logger.warning("Config file not found, using defaults")
    config = get_default_config()
```

---

## Type Safety

### Use Type Hints

**Impact: HIGH** | **Category: type-safety** | **Tags:** types, mypy, annotations, documentation

Type hints enable static analysis, improve IDE support, and serve as documentation.

#### Why This Matters

Python's dynamic nature can lead to runtime errors that are hard to catch. Type hints allow tools like `mypy` to verify code correctness before execution.

#### ❌ Incorrect

```python
def get_user(id):
    return users.get(id)
```

#### ✅ Correct

```python
from typing import Optional, Dict, Any

def get_user(user_id: int) -> Optional[Dict[str, Any]]:
    """Fetch user by ID.
    
    Args:
        user_id: The unique identifier for the user
        
    Returns:
        User dictionary if found, None otherwise
    """
    return users.get(user_id)
```

---

### Use Dataclasses

**Impact: HIGH** | **Category: type-safety** | **Tags:** dataclasses, classes, data, boilerplate

Use the `@dataclass` decorator for classes that primarily store data.

#### Why This Matters

Dataclasses automatically generate `__init__`, `__repr__`, and `__eq__` methods, reducing boilerplate and ensuring consistent behavior for data containers.

#### ❌ Incorrect

```python
class User:
    def __init__(self, id, name, email):
        self.id = id
        self.name = name
        self.email = email
    
    def __repr__(self):
        return f"User(id={self.id}, name={self.name}, email={self.email})"
    
    def __eq__(self, other):
        return self.id == other.id and self.name == other.name
```

#### ✅ Correct

```python
from dataclasses import data