ipodsync 0.1.5__tar.gz → 0.1.7__tar.gz

{ipodsync-0.1.5 → ipodsync-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipodsync
-Version: 0.1.5
+Version: 0.1.7
 Summary: Upload music to an iPod nano 6G/7G without iTunes: SQLite library, hashAB signing, cover art (pure-Python).
 Project-URL: Homepage, https://github.com/buldiei/ipodsync
 Project-URL: Repository, https://github.com/buldiei/ipodsync
@@ -94,6 +94,8 @@ Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 ipodsync status                     # ready / no access / not connected
 ipodsync list
 ipodsync add "Song.mp3"             # + cover auto
+ipodsync add a.mp3 b.mp3 c.mp3      # several at once (one library write)
+ipodsync add -f ~/Music/album       # a whole folder (recursively)
 ipodsync add "Song.mp3" --no-cover
 ipodsync export ~/Music/ipod --by-album
 ipodsync cover 123456789 --image cover.jpg
@@ -110,49 +112,36 @@ The iPod is discovered under `/Volumes` (macOS) and `/media`, `/run/media`, `/mn
 
 ## Linux: mounting the iPod
 
-On macOS, Finder mounts the iPod automatically. A headless Linux box usually
-doesn't — the device shows up as a disk but stays unmounted, so `ipodsync` reports
-"iPod not found". Mount it yourself, then point `IPODSYNC_MOUNT` at it.
+On macOS, Finder mounts the iPod automatically — you never need `--mount`, just run
+`ipodsync add song.mp3`. A headless Linux box usually doesn't mount it: the device
+shows up as a disk but stays unmounted, so `ipodsync` reports "iPod not found".
 
-Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
+The easy way is **mount once, work, unmount once**:
 
 ```bash
-lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT      # e.g.  sda2  14.7G  hfsplus
-```
-
-For read commands (`list` / `export`), the quickest way is `--mount`: it detects the
-device, mounts it read-only (asks for `sudo`), runs the command, then unmounts:
-
-```bash
-ipodsync --mount list
-```
-
-Or mount it yourself:
-
-```bash
-sudo modprobe hfsplus
-sudo mkdir -p /mnt/ipod
-sudo mount -t hfsplus -o ro /dev/sda2 /mnt/ipod
-IPODSYNC_MOUNT=/mnt/ipod ipodsync list
-sudo umount /mnt/ipod                     # before unplugging
+ipodsync --mount              # detect + mount the iPod (asks for sudo); stays mounted
+ipodsync add song-1.mp3       # add as many tracks as you like…
+ipodsync add song-2.mp3
+ipodsync add -f ~/Music/album # …or a whole folder at once
+ipodsync list
+ipodsync --unmount            # unmount when done — safe to unplug
 ```
 
-**Writing (`add` / `rm` / `cover`) on Linux.** `--mount` handles it in one command —
-it detects the device, mounts HFS+ read-write owned by your user (asks for `sudo`),
-runs the command, then unmounts:
+`--mount` leaves the iPod at `/mnt/ipodsync`, which the following commands find on
+their own. Pass `-b` to any write command to snapshot the library first
+(`ipodsync -b add song.mp3`).
 
-```bash
-ipodsync --mount add song.mp3
-ipodsync --mount -b add song.mp3    # -b: snapshot the library to ~/ipod-backups first
-```
-
-Or mount it yourself and point `IPODSYNC_MOUNT` at it:
+Or manage the mount yourself and point `IPODSYNC_MOUNT` at it:
 
 ```bash
 sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
 IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
+sudo umount /mnt/ipod                     # before unplugging
 ```
 
+Find the iPod's partition with `lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT` (an `hfsplus`
+one, roughly the iPod's size — e.g. `sda2 14.7G hfsplus`).
+
 Two catches:
 
 - **The GUID.** Signing needs the device's FireWireGUID, which lives in a

{ipodsync-0.1.5 → ipodsync-0.1.7}/README.md

@@ -62,6 +62,8 @@ Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 ipodsync status                     # ready / no access / not connected
 ipodsync list
 ipodsync add "Song.mp3"             # + cover auto
+ipodsync add a.mp3 b.mp3 c.mp3      # several at once (one library write)
+ipodsync add -f ~/Music/album       # a whole folder (recursively)
 ipodsync add "Song.mp3" --no-cover
 ipodsync export ~/Music/ipod --by-album
 ipodsync cover 123456789 --image cover.jpg
@@ -78,49 +80,36 @@ The iPod is discovered under `/Volumes` (macOS) and `/media`, `/run/media`, `/mn
 
 ## Linux: mounting the iPod
 
-On macOS, Finder mounts the iPod automatically. A headless Linux box usually
-doesn't — the device shows up as a disk but stays unmounted, so `ipodsync` reports
-"iPod not found". Mount it yourself, then point `IPODSYNC_MOUNT` at it.
+On macOS, Finder mounts the iPod automatically — you never need `--mount`, just run
+`ipodsync add song.mp3`. A headless Linux box usually doesn't mount it: the device
+shows up as a disk but stays unmounted, so `ipodsync` reports "iPod not found".
 
-Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
+The easy way is **mount once, work, unmount once**:
 
 ```bash
-lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT      # e.g.  sda2  14.7G  hfsplus
-```
-
-For read commands (`list` / `export`), the quickest way is `--mount`: it detects the
-device, mounts it read-only (asks for `sudo`), runs the command, then unmounts:
-
-```bash
-ipodsync --mount list
-```
-
-Or mount it yourself:
-
-```bash
-sudo modprobe hfsplus
-sudo mkdir -p /mnt/ipod
-sudo mount -t hfsplus -o ro /dev/sda2 /mnt/ipod
-IPODSYNC_MOUNT=/mnt/ipod ipodsync list
-sudo umount /mnt/ipod                     # before unplugging
+ipodsync --mount              # detect + mount the iPod (asks for sudo); stays mounted
+ipodsync add song-1.mp3       # add as many tracks as you like…
+ipodsync add song-2.mp3
+ipodsync add -f ~/Music/album # …or a whole folder at once
+ipodsync list
+ipodsync --unmount            # unmount when done — safe to unplug
 ```
 
-**Writing (`add` / `rm` / `cover`) on Linux.** `--mount` handles it in one command —
-it detects the device, mounts HFS+ read-write owned by your user (asks for `sudo`),
-runs the command, then unmounts:
+`--mount` leaves the iPod at `/mnt/ipodsync`, which the following commands find on
+their own. Pass `-b` to any write command to snapshot the library first
+(`ipodsync -b add song.mp3`).
 
-```bash
-ipodsync --mount add song.mp3
-ipodsync --mount -b add song.mp3    # -b: snapshot the library to ~/ipod-backups first
-```
-
-Or mount it yourself and point `IPODSYNC_MOUNT` at it:
+Or manage the mount yourself and point `IPODSYNC_MOUNT` at it:
 
 ```bash
 sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
 IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
+sudo umount /mnt/ipod                     # before unplugging
 ```
 
+Find the iPod's partition with `lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT` (an `hfsplus`
+one, roughly the iPod's size — e.g. `sda2 14.7G hfsplus`).
+
 Two catches:
 
 - **The GUID.** Signing needs the device's FireWireGUID, which lives in a

{ipodsync-0.1.5 → ipodsync-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipodsync"
-version = "0.1.5"
+version = "0.1.7"
 description = "Upload music to an iPod nano 6G/7G without iTunes: SQLite library, hashAB signing, cover art (pure-Python)."
 readme = "README.md"
 requires-python = ">=3.9"

{ipodsync-0.1.5 → ipodsync-0.1.7}/src/ipodsync/__init__.py

@@ -13,7 +13,7 @@ from .library import ItlpLibrary
 from .models import Track
 from .transport import IPod, IPodNotFound, find_ipod
 
-__version__ = "0.1.5"
+__version__ = "0.1.7"
 
 __all__ = [
     "find_ipod",

{ipodsync-0.1.5 → ipodsync-0.1.7}/src/ipodsync/cli.py

@@ -169,30 +169,66 @@ def cmd_wait(args):
     print(f"✅ iPod ready: {ipod.root}")
 
 
+AUDIO_EXTS = {".mp3", ".m4a", ".aac", ".alac", ".mp4"}
+
+
+def _collect_add_files(args) -> list[Path]:
+    """Resolve the files to add from positional paths and/or --folder."""
+    files: list[Path] = [Path(f) for f in (args.file or [])]
+    if args.folder:
+        root = Path(args.folder)
+        if not root.is_dir():
+            raise SystemExit(f"⚠️  --folder: {root} is not a directory")
+        files += sorted(p for p in root.rglob("*")
+                        if p.is_file() and p.suffix.lower() in AUDIO_EXTS)
+    # de-dup, keep order
+    seen, out = set(), []
+    for p in files:
+        rp = p.resolve()
+        if rp not in seen:
+            seen.add(rp)
+            out.append(p)
+    return out
+
+
 def cmd_add(ipod, args):
-    """Upload an MP3 to the iPod: audio -> Fxx/ (onto the device), .itlp -> edit a copy -> back."""
+    """Upload track(s) to the iPod: audio -> Fxx/ (onto the device), .itlp -> edit a copy -> back."""
+    files = _collect_add_files(args)
+    if not files:
+        raise SystemExit("⚠️  add: give a file path, or -f/--folder DIR")
+    if len(files) > 1 and (args.title or args.artist or args.album):
+        raise SystemExit("⚠️  --title/--artist/--album only apply to a single file")
+
     itlp = ipod.itunes_dir / "iTunes Library.itlp"
     stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
     backup = _backup_library(itlp, stamp) if args.backup else None
+    art_dir = None if args.no_cover else ipod.control / "Artwork"
+    if art_dir is not None and args.backup:
+        _backup_artwork(ipod, stamp)
 
     guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo, mount=ipod.root)
-    print("→ copying the track onto the iPod…")
-    location, abs_path = copy_audio_to_ipod(ipod, args.file)
+    overrides = {"title": args.title, "artist": args.artist, "album": args.album}
 
+    # Edit one working copy of the library, add every file, then write it back once.
     work = Path("/tmp") / f"itlp_add_{stamp}"
     shutil.copytree(itlp, work)
-    overrides = {"title": args.title, "artist": args.artist, "album": args.album}
-    art_dir = None if args.no_cover else ipod.control / "Artwork"
-    if art_dir is not None and args.backup:
-        _backup_artwork(ipod, stamp)
-    pid = add_mp3_to_library(work, location, args.file, abs_path.stat().st_size,
-                             guid, overrides=overrides, artwork_dir=art_dir)
+    n = len(files)
+    added = 0
+    for i, src in enumerate(files, 1):
+        prefix = f"[{i}/{n}] " if n > 1 else ""
+        print(f"→ {prefix}copying \"{src.name}\" onto the iPod…")
+        location, abs_path = copy_audio_to_ipod(ipod, str(src))
+        pid = add_mp3_to_library(work, location, str(src), abs_path.stat().st_size,
+                                 guid, overrides=overrides if n == 1 else {},
+                                 artwork_dir=art_dir)
+        cover = "" if args.no_cover else " (+ cover art)"
+        print(f"  ✓ {prefix}added \"{src.name}\"{cover}  ·  pid {pid}")
+        added += 1
+
     for name in ("Library.itdb", "Locations.itdb", "Dynamic.itdb",
                  "Extras.itdb", "Locations.itdb.cbk"):
         shutil.copy2(work / name, itlp / name)
-    cover = "" if args.no_cover else " (+ cover art)"
-    print(f"✓ Added \"{Path(args.file).name}\"{cover}  ·  pid {pid}")
-    print("  Eject the iPod, then check Songs.")
+    print(f"✓ Added {added} track{'s' if added != 1 else ''}. Eject the iPod, then check Songs.")
     if backup:
         print(f"  Undo: rm -rf '{itlp}' && cp -r '{backup}' '{itlp}'")
 
@@ -265,14 +301,17 @@ def main() -> int:
                     "The iPod mounts as a plain volume; ipodsync edits its SQLite library, "
                     "signs it (hashAB) and writes cover art.",
         epilog="Set IPODSYNC_MOUNT=/path to point at the iPod explicitly. "
-               "add/rm/cover back up the library before editing. Run "
-               "`ipodsync <command> -h` for per-command help.")
+               "On Linux, `ipodsync --mount` mounts the iPod once (sudo) and leaves it "
+               "mounted, so `add`/`list`/... just work; `ipodsync --unmount` when done. "
+               "Run `ipodsync <command> -h` for per-command help.")
     ap.add_argument("--mount", action="store_true",
-                    help="Linux: auto-mount the iPod (sudo) before the command, unmount after")
+                    help="Linux: mount the iPod (sudo) and leave it mounted, then exit")
+    ap.add_argument("--unmount", "--umount", action="store_true", dest="unmount",
+                    help="Linux: unmount the iPod mounted by --mount, then exit")
     ap.add_argument("-b", "--backup", action="store_true",
                     help="back up the library to ~/ipod-backups before editing "
                          "(off by default)")
