rekordbox-edit 0.5.1.dev4__tar.gz → 0.6.0.dev10__tar.gz

{rekordbox_edit-0.5.1.dev4 → rekordbox_edit-0.6.0.dev10}/CHANGELOG.md

@@ -1,6 +1,34 @@
-## v0.5.1.dev4 (2026-06-08)
-
-
+## v0.6.0.dev10 (2026-06-08)
+
+
+- test: restore coverage lost during api/cli redesign
+- Restore tests for ffmpeg conversion internals, post-commit/rollback
+paths, and the CLI preview-confirm-commit default flow that the
+single-function API redesign dropped. Coverage recovers from 87% to
+97% (baseline pre-redesign was 98%) and the test count from 200 to
+238.
+- refactor: privatize module-internal helpers and unify cli print helpers
+- - api/convert.py: prefix module-private helpers with underscore
+  (_convert_to_lossless, _convert_to_mp3, _update_database_record,
+  _cleanup_converted_files, _rollback_and_cleanup, _get_output_path)
+- cli/{edit,convert}.py: rename _render_*_response to _print_*_result
+- fix(api,cli): fixups post refactor
+- - convert(): on post-commit re-query failure, fall back to pre-mutation
+  snapshot tracks instead of an empty list, so the response validator
+  doesn't raise after a successful commit
+- cli/convert.py: remove duplicate "Deleted N" log in the default flow
+- cli/edit.py: log "No changes to make." in --yes path when no edits
+- Adds a regression test for the post-commit re-query fallback.
+- feat(api,cli)!: redesign around single-function commands
+- Replace the plan/execute split with one function per command that takes
+an optional dry_run kwarg. Each command (search, edit, convert) now
+returns a typed response envelope with tracks plus a command-specific
+result. CLI restructured to preview-then-commit by default and to call
+the API exactly once when --yes or --dry-run is given.
+- BREAKING CHANGE: drops plan_edit/plan_convert. The public API surface is
+now search/edit/convert; old EditPlanArgs/ConvertPlanArgs types removed.
+- feat: add new `--print json` option
+- refactor: Allow extra columns to ride with Track instances
 - chore(deps): update linters to v0.15.16 (#76)
 - Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 - fix: handle stdin BOM character on windows

{rekordbox_edit-0.5.1.dev4 → rekordbox_edit-0.6.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rekordbox-edit
-Version: 0.5.1.dev4
+Version: 0.6.0.dev10
 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.5.1.dev4 → rekordbox_edit-0.6.0.dev10}/pyproject.toml

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

{rekordbox_edit-0.5.1.dev4 → rekordbox_edit-0.6.0.dev10}/rekordbox_edit/__init__.py

@@ -4,6 +4,6 @@ __version__ = "0.1.0"
 __author__ = "James Viall"
 __email__ = "jamesviall@pm.me"
 
-from rekordbox_edit.api import convert, edit, plan_convert, plan_edit, search
+from rekordbox_edit.api import convert, edit, search
 
-__all__ = ["search", "plan_edit", "edit", "plan_convert", "convert"]
+__all__ = ["search", "edit", "convert"]

{rekordbox_edit-0.5.1.dev4 → rekordbox_edit-0.6.0.dev10}/rekordbox_edit/_click.py

@@ -8,6 +8,7 @@ class PrintChoice(Enum):
     IDS = 1
     INFO = 2
     DEBUG = 3
+    JSON = 4
 
 
 print_option = click.option(
@@ -15,7 +16,7 @@ print_option = click.option(
     "print_opt",  # avoid shadowing the print() function
     default="info",
     type=click.Choice(PrintChoice, case_sensitive=False),
-    help="Configures the kind of console output you want from the command, if any. The 'ids' option can be used to pipe a list of resulting content IDs into to another command.",
+    help="Configures the kind of console output you want from the command, if any. Use 'ids' to pipe a list of resulting content IDs or 'json' to pipe full track records into another command.",
 )
 
 track_ids_argument = click.argument("track-ids", type=str, required=False, nargs=-1)

rekordbox_edit-0.6.0.dev10/rekordbox_edit/api/__init__.py

@@ -0,0 +1,11 @@
+"""Public API for rekordbox-edit.
+
+Usage:
+    from rekordbox_edit.api import search, edit, convert
+"""
+
+from rekordbox_edit.api.convert import convert
+from rekordbox_edit.api.edit import edit
+from rekordbox_edit.api.search import search
+
+__all__ = ["search", "edit", "convert"]

rekordbox_edit-0.6.0.dev10/rekordbox_edit/api/_utils.py

@@ -0,0 +1,31 @@
+from collections.abc import Sequence
+
+from pyrekordbox.db6 import DjmdContent
+
+from rekordbox_edit.models import ConvertOp, EditOp, Track
+
+_COLUMN_KEYS = tuple(c.key for c in DjmdContent.__table__.columns)
+
+
+def _track_from_content(content: DjmdContent) -> Track:
+    data = {k: getattr(content, k) for k in _COLUMN_KEYS}
+    data["ID"] = str(data["ID"])
+    # association_proxy attributes; not present in __table__.columns
+    data["ArtistName"] = content.ArtistName
+    data["AlbumName"] = content.AlbumName
+    return Track(**data)
+
+
+def _order_tracks_by_op(
+    contents: Sequence[DjmdContent], ops: Sequence[EditOp | ConvertOp]
+) -> list[Track]:
+    """Build Track list in op order from raw DjmdContent rows.
+
+    Builds the id -> content lookup internally so callers don't have to. Ops
+    whose id is not in `contents` are silently skipped (the caller already
+    knows about the divergence from upstream logic).
+    """
+    content_map = {str(c.ID): c for c in contents}
+    return [
+        _track_from_content(content_map[op.id]) for op in ops if op.id in content_map
+    ]

{rekordbox_edit-0.5.1.dev4 → rekordbox_edit-0.6.0.dev10}/rekordbox_edit/api/convert.py

@@ -8,13 +8,18 @@ from typing import Tuple
 
 import ffmpeg
 from ffmpeg import Error as FfmpegError
-from pydantic import BaseModel
 from pyrekordbox import Rekordbox6Database
 from pyrekordbox.db6 import DjmdContent
 from sqlalchemy import select
 
-from rekordbox_edit.api._utils import _track_from_content
-from rekordbox_edit.models import ConvertPlanArgs, Track
+from rekordbox_edit.api._utils import _order_tracks_by_op
+from rekordbox_edit.models import (
+    ConvertArgs,
+    ConvertOp,
+    ConvertResponse,
+    ConvertResult,
+    SkippedTrack,
+)
 from rekordbox_edit.query import get_filtered_content
 from rekordbox_edit.utils import (
     OutputFormats,
@@ -26,10 +31,10 @@ from rekordbox_edit.utils import (
 logger = logging.getLogger(__name__)
 
 
-# ── Helpers  ──────────────────────────────────────────────────────────────
+# ── ffmpeg helpers ────────────────────────────────────────────────────────
 
 
-def convert_to_lossless(input_path, output_path, output_format):
+def _convert_to_lossless(input_path, output_path, output_format):
     """Convert lossless file to another lossless format, preserving bit depth."""
     from rekordbox_edit.utils import ffmpeg_in_path, get_ffmpeg_directions
 
@@ -62,12 +67,10 @@ def convert_to_lossless(input_path, output_path, output_format):
 
     logger.debug(f"Selected codec: {codec} (bit_depth={bit_depth})")
 
-    output_options = {"acodec": codec, "map_metadata": 0, "write_id3v2": 1}
-
     try:
         (
             ffmpeg.input(input_path)
-            .output(output_path, **output_options)
+            .output(output_path, acodec=codec, map_metadata=0, write_id3v2=1)
             .overwrite_output()
             .run(capture_stdout=True, capture_stderr=True)
         )
@@ -84,7 +87,7 @@ def convert_to_lossless(input_path, output_path, output_format):
         raise e
 
 
-def convert_to_mp3(input_path, mp3_path):
+def _convert_to_mp3(input_path, mp3_path):
     """Convert lossless file to MP3 320kbps CBR."""
     from rekordbox_edit.utils import ffmpeg_in_path, get_ffmpeg_directions
 
@@ -92,24 +95,18 @@ def convert_to_mp3(input_path, mp3_path):
         raise Exception(f"FFmpeg not found in PATH.{get_ffmpeg_directions()}")
 
     try:
-        acodec = "libmp3lame"
-        audio_bitrate = "320k"
-        map_metadata = 0
-        write_id3v2 = 1
-
         (
             ffmpeg.input(input_path)
             .output(
                 mp3_path,
-                acodec=acodec,
-                audio_bitrate=audio_bitrate,
-                map_metadata=map_metadata,
-                write_id3v2=write_id3v2,
+                acodec="libmp3lame",
+                audio_bitrate="320k",
+                map_metadata=0,
+                write_id3v2=1,
             )
             .overwrite_output()
             .run(capture_stdout=True, capture_stderr=True)
         )
-
         logger.debug(f"Conversion to mp3 succeeded: {mp3_path}")
         return True
     except FfmpegError as e:
@@ -123,7 +120,7 @@ def convert_to_mp3(input_path, mp3_path):
         raise e
 
 
-def update_database_record(
+def _update_database_record(
     db, content_id, new_filename, new_folder, output_format
 ) -> None:
     """Update database record with new file information."""
@@ -146,17 +143,14 @@ def update_database_record(
     if output_format.upper() in ["AIFF", "FLAC", "WAV"]:
         converted_bit_depth = converted_audio_info["bit_depth"]
         database_bit_depth = getattr(content, "BitDepth", None)
-        logger.debug(
-            f"Bit depth check: database={database_bit_depth}, file={converted_bit_depth}"
-        )
-
         if (
             database_bit_depth
             and converted_bit_depth
             and converted_bit_depth != database_bit_depth
         ):
             raise Exception(
-                f"Bit depth mismatch for lossless transcode: database={database_bit_depth}, file={converted_bit_depth}"
+                f"Bit depth mismatch for lossless transcode: "
+                f"database={database_bit_depth}, file={converted_bit_depth}"
             )
 
     content.FileNameL = new_filename
@@ -166,28 +160,22 @@ def update_database_record(
     # FLAC stores bitrate as 0 in Rekordbox to represent VBR
     if output_format.upper() == "FLAC":
         content.BitRate = 0
-        logger.debug(
-            f"Set FileType={file_type}, BitRate=0 (FLAC), FolderPath={converted_full_path}"
-        )
     else:
         content.BitRate = converted_bitrate
-        logger.debug(
-            f"Set FileType={file_type}, BitRate={converted_bitrate}, FolderPath={converted_full_path}"
-        )
 
 
-def cleanup_converted_files(converted_files) -> None:
-    """Clean up converted files on error or rollback."""
+def _cleanup_converted_files(converted_ops: list[ConvertOp]) -> None:
+    """Clean up converted output files on error or rollback."""
     logger.debug("Cleaning up converted files due to aborted conversion.")
-    for file_info in converted_files:
+    for op in converted_ops:
         try:
-            os.remove(file_info["output_path"])
-            logger.debug(f"Cleaned up {file_info['output_path']}")
+            os.remove(op.output_path)
+            logger.debug(f"Cleaned up {op.output_path}")
         except Exception:
             pass
 
 
-def rollback_and_cleanup(db, converted_files) -> None:
+def _rollback_and_cleanup(db, converted_ops: list[ConvertOp]) -> None:
     """Roll back the database session and clean up any converted files."""
     logger.debug("Attempting DB session rollback.")
     rollback_error = None
@@ -200,15 +188,13 @@ def rollback_and_cleanup(db, converted_files) -> None:
                 "Check the state of your rekordbox library and consider reverting to a backup database if something's not right"
             )
             rollback_error = e
-    else:
-        logger.debug("No DB session to rollback.")
-    if converted_files:
-        cleanup_converted_files(converted_files)
+    if converted_ops:
+        _cleanup_converted_files(converted_ops)
     if rollback_error:
         raise rollback_error
 
 
-def get_output_path(content, output_format) -> Tuple[str, str, str]:
+def _get_output_path(content, output_format) -> Tuple[str, str, str]:
     """Calculate output path for a content item."""
     src_folder_path = os.path.normpath(content.FolderPath or "")
     src_file_name = content.FileNameL or ""
@@ -220,149 +206,193 @@ def get_output_path(content, output_format) -> Tuple[str, str, str]:
     return output_path, output_filename, src_dirname
 
 
-# ── Result types ──────────────────────────────────────────────────────────
-
-
-class ConvertPlan(BaseModel):
-    files: list[Track]
-    skipped: list[Track]  # files skipped due to existing output (no overwrite)
-    should_delete: bool
-    format_out: str
-
+# ── Classifier ────────────────────────────────────────────────────────────
 
-class ConvertResult(BaseModel):
-    converted: list[dict]  # {source_path, output_path, content_id}
-    deleted: int
 
-
-# ── API functions ─────────────────────────────────────────────────────────
-
-
-def plan_convert(db: Rekordbox6Database, args: ConvertPlanArgs) -> ConvertPlan:
-    """Determine which tracks need conversion and resolve delete behaviour."""
-    should_delete = (
-        args.delete if args.delete is not None else args.format_out.upper() != "MP3"
+def _classify_convert(content, args: ConvertArgs) -> ConvertOp | SkippedTrack:
+    """Return ConvertOp if this track should be converted, or SkippedTrack with
+    reason if not."""
+    target = get_file_type_for_format(args.format_out)
+    mp3 = get_file_type_for_format("MP3")
+    m4a = get_file_type_for_format("M4A")
+    if content.FileType in (target, mp3, m4a):
+        logger.debug(
+            f"skip convert id={content.ID} reason=already_target_format "
+            f"file_type={content.FileType} target={target}"
+        )
+        return SkippedTrack(id=str(content.ID), reason="already_target_format")
+    output_path, _, _ = _get_output_path(content, args.format_out)
+    if not args.overwrite and os.path.exists(output_path):
+        logger.debug(
+            f"skip convert id={content.ID} reason=output_file_exists path={output_path}"
+        )
+        return SkippedTrack(id=str(content.ID), reason="output_file_exists")
+    return ConvertOp(
+        id=str(content.ID),
+        source_path=content.FolderPath or "",
+        output_path=output_path,
     )
 
-    result = get_filtered_content(db, args)
-    filtered_content = result.scalars().all()
-
-    target_file_type = get_file_type_for_format(args.format_out)
-    mp3_type = get_file_type_for_format("MP3")
-    m4a_type = get_file_type_for_format("M4A")
 
-    needs_conversion = [
-        c
-        for c in filtered_content
-        if c.FileType != target_file_type
-        and c.FileType != mp3_type
-        and c.FileType != m4a_type
-    ]
-
-    if args.overwrite:
-        files = needs_conversion
-        skipped = []
-    else:
-        files, skipped = [], []
-        for content in needs_conversion:
-            output_path, _, _ = get_output_path(content, args.format_out)
-            if os.path.exists(output_path):
-                skipped.append(content)
-            else:
-                files.append(content)
-
-    logger.debug(
-        f"plan_convert: {len(files)} to convert, {len(skipped)} skipped (conflict)"
-    )
+# ── Public API ────────────────────────────────────────────────────────────
 
-    return ConvertPlan(
-        files=[_track_from_content(c) for c in files],
-        skipped=[_track_from_content(c) for c in skipped],
-        should_delete=should_delete,
-        format_out=args.format_out,
-    )
 
+def convert(
+    db: Rekordbox6Database,
+    args: ConvertArgs,
+    *,
+    dry_run: bool = False,
+) -> ConvertResponse:
+    """Convert audio files to a target format and update the Rekordbox database.
 
-def convert(db: Rekordbox6Database, plan: ConvertPlan) -> ConvertResult:
-    """Execute a ConvertPlan: convert files and update the database.
+    With `dry_run=True`, returns the planned conversions without any ffmpeg or
+    DB writes. With `dry_run=False` (default), commits the changes.
 
-    Uses try/except BaseException so KeyboardInterrupt triggers rollback before
-    the exception propagates to the caller.
+    The rollback block protects only pre-commit work; once commit lands, the
+    transaction is honoured even if the delete-originals loop or response
+    re-query later fails.
     """
     from rekordbox_edit.utils import ffmpeg_in_path, get_ffmpeg_directions
 
-    if not plan.files:
-        return ConvertResult(converted=[], deleted=0)
+    logger.debug(f"convert start format_out={args.format_out} dry_run={dry_run}")
 
     if not ffmpeg_in_path():
+        logger.debug("convert aborted: FFmpeg not in PATH")
         raise RuntimeError(
             f"FFmpeg is required but not found in PATH.{get_ffmpeg_directions()}"
         )
 
+    contents = get_filtered_content(db, args).scalars().all()
+    logger.debug(f"convert fetched {len(contents)} candidate(s) from filter")
+
+    ops: list[ConvertOp] = []
+    skipped: list[SkippedTrack] = []
+    for c in contents:
+        result = _classify_convert(c, args)
+        if isinstance(result, ConvertOp):
+            ops.append(result)
+        else:
+            skipped.append(result)
+    logger.debug(f"convert classified ops={len(ops)} skipped={len(skipped)}")
+
+    if dry_run:
+        logger.debug(f"convert dry-run return with {len(ops)} planned conversion(s)")
+        return ConvertResponse(
+            tracks=_order_tracks_by_op(contents, ops),
+            result=ConvertResult(
+                format_out=args.format_out,
+                converted=ops,
+                deleted=0,
+                skipped=skipped,
+            ),
+        )
+
+    if not ops:
+        return ConvertResponse(
+            tracks=[],
+            result=ConvertResult(
+                format_out=args.format_out,
+                converted=[],
+                deleted=0,
+                skipped=skipped,
+            ),
+        )
+
     assert db.session is not None
 
-    ids = [t.ID for t in plan.files]
-    contents = (
-        db.session.execute(select(DjmdContent).where(DjmdContent.ID.in_(ids)))
-        .scalars()
-        .all()
+    should_delete = (
+        args.delete if args.delete is not None else args.format_out.upper() != "MP3"
+    )
+    logger.debug(
+        f"convert should_delete={should_delete} "
+        f"(args.delete={args.delete}, format_out={args.format_out})"
     )
-    content_map = {str(c.ID): c for c in contents}
 
-    converted_files: list[dict] = []
+    # content_map enables per-op live FolderPath / FileNameL reads in the loop.
+    content_map = {str(c.ID): c for c in contents}
+    converted_ops: list[ConvertOp] = []
     try:
-        for i, track in enumerate(plan.files, 1):
-            content = content_map[track.ID]
-            src_folder_path = content.FolderPath or ""
-            output_path, output_filename, src_dirname = get_output_path(
-                content, plan.format_out
-            )
-
-            logger.info(f"[{i}/{len(plan.files)}] {content.FileNameL}")
+        for i, op in enumerate(ops, 1):
+            content = content_map[op.id]
+            src = content.FolderPath or ""
+            logger.info(f"[{i}/{len(ops)}] {content.FileNameL}")
 
-            if not os.path.exists(src_folder_path):
-                raise RuntimeError(f"Source not found: {src_folder_path}")
+            if not os.path.exists(src):
+                raise RuntimeError(f"Source not found: {src}")
 
-            if plan.format_out.upper() == "MP3":
-                success = convert_to_mp3(src_folder_path, output_path)
+            if args.format_out.upper() == "MP3":
+                success = _convert_to_mp3(src, op.output_path)
             else:
-                success = convert_to_lossless(
-                    src_folder_path, output_path, OutputFormats(plan.format_out.lower())
+                success = _convert_to_lossless(
+                    src, op.output_path, OutputFormats(args.format_out.lower())
                 )
 
             if not success:
-                raise RuntimeError(f"Conversion failed for {src_folder_path}")
-
-            if not os.path.exists(output_path):
-                raise RuntimeError(f"Output file not created: {output_path}")
-
-            update_database_record(
-                db, content.ID, output_filename, src_dirname, plan.format_out.upper()
+                raise RuntimeError(f"Conversion failed for {src}")
+            if not os.path.exists(op.output_path):
+                raise RuntimeError(f"Output file not created: {op.output_path}")
+
+            _update_database_record(
+                db,
+                op.id,
+                os.path.basename(op.output_path),
+                os.path.dirname(op.output_path),
+                args.format_out.upper(),
             )
-            converted_files.append(
-                {
-                    "source_path": src_folder_path,
-                    "output_path": output_path,
-                    "content_id": content.ID,
-                }
+            converted_ops.append(
+                ConvertOp(id=op.id, source_path=src, output_path=op.output_path)
             )
 
         db.session.commit()
         logger.info(
-            f"\nConverted {len(converted_files)} files to {plan.format_out.upper()}"
+            f"\nConverted {len(converted_ops)} files to {args.format_out.upper()}"
         )
-
-        deleted = 0
-        if plan.should_delete:
-            for file_info in converted_files:
-                try:
-                    os.remove(file_info["source_path"])
-                    deleted += 1
-                except Exception as e:
-                    logger.warning(f"Failed to delete {file_info['source_path']}: {e}")
-
-        return ConvertResult(converted=converted_files, deleted=deleted)
-
+        logger.debug(f"convert committed {len(converted_ops)} conversion(s)")
     except BaseException:
-        rollback_and_cleanup(db, converted_files)
+        logger.debug(
+            f"convert rolling back after {len(converted_ops)} partial conversion(s)"
+        )
+        _rollback_and_cleanup(db, converted_ops)
         raise
+
+    deleted = 0
+    if should_delete:
+        for op in converted_ops:
+            try:
+                os.remove(op.source_path)
+                deleted += 1
+            except Exception as e:
+                logger.warning(f"Failed to delete {op.source_path}: {e}")
+        logger.debug(f"convert deleted {deleted}/{len(converted_ops)} source file(s)")
+
+    converted_ids = [op.id for op in converted_ops]
+    try:
+        post_contents = (
+            db.session.execute(
+                select(DjmdContent).where(DjmdContent.ID.in_(converted_ids))
+            )
+            .scalars()
+            .all()
+        )
+        logger.debug(
+            f"convert post-commit re-query returned {len(post_contents)} track(s)"
+        )
+        tracks = _order_tracks_by_op(post_contents, converted_ops)
+    except Exception as e:
+        # Fall back to pre-mutation snapshots so the response stays valid;
+        # the commit succeeded, the caller should not see an alignment error.
+        logger.warning(
+            f"Failed to re-query tracks after commit; falling back to "
+            f"pre-mutation snapshots: {e}"
+        )
+        tracks = _order_tracks_by_op(list(content_map.values()), converted_ops)
+
+    return ConvertResponse(
+        tracks=tracks,
+        result=ConvertResult(
+            format_out=args.format_out,
+            converted=converted_ops,
+            deleted=deleted,
+            skipped=skipped,
+        ),
+    )