python-musefs 0.0.1__py3-none-any.whl

musefs_common/__init__.py

@@ -0,0 +1,49 @@
+"""python-musefs: the shared musefs SQLite-store contract.
+
+Single source of truth for the schema-version check, the tags/art/track_art
+writes, art content-addressing, path-key normalization, the `musefs scan`
+shell-out, and the per-file sync write-loop. Consumed by the beets plugin (as a
+pip dependency) and by the Picard plugin (vendored into ``musefs/_common``).
+"""
+
+from .constants import EXPECTED_USER_VERSION, MAX_ART_BYTES, SCAN_TIMEOUT_SECONDS
+from .errors import ScanError, SchemaMismatch
+from .paths import realpath_key
+from .scan import run_scan
+from .store import (
+    check_schema_version,
+    connect,
+    prune_missing,
+    replace_tags,
+    replace_track_art,
+    sniff_mime,
+    track_id_for_path,
+    upsert_art,
+)
+from .sync import ArtImage, Record, SyncStats, sync_files, sync_one
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EXPECTED_USER_VERSION",
+    "MAX_ART_BYTES",
+    "SCAN_TIMEOUT_SECONDS",
+    "SchemaMismatch",
+    "ScanError",
+    "realpath_key",
+    "run_scan",
+    "connect",
+    "check_schema_version",
+    "track_id_for_path",
+    "prune_missing",
+    "replace_tags",
+    "upsert_art",
+    "replace_track_art",
+    "sniff_mime",
+    "ArtImage",
+    "Record",
+    "SyncStats",
+    "sync_one",
+    "sync_files",
+    "__version__",
+]

musefs_common/constants.py

@@ -0,0 +1,9 @@
+from .schema import USER_VERSION
+
+EXPECTED_USER_VERSION = USER_VERSION
+
+MAX_ART_BYTES = 16 * 1024 * 1024 - 64 * 1024
+
+# Wall-clock cap (seconds) for a single `musefs scan` shell-out; a wedged scan
+# (stuck disk, DB lock) raises ScanError(kind="timeout") rather than hanging.
+SCAN_TIMEOUT_SECONDS = 120

musefs_common/contract.py

@@ -0,0 +1,44 @@
+"""Canonical tag-row contract both plugins must satisfy.
+
+Each plugin's test builds an equivalent host object (a beets ``Item`` from the
+list fields, a Picard ``Metadata`` from ``getall``) carrying ``CONTRACT_VALUES``
+and asserts its ``map_fields`` output, normalized, equals
+``normalize_rows(CONTRACT_EXPECTED)``. This guards #84/#86 against future
+divergence between the two mappers.
+
+Scope: the genuinely-shared multi-value fields (``genre``, ``composer``). beets
+has no multi-artist field, so ``artist``/``albumartist`` are single-valued here;
+Picard's multi-artist expansion is tested in its own unit tests.
+"""
+
+from collections import defaultdict
+
+CONTRACT_VALUES = {
+    "title": "Song",
+    "artist": "Alice",
+    "albumartist": "Alice",
+    "album": "Greatest Hits",
+    "genre": ["Rock", "Pop"],
+    "composer": ["Carol", "Dave"],
+}
+
+CONTRACT_EXPECTED = [
+    ("title", "Song"),
+    ("artist", "Alice"),
+    ("albumartist", "Alice"),
+    ("album", "Greatest Hits"),
+    ("genre", "Rock"),
+    ("genre", "Pop"),
+    ("composer", "Carol"),
+    ("composer", "Dave"),
+]
+
+
+def normalize_rows(rows):
+    """Group ``(key, value)`` rows by key into a comparison-stable dict. All
+    contract keys use set semantics (the store treats multi-values as a set), so
+    each key's values are returned sorted."""
+    grouped = defaultdict(list)
+    for key, value in rows:
+        grouped[key].append(value)
+    return {key: sorted(values) for key, values in grouped.items()}