-    sub = ap.add_subparsers(dest="cmd", required=True, metavar="<command>")
+    sub = ap.add_subparsers(dest="cmd", required=False, metavar="<command>")
 
     sub.add_parser("list", help="show tracks on the iPod")
 
@@ -286,11 +325,12 @@ def main() -> int:
     pr.add_argument("pid", type=int, help="track pid (see `list`)")
     pr.add_argument("--delete-file", action="store_true", help="also delete the audio file")
 
-    pa = sub.add_parser("add", help="upload an MP3 (cover attached automatically)")
-    pa.add_argument("file", help="path to the MP3 to upload")
-    pa.add_argument("--title", help="override the title tag")
-    pa.add_argument("--artist", help="override the artist tag")
-    pa.add_argument("--album", help="override the album tag")
+    pa = sub.add_parser("add", help="upload a track (or a whole folder); cover attached automatically")
+    pa.add_argument("file", nargs="*", help="path(s) to the audio file(s) to upload")
+    pa.add_argument("-f", "--folder", help="add every audio file in this folder (recursively)")
+    pa.add_argument("--title", help="override the title tag (single file only)")
+    pa.add_argument("--artist", help="override the artist tag (single file only)")
+    pa.add_argument("--album", help="override the album tag (single file only)")
     pa.add_argument("--no-cover", action="store_true", help="don't attach the embedded cover")
 
     sub.add_parser("status", help="report ready / no-access / not-connected")
