python-musefs 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

musefs_common/__init__.py

@@ -11,19 +11,24 @@ from .errors import ScanError, SchemaMismatch
 from .paths import realpath_key
 from .scan import run_scan
 from .store import (
+    TagRow,
     check_schema_version,
     connect,
+    delete_tracks,
     merge_tags,
     prune_missing,
     replace_tags,
     replace_track_art,
     sniff_mime,
+    tags_for_track,
     track_id_for_path,
+    track_ids_by_tag,
+    track_ids_for_paths,
     upsert_art,
 )
 from .sync import ArtImage, Record, SyncStats, sync_files, sync_one
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "EXPECTED_USER_VERSION",
@@ -36,6 +41,11 @@ __all__ = [
     "connect",
     "check_schema_version",
     "track_id_for_path",
+    "track_ids_for_paths",
+    "track_ids_by_tag",
+    "tags_for_track",
+    "TagRow",
+    "delete_tracks",
     "prune_missing",
     "merge_tags",
     "replace_tags",

musefs_common/scan.py

@@ -4,19 +4,23 @@ import subprocess
 from .errors import ScanError
 
 
-def run_scan(binary, db_path, target, *, timeout=None):
-    """Run ``<binary> scan <target...> --db <db_path>``. ``target`` is a single
-    path or an iterable of paths; all targets precede the ``--db`` flag and are
-    scanned under one process (one DB open). Creates the DB if absent and fills
-    the structural columns a plugin can't compute. Raises ``ScanError`` (with
-    ``kind`` in ``"not_found" | "timeout" | "failed"``) on failure; the caller
-    formats its own user-facing message from the exception attributes."""
+def run_scan(binary, db_path, target, *, revalidate=False, timeout=None):
+    """Run ``<binary> scan <target...> --db <db_path> [--revalidate]``. ``target``
+    is a single path or an iterable of paths; all targets precede the ``--db``
+    flag and are scanned under one process (one DB open). Creates the DB if
+    absent and fills the structural columns a plugin can't compute. With
+    ``revalidate``, the scanner re-checks stamps, prunes rows whose backing file
+    is gone, and GCs orphaned art. Raises ``ScanError`` (with ``kind`` in
+    ``"not_found" | "timeout" | "failed"``) on failure; the caller formats its
+    own user-facing message from the exception attributes."""
     if isinstance(target, (str, os.PathLike)):
         targets = [target]
     else:
         targets = list(target)
     display = str(targets[0]) if len(targets) == 1 else f"{len(targets)} target(s)"
     argv = [binary, "scan", *(str(t) for t in targets), "--db", str(db_path)]
+    if revalidate:
+        argv.append("--revalidate")
     try:
         result = subprocess.run(argv, capture_output=True, timeout=timeout)
     except FileNotFoundError as exc:

musefs_common/schema.py

@@ -200,6 +200,71 @@ CREATE TRIGGER structural_blocks_ad AFTER DELETE ON structural_blocks BEGIN
     UPDATE tracks SET content_version = content_version + 1 WHERE id = OLD.track_id;
 END;
 PRAGMA user_version = 1;
+
+-- ── MIGRATION_V2 ──
+-- fingerprint/content_hash are scanner-owned content identities. Neither is
+-- UNIQUE and the index is NON-unique BY DESIGN: duplicate-content tracks (same
+-- album in two places, genuine dupes) legitimately share both values, and a
+-- UNIQUE constraint would abort the scan batch on the second copy. Correctness
+-- comes from the refind logic (unique-missing candidate + confirmation), not
+-- from DB uniqueness. Both columns carry a length(x) = 64 CHECK locking them
+-- to SHA-256 hex (Task E2 benchmark locked the hash to SHA-256: under a
+-- realistic SSD/HDD I/O profile the fingerprint adds ~8.6%; the RAM
+-- microbench's higher ratio is an I/O-elimination artifact — see
+-- the benchmarks docs). Hash function is now fixed, so the CHECK is added here.
+ALTER TABLE tracks ADD COLUMN fingerprint  TEXT
+    CHECK (fingerprint IS NULL OR length(fingerprint) = 64);
+ALTER TABLE tracks ADD COLUMN content_hash TEXT
+    CHECK (content_hash IS NULL OR length(content_hash) = 64);
+CREATE INDEX tracks_fingerprint_idx ON tracks(fingerprint);
+
+-- Rebuild `tags` with a byte-accurate value cap (#505). SQLite's length() on
+-- TEXT counts characters, so the V1 `CHECK (length(value) <= 262144)` was up to
+-- ~4x looser than the documented 256 KiB byte bound; length(CAST(value AS BLOB))
+-- counts bytes. SQLite cannot alter a CHECK in place, so recreate the table
+-- (V2 is unreleased — this is folded in rather than added as a new migration).
+-- Pre-existing over-cap rows (only reachable on an upgraded store) are dropped:
+-- the read-time guard already counts bytes, so they were unreadable anyway, and
+-- carrying them would abort the rebuild on the new CHECK.
+CREATE TABLE tags_new (
+    track_id   INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
+    key        TEXT NOT NULL,
+    value      TEXT NOT NULL,
+    ordinal    INTEGER NOT NULL DEFAULT 0,
+    value_blob BLOB,
+    PRIMARY KEY (track_id, key, ordinal),
+    CHECK (ordinal >= 0),
+    CHECK (value_blob IS NULL OR value = ''),
+    CHECK (length(key) <= 256),
+    CHECK (length(key) >= 1
+           AND key NOT GLOB '*[' || char(1) || '-' || char(31) || ']*'),
+    CHECK (length(CAST(value AS BLOB)) <= 262144),
+    CHECK (value_blob IS NULL OR length(value_blob) <= 16711680)
+);
+INSERT INTO tags_new (track_id, key, value, ordinal, value_blob)
+    SELECT track_id, key, value, ordinal, value_blob FROM tags
+    WHERE length(CAST(value AS BLOB)) <= 262144;
+DROP TABLE tags;
+ALTER TABLE tags_new RENAME TO tags;
+
+-- DROP TABLE tags dropped its INSERT/UPDATE/DELETE triggers; recreate them
+-- verbatim so the content_version/updated_at bump contract is unchanged.
+CREATE TRIGGER tags_ai AFTER INSERT ON tags BEGIN
+    UPDATE tracks SET content_version = content_version + 1,
+                      updated_at = CAST(strftime('%s','now') AS INTEGER)
+    WHERE id = NEW.track_id;
+END;
+CREATE TRIGGER tags_au AFTER UPDATE ON tags BEGIN
+    UPDATE tracks SET content_version = content_version + 1,
+                      updated_at = CAST(strftime('%s','now') AS INTEGER)
+    WHERE id = NEW.track_id;
+END;
+CREATE TRIGGER tags_ad AFTER DELETE ON tags BEGIN
+    UPDATE tracks SET content_version = content_version + 1,
+                      updated_at = CAST(strftime('%s','now') AS INTEGER)
+    WHERE id = OLD.track_id;
+END;
+PRAGMA user_version = 2;
 """
 
-USER_VERSION = 1
+USER_VERSION = 2

musefs_common/store.py

@@ -2,10 +2,27 @@ import contextlib
 import hashlib
 import os
 import sqlite3
+from dataclasses import dataclass
 
 from .constants import EXPECTED_USER_VERSION
 from .errors import SchemaMismatch
 
+# SQLite caps a statement's host parameters (SQLITE_MAX_VARIABLE_NUMBER: 999 on
+# the <3.32 floor). Chunk bulk IN-lists below it so large lookups never trip it.
+_MAX_SQL_VARS = 900
+
+
+@dataclass(frozen=True)
+class TagRow:
+    """One tag row read back from the store: the key, the text value, and the
+    raw ``value_blob``. Plugin-owned text tags have ``value_blob is None``;
+    scanner-written binary tags have ``value == ""`` and ``value_blob`` bytes."""
+
+    key: str
+    value: str
+    value_blob: object = None  # bytes | None
+
+
 # sqlite3.LEGACY_TRANSACTION_CONTROL is 3.12+; it is == -1. Use getattr so this
 # module still imports on the 3.8 floor (where the constant does not exist).
 _LEGACY = getattr(sqlite3, "LEGACY_TRANSACTION_CONTROL", -1)
@@ -88,6 +105,77 @@ def track_id_for_path(conn, key):
     return row[0] if row else None
 
 
+def track_ids_for_paths(conn, keys):
+    """Resolve many ``backing_path`` keys to track ids in one pass, returning a
+    ``{key: id}`` dict that omits keys with no matching track row. The IN-list is
+    chunked under SQLite's host-parameter cap so arbitrarily large lookups work
+    (the bulk counterpart to ``track_id_for_path``)."""
+    # Deduplicate while preserving first-seen order: a key repeated across chunk
+    # boundaries would re-fetch its row in a later chunk and trip the duplicate
+    # guard below even on a conformant DB.
+    keys = list(dict.fromkeys(keys))
+    out = {}
+    for start in range(0, len(keys), _MAX_SQL_VARS):
+        chunk = keys[start : start + _MAX_SQL_VARS]
+        placeholders = ",".join("?" for _ in chunk)
+        rows = conn.execute(
+            f"SELECT backing_path, id FROM tracks WHERE backing_path IN ({placeholders})",
+            chunk,
+        )
+        for backing_path, track_id in rows:
+            if backing_path in out:
+                # backing_path is UNIQUE in the schema, so a duplicate means a
+                # non-conformant DB; collapsing it would silently hide a track
+                # from prune (#478). Fail loudly instead.
+                raise ValueError(
+                    f"duplicate backing_path {backing_path!r} in tracks "
+                    f"(ids {out[backing_path]} and {track_id})"
+                )
+            out[backing_path] = track_id
+    return out
+
+
+def track_ids_by_tag(conn, key, value):
+    """Return a list of track ids whose plugin-owned text tag ``(key, value)``
+    matches (order unspecified, possibly empty).
+
+    Scoped to text rows (``value_blob IS NULL``); scanner-written binary tags
+    never match. The intent-based counterpart to ``prune_missing``'s
+    existence-based scoping: used to map a source's "I deleted this album/artist"
+    signal back to the rows it tagged.
+    """
+    rows = conn.execute(
+        "SELECT track_id FROM tags WHERE key = ? AND value = ? AND value_blob IS NULL",
+        (key, value),
+    )
+    return [track_id for (track_id,) in rows]
+
+
+def delete_tracks(conn, track_ids):
+    """Unconditionally delete the given track rows; return the count actually
+    deleted (an already-gone id contributes 0).
+
+    The intent-based delete: unlike ``prune_missing`` it does not check on-disk
+    existence. ``tags`` and ``track_art`` rows cascade away via the schema's
+    ``ON DELETE CASCADE`` (``connect`` enables ``foreign_keys = ON``).
+    """
+    deleted = 0
+    for track_id in track_ids:
+        deleted += conn.execute("DELETE FROM tracks WHERE id = ?", (track_id,)).rowcount
+    return deleted
+
+
+def tags_for_track(conn, track_id):
+    """Read back a track's tag rows as an ordered ``list[TagRow]`` (by key, then
+    ordinal). Includes both plugin-owned text tags (``value_blob is None``) and
+    scanner-written binary tags (``value == ""``, ``value_blob`` bytes)."""
+    rows = conn.execute(
+        "SELECT key, value, value_blob FROM tags WHERE track_id = ? ORDER BY key, ordinal",
+        (track_id,),
+    )
+    return [TagRow(key, value, value_blob) for key, value, value_blob in rows]
+
+
 def prune_missing(conn, track_ids=None):
     """Delete track rows whose backing file no longer exists on disk.
 
@@ -150,9 +238,14 @@ def merge_tags(conn, track_id, managed_pairs, delete_keys):
         for key, value in managed_pairs:
             by_key.setdefault(key, []).append(value)
 
+        # Case-fold the key match: a scan seeds an unmapped tag in the file's
+        # native case (e.g. Vorbis ``LABEL``) while the plugin canonicalises to
+        # lowercase (``label``). Vorbis keys render case-insensitively, so an
+        # exact-case delete would leave the scan row and render a duplicate (#407).
         for key in set(by_key) | set(delete_keys or ()):
             conn.execute(
-                "DELETE FROM tags WHERE track_id = ? AND key = ? AND value_blob IS NULL",
+                "DELETE FROM tags WHERE track_id = ? AND lower(key) = lower(?) "
+                "AND value_blob IS NULL",
                 (track_id, key),
             )
 

musefs_common/sync.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import sqlite3
 from dataclasses import dataclass, field
 
 from .constants import MAX_ART_BYTES
@@ -42,11 +43,14 @@ class SyncStats:
     skipped: int = 0  # path had no matching track row
     art_linked: int = 0
     skipped_art: int = 0  # art over the size cap (or, in the beets adapter, unreadable)
+    skipped_invalid: int = 0  # record violated a store CHECK constraint
+    invalid: list = field(default_factory=list)  # (record key, sqlite error message)
 
     def summary(self):
         return (
             f"synced={self.synced} skipped={self.skipped} "
-            f"art_linked={self.art_linked} skipped_art={self.skipped_art}"
+            f"art_linked={self.art_linked} skipped_art={self.skipped_art} "
+            f"skipped_invalid={self.skipped_invalid}"
         )
 
 
@@ -58,7 +62,13 @@ def sync_one(conn, record, stats, *, dry_run=False, merge=False):
     scanner-written binary tags survive. Art is replaced when at least one image is
     within ``MAX_ART_BYTES``; each over-cap image bumps ``skipped_art``, and if
     every provided image is over cap any scan-seeded ``track_art`` is left
-    untouched."""
+    untouched.
+
+    A record whose tags or art violate a store CHECK constraint (key/value/mime
+    length, ``picture_type`` range, control chars, ...) is rolled back through its
+    own savepoint and skipped -- it bumps ``skipped_invalid`` and appends
+    ``(record.key, message)`` to ``invalid`` rather than aborting the whole batch
+    with an opaque commit-time ``IntegrityError`` (#420)."""
     track_id = track_id_for_path(conn, record.key)
     if track_id is None:
         stats.skipped += 1
@@ -73,17 +83,22 @@ def sync_one(conn, record, stats, *, dry_run=False, merge=False):
     will_link_art = bool(kept)
 
     if not dry_run:
-        with _savepoint(conn, "musefs_sync_one"):
-            if merge:
-                merge_tags(conn, track_id, record.pairs, record.delete_keys or [])
-            else:
-                replace_tags(conn, track_id, record.pairs)
-            if will_link_art:
-                arts = [
-                    (upsert_art(conn, img.data, img.mime), img.picture_type, img.description)
-                    for img in kept
-                ]
-                replace_track_art(conn, track_id, arts)
+        try:
+            with _savepoint(conn, "musefs_sync_one"):
+                if merge:
+                    merge_tags(conn, track_id, record.pairs, record.delete_keys or [])
+                else:
+                    replace_tags(conn, track_id, record.pairs)
+                if will_link_art:
+                    arts = [
+                        (upsert_art(conn, img.data, img.mime), img.picture_type, img.description)
+                        for img in kept
+                    ]
+                    replace_track_art(conn, track_id, arts)
+        except sqlite3.IntegrityError as err:
+            stats.skipped_invalid += 1
+            stats.invalid.append((record.key, str(err)))
+            return
 
     if will_link_art:
         stats.art_linked += 1

python_musefs-1.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: python-musefs
+Version: 1.1.0
+Summary: Shared musefs SQLite-store contract for the beets and Picard plugins
+Author: Conor Futro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sohex/musefs
+Project-URL: Repository, https://github.com/Sohex/musefs
+Project-URL: Issues, https://github.com/Sohex/musefs/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# python-musefs
+
+The full guide now lives in the musefs documentation site:
+
+- **Published:** <https://sohex.github.io/musefs/integrations/python-musefs.html>
+- **In-repo source:** [`docs/src/integrations/python-musefs.md`](../../docs/src/integrations/python-musefs.md)

python_musefs-1.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+musefs_common/__init__.py,sha256=fA6mE93fSYBjObMMeCjDKnOnmETrbc2xt1TrdMKJ5cE,1505
+musefs_common/constants.py,sha256=M0zS6YCnYdE_JjIbvxg-GhbYdfbe30ccKZvbZ1WTZZ8,302
+musefs_common/contract.py,sha256=tUflCxfFiaIzJiTqYL-o-bjKNH_s91EHkC2amk8sKxE,1472
+musefs_common/errors.py,sha256=OUBXzpa4q7TPYvFFiTyoIfRC3SGRRgZcpXlr43RP0jk,1456
+musefs_common/paths.py,sha256=dE3wwop5mRxoJ8RhdYwTIZpX4MPaUUw2LJhjcxApOIA,649
+musefs_common/scan.py,sha256=C20WmDWhGJ3FqjNOssLsoxtx0KgsTg9PPlrGPhOkE2E,1662
+musefs_common/schema.py,sha256=HFo2qG0xtTgBVgxm8hCjVQAjxTeCqaPvYklw08rhOoU,11853
+musefs_common/store.py,sha256=pUNlad1FITJCKwBNy4EH98jQQTmb9Ao5ggLlgo99XwU,12769
+musefs_common/sync.py,sha256=iXlekqpuRfBEoOrjvujnZQYfDgs3afENaPU0n3D59nQ,4200
+python_musefs-1.1.0.dist-info/licenses/LICENSE,sha256=4VbfzhgMpuFrhFjBCtLptGV_bzCj_gML9y_9o2Tr1OQ,1068
+python_musefs-1.1.0.dist-info/METADATA,sha256=R3v-Qu_1-kc0JKc_xPlgIcZPhNuzcjIo6rvuZ8gAjT8,1012
+python_musefs-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_musefs-1.1.0.dist-info/top_level.txt,sha256=ejWexGk95-s11kZnTFwg1T3iG_dFcaE4vhcLnL3t3Ak,14
+python_musefs-1.1.0.dist-info/RECORD,,

python_musefs-1.0.0.dist-info/METADATA

@@ -1,274 +0,0 @@
-Metadata-Version: 2.4
-Name: python-musefs
-Version: 1.0.0
-Summary: Shared musefs SQLite-store contract for the beets and Picard plugins
-Author: Conor Futro
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/Sohex/musefs
-Project-URL: Repository, https://github.com/Sohex/musefs
-Project-URL: Issues, https://github.com/Sohex/musefs/issues
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: POSIX
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Multimedia :: Sound/Audio
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: test
-Requires-Dist: pytest>=7; extra == "test"
-Dynamic: license-file
-
-# python-musefs
-
-The shared store-contract library behind the [beets](../beets/README.md),
-[Picard](../picard/README.md), and [Lidarr](../lidarr/README.md) musefs
-plugins. It is the single source of truth for how a plugin writes the musefs
-SQLite store: the schema-version check, the `tags` / `art` / `track_art`
-writes, sha256 art content-addressing, the `realpath_key` path normalization,
-the `musefs scan` shell-out (`run_scan`), and the per-file sync write-loop
-(`Record` / `sync_files`).
-
-Field mapping stays in each plugin — beets expands multi-valued
-`genres`/`composers` into one tag each, Picard takes the first value — so this
-library deliberately does not own it.
-
-## Writing a plugin
-
-A plugin turns host metadata (a beets item, a Picard track, a Lidarr release)
-into musefs store writes. This library owns every store-touching step except the
-field mapping: you supply the per-file tag and art values, and it handles the
-schema check, the scan shell-out, content-addressing, and the write loop.
-
-### The write flow
-
-The canonical order is **connect → check_schema_version → run_scan → build
-`Record`s → sync_files → commit → prune_missing**. The caller owns the
-transaction — nothing here commits for you.
-
-```python
-from musefs_common import (
-    SCAN_TIMEOUT_SECONDS,
-    ArtImage,
-    Record,
-    check_schema_version,
-    connect,
-    prune_missing,
-    realpath_key,
-    run_scan,
-    sync_files,
-)
-
-
-def sync(db_path, files, *, musefs_bin="musefs"):
-    # `run_scan` creates the DB if absent and fills the structural columns a
-    # plugin cannot compute (format, audio offset/length, backing size/mtime).
-    # On a brand-new store it must precede `connect`, which has nothing to open
-    # until the scan has created the file.
-    run_scan(musefs_bin, db_path, files, timeout=SCAN_TIMEOUT_SECONDS)
-
-    conn = connect(db_path)
-    try:
-        check_schema_version(conn)  # raises SchemaMismatch on a version skew
-
-        records = [
-            Record(
-                key=realpath_key(path),  # MUST equal the scanned row's backing_path
-                pairs=[("artist", artist), ("title", title)],
-                art=[ArtImage(data=cover, mime="image/jpeg")] if cover else None,
-            )
-            for path, artist, title, cover in host_metadata(files)
-        ]
-
-        stats = sync_files(conn, records)  # full-replace of plugin text tags
-        conn.commit()  # the caller commits
-
-        prune_missing(conn)  # drop rows whose backing file vanished
-        conn.commit()
-        return stats
-    finally:
-        conn.close()
-```
-
-For a dry run, pass `dry_run=True` to `sync_files` and `conn.rollback()` instead
-of committing — `SyncStats` still reports what *would* change.
-
-`run_scan` raises `ScanError` (`kind` ∈ `{"not_found", "timeout", "failed"}`)
-and `check_schema_version` raises `SchemaMismatch`; a host adapter formats its
-own user-facing message from the exception attributes (see the beets plugin's
-`_scan_user_error`).
-
-### The `Record` shape
-
-One `Record` per file is your primary output. Its fields:
-
-| field | type | meaning |
-| ----- | ---- | ------- |
-| `key` | `str` | The file's identity in the store. **Must** be `realpath_key(path)` — the canonicalized absolute path the scanner stored as `backing_path`. A `key` that matches no scanned row is silently counted in `SyncStats.skipped`, not written. |
-| `pairs` | `list[tuple[str, str]]` | Ordered `(tag_key, value)` text tags. Duplicate keys are allowed and get contiguous ordinals (multi-valued tags). |
-| `art` | `list[ArtImage] \| None` | Embedded pictures, already resolved to bytes. `None`/`[]` leaves existing art untouched. |
-| `delete_keys` | `list[str] \| None` | Merge mode only: keys to clear without rewriting (see below). Ignored in replace mode. |
-
-`ArtImage(data, mime, picture_type=3, description="")` is one picture: `data` is
-raw bytes, `picture_type` is the ID3/FLAC type (3 = front cover). Images larger
-than `MAX_ART_BYTES` are dropped and counted in `SyncStats.skipped_art`.
-
-If every record lands in `skipped`, the `key`s and the scan target disagree —
-both must canonicalize the same way, so scan the *real* files (not a symlink
-farm) and build keys with `realpath_key`.
-
-### Merge vs. replace, and sticky deletes
-
-`sync_files(..., merge=False)` (the default) **replaces** every plugin-owned
-text tag on each track: it clears all `value_blob IS NULL` rows and rewrites
-them from `record.pairs`. Scanner-written binary tags always survive.
-
-`sync_files(..., merge=True)` **merges**: only the keys named in `record.pairs`
-and `record.delete_keys` are touched; other scan-seeded text tags stay. Use
-merge when your plugin owns a *subset* of the tags and must not clobber the
-rest. The store does not remember which keys you manage — **you** track your
-managed-key set out of band (the contract is explicit that the store is not the
-place for plugin state).
-
-When the user removes a tag in the host, merge mode needs to delete the
-now-orphaned store row. The beets plugin solves this with an **accumulating
-managed-key set** (the `musefs_managed` pattern), worth copying:
-
-- Persist, per file, the set of keys you have *ever* written (beets uses a
-  flexattr; any per-file host metadata works).
-- On each sync, `delete_keys = previous_managed − keys_written_now`, and the new
-  persisted set is `previous_managed ∪ keys_written_now`.
-- A key you stop writing becomes a tombstone: it keeps getting deleted on every
-  sync until you write it again. Persist the managed set **only after** the store
-  commit succeeds, so a failed sync doesn't lose the record of what you owe.
-
-See `contrib/beets/beetsplug/_core.py` (`build_records` / `persist_managed`) for
-the reference implementation.
-
-### Store invariants you must respect
-
-The full external-writer contract is in
-[ARCHITECTURE.md](../../ARCHITECTURE.md#the-external-writer-contract). The rules
-that bite plugin authors:
-
-- **Write only `tags`, `art`, and `track_art`.** The scanner owns the structural
-  columns of `tracks` and all of `structural_blocks`; never compute them — run
-  `musefs scan` (i.e. `run_scan`). `CHECK` constraints reject malformed
-  structural shapes at commit, so you cannot persist them anyway.
-- **Binary tags survive a sync.** `merge_tags` / `replace_tags` scope their
-  deletes to text rows (`value_blob IS NULL`), so the write loop never wipes
-  scanner-written binary tags. You may write binary tags yourself too — a binary
-  row carries its payload in `value_blob` and must leave `value` empty (the only
-  `CHECK` on the row).
-- **Content-address art** through `upsert_art` (sha256 de-dup) rather than
-  inserting `art` rows by hand; `sync_files` does this for you.
-- **Art rows are immutable.** A trigger rejects in-place updates of an
-  `art` row's content columns (`data`, `sha256`, `mime`, `byte_len`, `width`,
-  `height`). To change a track's art, insert a new content-addressed row via
-  `upsert_art` and relink it via `replace_track_art`.
-- **Path layout is just a tag.** To drive a reorganized mount, write your
-  computed relative path into a custom tag (e.g. `beets_path`) and mount with
-  `--template '$!{beets_path}'`. musefs sanitizes each path segment, so a writer
-  cannot inject traversal.
-
-## API reference
-
-Everything in `__all__`, imported from the top-level `musefs_common` package.
-
-**Connection & schema**
-
-- `connect(db_path)` → `sqlite3.Connection` — open with a 5s busy timeout and
-  `foreign_keys = ON`.
-- `check_schema_version(conn)` — raise `SchemaMismatch` unless the store's
-  `user_version` equals `EXPECTED_USER_VERSION`.
-
-**Scanning**
-
-- `run_scan(binary, db_path, target, *, timeout=None)` — shell out to `musefs
-  scan`; `target` is one path or an iterable, all scanned under one process.
-  Creates the DB if absent. Raises `ScanError`.
-
-**Building records**
-
-- `Record(key, pairs=[], art=None, delete_keys=None)` — one file's sync inputs
-  (see *The `Record` shape*).
-- `ArtImage(data, mime, picture_type=3, description="")` — one embedded picture.
-- `realpath_key(path)` — canonical path string matching the scanner's
-  `backing_path`; accepts `str`/`bytes`, returns `str`.
-
-**Writing**
-
-- `sync_files(conn, records, *, dry_run=False, stats=None, merge=False)` →
-  `SyncStats` — the write loop; caller owns the transaction. Pass `stats` to
-  accumulate into a caller-seeded instance.
-- `sync_one(conn, record, stats, *, dry_run=False, merge=False)` — sync a single
-  record into a caller-supplied `SyncStats`.
-- `SyncStats` — `synced` / `skipped` / `art_linked` / `skipped_art` counters,
-  plus `.summary()`.
-
-**Lower-level store helpers** (called for you by `sync_files`; use directly only
-for a custom write loop)
-
-- `track_id_for_path(conn, key)` → track id or `None`.
-- `merge_tags(conn, track_id, managed_pairs, delete_keys)` — per-key replace of
-  plugin-managed text tags, leaving unmanaged text rows intact.
-- `replace_tags(conn, track_id, pairs)` — replace all plugin-owned text tags.
-- `upsert_art(conn, data, mime)` → art id — content-address `data` by sha256,
-  inserting only if new.
-- `replace_track_art(conn, track_id, arts)` — replace a track's `track_art`
-  rows; `arts` is `[(art_id, picture_type, description), …]`.
-- `sniff_mime(data, path)` — image mime from magic bytes, falling back to file
-  extension.
-- `prune_missing(conn, track_ids=None)` → count — delete tracks whose backing
-  file no longer exists (every track, or just `track_ids`).
-
-**Constants**
-
-- `EXPECTED_USER_VERSION` — schema `user_version` this library targets.
-- `MAX_ART_BYTES` — per-image art cap; larger images are skipped.
-- `SCAN_TIMEOUT_SECONDS` — default wall-clock cap for one `run_scan`.
-
-**Exceptions**
-
-- `SchemaMismatch(found)` — schema-version skew; `.found` is the DB's version.
-- `ScanError(kind, *, binary, target, …)` — a `musefs scan` failure; `.kind` ∈
-  `{"not_found", "timeout", "failed"}`, with context attributes for messaging.
-
-## Consumers
-
-- **beets** depends on this package via pip (`contrib/beets/pyproject.toml`).
-- **Picard** cannot pip-install plugin dependencies, so the package is
-  **vendored** into `contrib/picard/musefs/_common/` by
-  `vendor_to_picard.py`. After any change here, re-run:
-
-  ```bash
-  python contrib/python-musefs/vendor_to_picard.py
-  ```
-
-  The Picard test `tests/test_vendor_sync.py` fails if the committed copy drifts.
-- **Lidarr** depends on this package via pip (`contrib/lidarr/pyproject.toml`).
-
-## Schema coupling
-
-`musefs_common/schema.py` (`SCHEMA_SQL`, `USER_VERSION`) is **generated** from
-the Rust migrations in `musefs-db/src/schema.rs` — do not edit it by hand.
-`EXPECTED_USER_VERSION` (in `constants.py`) derives from it. When the Rust
-schema bumps, regenerate and re-vendor:
-
-```bash
-MUSEFS_REGEN_SCHEMA_PY=1 cargo test -p musefs-db schema_py
-python contrib/python-musefs/vendor_to_picard.py
-```
-
-A `musefs-db` unit test fails if the generated file drifts. This is all
-independent of the package's own `__version__` (its release SemVer).
-
-## Tests
-
-```bash
-cd contrib/python-musefs
-python -m venv .venv && source .venv/bin/activate
-pip install -e ".[test]"
-python -m pytest -v
-ruff check . && ruff format --check .
-```

python_musefs-1.0.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-musefs_common/__init__.py,sha256=e8xfwhe770V9_gnoJEjNqk4lJmpHcqaLgojSo9-MXks,1299
-musefs_common/constants.py,sha256=M0zS6YCnYdE_JjIbvxg-GhbYdfbe30ccKZvbZ1WTZZ8,302
-musefs_common/contract.py,sha256=tUflCxfFiaIzJiTqYL-o-bjKNH_s91EHkC2amk8sKxE,1472
-musefs_common/errors.py,sha256=OUBXzpa4q7TPYvFFiTyoIfRC3SGRRgZcpXlr43RP0jk,1456
-musefs_common/paths.py,sha256=dE3wwop5mRxoJ8RhdYwTIZpX4MPaUUw2LJhjcxApOIA,649
-musefs_common/scan.py,sha256=2rOFQQt0pE1uhF31huSwRtapU0QK3fFDGbscynwLtRE,1453
-musefs_common/schema.py,sha256=Blab4CIiFIQaaqh5IjMpUR0jD01xU0CFrl4AQQM3yKM,8511
-musefs_common/store.py,sha256=nk34ghVlqMsF__PozYZHCu8Xd0QsoChl9bGTFsrdbwE,8721
-musefs_common/sync.py,sha256=Rh65b69d92FLxNwN4Z939GmfUiZ1Sfw7F_vL31i4VtM,3375
-python_musefs-1.0.0.dist-info/licenses/LICENSE,sha256=4VbfzhgMpuFrhFjBCtLptGV_bzCj_gML9y_9o2Tr1OQ,1068
-python_musefs-1.0.0.dist-info/METADATA,sha256=F2pO6iiY0rn4HLaefxYYo73hc7dbc_KSgWWzvooCXm4,11971
-python_musefs-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_musefs-1.0.0.dist-info/top_level.txt,sha256=ejWexGk95-s11kZnTFwg1T3iG_dFcaE4vhcLnL3t3Ak,14
-python_musefs-1.0.0.dist-info/RECORD,,