python

# Python Development

## Core Practices

| Practice | Rule |
|-----------|-------|
| **No barrel imports** | Import directly from modules, don't re-export everything |
| **Type hints** | Always use `str`, `int`, `dict[str, Any]`, etc. |
| **Ruff** | Run `ruff check --fix && ruff format` before commit |
| **Script execution** | Use `python script.py`, not `chmod +x script.py` |

## Type Hints

```python
from typing import Any

# Always annotate function signatures
def process_data(data: dict[str, Any], limit: int = 100) -> list[dict]:
    ...

# Return types required for non-None returns
def get_record(id: str) -> dict[str, Any] | None:
    ...
```

## Import Organization

### Avoid Barrel Imports

**Bad** (barrel pattern - re-exports from submodules):
```python
# etl/__init__.py
from etl.parsers import *  # Don't do this
from etl.models import *
```

**Good** (direct imports):
```python
# In consuming code
from etl.parsers import ParserBase
from etl.models import UnifiedPropertyRecord
```

### Group Imports

Order: stdlib → third-party → local

```python
# 1. Standard library
from pathlib import Path
from typing import Any

# 2. Third-party
from pymongo import MongoClient

# 3. Local
from etl.config import CONFIG
```

## Script Execution

### Python Scripts

```python
#!/usr/bin/env python3
"""Script description."""

def main():
    ...

if __name__ == "__main__":
    main()
```

**Run with**: `python script.py`

### Shell Scripts (with chmod)

```bash
#!/usr/bin/env bash
# Only .sh files should be executable

# Rest of script
```

**Make executable**: `chmod +x script.sh` (only for .sh)

## Ruff Integration

```bash
# Check and fix
ruff check --fix

# Format
ruff format

# Combined
ruff check --fix && ruff format
```

## When to Use References

| Need | Reference |
|-------|-----------|
| Type hint patterns | `references/types.md` |
| Import patterns | `references/imports.md` |