lukas.pupkalipinski/Aniworld
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: remove startup NFO repair, update docs and tests

Browse Source 
- Remove NFO repair scan step from ARCHITECTURE.md startup sequence
- Update CHANGELOG.md: rephrase perform_nfo_repair_scan as scheduled scan
- Add test verifying perform_nfo_repair_scan is NOT called in lifespan
- Keep existing folder scan wiring tests and unit tests intact
- NFO_GUIDE.md already correctly describes scheduled scan behavior
This commit is contained in:
Lukas
2026-05-13 09:23:21 +02:00
parent eb0e6e8ccb
commit 756731cd5d
9 changed files with 1226 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/ARCHITECTURE.md
View File

@@ -294,8 +294,6 @@ The FastAPI lifespan function (`src/server/fastapi_app.py`) runs the following s
+-- Cron-based library rescans configured
+-- Optional: auto-download missing episodes after rescan
+-- Optional: folder maintenance (NFO repair, renaming, poster checks) during scheduled runs
10. NFO repair scan (queue incomplete tvshow.nfo files for background reload)
```
### 12.2 Temp Folder Guarantee

19
docs/CHANGELOG.md
View File

@@ -73,17 +73,16 @@ This changelog follows [Keep a Changelog](https://keepachangelog.com/) principle
that detects incomplete `tvshow.nfo` files and triggers TMDB re-fetch.
Provides `parse_nfo_tags()`, `find_missing_tags()`, `nfo_needs_repair()`, and
`NfoRepairService.repair_series()`. 13 required tags are checked.
- **`perform_nfo_repair_scan()` startup hook
- **`perform_nfo_repair_scan()`
(`src/server/services/initialization_service.py`)**: New async function
called during application startup. Iterates every series directory, checks
whether `tvshow.nfo` is missing required tags using `nfo_needs_repair()`, and
either queues the series for background reload (when a `background_loader` is
provided) or calls `NfoRepairService.repair_series()` directly. Skips
gracefully when `tmdb_api_key` or `anime_directory` is not configured.
- **NFO repair wired into startup lifespan (`src/server/fastapi_app.py`)**:
`perform_nfo_repair_scan(background_loader)` is called at the end of the
FastAPI lifespan startup, after `perform_media_scan_if_needed`, ensuring
every existing series NFO is checked and repaired on each server start.
that iterates every series directory, checks whether `tvshow.nfo` is missing
required tags using `nfo_needs_repair()`, and queues the series for background
reload via `asyncio.create_task`. Skips gracefully when `tmdb_api_key` or
`anime_directory` is not configured.
- **NFO repair wired into scheduled folder scan (`src/server/services/folder_scan_service.py`)**:
`perform_nfo_repair_scan(background_loader=None)` is called during the
scheduled daily folder scan, keeping startup fast while ensuring regular
maintenance.
### Changed

3
docs/CONFIGURATION.md
View File

@@ -174,7 +174,7 @@ Controls automatic cron-based library rescanning (powered by APScheduler).
| `scheduler.schedule_time` | string | `"03:00"` | Daily run time in 24-h `HH:MM` format. |
| `scheduler.schedule_days` | list[string] | `["mon","tue","wed","thu","fri","sat","sun"]` | Days of the week to run the scan. Empty list disables the cron job. |
| `scheduler.auto_download_after_rescan` | bool | `false` | Automatically queue missing episodes for download after each rescan. |
| `scheduler.folder_scan_enabled` | bool | `false` | Run folder maintenance (NFO repair, folder renaming, poster checks) during scheduled runs. |
| `scheduler.folder_scan_enabled` | bool | `false` | Run folder maintenance (NFO repair, folder renaming, poster checks) during scheduled runs. **When enabled, series folders are automatically renamed to match the `<title> (<year>)` convention derived from their `tvshow.nfo` files.** |
Valid day abbreviations: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`.
@@ -218,6 +218,7 @@ Source: [src/server/models/config.py](../src/server/models/config.py#L15-L24)
- Obtain a TMDB API key from https://www.themoviedb.org/settings/api
- `auto_create` creates NFO files during the download process
- `update_on_scan` refreshes metadata when scanning existing anime
- `download_poster` also controls whether the scheduled folder scan checks for and re-downloads missing or corrupted `poster.jpg` files (see [NFO_GUIDE.md](NFO_GUIDE.md#6-poster-check))
- Image downloads require valid `tmdb_api_key`
- `TMDB_API_KEY` environment variable is optional when `nfo.tmdb_api_key` is configured in `data/config.json`
- Larger image sizes (`w780`, `original`) consume more storage space

79
docs/NFO_GUIDE.md
View File

@@ -246,7 +246,84 @@ NFO files are created in the anime directory:
---
## 5. API Reference
## 5. Folder Naming Convention
### 5.1 Expected Format
After the daily folder scan (when **Update on library scan** is enabled), Aniworld validates every series folder against its `tvshow.nfo` metadata. If the folder name does not match the expected convention, it is automatically renamed.
**Format:**
```
{title} ({year})
```
**Examples:**
| NFO `<title>` | NFO `<year>` | Expected Folder Name |
|---------------|--------------|----------------------|
| `Attack on Titan` | `2013` | `Attack on Titan (2013)` |
| `One Piece` | `1999` | `One Piece (1999)` |
| `Demon Slayer: Kimetsu no Yaiba` | `2019` | `Demon Slayer Kimetsu no Yaiba (2019)` |
### 5.2 Sanitization Rules
Illegal filesystem characters are removed or replaced to ensure cross-platform compatibility:
- Removed: `< > : " / \ | ? *` and null bytes
- Control characters stripped
- Multiple spaces collapsed to one
- Leading/trailing dots and whitespace trimmed
- Maximum length: 200 characters (truncated at word boundary if possible)
### 5.3 Skip Conditions
A folder is **not** renamed when any of the following apply:
- `tvshow.nfo` is missing `<title>` or `<year>` (or they are empty)
- The series has an **active or pending download**
- The target folder name already exists (duplicate)
- The resulting path would exceed the OS path-length limit
- The app lacks write permission to the anime directory
All skipped and renamed actions are logged.
---
## 6. Poster Check
### 6.1 Overview
During the daily folder scan, Aniworld checks every series folder for a valid `poster.jpg`. If the file is missing or smaller than 1 KB, the application attempts to re-download it from the URL stored in the series' `tvshow.nfo` file.
### 6.2 How It Works
1. **Scan** — After folder renaming, the scan iterates over all series folders that contain a `tvshow.nfo`.
2. **Validate** — For each folder, it checks whether `poster.jpg` exists and is at least 1 KB.
3. **Parse NFO** — If the poster is missing or too small, the scan reads `tvshow.nfo` and looks for a `<thumb aspect="poster">` (or any `<thumb>`) URL.
4. **Download** — If a URL is found, the poster is downloaded using `ImageDownloader` with a concurrency limit of 3 simultaneous downloads.
5. **Validate Download** — The downloaded image is validated with PIL to ensure it is not corrupted.
### 6.3 Skip Conditions
A folder is **not** processed for poster download when any of the following apply:
- `tvshow.nfo` does not exist in the folder.
- `poster.jpg` already exists and is ≥ 1 KB.
- No `<thumb>` URL is found in the NFO (the NFO may have been created before thumb tags were added).
- The `nfo.download_poster` setting is `false` (poster checks are still performed, but downloads are skipped if the setting is disabled; see [CONFIGURATION.md](CONFIGURATION.md)).
### 6.4 Logging
Every poster check action is logged:
- **INFO** — When a poster is successfully downloaded.
- **WARNING** — When a download fails or no URL is found.
- **ERROR** — When an unexpected exception occurs during download.
---
## 7. API Reference
### 5.1 Check NFO Status