# Import Organization Constraints

## Standard Order

Organize imports in three groups with blank lines between:

```python
# 1. Standard library imports (alphabetical within group)
import json
import logging
import os
from datetime import datetime, timedelta
from typing import Dict, List, Optional, Tuple

# 2. Third-party packages (alphabetical within group)
import duckdb
import requests
from config import config

# 3. Local application modules (can use relative imports)
from database import db
from summarizer import summarizer
```

## Alphabetical Ordering

Within each group, sort imports alphabetically:

```python
# GOOD - alphabetical
import json
import logging
from datetime import datetime
from typing import Dict, List, Optional

# BAD - random order
from typing import Optional
import json
from datetime import datetime
import logging
from typing import Dict, List
```

## Grouping Rules

### Standard Library
- `json`, `logging`, `os`, `sys`, `time`
- `datetime`, `timedelta` from `datetime`
- `Dict`, `List`, `Optional`, etc. from `typing`
- `argparse`, `pathlib`, `re`, `uuid`

### Third-Party
- `duckdb`, `requests`, `streamlit`
- `numpy`, `scipy`, `sklearn`
- `plotly`, `beautifulsoup4`
- `pytest`

### Local Application
- Modules from same package
- Relative imports when appropriate

## When to Use `from X import Y`

### Prefer `from module import specific_items` for:
- Constants and config
- Single classes or functions used frequently
- Type annotations

```python
# GOOD - clear about what we're using
from config import config
from database import db

# GOOD - type hints
from typing import Dict, List, Optional
```

### Use `import module` when:
- You need multiple items from the module
- Using module.namespace is clearer

```python
# GOOD - duckdb used for types and module access
import duckdb

conn = duckdb.connect(...)
result = conn.execute(...)

# Also acceptable for types
from typing import Dict
```

## Relative Imports

In package modules, prefer relative imports:

```python
# pipeline/svd_pipeline.py
from ..database import MotionDatabase  # relative import
from .text_pipeline import process_text  # relative import
```

## Circular Imports

Avoid circular imports by:
1. Moving shared code to a third module
2. Using TYPE_CHECKING for type hints only

```python
# types.py - shared type definitions
from typing import TypedDict

class MotionDict(TypedDict):
    id: int
    title: str
    ...

# module_a.py
from .types import MotionDict

# module_b.py - if needed here too
from .types import MotionDict
```

## Import Patterns to Avoid

### Wildcard Imports
```python
# BAD
from database import *

# GOOD
from database import db, MotionDatabase
```

### Import in Function Scope (unless necessary)
```python
# AVOID - delays import, makes dependencies unclear
def some_function():
    import pandas as pd  # Late import
    return pd.DataFrame(...)

# PREFER - import at module level
import pandas as pd

def some_function():
    return pd.DataFrame(...)
```

### Reassigning Imported Names
```python
# BAD - confusing
from module import process
process = something_else  # Reassigning

# GOOD - clear naming
from module import process as process_data
```

## Type Checking Imports

For type hints only, use TYPE_CHECKING:

```python
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .models import Motion

def get_motion(motion_id: int) -> "Motion":  # String quote for forward ref
    ...
```

## Optional Dependency Imports

Handle optional dependencies gracefully:

```python
try:
    import duckdb
except Exception:
    duckdb = None  # Will be checked later

class MotionDatabase:
    def __init__(self):
        if duckdb is None:
            self._file_mode = True  # Fallback mode
```

## Example: Complete Import Block

```python
# Complete example from database.py
import json
import logging
import uuid
from datetime import datetime, timedelta
from typing import Dict, List, Optional, Tuple

import duckdb

from config import config

from database import db
```