Tagger/PROJECT.md

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

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