musefs_common/errors.py

@@ -0,0 +1,38 @@
+from .constants import EXPECTED_USER_VERSION
+
+
+class SchemaMismatch(Exception):  # noqa: N818
+    """Raised when the musefs DB schema version differs from what this library
+    targets (``EXPECTED_USER_VERSION``)."""
+
+    def __init__(self, found):
+        self.found = found
+        super().__init__(
+            f"musefs DB user_version is {found}, plugin targets "
+            f"{EXPECTED_USER_VERSION}; the musefs and plugin versions have "
+            f"diverged."
+        )
+
+
+class ScanError(Exception):  # noqa: N818
+    """A `musefs scan` invocation failed. ``kind`` is one of ``"not_found"``,
+    ``"timeout"``, ``"failed"``; the remaining attributes carry enough context
+    for a host adapter to format its own user-facing message."""
+
+    def __init__(self, kind, *, binary, target, timeout=None, returncode=None, stderr=""):
+        self.kind = kind
+        self.binary = binary
+        self.target = target
+        self.timeout = timeout
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(self._default_message())
+
+    def _default_message(self):
+        if self.kind == "not_found":
+            return f"musefs binary '{self.binary}' not found"
+        if self.kind == "timeout":
+            return f"`{self.binary} scan` for {self.target} timed out after {self.timeout}s"
+        return (
+            f"`{self.binary} scan` failed for {self.target} (exit {self.returncode}): {self.stderr}"
+        )

musefs_common/paths.py

@@ -0,0 +1,16 @@
+import os
+
+
+def realpath_key(path):
+    """Canonical absolute path string matching musefs scan's stored
+    ``backing_path`` (``std::fs::canonicalize`` + ``to_string_lossy``).
+
+    Accepts ``str`` or ``bytes`` and always returns ``str``.
+    """
+    real = os.path.realpath(path)
+    if isinstance(real, bytes):
+        real = os.fsdecode(real)
+    # os.fsdecode uses surrogateescape; Rust's to_string_lossy uses U+FFFD for
+    # undecodable bytes. Normalize so a non-UTF-8 path component produces the
+    # same key string on both sides instead of silently mismatching.
+    return real.encode("utf-8", "surrogateescape").decode("utf-8", "replace")

musefs_common/scan.py

