102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
|
# Tagger - Project Documentation
|
||
|
|
|
||
|
|
**Version:** 1.1.0 | **Status:** Stable | **GUI:** PySide6/Qt6
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## About
|
||
|
|
|
||
|
|
Desktop app for organizing files using hierarchical tags (category/name).
|
||
|
|
|
||
|
|
**Features:** Folder scanning, tag filtering, rename/merge tags, CSFD.cz integration, hardlink structure, 3-level config (global/folder/file).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
Tagger/
|
||
|
|
├── Tagger.py # Entry point
|
||
|
|
├── src/core/ # Business logic (NO UI imports!)
|
||
|
|
│ ├── tag.py # Tag value object (immutable)
|
||
|
|
│ ├── tag_manager.py # Tag/category management
|
||
|
|
│ ├── file.py # File with metadata
|
||
|
|
│ ├── file_manager.py # File management, filtering
|
||
|
|
│ ├── config.py # 3-level config system
|
||
|
|
│ ├── hardlink_manager.py
|
||
|
|
│ ├── csfd.py # CSFD scraper
|
||
|
|
│ ├── constants.py # APP_NAME, VERSION
|
||
|
|
│ └── _version.py # Version fallback for PyInstaller
|
||
|
|
├── src/ui/
|
||
|
|
│ ├── gui.py # Qt6 GUI (MainWindow)
|
||
|
|
│ └── utils.py # load_icon()
|
||
|
|
└── tests/ # 274 tests
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Architecture Rules
|
||
|
|
|
||
|
|
1. **UI must not contain business logic** - call FileManager/TagManager
|
||
|
|
2. **Core must not import UI** - no PySide6/tkinter in src/core/
|
||
|
|
3. **Dependency injection** - pass via constructor
|
||
|
|
4. **UTF-8 everywhere** - `encoding='utf-8'`, `ensure_ascii=False`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Config Files
|
||
|
|
|
||
|
|
| Level | File | Contents |
|
||
|
|
|-------|------|----------|
|
||
|
|
| Global | `.Tagger.!gtag` | window geometry, last folder |
|
||
|
|
| Folder | `.Tagger.!ftag` | ignore patterns, hardlink settings |
|
||
|
|
| File | `.filename.!tag` | tags, date, state |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Key Components
|
||
|
|
|
||
|
|
**Tag** - immutable, `Tag(category, name)`, `Tag.from_string("cat/name")`
|
||
|
|
|
||
|
|
**File** - `file_path`, `tags[]`, `date`, `csfd_url`, metadata in `.filename.!tag`
|
||
|
|
|
||
|
|
**TagManager** - `add_tag()`, `get_categories()`, `rename_tag()`, `merge_tag()`
|
||
|
|
|
||
|
|
**FileManager** - `append(folder)`, `filter_files_by_tags()`, `close_folder()`
|
||
|
|
|
||
|
|
**HardlinkManager** - `create_structure_for_files()`, `sync_structure()`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Running
|
||
|
|
|
||
|
|
```bash
|
||
|
|
poetry run python Tagger.py # GUI
|
||
|
|
poetry run pytest -q # Tests
|
||
|
|
poetry run pyinstaller --onefile Tagger.py # Build
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Shortcuts
|
||
|
|
|
||
|
|
`Ctrl+O` Open | `Ctrl+T` Tags | `Ctrl+D` Date | `F5` Refresh | `Del` Remove
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Debugging
|
||
|
|
|
||
|
|
**Version 0.0.0 in build:** Run app once from source to update `_version.py`, then rebuild.
|
||
|
|
|
||
|
|
**Cannot import:** Use `poetry run python Tagger.py`
|
||
|
|
|
||
|
|
**Metadata corrupted:** Auto-recovers with defaults.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Metrics
|
||
|
|
|
||
|
|
- **Tests:** 274 ✅
|
||
|
|
- **Python:** 3.13+
|
||
|
|
- **Dependencies:** PySide6, Pillow, requests, beautifulsoup4
|