rekordbox-edit 0.12.0.dev17__tar.gz → 0.13.0.dev7__tar.gz

{rekordbox_edit-0.12.0.dev17 → rekordbox_edit-0.13.0.dev7}/CHANGELOG.md

@@ -1,4 +1,27 @@
-## v0.12.0.dev17 (2026-09-06)
+## v0.13.0.dev7 (2026-09-08)
+
+
+- fix(edit): give the records an edit creates and collects their USNs
+- An edit that reassigned a relational field left the record it created
+unstamped and the one it collected outside the counter, so a syncing peer
+never learned about either. import and remove already did both.
+- feat(edit): support the remaining audio-tag columns
+- Adds Genre, Label, ComposerName, ISRC, TrackNo, DiscNo, and ReleaseYear,
+built from the tag registry so edit and import cover the same set. Key is
+left out: Rekordbox derives it from analysis.
+- refactor: name the audio tags import reads in one registry
+- Which column a tag lands in was spread across _resolve_relations and the
+add_content call; edit needs the same mapping to stay in step with import.
+- refactor(api): gather shared-record handling behind _relations
+- edit, import, and remove each carried their own copy of which table holds a
+kind, which columns count as a reference to it, and how a new one is made.
+- test(e2e): cover the remove command
+- test(e2e): give the fixture rows a Rekordbox-shaped ImagePath
+- The fixture audio carries no embedded art, so analysis left every row with
+an empty ImagePath and no e2e case could reach the artwork cleanup.
+- test(e2e): share the private-DB fixtures through conftest
+
+## v0.12.0 (2026-09-07)
 
 
 - refactor(api)!: gather the public surface behind rekordbox_edit.api

