beets-unskipper 1.0.0__tar.gz

beets_unskipper-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+.idea
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+tests/

beets_unskipper-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florent Le Moël
+
+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.

beets_unskipper-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: beets-unskipper
+Version: 1.0.0
+Summary: Beets plugin to browse and edit the import state file (state.pickle) with a small TUI
+Project-URL: Homepage, https://github.com/FlorentLM/beets-unskipper
+Project-URL: Issues, https://github.com/FlorentLM/beets-unskipper/issues
+Author-email: Florent Le Moël <25004801+FlorentLM@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: beets,beetsplug,import,music,skipped,tui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: <3.15,>=3.10
+Requires-Dist: beets>=2.11.0
+Description-Content-Type: text/markdown
+
+# beets-unskipper
+
+A [beets](https://beets.io) plugin to browse and edit beets' import state
+file (`state.pickle`) with a small terminal UI.
+
+Beets records already-imported directories in `state.pickle`, and then any other import with
+`--incremental` will skip anything listed in there. `unskipper` lets you browse this
+file and remove ("unskip") entries, so beets will reconsider them next time you import.
+
+It also keeps a human-readable sidecar file (`<statefile>.unskipper.json`) with additional data
+per item, recorded automatically during import, and that can be used to rebuild a lost
+or corrupted `state.pickle`.
+
+<div align="center">
+<img src="screenshot.png" alt="Screenshot of te plugin's interface" width="900">
+</div>
+
+## Installation
+
+```sh
+git clone https://github.com/FlorentLM/beets-unskipper
+uv pip install beets-unskipper
+```
+
+or with Beets' default `uv tool` install:
+
+```sh
+uv tool install beets --with ./beets-unskipper --reinstall
+```
+
+Then add `unskipper` to the `plugins` line in your beets config.
+
+## Usage
+
+```sh
+beet unskipper
+```
+
+| Option                     | Description                                                               |
+|----------------------------|---------------------------------------------------------------------------|
+| `-s`, `--state-file`       | Path to `state.pickle` (default: beets' configured location)              |
+| `-j`, `--unskipper-json`   | Path to the sidecar JSON (default: alongside the state file)              |
+| `-r`, `--remap OLD=NEW`    | Remap paths starting with `OLD` to `NEW` when loading                     |
+| `--rebuild`                | Rebuild `state.pickle` from the sidecar JSON, then exit                   |
+| `--migrate-db`             | With `--remap`, rewrite item/album paths in the beets database, then exit |
+| `-d`, `--dry-run`          | With `--rebuild` or `--migrate-db`, preview changes without writing       |
+
+### Moving your music library
+
+If you move your whole library to a new location (new drive, new mount point, etc.),
+`--remap` can update everything that beets-unskipper and beets itself track, so incremental
+imports and the state UI keep working against the new paths:
+
+```sh
+beet unskipper --remap /old/path=/new/path --migrate-db    # rewrite paths in the beets database
+beet unskipper --remap /old/path=/new/path --rebuild       # rebuild state.pickle and apply the remap to the sidecar
+```
+
+Add `-d`/`--dry-run` to either command to preview what would change without writing anything.
+
+### Keys
+
+| Key                                | Action                                                                          |
+|------------------------------------|---------------------------------------------------------------------------------|
+| `↓`/`↑`                            | move                                                                            |
+| `Shift+↓`/`Shift+↑`, `PgDn`/`PgUp` | move by a page                                                                  |
+| `a`-`z`                            | jump to next row starting with that letter                                      |
+| `+`/`-`                            | jump to next entry marked new (unimported)                                      |
+| `Enter`                            | run `beet import` on the selected new folder (using your existing beets config) |
+| `space`                            | mark/unmark row                                                                 |
+| `Del`/`Backspace`                  | delete marked rows (or current one if none marked)                              |
+| `Ctrl+S`                           | save                                                                            |
+| `Esc`                              | quit                                                                            |

beets_unskipper-1.0.0/README.md

@@ -0,0 +1,73 @@
+# beets-unskipper
+
+A [beets](https://beets.io) plugin to browse and edit beets' import state
+file (`state.pickle`) with a small terminal UI.
+
+Beets records already-imported directories in `state.pickle`, and then any other import with
+`--incremental` will skip anything listed in there. `unskipper` lets you browse this
+file and remove ("unskip") entries, so beets will reconsider them next time you import.
+
+It also keeps a human-readable sidecar file (`<statefile>.unskipper.json`) with additional data
+per item, recorded automatically during import, and that can be used to rebuild a lost
+or corrupted `state.pickle`.
+
+<div align="center">
+<img src="screenshot.png" alt="Screenshot of te plugin's interface" width="900">
+</div>
+
+## Installation
+
+```sh
+git clone https://github.com/FlorentLM/beets-unskipper
+uv pip install beets-unskipper
+```
+
+or with Beets' default `uv tool` install:
+
+```sh
+uv tool install beets --with ./beets-unskipper --reinstall
+```
+
+Then add `unskipper` to the `plugins` line in your beets config.
+
+## Usage
+
+```sh
+beet unskipper
+```
+
+| Option                     | Description                                                               |
+|----------------------------|---------------------------------------------------------------------------|
+| `-s`, `--state-file`       | Path to `state.pickle` (default: beets' configured location)              |
+| `-j`, `--unskipper-json`   | Path to the sidecar JSON (default: alongside the state file)              |
+| `-r`, `--remap OLD=NEW`    | Remap paths starting with `OLD` to `NEW` when loading                     |
+| `--rebuild`                | Rebuild `state.pickle` from the sidecar JSON, then exit                   |
+| `--migrate-db`             | With `--remap`, rewrite item/album paths in the beets database, then exit |
+| `-d`, `--dry-run`          | With `--rebuild` or `--migrate-db`, preview changes without writing       |
+
+### Moving your music library
+
+If you move your whole library to a new location (new drive, new mount point, etc.),
+`--remap` can update everything that beets-unskipper and beets itself track, so incremental
+imports and the state UI keep working against the new paths:
+
+```sh
+beet unskipper --remap /old/path=/new/path --migrate-db    # rewrite paths in the beets database
+beet unskipper --remap /old/path=/new/path --rebuild       # rebuild state.pickle and apply the remap to the sidecar
+```
+
+Add `-d`/`--dry-run` to either command to preview what would change without writing anything.
+
+### Keys
+
+| Key                                | Action                                                                          |
+|------------------------------------|---------------------------------------------------------------------------------|
+| `↓`/`↑`                            | move                                                                            |
+| `Shift+↓`/`Shift+↑`, `PgDn`/`PgUp` | move by a page                                                                  |
+| `a`-`z`                            | jump to next row starting with that letter                                      |
+| `+`/`-`                            | jump to next entry marked new (unimported)                                      |
+| `Enter`                            | run `beet import` on the selected new folder (using your existing beets config) |
+| `space`                            | mark/unmark row                                                                 |
+| `Del`/`Backspace`                  | delete marked rows (or current one if none marked)                              |
+| `Ctrl+S`                           | save                                                                            |
+| `Esc`                              | quit                                                                            |

beets_unskipper-1.0.0/beetsplug/unskipper/__init__.py

@@ -0,0 +1,338 @@
+"""
+Beets plugin unskipper: browse and edit beets' import state file
+(`state.pickle`) with a small terminal UI.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Optional, Dict, Tuple
+
+from beets import ui
+from beets.importer import SentinelImportTask
+from beets.plugins import BeetsPlugin
+
+from . import sidecar
+from . import pathremap
+from .statefile import default_state_path, StateFileData
+
+
+class UnskipperPlugin(BeetsPlugin):
+
+    def __init__(self):
+        super().__init__()
+        # id(task) -> {'paths': ..., 'toppath': ..., 'task': ...}, until the task's outcome (imported/skipped) is known
+        self._pending: Dict[int, dict] = {}
+
+        self._session = None    # Session doing the touching
+        self._toppaths: set[bytes] = set()  # toppaths touched so far in the session
+
+        self.register_listener('import_task_choice', self._on_choice)
+        self.register_listener('import_task_files', self._on_files)
+        self.register_listener('cli_exit', self._on_exit)
+
+    def commands(self):
+        cmd = ui.Subcommand(
+            'unskipper',
+            help="Browse/edit beets' import state file",
+        )
+        cmd.parser.add_option(
+            '-s', '--state-file',
+            dest='state_file',
+            help='Path to state.pickle',
+        )
+        cmd.parser.add_option(
+            '-j', '--unskipper-json',
+            dest='sidecar_file',
+            help='Path to the unskipper sidecar JSON (defaults to alongside the state file)',
+        )
+        cmd.parser.add_option(
+            '-r', '--remap',
+            dest='remap',
+            metavar='OLD=NEW',
+            help='Remap paths starting with OLD to start with NEW when loading',
+        )
+        cmd.parser.add_option(
+            '--rebuild', action='store_true', dest='rebuild',
+            help="Overwrite state.pickle by rebuilding it from the sidecar JSON",
+        )
+        cmd.parser.add_option(
+            '--migrate-db', action='store_true', dest='migrate_db',
+            help="Rewrite item/album paths in the beets database using --remap OLD=NEW",
+        )
+        cmd.parser.add_option(
+            '-d', '--dry-run', action='store_true', dest='dry_run',
+            help="With --rebuild, print a summary of what would change without writing state.pickle",
+        )
+        cmd.func = self._run
+        return [cmd]
+
+    def _run(self, lib, opts, args):
+        from .app import UnskipperApp
+
+        path = Path(opts.state_file) if opts.state_file else default_state_path()
+        sidecar_path = Path(opts.sidecar_file) if opts.sidecar_file else sidecar.sidecar_path(path)
+
+        remap = None
+        if opts.remap:
+            try:
+                remap = pathremap.parse_remap_arg(opts.remap)
+            except ValueError as exc:
+                raise ui.UserError(f'--remap {exc}')
+
+        if opts.migrate_db:
+            if not remap:
+                raise ui.UserError('--migrate-db requires --remap OLD=NEW')
+            self._migrate_db(lib, remap, dry_run=bool(opts.dry_run))
+            return
+
+        if opts.rebuild:
+            self._rebuild(path, sidecar_path, remap, dry_run=bool(opts.dry_run))
+            return
+
+        if not path.exists():
+            raise ui.UserError(f'State file not found: {path}')
+
+        UnskipperApp(path, remap=remap, sidecar_path=sidecar_path, lib=lib).run()
+
+    @staticmethod
+    def _rebuild(path: Path, sidecar_path: Path, remap, dry_run: bool = False) -> None:
+        from .statefile import StateFileData, from_sidecar, load as load_state, save as save_state
+
+        if not sidecar_path.exists():
+            raise ui.UserError(f'Sidecar file not found: {sidecar_path}')
+
+        data = sidecar.load(sidecar_path)
+        new_data = data
+        if remap:
+            old, new = remap
+            new_data = pathremap.remap_sidecar(data, old, new)
+
+        new_state = from_sidecar(new_data)
+        sidecar_changed = new_data != data
+
+        if dry_run:
+            old_state = load_state(path) if path.exists() else StateFileData()
+            UnskipperPlugin._print_rebuild_diff(path, old_state, new_state)
+            if sidecar_changed:
+                print(f'  sidecar: {sidecar_path} would also be rewritten in place with remapped paths')
+            return
+
+        prompt = f'This will overwrite {path}'
+        if sidecar_changed:
+            prompt += f' and remap paths in {sidecar_path}'
+        prompt += '. Continue?'
+
+        if (path.exists() or sidecar_changed) and not ui.input_yn(prompt, require=True):
+            return
+
+        if sidecar_changed:
+            sidecar.save(sidecar_path, new_data)
+
+        save_state(path, new_state)
+        print(
+            f'Rebuilt {path} from {sidecar_path} '
+            f'({len(new_state.taghistory)} taghistory entries, '
+            f'{len(new_state.tagprogress)} tagprogress toppaths)'
+        )
+        if sidecar_changed:
+            print(f'Remapped paths in {sidecar_path}.')
+
+    @staticmethod
+    def _print_rebuild_diff(path: Path, old_state: StateFileData, new_state: StateFileData) -> None:
+        added_history = new_state.taghistory - old_state.taghistory
+        removed_history = old_state.taghistory - new_state.taghistory
+
+        old_toppaths = set(old_state.tagprogress)
+        new_toppaths = set(new_state.tagprogress)
+
+        added_progress = new_toppaths - old_toppaths
+        removed_progress = old_toppaths - new_toppaths
+
+        changed_progress = {
+            t for t in old_toppaths & new_toppaths
+            if old_state.tagprogress[t] != new_state.tagprogress[t]
+        }
+
+        print(f'Rebuild preview for {path} (dry run):')
+        print(
+            f'  taghistory: {len(old_state.taghistory)} -> {len(new_state.taghistory)} entries '
+            f'(+{len(added_history)}, -{len(removed_history)})'
+        )
+        print(
+            f'  tagprogress: {len(old_state.tagprogress)} -> {len(new_state.tagprogress)} toppaths '
+            f'(+{len(added_progress)}, -{len(removed_progress)}, ~{len(changed_progress)} changed)'
+        )
+
+    @staticmethod
+    def _migrate_db(lib, remap: Tuple[str, str], dry_run: bool = False) -> None:
+
+        old, new = remap
+        old_b = os.fsencode(old.rstrip(os.sep))
+        new_b = os.fsencode(new.rstrip(os.sep))
+
+        item_changes = []
+        for item in lib.items():
+            new_path = pathremap.remap_bytes(item.path, old_b, new_b)
+            if new_path != item.path:
+                item_changes.append((item, new_path))
+
+        album_changes = []
+        for album in lib.albums():
+            if not album.artpath:
+                continue
+            new_artpath = pathremap.remap_bytes(album.artpath, old_b, new_b)
+            if new_artpath != album.artpath:
+                album_changes.append((album, new_artpath))
+
+        print(
+            f'{len(item_changes)} item path(s) and {len(album_changes)} album art path(s) '
+            f'would be remapped ({old} -> {new}).'
+        )
+
+        if dry_run:
+            for item, new_path in item_changes[:20]:
+                print(f'  {os.fsdecode(item.path)} -> {os.fsdecode(new_path)}')
+            if len(item_changes) > 20:
+                print(f'  … (+{len(item_changes) - 20} more)')
+            return
+
+        if not (item_changes or album_changes):
+            return
+
+        if not ui.input_yn(
+            f'This will rewrite {len(item_changes)} item path(s) and {len(album_changes)} '
+            f'album art path(s) in the beets database. Continue?', require=True
+        ):
+            return
+
+        if lib.path.exists():
+            backup_path = lib.path.with_name(lib.path.name + '.bak')
+            shutil.copy2(lib.path, backup_path)
+
+        with lib.transaction():
+            for item, new_path in item_changes:
+                item.path = new_path
+                item.store()
+            for album, new_artpath in album_changes:
+                album.artpath = new_artpath
+                album.store()
+
+        print('Database paths migrated.')
+
+    # Import-time sidecar recording
+
+    def _on_choice(self, session, task) -> None:
+
+        # Sentinel: nothing to record
+        if task.toppath is None or isinstance(task, SentinelImportTask):
+            return
+
+        self._session = session
+        self._toppaths.add(task.toppath)
+
+        self._pending[id(task)] = {
+            'task': task,
+            'session': session,
+            'paths': tuple(task.paths),
+            'toppath': task.toppath,
+        }
+
+    def _on_files(self, session, task) -> None:
+        # Fires once a task's status is set to "not skipped", after
+        # files have been moved/copied/linked
+        rec = self._pending.pop(id(task), None)
+        if rec is not None:
+            self._record(
+                rec, outcome='imported',
+                operation=self._operation_name(session),
+                release=self._release_id(task),
+                dest_paths=[item.path for item in task.imported_items()],
+            )
+
+    def _on_exit(self, lib) -> None:
+        # Anything still pending never reached import_task_files: it was skipped
+        for rec in self._pending.values():
+            self._record(rec, outcome='skipped', release=self._release_id(rec['task']))
+        self._pending.clear()
+
+        if self._toppaths and self._in_tagprogress(self._session):
+            path = sidecar.sidecar_path(default_state_path())
+            with sidecar.lock:
+                data = sidecar.load(path)
+
+                for toppath in self._toppaths:
+                    sidecar.record_import_done(data, toppath)
+
+                sidecar.save(path, data)
+
+        self._toppaths.clear()
+        self._session = None
+
+    @staticmethod
+    def _operation_name(session) -> str | None:
+        # Mirrors logic in beets.importer.stages.manipulate_files
+        cfg = session.config
+
+        if cfg['move']:
+            return 'move'
+        if cfg['copy']:
+            return 'copy'
+        if cfg['link']:
+            return 'symlink'
+        if cfg['hardlink']:
+            return 'hardlink'
+        if cfg['reflink'].get() == 'auto':
+            return 'reflink_auto'
+        if cfg['reflink']:
+            return 'reflink'
+        return 'in-place'  # file left where it was
+
+    @staticmethod
+    def _release_id(task) -> str | None:
+        album = getattr(task, 'album', None)
+        if album is not None and getattr(album, 'mb_albumid', None):
+            return album.mb_albumid
+        match = getattr(task, 'match', None)
+        info = getattr(match, 'info', None) if match else None
+        return getattr(info, 'album_id', None) if info else None
+
+    def _record(self,
+        rec: dict,
+        outcome: str,
+        operation: Optional[str] = None,
+        release: Optional[str] = None,
+        dest_paths: Optional[list] = None,
+    ) -> None:
+
+        path = sidecar.sidecar_path(default_state_path())
+        session = rec['session']
+
+        with sidecar.lock:
+            data = sidecar.load(path)
+
+            sidecar.record(
+                data, rec['paths'], rec['toppath'], outcome,
+                choice=rec['task'].choice_flag.name if rec['task'].choice_flag else None,
+                operation=operation,
+                release=release,
+                kind='album' if rec['task'].is_album else 'singleton',
+                in_tagprogress=self._in_tagprogress(session),
+                in_taghistory=self._in_taghistory(session, outcome),
+                dest_paths=dest_paths,
+            )
+            sidecar.save(path, data)
+
+    @staticmethod
+    def _in_tagprogress(session) -> bool:
+        return bool(getattr(session, 'want_resume', False)) # True, False or "ask"
+
+    @staticmethod
+    def _in_taghistory(session, outcome: str) -> bool:
+        cfg = session.config
+        if not cfg['incremental']:
+            return False
+        if outcome == 'skipped' and cfg['incremental_skip_later']:
+            return False
+        return True