mirror of
https://git.srhtnin.garden/sarah/SaraTag.git
synced 2026-10-13 18:28:16 +02:00
77 lines
4.5 KiB
Markdown
77 lines
4.5 KiB
Markdown
# SaraTag
|
|
|
|
Tag your files without touching them, built with Flet. Every file gets a **Book**, a hidden sidecar
|
|
(`.<file name>.book.toml`) with its tag values. The tags themselves are defined in **Lexicons**:
|
|
which tags exist, their type (Text, Number, Rating, List, Boolean), defaults and limits.
|
|
|
|
A **Record** is a directory you register with SaraTag, with its Lexicon. Subdirectories can get their own
|
|
Lexicon, which inherits from the one above it. A **Library** groups Records so they can be browsed as one list.
|
|
|
|
SaraFem and SaraView read Books through `.saratag/Core.py`, so that file stays where it is, stdlib-only,
|
|
with its function names unchanged.
|
|
|
|
## Pages
|
|
|
|
- **Browse**: Records and Libraries on the left, files in the middle, the preview and tags on the right.
|
|
The filter takes conditions like `*beach* ext:png Rating:>=2 size:>5MB modified:>=2026-07-01` (hover the `?`
|
|
for all of them). Sorting chains criteria (Name, dates, size, type, Record, any tag) in the order you click them.
|
|
Tick files to edit their shared tags at once; mixed values show as mixed until set. Click an image preview
|
|
for a fullscreen view (Left/Right step through). Videos open in `[Media] VideoPlayer`.
|
|
**Right-click** a file (Open, View Fullscreen, Rename (the Book follows), Create Its Book, Edit Its Lexicon,
|
|
Copy Path), a directory (Open, Add a Lexicon / Edit Its Lexicon) or the background (Tick All, Create Books
|
|
for Ticked Files, ...).
|
|
Keys: Up/Down, Enter opens, Space ticks, F2 renames, Ctrl+A ticks all, Backspace goes up, Escape.
|
|
- **Records**: add, rename (the name or the directory on disk), enable/disable, change the Lexicon, unregister.
|
|
Below, the subdirectory tree: purple has a Lexicon everywhere, yellow partly, grey not at all. Add or remove a
|
|
subdirectory's Lexicon, or tag a whole subtree from its right-click menu.
|
|
- **Libraries**: make, edit and delete Libraries, with each Record's size.
|
|
- **Lexicons**: every Lexicon in `Lexicons/` and inside Record directories. Set Inherit/Source, add, rename,
|
|
delete, reorder and retype tags, edit their properties and List values. Inherited tags are shown as Inherited,
|
|
Overridden (only the changed properties are written, Revert drops them) or Excluded.
|
|
- **Update**: bring Books in line with their Lexicons, for every Record or one: add missing Books and tags,
|
|
clean unused tags, reset to defaults, regenerate, or repair Parent links. Preview only runs it without writing.
|
|
|
|
The gear opens **Settings**, laid out like SaraFem's, SaraSuite's and SaraSort's: the shared SaraSuite
|
|
appearance and export/import, SaraTag's own settings, and `SaraTagConf.toml`'s Browse, Lexicon and History options.
|
|
|
|
## Where things live
|
|
|
|
| Path | What |
|
|
| --- | --- |
|
|
| `~/.config/SaraSuite/Config.toml` | shared SaraSuite settings (theme, font, title bar) |
|
|
| `~/.config/SaraSuite/SaraTag/Config.toml` | SaraTag's own GUI settings |
|
|
| `SaraTagConf.toml` | SaraTag's data settings |
|
|
| `.SaraTagRecords.toml` | Records and Libraries |
|
|
| `.SaraTagHistory.toml` | where each Record/Library was left, recent files, updater runs |
|
|
| `Lexicons/` | Lexicons |
|
|
|
|
The last four live in SaraTag's data folder, which `.saratag/Core.py` picks in this order:
|
|
`$SARATAG_DATA_DIR`; `DataDir` in `.saratag/Location.toml` (installed by SaraSuite, pointing at
|
|
`~/.config/SaraSuite/SaraTag/`); otherwise the program folder itself, so a plain copy stays portable.
|
|
Missing files are created on start. None of them are in git.
|
|
|
|
## Running
|
|
|
|
- SaraSuite: install SaraTag from it. `Packaging/SaraSuite/` is the manifest (`Manifest.toml` + `Templates/`),
|
|
kept in sync with SaraSuite's `Programs/SaraTag/`.
|
|
- From source: `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`, then `Packaging/Launch.sh`
|
|
(or `.venv/bin/python Main.py`; `SaraTag.py` still works too).
|
|
|
|
## Files
|
|
|
|
| File | What |
|
|
| --- | --- |
|
|
| `Main.py` | window, navigation |
|
|
| `Core.py` | palette/theme, SaraTag's GUI settings, export/import (same as the other SaraSuite programs) |
|
|
| `Library.py` | loads `.saratag/Core.py`; TOML and SaraTagConf.toml helpers |
|
|
| `Books.py` | reading, writing and validating Books; renaming files with their Book |
|
|
| `Records.py` | Records, Libraries and directory Lexicons |
|
|
| `Lexicons.py` | editing a Lexicon (inheritance, overrides, types) |
|
|
| `Updater.py` | the Update page's modes |
|
|
| `Query.py` | Browse's filter and sort |
|
|
| `History.py` | `.SaraTagHistory.toml` |
|
|
| `TagEditor.py` | the tag panel |
|
|
| `Widgets.py` | the shared App context, right-click menus, small controls |
|
|
| `Settings.py` | the Settings dialog |
|
|
| `*Page.py` | one per page |
|