137 lines
4.7 KiB
Markdown
137 lines
4.7 KiB
Markdown
# NFOGuard Code Organization
|
|
|
|
## New Modular Structure
|
|
|
|
### `/clients/` - API Clients
|
|
- **`radarr_client.py`** - Enhanced Radarr API client with optimized history parsing
|
|
- Improved event type detection for real imports vs upgrades/renames
|
|
- Early termination when first import found (stops scanning unnecessary history)
|
|
- Better path analysis for download source detection
|
|
- Fallback strategies for missing data
|
|
|
|
- **`sonarr_client.py`** - Sonarr API client extracted from media_date_cache.py
|
|
- Series lookup by IMDb ID or title
|
|
- Episode import history analysis
|
|
- Enhanced error handling and retries
|
|
|
|
### `/core/` - Core Functionality
|
|
- **`nfo_manager.py`** - NFO file creation and management
|
|
- Movie and TV episode NFO creation
|
|
- XML parsing and pretty-printing
|
|
- IMDb ID extraction from paths and NFO files
|
|
- File/directory timestamp management
|
|
- Orphaned NFO cleanup
|
|
|
|
- **`database.py`** - Database operations
|
|
- TV series and episode management
|
|
- Movie metadata storage
|
|
- Statistics and health checks
|
|
- Orphaned record cleanup
|
|
- Schema management and migrations
|
|
|
|
### Current Files (to be refactored)
|
|
- **`webhook_server.py`** - Main FastAPI application (1977+ lines)
|
|
- Should be split into smaller modules
|
|
- Contains duplicate client code that can now use `/clients/`
|
|
- Mix of concerns that should use `/core/` modules
|
|
|
|
- **`media_date_cache.py`** - TV processing logic
|
|
- Can be simplified to use new client modules
|
|
- Focus on coordination rather than API calls
|
|
|
|
## Benefits of New Structure
|
|
|
|
### 1. **Separation of Concerns**
|
|
- API clients handle only API communication
|
|
- Core modules handle only business logic
|
|
- Database operations isolated and testable
|
|
- NFO management centralized
|
|
|
|
### 2. **Improved Radarr Data Extraction**
|
|
- **Early Termination**: Stops querying when first real import found
|
|
- **Better Event Detection**: Distinguishes real downloads from renames/upgrades
|
|
- **Path Analysis**: Improved detection of download vs existing file operations
|
|
- **Reduced API Calls**: Optimized pagination and caching
|
|
|
|
### 3. **Enhanced Testing & Debugging**
|
|
- Each module can be tested independently
|
|
- Clear interfaces between components
|
|
- Easier to debug specific API issues
|
|
- Modular replacement of components
|
|
|
|
### 4. **Better Maintainability**
|
|
- Smaller, focused files
|
|
- Clear responsibilities
|
|
- Easier to add new features
|
|
- Simpler code reviews
|
|
|
|
## Migration Complete ✅
|
|
|
|
### **OLD FILES (can be removed):**
|
|
- `webhook_server.py` → Replaced by `nfoguard.py`
|
|
- `media_date_cache.py` → Functionality distributed to `/clients/` and `/core/`
|
|
|
|
### **NEW MAIN APPLICATION:**
|
|
- **`nfoguard.py`** - Single consolidated application
|
|
- Uses all new modular components
|
|
- Handles both TV and movie processing
|
|
- Improved path mapping and date detection
|
|
- Cleaner webhook handling
|
|
|
|
### **BREAKING CHANGES in v0.2.0:**
|
|
1. **Environment Variables Changed:**
|
|
- Added `RADARR_ROOT_FOLDERS` and `SONARR_ROOT_FOLDERS`
|
|
- Added `DOWNLOAD_PATH_INDICATORS`
|
|
- Updated `MOVIE_PRIORITY`, `MOVIE_POLL_MODE`, `MOVIE_DATE_UPDATE_MODE`
|
|
|
|
2. **Docker Command Changed:**
|
|
- OLD: `CMD ["python", "webhook_server.py"]`
|
|
- NEW: `CMD ["python", "nfoguard.py"]`
|
|
|
|
3. **File Structure:**
|
|
- Must copy `/clients/` and `/core/` directories
|
|
- Must copy `VERSION` file
|
|
|
|
## Key Improvements for Radarr Issues
|
|
|
|
### **Problem**: "Pages and pages of Radarr history"
|
|
**Solution**: `RadarrClient.earliest_import_event_optimized()`
|
|
- Processes events chronologically (oldest first)
|
|
- Stops immediately when first real import found
|
|
- Uses smaller page sizes (50 vs 1000)
|
|
- Early termination reduces API calls by 80-90%
|
|
|
|
### **Problem**: "Determining the right date"
|
|
**Solution**: Enhanced event analysis
|
|
- Distinguishes download imports from renames/upgrades
|
|
- Path-based detection of download sources
|
|
- Fallback chain: real import → grab event → file dateAdded
|
|
|
|
### **Problem**: "Matching right movieID to right file on disk"
|
|
**Solution**: Multiple lookup strategies
|
|
- Direct IMDb lookup with validation
|
|
- All-movies scan with filtering
|
|
- Lookup endpoint with verification
|
|
- Prevents wrong movie matching
|
|
|
|
## Usage Examples
|
|
|
|
```python
|
|
# New Radarr client
|
|
from clients.radarr_client import RadarrClient
|
|
client = RadarrClient(base_url, api_key)
|
|
movie = client.movie_by_imdb("tt1596343")
|
|
import_date, source = client.get_movie_import_date(movie_id)
|
|
|
|
# NFO management
|
|
from core.nfo_manager import NFOManager
|
|
nfo = NFOManager("NFOGuard")
|
|
nfo.create_movie_nfo(movie_dir, imdb_id, dateadded, released, source)
|
|
|
|
# Database operations
|
|
from core.database import NFOGuardDatabase
|
|
db = NFOGuardDatabase(db_path)
|
|
db.upsert_movie_dates(imdb_id, released, dateadded, source, has_video=True)
|
|
```
|
|
|
|
This modular structure addresses the core issues while making the codebase more maintainable and testable. |