@@ -317,26 +357,43 @@ def main() -> int:
 
     args = ap.parse_args()
 
-    WRITE_CMDS = {"add", "rm", "cover", "pl-create", "pl-add", "pl-rm", "pl-del"}
-    mounted = None
+    if args.unmount:
+        return _do_unmount()
     if args.mount:
-        from ipodsync.transport import mount_ipod
-        try:
-            mp, mounted_by_us = mount_ipod(rw=args.cmd in WRITE_CMDS)
-        except IPodNotFound as e:
-            print(f"⚠️  {e}")
-            return 2
-        os.environ["IPODSYNC_MOUNT"] = mp
+        rc = _do_mount()
+        if rc != 0 or args.cmd is None:
+            return rc                       # standalone: mounted, now exit
+    if args.cmd is None:
+        ap.print_help()
+        return 1
+    return _dispatch(args)
+
+
+def _do_mount() -> int:
+    """Mount the iPod and leave it mounted for subsequent commands."""
+    from ipodsync.transport import mount_ipod
+    try:
+        mp, mounted_by_us = mount_ipod(rw=True)
+    except IPodNotFound as e:
+        print(f"⚠️  {e}")
+        return 2
+    if mounted_by_us:
         print(f"✓ iPod mounted at {mp}")
-        mounted = mp if mounted_by_us else None
+    else:
+        print(f"✓ iPod already mounted at {mp}")
+    print("  Now run e.g. `ipodsync add song.mp3`; `ipodsync --unmount` when done.")
+    return 0
+
 
