python-musefs 1.0.0__tar.gz → 1.1.0__tar.gz

python_musefs-1.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,6 @@
+# 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.0.0 → python_musefs-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-musefs"
-version = "1.0.0"
+version = "1.1.0"
 description = "Shared musefs SQLite-store contract for the beets and Picard plugins"
 readme = "README.md"
 requires-python = ">=3.8"

{python_musefs-1.0.0 → python_musefs-1.1.0}/src/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",

{python_musefs-1.0.0 → python_musefs-1.1.0}/src/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:

{python_musefs-1.0.0 → python_musefs-1.1.0}/src/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

{python_musefs-1.0.0 → python_musefs-1.1.0}/src/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),
             )
 

{python_musefs-1.0.0 → python_musefs-1.1.0}/src/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/src/python_musefs.egg-info/PKG-INFO

@@ -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.0.0 → python_musefs-1.1.0}/tests/test_constants.py

@@ -2,7 +2,7 @@ from musefs_common import constants
 
 
 def test_expected_user_version_matches_rust_migrations():
-    assert constants.EXPECTED_USER_VERSION == 1
+    assert constants.EXPECTED_USER_VERSION == 2
 
 
 def test_max_art_bytes_is_16mib_minus_64kib():

{python_musefs-1.0.0 → python_musefs-1.1.0}/tests/test_merge_tags.py

@@ -76,3 +76,39 @@ def test_merge_preserves_binary_tags(db_path):
         assert text_tags(conn, tid)["comment"] == ["text"]
     finally:
         conn.close()
+
+
+def test_merge_replaces_case_variant_scan_key(db_path):
+    """A scan seeds an unmapped Vorbis key in the file's native (upper) case;
+    the plugin's lowercase canonical key must replace it, not coexist (#407)."""
+    conn = connect(db_path)
+    try:
+        tid = insert_track(conn, "/m/e.flac")
+        # Scanner-seeded row, native FLAC Vorbis case (uppercase).
+        replace_tags(conn, tid, [("LABEL", "New Friends")])
+        # Plugin sync writes the canonical lowercase key for the same field.
+        merge_tags(conn, tid, [("label", "New Friends")], delete_keys=[])
+        conn.commit()
+        rows = conn.execute(
+            "SELECT key, value FROM tags WHERE track_id=? AND value_blob IS NULL", (tid,)
+        ).fetchall()
+        # Exactly one row survives (no LABEL/label duplicate that renders twice).
+        assert rows == [("label", "New Friends")]
+    finally:
+        conn.close()
+
+
+def test_merge_delete_keys_clears_case_variant(db_path):
+    """delete_keys must also clear a scan-seeded case variant of the named key."""
+    conn = connect(db_path)
+    try:
+        tid = insert_track(conn, "/m/f.flac")
+        replace_tags(conn, tid, [("LABEL", "Old")])
+        merge_tags(conn, tid, [], delete_keys=["label"])
+        conn.commit()
+        rows = conn.execute(
+            "SELECT key FROM tags WHERE track_id=? AND value_blob IS NULL", (tid,)
+        ).fetchall()
+        assert rows == []
+    finally:
+        conn.close()

{python_musefs-1.0.0 → python_musefs-1.1.0}/tests/test_public_api.py

@@ -2,7 +2,7 @@ import musefs_common
 
 
 def test_version_is_package_semver_not_schema_version():
-    assert musefs_common.__version__ == "1.0.0"
+    assert musefs_common.__version__ == "1.1.0"
     assert musefs_common.__version__ != str(musefs_common.EXPECTED_USER_VERSION)
 
 
@@ -18,7 +18,12 @@ def test_public_api_surface():
         "connect",
         "check_schema_version",
         "track_id_for_path",
+        "track_ids_for_paths",
+        "track_ids_by_tag",
+        "tags_for_track",
+        "TagRow",
         "prune_missing",
+        "delete_tracks",
         "replace_tags",
         "upsert_art",
         "replace_track_art",