You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
205 lines
3.9 KiB
205 lines
3.9 KiB
# 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
|
|
```
|
|
|