File size: 3,950 Bytes
7a87926 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 |
# Import Guidelines for YLFF
## Overview
This document provides clear guidelines for importing modules in the YLFF codebase to ensure consistency and avoid confusion.
## Directory Structure
```
ylff/
├── model_loader.py # ML model loading utilities (renamed from models.py)
├── models/ # Pydantic API models (package)
│ └── api_models.py
├── services/ # Business logic
├── utils/ # Utility functions
└── routers/ # API route handlers
```
## Import Patterns
### 1. ML Model Utilities (`model_loader.py`)
**Correct:**
```python
from ylff.model_loader import load_da3_model, get_recommended_model
from ..model_loader import load_da3_model # In submodules
```
**Incorrect:**
```python
from ylff.models import load_da3_model # ❌ This imports from models/ package
```
### 2. Pydantic API Models (`models/api_models.py`)
**Correct:**
```python
from ylff.models import JobResponse, ValidateSequenceRequest
from ..models import JobResponse # In submodules
```
**Incorrect:**
```python
from ylff.model_loader import JobResponse # ❌ Wrong module
```
### 3. Services
**Correct:**
```python
from ylff.services import BAValidator, ARKitProcessor
from ylff.services.ba_validator import BAValidator
from ..services import BAValidator # In submodules
```
### 4. Utils
**Correct:**
```python
from ylff.utils.profiler import Profiler, profile
from ylff.utils.coordinate_utils import convert_arkit_to_opencv
from ..utils.profiler import Profiler # In submodules
```
### 5. Routers
**Correct:**
```python
from ylff.routers import health_router, validation_router
from ..routers import health_router # In submodules
```
## Naming Convention Summary
| Module | Import Path | Purpose |
| ---------------------- | ----------------------------------- | ------------------------------------ |
| `model_loader.py` | `from ylff.model_loader import ...` | ML model loading utilities |
| `models/api_models.py` | `from ylff.models import ...` | Pydantic API request/response models |
| `services/*.py` | `from ylff.services import ...` | Business logic |
| `utils/*.py` | `from ylff.utils import ...` | Utility functions |
| `routers/*.py` | `from ylff.routers import ...` | API route handlers |
## Common Mistakes to Avoid
### ❌ Mistake 1: Confusing `model_loader` and `models`
```python
# WRONG - This will fail or import wrong thing
from ylff.models import load_da3_model # ❌
# CORRECT
from ylff.model_loader import load_da3_model # ✅
```
### ❌ Mistake 2: Using `importlib.util` workarounds
```python
# WRONG - Complex workaround
import importlib.util
spec = importlib.util.spec_from_file_location(...)
# CORRECT - Direct import
from ylff.model_loader import get_recommended_model # ✅
```
### ❌ Mistake 3: Inconsistent relative imports
```python
# WRONG - Mixing styles
from .models import ... # Sometimes
from ..models import ... # Other times
# CORRECT - Consistent relative imports
from ..model_loader import ... # In submodules
from ylff.model_loader import ... # At package level
```
## Best Practices
1. **Use absolute imports at package level**: `from ylff.services import BAValidator`
2. **Use relative imports in submodules**: `from ..services import BAValidator`
3. **Be explicit about source**: Import from the specific module, not a parent package
4. **Avoid circular imports**: Services shouldn't import from routers, etc.
## Migration Notes
After renaming `models.py` → `model_loader.py`:
- ✅ All imports updated to use `model_loader`
- ✅ No more `importlib.util` workarounds
- ✅ Clear separation: `model_loader` = ML utilities, `models/` = API models
- ✅ Better IDE autocomplete and type checking
|