{rekordbox_edit-0.12.0.dev17 → rekordbox_edit-0.13.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rekordbox-edit
-Version: 0.12.0.dev17
+Version: 0.13.0.dev7
 Summary: Tools for managing and modifying a RekordBox library en-masse
 Project-URL: Homepage, https://github.com/jviall/rekordbox-edit
 Project-URL: Repository, https://github.com/jviall/rekordbox-edit

{rekordbox_edit-0.12.0.dev17 → rekordbox_edit-0.13.0.dev7}/docs/commands/edit.md

@@ -6,7 +6,33 @@ Bulk-edit a metadata field on tracks in your Rekordbox database.
 rbe edit [OPTIONS] [TRACK-IDS]... FIELD
 ```
 
-`FIELD` specifies the [DjmdContent](https://pyrekordbox.readthedocs.io/en/latest/formats/db6.html#djmdcontent) column to change. The editable fields are `Title`, `Comment`, `ArtistName`, `AlbumName`, `Rating`, and `FolderPath`.
+`FIELD` specifies the [DjmdContent](https://pyrekordbox.readthedocs.io/en/latest/formats/db6.html#djmdcontent) column to change:
+
+| Field | What it changes |
+| --- | --- |
+| `Title` | The track title. |
+| `Comment` | The comment column (`Commnt`). |
+| `ArtistName` | The artist, through the shared `DjmdArtist` record. |
+| `AlbumName` | The album, through the shared `DjmdAlbum` record. |
+| `ComposerName` | The composer, which shares the `DjmdArtist` table with the artist. |
+| `Genre` | The genre, through the shared `DjmdGenre` record. |
+| `Label` | The record label, through the shared `DjmdLabel` record. |
+| `ISRC` | The recording's ISRC. |
+| `TrackNo` | The track number. |
+| `DiscNo` | The disc number. |
+| `ReleaseYear` | The release year. `ReleaseDate` is left as it is. |
+| `Rating` | The 0-5 star rating. |
+| `FolderPath` | The audio file the track points at. See [FolderPath](#folderpath). |
+
+Every field above except `Rating` and `FolderPath` also comes from an audio tag, and [`import`](import.md) reads the same set. Musical key is the one tag `edit` does not offer: Rekordbox derives it from its own analysis, which would overwrite whatever you set.
+
+`Rating`, `TrackNo`, `DiscNo`, and `ReleaseYear` hold numbers, so `--match` does not apply to them; passing it warns and sets the value directly.
+
+## Relational fields
+
+`ArtistName`, `AlbumName`, `ComposerName`, `Genre`, and `Label` do not live on the track's own row. Each names a record in a shared table that many tracks point at, so editing one works the way it does in Rekordbox: the track is reassigned to a record with the new name, reusing an existing one or creating it, and every other track keeps the record it had. `--replace ""` clears the field. A record nothing references any more is deleted, again matching Rekordbox.
+
+One deliberate difference: reusing an existing album leaves that album's album-artist alone, where Rekordbox blanks it for every track on the album.
 
 `--replace` supplies the new value. On its own it overwrites the whole field; add `--match PATTERN` to find that literal text within the field and replace only that portion:
 

{rekordbox_edit-0.12.0.dev17 → rekordbox_edit-0.13.0.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rekordbox-edit"
-version = "0.12.0.dev17"
+version = "0.13.0.dev7"
 description = "Tools for managing and modifying a RekordBox library en-masse"
 authors = [{ name = "James Viall", email= "jamesviall@pm.me"}]
 license = "MIT"

rekordbox_edit-0.13.0.dev7/rekordbox_edit/_tag_fields.py

@@ -0,0 +1,88 @@
+"""The audio tags Rekordbox reads, and the columns they land in.
+
+`import` writes these columns from a file's tags and `edit` changes them
+afterward, so both commands read the mapping from here. Adding a tag to
+`tags.TrackTags` without adding it here (or the reverse) fails the parity
+test in tests/test_tag_fields.py.
+
+Which mutagen key holds a tag is a separate, format-specific concern and
+stays in `tags.py`.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TagField:
+    """One audio tag, the DjmdContent column it lands in, and how each
+    command reaches it."""
+
+    tag: str
+    """The `tags.TrackTags` key holding the value read off the file."""
+    column: str
+    """The DjmdContent column storing it: the value itself for a scalar tag,
+    or the foreign key for a relational one."""
+    relation: str | None = None
+    """The `api._relations.RELATIONS` kind `column` points at, or None where
+    the column holds the value directly."""
+    proxy: str | None = None
+    """The DjmdContent attribute reading the related record's name. Set for a
+    relational tag only."""
+    edit_field: str | None = None
+    """The `edit` command's name for this field, or None where the column is
+    not editable."""
+    default: str | int = ""
+    """What `import` writes when the file carries no such tag."""
+
+
+#: Every tag both commands know about, in the order `import` reads them.
+#:
+#: `key` is deliberately not editable: Rekordbox derives KeyID from its own
+#: analysis, so a user-supplied key would be overwritten the next time the
+#: track is analyzed.
+TAG_FIELDS: tuple[TagField, ...] = (
+    TagField(tag="title", column="Title", edit_field="Title"),
+    TagField(
+        tag="artist",
+        column="ArtistID",
+        relation="artist",
+        proxy="ArtistName",
+        edit_field="ArtistName",
+    ),
+    TagField(
+        tag="album",
+        column="AlbumID",
+        relation="album",
+        proxy="AlbumName",
+        edit_field="AlbumName",
+    ),
+    TagField(
+        tag="genre",
+        column="GenreID",
+        relation="genre",
+        proxy="GenreName",
+        edit_field="Genre",
+    ),
+    TagField(
+        tag="label",
+        column="LabelID",
+        relation="label",
+        proxy="LabelName",
+        edit_field="Label",
+    ),
+    TagField(
+        tag="composer",
+        column="ComposerID",
+        relation="artist",
+        proxy="ComposerName",
+        edit_field="ComposerName",
+    ),
+    TagField(tag="key", column="KeyID", relation="key", proxy="KeyName"),
+    TagField(tag="comment", column="Commnt", edit_field="Comment"),
+    TagField(tag="isrc", column="ISRC", edit_field="ISRC"),
+    TagField(tag="track_no", column="TrackNo", edit_field="TrackNo", default=0),
+    TagField(tag="disc_no", column="DiscNo", edit_field="DiscNo", default=0),
+    TagField(
+        tag="release_year", column="ReleaseYear", edit_field="ReleaseYear", default=0
+    ),
+)

{rekordbox_edit-0.12.0.dev17 → rekordbox_edit-0.13.0.dev7}/rekordbox_edit/api/_edit.py

@@ -5,6 +5,7 @@ import logging
 from pyrekordbox import Rekordbox6Database
 
 from rekordbox_edit.api._utils import (
+    reserve_usns,
     stamp_usns,
     track_from_content,
     writing,
@@ -141,12 +142,19 @@ def edit(
     old_values: dict[str, str | None] = {}
     edited = []
     with writing(db, "edit"):
+        # Shared records the edit creates or collects along the way each take a
+        # USN too, the same as the tracks themselves.
+        created: list = []
+        collected = 0
         for content in contents:
             if str(content.ID) in new_values:
                 old_values[str(content.ID)] = handler.current_value(content)
-                handler.apply(db, content, new_values[str(content.ID)])
+                incidental = handler.apply(db, content, new_values[str(content.ID)])
+                created.extend(incidental.created)
+                collected += incidental.deleted
                 edited.append(content)
-        stamp_usns(db, edited)
+        stamp_usns(db, [*edited, *created])
+        reserve_usns(db, collected)
         db.session.commit()
         _logger.debug(f"edit committed {len(ops)} change(s) on field={args.field}")
 

{rekordbox_edit-0.12.0.dev17 → rekordbox_edit-0.13.0.dev7}/rekordbox_edit/api/_field_handlers.py

@@ -8,11 +8,17 @@ own encoding or relational lookup.
 
 import logging
 import os
+from typing import NamedTuple
 
 from pyrekordbox import Rekordbox6Database
 from pyrekordbox.db6 import tables as tb
-from sqlalchemy import or_
 
+from rekordbox_edit._tag_fields import TAG_FIELDS, TagField
+from rekordbox_edit.api._relations import (
+    RELATIONS,
+    delete_if_orphaned,
+    get_or_create,
+)
 from rekordbox_edit.api._utils import _sync_audio_columns, _update_anlz_paths
 from rekordbox_edit.errors import DependencyMissingError
 from rekordbox_edit.models import EditRequest, SkipReason
@@ -28,6 +34,22 @@ from rekordbox_edit.utils import (
 _logger = logging.getLogger(__name__)
 
 
+class IncidentalRows(NamedTuple):
+    """Rows a write touched besides the track itself.
+
+    Rekordbox gives every row it writes a USN, so the caller stamps `created`
+    and reserves one USN per row in `deleted`, which no longer exists to carry
+    a stamp of its own.
+    """
+
+    created: tuple = ()
+    deleted: int = 0
+
+
+#: What a handler writing nothing but the track's own row returns.
+NO_INCIDENTAL_ROWS = IncidentalRows()
+
+
 class FieldHandler:
     """Read, compute, validate, and apply one editable field."""
 
@@ -59,7 +81,9 @@ class FieldHandler:
         """New value as a string, or None to signal no change / skip."""
         raise NotImplementedError  # pragma: no cover
 
-    def apply(self, db: Rekordbox6Database, content, new_value: str) -> None:
+    def apply(self, db: Rekordbox6Database, content, new_value: str) -> IncidentalRows:
+        """Write the new value, returning the rows the write added or removed
+        alongside the track's own."""
         raise NotImplementedError  # pragma: no cover
 
     def post_commit(
@@ -99,6 +123,7 @@ class StringField(FieldHandler):
 
     def apply(self, db, content, new_value):
         setattr(content, self.column, new_value)
+        return NO_INCIDENTAL_ROWS
 
 
 class RatingField(FieldHandler):
@@ -123,21 +148,55 @@ class RatingField(FieldHandler):
 
     def apply(self, db, content, new_value):
         content.Rating = star_rating_to_stored(int(new_value))
+        return NO_INCIDENTAL_ROWS
 
 
-# Every DjmdContent column pointing at a DjmdArtist row; an artist is orphaned
-# only when none of these, nor any album's AlbumArtistID, still reference it.
-_ARTIST_ROLE_COLUMNS = (
-    tb.DjmdContent.ArtistID,
-    tb.DjmdContent.RemixerID,
-    tb.DjmdContent.OrgArtistID,
-    tb.DjmdContent.ComposerID,
-    tb.DjmdContent.Lyricist,
-)
+class IntegerField(FieldHandler):
+    """A whole-number column: track number, disc number, or release year.
+
+    `--match` does not apply, so the value is validated once per request
+    rather than per track. A cleared value writes 0, the value an import
+    stores for a tag the file does not carry.
+    """
+
+    supports_match = False
+
+    def __init__(self, name: str, column: str):
+        self.name = name
+        self.column = column
+
+    def validate_request(self, args):
+        if args.match_pattern is not None:
+            _logger.warning(
+                f"--match does not apply to {self.name}; setting the value directly"
+            )
+        self._parse(args.replace_value)  # raises ValueError on bad input
+
+    def _parse(self, value: str) -> int:
+        if value == "":
+            return 0
+        try:
+            return int(value)
+        except ValueError:
+            raise ValueError(
+                f"{self.name} must be a whole number, got {value!r}"
+            ) from None
+
+    def current_value(self, content):
+        stored = getattr(content, self.column)
+        return None if stored is None else str(stored)
+
+    def compute_new_value(self, current, args):
+        return str(self._parse(args.replace_value))
+
+    def apply(self, db, content, new_value):
+        setattr(content, self.column, int(new_value))
+        return NO_INCIDENTAL_ROWS
 
 
 class RelationalField(FieldHandler):
-    """Artist or album: a shared record reached through a foreign key.
+    """A shared record reached through a foreign key: artist, album, genre, or
+    label.
 
     Setting the value reuses an existing record with the same name or creates
     one, then repoints the track. A record left with no references is deleted,
@@ -161,59 +220,15 @@ class RelationalField(FieldHandler):
 
     def apply(self, db, content, new_value):
         old_id = getattr(content, self.fk_column)
+        created: list = []
         if new_value == "":
-            setattr(content, self.fk_column, "")
+            setattr(content, self.fk_column, RELATIONS[self.kind].empty_value)
         else:
-            record = self._get_or_create(db, new_value)
+            record = get_or_create(db, self.kind, new_value, created)
             setattr(content, self.fk_column, record.ID)
         db.session.flush()
-        self._delete_if_orphaned(db, old_id)
-
-    def _get_or_create(self, db, name):
-        if self.kind == "artist":
-            existing = (
-                db.session.query(tb.DjmdArtist)
-                .filter_by(Name=name)
-                .order_by(tb.DjmdArtist.ID)
-                .first()
-            )
-            return existing or db.add_artist(name)
-        existing = (
-            db.session.query(tb.DjmdAlbum)
-            .filter_by(Name=name)
-            .order_by(tb.DjmdAlbum.ID)
-            .first()
-        )
-        return existing or db.add_album(name)
-
-    def _delete_if_orphaned(self, db, old_id):
-        if old_id in (None, ""):
-            return
-        if self.kind == "artist":
-            in_content = (
-                db.session.query(tb.DjmdContent)
-                .filter(or_(*(col == old_id for col in _ARTIST_ROLE_COLUMNS)))
-                .first()
-            )
-            in_album = (
-                db.session.query(tb.DjmdAlbum)
-                .filter(tb.DjmdAlbum.AlbumArtistID == old_id)
-                .first()
-            )
-            if in_content is None and in_album is None:
-                row = db.get_artist(ID=old_id)
-                if row is not None:
-                    db.delete(row)
-        else:
-            in_content = (
-                db.session.query(tb.DjmdContent)
-                .filter(tb.DjmdContent.AlbumID == old_id)
-                .first()
-            )
-            if in_content is None:
-                row = db.get_album(ID=old_id)
-                if row is not None:
-                    db.delete(row)
+        collected = delete_if_orphaned(db, self.kind, old_id)
+        return IncidentalRows(tuple(created), collected)
 
 
 class FolderPathField(FieldHandler):
@@ -304,6 +319,12 @@ class FolderPathField(FieldHandler):
             content.OrgFolderPath = new_value
         content.FolderPath = new_value
         content.FileNameL = new_value.rsplit("/", 1)[-1]
+        self._sync_from_file(content, new_value)
+        return NO_INCIDENTAL_ROWS
+
+    def _sync_from_file(self, content, new_value) -> None:
+        """Rewrite the columns describing the audio file, when there is a
+        changed file to read them from."""
         if not os.path.exists(new_value):
             return
         file_size = os.path.getsize(new_value)
@@ -337,13 +358,28 @@ class FolderPathField(FieldHandler):
         return cue is not None
 
 
+def _handler_for(tag_field: TagField) -> FieldHandler:
+    """The handler for one editable tag, chosen by how its column stores the
+    value: through a foreign key, as a number, or as text."""
+    name = tag_field.edit_field
+    assert name is not None and tag_field.column is not None
+    if tag_field.relation is not None:
+        assert tag_field.proxy is not None
+        return RelationalField(
+            name, tag_field.column, tag_field.proxy, tag_field.relation
+        )
+    if isinstance(tag_field.default, int):
+        return IntegerField(name, tag_field.column)
+    return StringField(name, tag_field.column)
+
+
+#: Every field `edit` can change. The tag-backed ones come from TAG_FIELDS so
+#: `edit` and `import` cannot drift apart; Rating and FolderPath are not audio
+#: tags and are declared here.
 FIELD_HANDLERS: dict[str, FieldHandler] = {
     handler.name: handler
     for handler in (
-        StringField("Title", "Title"),
-        StringField("Comment", "Commnt"),
-        RelationalField("ArtistName", "ArtistID", "ArtistName", "artist"),
-        RelationalField("AlbumName", "AlbumID", "AlbumName", "album"),
+        *(_handler_for(f) for f in TAG_FIELDS if f.edit_field is not None),
         RatingField(),
         FolderPathField(),
     )

{rekordbox_edit-0.12.0.dev17 → rekordbox_edit-0.13.0.dev7}/rekordbox_edit/api/_import.py

@@ -9,6 +9,8 @@ from typing import NamedTuple, cast
 from pyrekordbox import Rekordbox6Database
 from pyrekordbox.db6 import tables as tb
 
+from rekordbox_edit._tag_fields import TAG_FIELDS
+from rekordbox_edit.api._relations import RELATIONS, find_by_name, get_or_create
 from rekordbox_edit.api._utils import stamp_usns, track_from_content, writing
 from rekordbox_edit.errors import (
     DirectoryConfirmationRequired,
@@ -162,60 +164,38 @@ IMPORT_DEFAULTS: dict[str, object] = {
 }
 
 
-def _get_or_create(db, table, name: str, factory, created: list | None = None):
-    """Reuse a row matching by name, else create one.
-
-    Same query shape as RelationalField._get_or_create in api/field_handlers.py,
-    generalized over a table and factory so one function covers all five
-    relational columns instead of a per-kind branch.
-
-    New rows are appended to `created` when given: add_content flushes,
-    which moves them out of session.new before they can be found again.
-    """
-    existing = db.session.query(table).filter_by(Name=name).order_by(table.ID).first()
-    if existing is not None:
-        return existing
-    row = factory(name)
-    if created is not None:
-        created.append(row)
-    return row
-
-
 def _resolve_relations(
     db: Rekordbox6Database, tags: TrackTags, created: list | None = None
 ) -> dict[str, str]:
     """Foreign keys for a track's tags, creating shared rows as needed.
 
     A tag that is absent yields no key, leaving the column at add_content's
-    default. KeyID is the exception: DjmdKey is a fixed table with no add_key
-    helper, so an unmatched key falls back to Rekordbox's '0' sentinel.
+    default. A closed relation is the exception: DjmdKey cannot be added to,
+    so an unmatched key falls back to Rekordbox's '0' sentinel.
     """
-    session = require_session(db)
     relations: dict[str, str] = {}
-    for field, column, table, factory in (
-        ("artist", "ArtistID", tb.DjmdArtist, db.add_artist),
-        ("composer", "ComposerID", tb.DjmdArtist, db.add_artist),
-        ("album", "AlbumID", tb.DjmdAlbum, db.add_album),
-        ("genre", "GenreID", tb.DjmdGenre, db.add_genre),
-        ("label", "LabelID", tb.DjmdLabel, db.add_label),
-    ):
-        value = tags.get(field)
-        if value:
-            relations[column] = _get_or_create(db, table, value, factory, created).ID
-
-    key = tags.get("key")
-    row = (
-        session.query(tb.DjmdKey)
-        .filter_by(ScaleName=key)
-        .order_by(tb.DjmdKey.ID)
-        .first()
-        if key
-        else None
-    )
-    relations["KeyID"] = row.ID if row else "0"
+    for tag_field in TAG_FIELDS:
+        if tag_field.relation is None:
+            continue
+        value = tags.get(tag_field.tag)
+        relation = RELATIONS[tag_field.relation]
+        if not relation.sweepable:
+            row = find_by_name(db, tag_field.relation, value) if value else None
+            relations[tag_field.column] = row.ID if row else relation.empty_value
+        elif value:
+            relations[tag_field.column] = get_or_create(
+                db, tag_field.relation, value, created
+            ).ID
     return relations
 
 
+def _scalar_columns(tags: TrackTags) -> dict[str, str | int]:
+    """Column values for the tags stored on the DjmdContent row itself."""
+    return {
+        f.column: tags.get(f.tag) or f.default for f in TAG_FIELDS if f.relation is None
+    }
+
+
 def _created_date(path: str) -> str:
     """The file's creation date, as Rekordbox records DateCreated.
 
@@ -244,12 +224,7 @@ def _build_content(
         candidate.stored,
         **IMPORT_DEFAULTS,
         **_resolve_relations(db, tags, created),
-        Title=tags["title"],
-        Commnt=tags["comment"] or "",
-        ISRC=tags["isrc"] or "",
-        TrackNo=tags["track_no"] or 0,
-        DiscNo=tags["disc_no"] or 0,
-        ReleaseYear=tags["release_year"] or 0,
+        **_scalar_columns(tags),
         Length=tags["length"] or 0,
     )
     # add_content types by extension, mapping every .m4a to AAC, and stamps