# 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 |