+def _do_unmount() -> int:
+    from ipodsync.transport import find_ipod, umount_ipod, MOUNTPOINT
     try:
-        return _dispatch(args)
-    finally:
-        if mounted:
-            from ipodsync.transport import umount_ipod
-            umount_ipod(mounted)
-            print(f"✓ iPod unmounted — safe to unplug")
+        mp = str(find_ipod().root)
+    except IPodNotFound:
+        mp = MOUNTPOINT
+    umount_ipod(mp)
+    print(f"✓ iPod unmounted ({mp}) — safe to unplug.")
+    return 0
 
 
 def _dispatch(args) -> int:

{ipodsync-0.1.5 → ipodsync-0.1.7}/src/ipodsync/library.py

@@ -229,11 +229,40 @@ class ItlpLibrary:
         self.cx["Library.itdb"].commit()
 
     # --- DELETE ---------------------------------------------------------------
+    # Lookup tables that are reference-counted by `item`: (table, key col, item col).
+    _LOOKUP_TABLES = (
+        ("album", "pid", "album_pid"),
+        ("artist", "pid", "artist_pid"),
+        ("composer", "pid", "composer_pid"),
+        ("track_artist", "pid", "track_artist_pid"),
+        ("genre_map", "id", "genre_id"),
+    )
+
+    def gc_orphan_lookups(self) -> int:
+        """Delete album/artist/composer/track_artist/genre rows no longer referenced
+        by any item. Otherwise removed tracks leave behind empty albums in the UI.
+
+        A full sweep, so it also cleans up orphans left by earlier versions. Returns
+        the number of rows removed.
+        """
+        lib = self.cx["Library.itdb"]
+        removed = 0
+        for table, key, ref in self._LOOKUP_TABLES:
+            try:
+                cur = lib.execute(
+                    f'DELETE FROM "{table}" WHERE "{key}" NOT IN '
+                    f'(SELECT "{ref}" FROM item WHERE "{ref}" IS NOT NULL)')
+                removed += cur.rowcount if cur.rowcount and cur.rowcount > 0 else 0
+            except sqlite3.OperationalError:
+                continue  # table/column absent on this device — skip it
+        lib.commit()
+        return removed
+
     def remove_track(self, pid: int, *, music_dir: Path | None = None) -> str | None:
         """Remove a track from all tables. If music_dir is given — also delete the file.
 
         Returns the location of the deleted file (or None). After removal, don't
-        forget resign(). We leave orphaned album/artist/genre (iTunes is fine with it).
+        forget resign(). Orphaned album/artist/genre rows are swept by gc_orphan_lookups().
         """
         lib = self.cx["Library.itdb"]
         r = self.cx["Locations.itdb"].execute(
@@ -249,6 +278,7 @@ class ItlpLibrary:
         self.cx["Locations.itdb"].execute("DELETE FROM location WHERE item_pid=?", (pid,))
         self.cx["Dynamic.itdb"].execute("DELETE FROM item_stats WHERE item_pid=?", (pid,))
         self.cx["Extras.itdb"].execute("DELETE FROM chapter WHERE item_pid=?", (pid,))
+        self.gc_orphan_lookups()
         for c in self.cx.values():
             c.commit()
 

ipodsync-0.1.7/tests/test_gc_orphans.py

@@ -0,0 +1,76 @@
+"""gc_orphan_lookups() must delete lookup rows (album/artist/track_artist/genre)
+no longer referenced by any item, so removing tracks doesn't leave empty albums."""
+import sqlite3
+
+from ipodsync.library import ItlpLibrary
+
+
+def _make_itlp(tmp_path):
+    """A minimal .itlp dir: a Library.itdb with item + lookup tables, plus the
+    other three (empty) dbs the constructor opens."""
+    d = tmp_path / "iTunes Library.itlp"
+    d.mkdir()
+    for name in ("Locations.itdb", "Dynamic.itdb", "Extras.itdb"):
+        sqlite3.connect(d / name).close()          # just needs to exist & be valid
+    lib = sqlite3.connect(d / "Library.itdb")
+    lib.executescript(
+        """
+        CREATE TABLE item (pid INTEGER PRIMARY KEY, album_pid INTEGER,
+            artist_pid INTEGER, track_artist_pid INTEGER, genre_id INTEGER);
+        CREATE TABLE album (pid INTEGER PRIMARY KEY, name TEXT);
+        CREATE TABLE artist (pid INTEGER PRIMARY KEY, name TEXT);
+        CREATE TABLE track_artist (pid INTEGER PRIMARY KEY, name TEXT);
+        CREATE TABLE genre_map (id INTEGER PRIMARY KEY, genre TEXT);
+
+        INSERT INTO album VALUES (10, 'Kept'), (11, 'Empty');
+        INSERT INTO artist VALUES (20, 'Kept'), (21, 'Empty');
+        INSERT INTO track_artist VALUES (30, 'Kept'), (31, 'Empty');
+        INSERT INTO genre_map VALUES (40, 'Rock'), (41, 'Ambient');
+
+        -- one item referencing only the *Kept* lookups; the *Empty* ones are orphans
+        INSERT INTO item VALUES (100, 10, 20, 30, 40);
+        """
+    )
+    lib.commit()
+    lib.close()
+    return d
+
+
+def test_gc_removes_orphans_keeps_referenced(tmp_path):
+    d = _make_itlp(tmp_path)
+    lib = ItlpLibrary(d)
+    try:
+        removed = lib.gc_orphan_lookups()
+        assert removed == 4  # one orphan in each of the 4 tables
+
+        cx = lib.cx["Library.itdb"]
+        assert [r[0] for r in cx.execute("SELECT pid FROM album ORDER BY pid")] == [10]
+        assert [r[0] for r in cx.execute("SELECT pid FROM artist ORDER BY pid")] == [20]
+        assert [r[0] for r in cx.execute("SELECT pid FROM track_artist ORDER BY pid")] == [30]
+        assert [r[0] for r in cx.execute("SELECT id FROM genre_map ORDER BY id")] == [40]
+    finally:
+        lib.close()
+
+
+def test_gc_wipes_all_lookups_when_no_items(tmp_path):
+    d = _make_itlp(tmp_path)
+    lib = ItlpLibrary(d)
+    try:
+        lib.cx["Library.itdb"].execute("DELETE FROM item")
+        lib.cx["Library.itdb"].commit()
+        lib.gc_orphan_lookups()
+        for table in ("album", "artist", "track_artist", "genre_map"):
+            n = lib.cx["Library.itdb"].execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+            assert n == 0, f"{table} should be empty once no item references it"
+    finally:
+        lib.close()
+
+
+def test_gc_tolerates_missing_table(tmp_path):
+    """composer table isn't present here — gc must skip it, not raise."""
+    d = _make_itlp(tmp_path)
+    lib = ItlpLibrary(d)
+    try:
+        lib.gc_orphan_lookups()  # must not raise despite no `composer` table
+    finally:
+        lib.close()