@@ -0,0 +1,33 @@
+import os
+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."""
+    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)]
+    try:
+        result = subprocess.run(argv, capture_output=True, timeout=timeout)
+    except FileNotFoundError as exc:
+        raise ScanError("not_found", binary=binary, target=display) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise ScanError("timeout", binary=binary, target=display, timeout=timeout) from exc
+    if result.returncode != 0:
+        raise ScanError(
+            "failed",
+            binary=binary,
+            target=display,
+            returncode=result.returncode,
+            stderr=result.stderr.decode(errors="replace").strip(),
+        )

musefs_common/schema.py

@@ -0,0 +1,243 @@
+# GENERATED from musefs-db/src/schema.rs — do not edit.
+# Regenerate: MUSEFS_REGEN_SCHEMA_PY=1 cargo test -p musefs-db schema_py
+# Re-vendor:  python contrib/python-musefs/vendor_to_picard.py
+
+SCHEMA_SQL = """\
+-- ── MIGRATION_V1 ──
+CREATE TABLE tracks (
+    id              INTEGER PRIMARY KEY,
+    backing_path    TEXT NOT NULL UNIQUE,
+    format          TEXT NOT NULL,
+    audio_offset    INTEGER NOT NULL,
+    audio_length    INTEGER NOT NULL,
+    backing_size    INTEGER NOT NULL,
+    backing_mtime   INTEGER NOT NULL,
+    content_version INTEGER NOT NULL DEFAULT 0,
+    updated_at      INTEGER NOT NULL
+);
+
+CREATE TABLE tags (
+    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,
+    PRIMARY KEY (track_id, key, ordinal)
+);
+
+CREATE TABLE art (
+    id       INTEGER PRIMARY KEY,
+    sha256   TEXT NOT NULL UNIQUE,
+    mime     TEXT NOT NULL,
+    width    INTEGER,
+    height   INTEGER,
+    byte_len INTEGER NOT NULL,
+    data     BLOB NOT NULL
+);
+
+CREATE TABLE track_art (
+    track_id     INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
+    art_id       INTEGER NOT NULL REFERENCES art(id),
+    picture_type INTEGER NOT NULL DEFAULT 3,
+    description  TEXT NOT NULL DEFAULT '',
+    ordinal      INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (track_id, ordinal)
+);
+
+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;
+
+CREATE TRIGGER track_art_ai AFTER INSERT ON track_art 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 track_art_au AFTER UPDATE ON track_art 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 track_art_ad AFTER DELETE ON track_art 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 = 1;
+
+-- ── MIGRATION_V2 ──
+-- Binary tag payloads live alongside text tags. A row is binary iff
+-- value_blob IS NOT NULL; binary rows store '' in value.
+ALTER TABLE tags ADD COLUMN value_blob BLOB;
+
+-- Read-only, derived-from-file structural metadata (FLAC STREAMINFO/SEEKTABLE).
+-- NOT part of the editable `tags` contract: external tools never touch it.
+CREATE TABLE structural_blocks (
+    track_id INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
+    kind     TEXT NOT NULL,
+    ordinal  INTEGER NOT NULL DEFAULT 0,
+    body     BLOB NOT NULL,
+    PRIMARY KEY (track_id, kind, ordinal)
+);
+PRAGMA user_version = 2;
+
+-- ── MIGRATION_V3 ──
+-- Bounded changelog ring for O(changed) refresh. Every metadata edit funnels
+-- through an UPDATE on the tracks row (the V1 tags/track_art triggers), so
+-- triggers on tracks alone capture all writers. Relies on SQLite nested
+-- trigger activation (on by default; distinct from PRAGMA recursive_triggers).
+CREATE TABLE track_changes (
+    seq      INTEGER PRIMARY KEY AUTOINCREMENT,
+    track_id INTEGER NOT NULL
+);
+
+CREATE TRIGGER tracks_changelog_ai AFTER INSERT ON tracks BEGIN
+    INSERT INTO track_changes (track_id) VALUES (NEW.id);
+END;
+CREATE TRIGGER tracks_changelog_au AFTER UPDATE ON tracks BEGIN
+    INSERT INTO track_changes (track_id) VALUES (NEW.id);
+END;
+CREATE TRIGGER tracks_changelog_ad AFTER DELETE ON tracks BEGIN
+    INSERT INTO track_changes (track_id) VALUES (OLD.id);
+END;
+
+-- Self-pruning ring: writers maintain it; the mount's read-only connections
+-- never need to. Deletes only from the old end, so retained seqs stay contiguous.
+CREATE TRIGGER track_changes_prune AFTER INSERT ON track_changes BEGIN
+    DELETE FROM track_changes WHERE seq <= NEW.seq - 8192;
+END;
+PRAGMA user_version = 3;
+
+-- ── MIGRATION_V4 ──
+CREATE TEMP TABLE _m4_tracks AS SELECT * FROM tracks;
+CREATE TEMP TABLE _m4_tags AS SELECT * FROM tags;
+CREATE TEMP TABLE _m4_art AS SELECT * FROM art;
+CREATE TEMP TABLE _m4_track_art AS SELECT * FROM track_art;
+
+DROP TABLE track_art;
+DROP TABLE tags;
+DROP TABLE art;
+DROP TABLE tracks;
+
+CREATE TABLE tracks (
+    id              INTEGER PRIMARY KEY,
+    backing_path    TEXT NOT NULL UNIQUE,
+    format          TEXT NOT NULL,
+    audio_offset    INTEGER NOT NULL,
+    audio_length    INTEGER NOT NULL,
+    backing_size    INTEGER NOT NULL,
+    backing_mtime   INTEGER NOT NULL,
+    content_version INTEGER NOT NULL DEFAULT 0,
+    updated_at      INTEGER NOT NULL,
+    CHECK (format IN ('flac','mp3','m4a','opus','vorbis','oggflac','wav')),
+    CHECK (audio_offset >= 0),
+    CHECK (audio_length >= 0),
+    CHECK (backing_size >= 0),
+    CHECK (backing_mtime >= 0),
+    CHECK (content_version >= 0),
+    CHECK (updated_at >= 0),
+    CHECK (audio_offset + audio_length <= backing_size)
+);
+
+CREATE TABLE tags (
+    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 = '')
+);
+
+CREATE TABLE art (
+    id       INTEGER PRIMARY KEY,
+    sha256   TEXT NOT NULL UNIQUE,
+    mime     TEXT NOT NULL,
+    width    INTEGER,
+    height   INTEGER,
+    byte_len INTEGER NOT NULL,
+    data     BLOB NOT NULL,
+    CHECK (byte_len = length(data)),
+    CHECK (length(sha256) = 64),
+    CHECK (width IS NULL OR width >= 0),
+    CHECK (height IS NULL OR height >= 0)
+);
+
+CREATE TABLE track_art (
+    track_id     INTEGER NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
+    art_id       INTEGER NOT NULL REFERENCES art(id),
+    picture_type INTEGER NOT NULL DEFAULT 3,
+    description  TEXT NOT NULL DEFAULT '',
+    ordinal      INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (track_id, ordinal),
+    CHECK (picture_type BETWEEN 0 AND 20),
+    CHECK (ordinal >= 0)
+);
+
+INSERT INTO tracks SELECT * FROM _m4_tracks;
+INSERT INTO art SELECT * FROM _m4_art;
+INSERT INTO tags SELECT * FROM _m4_tags;
+INSERT INTO track_art SELECT * FROM _m4_track_art;
+
+DROP TABLE _m4_track_art;
+DROP TABLE _m4_tags;
+DROP TABLE _m4_art;
+DROP TABLE _m4_tracks;
+
+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;
+
+CREATE TRIGGER track_art_ai AFTER INSERT ON track_art 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 track_art_au AFTER UPDATE ON track_art 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 track_art_ad AFTER DELETE ON track_art BEGIN
+    UPDATE tracks SET content_version = content_version + 1,
+                      updated_at = CAST(strftime('%s','now') AS INTEGER)
+    WHERE id = OLD.track_id;
+END;
+
+CREATE TRIGGER tracks_changelog_ai AFTER INSERT ON tracks BEGIN
+    INSERT INTO track_changes (track_id) VALUES (NEW.id);
+END;
+CREATE TRIGGER tracks_changelog_au AFTER UPDATE ON tracks BEGIN
+    INSERT INTO track_changes (track_id) VALUES (NEW.id);
+END;
+CREATE TRIGGER tracks_changelog_ad AFTER DELETE ON tracks BEGIN
+    INSERT INTO track_changes (track_id) VALUES (OLD.id);
+END;
+PRAGMA user_version = 4;
+"""
+
+USER_VERSION = 4

musefs_common/store.py

@@ -0,0 +1,119 @@
+import hashlib
+import os
+import sqlite3
+
+from .constants import EXPECTED_USER_VERSION
+from .errors import SchemaMismatch
+
+
+def connect(db_path):
+    """Open the musefs DB with a busy timeout and foreign keys enabled."""
+    conn = sqlite3.connect(db_path)
+    # 5s busy timeout so a brief write doesn't fail while the FUSE mount reads.
+    conn.execute("PRAGMA busy_timeout = 5000")
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def check_schema_version(conn):
+    """Raise ``SchemaMismatch`` unless the DB's ``user_version`` matches the
+    version this library targets. Call on an open connection from ``connect``."""
+    found = conn.execute("PRAGMA user_version").fetchone()[0]
+    if found != EXPECTED_USER_VERSION:
+        raise SchemaMismatch(found)
+
+
+def track_id_for_path(conn, key):
+    """Return the track id whose backing_path equals ``key``, or None."""
+    row = conn.execute("SELECT id FROM tracks WHERE backing_path = ?", (key,)).fetchone()
+    return row[0] if row else None
+
+
+def prune_missing(conn, track_ids=None):
+    """Delete track rows whose backing file no longer exists on disk.
+
+    When ``track_ids`` is provided, only those tracks are checked and
+    potentially pruned. Otherwise, every track in the database is checked.
+    Returns the number pruned.
+    """
+    if track_ids is not None:
+        gone = []
+        for tid in track_ids:
+            row = conn.execute("SELECT backing_path FROM tracks WHERE id=?", (tid,)).fetchone()
+            if row is not None and not os.path.exists(row[0]):
+                gone.append((tid,))
+    else:
+        gone = [
+            (tid,)
+            for tid, path in conn.execute("SELECT id, backing_path FROM tracks")
+            if not os.path.exists(path)
+        ]
+    conn.executemany("DELETE FROM tracks WHERE id = ?", gone)
+    return len(gone)
+
+
+def replace_tags(conn, track_id, pairs):
+    """Replace all tags for a track. Duplicate keys get incrementing ordinals
+    (mirroring musefs scan ingest)."""
+    # Scope to the plugin-owned text rows: scanner-written binary tags
+    # (value_blob NOT NULL) must survive a sync (#82).
+    conn.execute("DELETE FROM tags WHERE track_id = ? AND value_blob IS NULL", (track_id,))
+    ordinals = {}
+    rows = []
+    for key, value in pairs:
+        ordinal = ordinals.get(key, 0)
+        ordinals[key] = ordinal + 1
+        rows.append((track_id, key, value, ordinal))
+    conn.executemany(
+        "INSERT INTO tags (track_id, key, value, ordinal) VALUES (?, ?, ?, ?)",
+        rows,
+    )
+
+
+_EXT_MIME = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+}
+
+
+def sniff_mime(data, path):
+    """Detect image mime from magic bytes, falling back to file extension."""
+    if data[:3] == b"\xff\xd8\xff":
+        return "image/jpeg"
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return "image/png"
+    # WebP: 'RIFF' <4-byte size> 'WEBP'.
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    ext = os.path.splitext(path)[1].lower()
+    return _EXT_MIME.get(ext, "application/octet-stream")
+
+
+def upsert_art(conn, data, mime):
+    """Content-address ``data`` by sha256 and return its art id, inserting only
+    if new (mirrors musefs Db::upsert_art). If the sha256 already exists, the
+    stored row (and its mime) is kept and the ``mime`` argument is ignored."""
+    sha = hashlib.sha256(data).hexdigest()
+    conn.execute(
+        "INSERT INTO art (sha256, mime, width, height, byte_len, data) "
+        "VALUES (?, ?, NULL, NULL, ?, ?) ON CONFLICT(sha256) DO NOTHING",
+        (sha, mime, len(data), data),
+    )
+    return conn.execute("SELECT id FROM art WHERE sha256 = ?", (sha,)).fetchone()[0]
+
+
+def replace_track_art(conn, track_id, arts):
+    """Replace the track's art rows. ``arts`` is an ordered list of
+    ``(art_id, picture_type, description)``; each row's ``ordinal`` is its
+    list index."""
+    conn.execute("DELETE FROM track_art WHERE track_id = ?", (track_id,))
+    conn.executemany(
+        "INSERT INTO track_art (track_id, art_id, picture_type, description, "
+        "ordinal) VALUES (?, ?, ?, ?, ?)",
+        [
+            (track_id, art_id, picture_type, description, i)
+            for i, (art_id, picture_type, description) in enumerate(arts)
+        ],
+    )

musefs_common/sync.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .constants import MAX_ART_BYTES
+from .store import replace_tags, replace_track_art, track_id_for_path, upsert_art
+
+
+@dataclass(frozen=True)
+class ArtImage:
+    """One embedded picture to sync: raw bytes, mime, ID3/FLAC picture type
+    (3 = front cover), and free-text description."""
+
+    data: bytes
+    mime: str
+    picture_type: int = 3
+    description: str = ""
+
+
+@dataclass
+class Record:
+    """One file's sync inputs: the realpath key, the (key, value) tag pairs, and
+    pre-resolved art as a list of ``ArtImage``s (``None``/empty list = no art
+    from the host)."""
+
+    key: str
+    pairs: list = field(default_factory=list)
+    art: object = None  # list[ArtImage] | None
+
+
+@dataclass
+class SyncStats:
+    synced: int = 0
+    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)
+
+    def summary(self):
+        return (
+            f"synced={self.synced} skipped={self.skipped} "
+            f"art_linked={self.art_linked} skipped_art={self.skipped_art}"
+        )
+
+
+def sync_one(conn, record, stats, *, dry_run=False):
+    """Sync one ``Record`` into the DB, mutating ``stats``. Caller owns the
+    transaction. Tags are always fully replaced (scanner-written binary tags
+    survive — see ``replace_tags``). 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."""
+    track_id = track_id_for_path(conn, record.key)
+    if track_id is None:
+        stats.skipped += 1
+        return
+
+    kept = []
+    for img in record.art or []:
+        if len(img.data) > MAX_ART_BYTES:
+            stats.skipped_art += 1
+        else:
+            kept.append(img)
+    will_link_art = bool(kept)
+
+    if not dry_run:
+        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)
+
+    if will_link_art:
+        stats.art_linked += 1
+    stats.synced += 1
+
+
+def sync_files(conn, records, *, dry_run=False, stats=None):
+    """Sync an iterable of ``Record``s, returning the ``SyncStats``. Pass
+    ``stats`` to accumulate into a caller-seeded instance (e.g. beets pre-counts
+    unreadable art); otherwise a fresh one is created. Caller owns the
+    transaction (commit on success, rollback for dry runs)."""
+    if stats is None:
+        stats = SyncStats()
+    for record in records:
+        sync_one(conn, record, stats, dry_run=dry_run)
+    return stats

python_musefs-0.0.1.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: python-musefs
+Version: 0.0.1
+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.
+
+## 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-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+musefs_common/__init__.py,sha256=hV6UKgOJ4n98n-2OR9LVTSE3Yhhz_E4MSRERUzQOpqM,1265
+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=Y9zE25PEFX-mVJzULT2aOi5AiS10pYp6_y50oirrrvo,8716
+musefs_common/store.py,sha256=O3HNrq5clPMcWYGDiiKhfbDpBB3u8UNtpvIcqWP6_Gs,4316
+musefs_common/sync.py,sha256=aCK0zacYZ0B5GWlS-MwOdMf4j6XutX7wi62QxZzXqP8,2835
+python_musefs-0.0.1.dist-info/licenses/LICENSE,sha256=4VbfzhgMpuFrhFjBCtLptGV_bzCj_gML9y_9o2Tr1OQ,1068
+python_musefs-0.0.1.dist-info/METADATA,sha256=_n-iNLP2PZQpW-JzfE44FL-y9fwnlu5iuS-5LqUpCk8,2664
+python_musefs-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_musefs-0.0.1.dist-info/top_level.txt,sha256=ejWexGk95-s11kZnTFwg1T3iG_dFcaE4vhcLnL3t3Ak,14
+python_musefs-0.0.1.dist-info/RECORD,,

python_musefs-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_musefs-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conor Futro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_musefs-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+musefs_common