ipodsync 0.1.0__tar.gz → 0.1.2__tar.gz

{ipodsync-0.1.0 → ipodsync-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipodsync
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -17,6 +17,11 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Multimedia :: Sound/Audio
 Requires-Python: >=3.9
 Requires-Dist: mutagen>=1.47
@@ -28,17 +33,19 @@ Description-Content-Type: text/markdown
 # ipodsync
 
 [![CI](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml/badge.svg)](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg)](https://pypi.org/project/ipodsync/)
-[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg)](https://pypi.org/project/ipodsync/)
+[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
+[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 Upload music to an **iPod nano 6G/7G** without iTunes/Apple Music — straight from
 the terminal, on macOS and Linux. The iPod mounts as a plain volume; `ipodsync`
 edits its SQLite library, signs it (hashAB) and **generates cover art itself**.
 
-> ⚠️ Alpha. Works on real hardware, but it writes to the player's binary database.
-> **Keep backups** (the tool makes one before every edit) and don't open this iPod
-> in iTunes.
+> ⚠️ Alpha. Works on real hardware, but it writes to the player's binary database,
+> so **keep backups** (the tool makes one before every edit). Browsing the iPod in
+> Finder or the Music app is fine — just don't let Apple's software **auto-sync** it:
+> a sync rebuilds the library from your computer and would drop manually-added tracks
+> (keep the iPod in "manually manage music" mode).
 
 ## Features
 
@@ -52,9 +59,29 @@ edits its SQLite library, signs it (hashAB) and **generates cover art itself**.
 
 ## Install
 
+`ipodsync` is a command-line tool, so install it with **pipx** — it lands in an
+isolated environment while the `ipodsync` command stays available everywhere:
+
+```bash
+pipx install ipodsync
+```
+
+No pipx yet? `brew install pipx` (macOS) or `sudo apt install pipx` (Debian/Ubuntu),
+then `pipx ensurepath`.
+
+<details>
+<summary><code>pip install ipodsync</code> fails with <code>externally-managed-environment</code>?</summary>
+
+On modern Debian/Ubuntu (PEP 668) the system Python is locked, so a plain
+`pip install` into it is refused — that's an OS guard, not an ipodsync issue.
+Use `pipx` (above), or a virtualenv:
+
 ```bash
-pipx install ipodsync      # recommended (isolated), or: pip install ipodsync
+python3 -m venv ~/.venvs/ipodsync
+~/.venvs/ipodsync/bin/pip install ipodsync
+~/.venvs/ipodsync/bin/ipodsync --help
 ```
+</details>
 
 Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 

{ipodsync-0.1.0 → ipodsync-0.1.2}/README.md

@@ -1,17 +1,19 @@
 # ipodsync
 
 [![CI](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml/badge.svg)](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg)](https://pypi.org/project/ipodsync/)
-[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg)](https://pypi.org/project/ipodsync/)
+[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
+[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 Upload music to an **iPod nano 6G/7G** without iTunes/Apple Music — straight from
 the terminal, on macOS and Linux. The iPod mounts as a plain volume; `ipodsync`
 edits its SQLite library, signs it (hashAB) and **generates cover art itself**.
 
-> ⚠️ Alpha. Works on real hardware, but it writes to the player's binary database.
-> **Keep backups** (the tool makes one before every edit) and don't open this iPod
-> in iTunes.
+> ⚠️ Alpha. Works on real hardware, but it writes to the player's binary database,
+> so **keep backups** (the tool makes one before every edit). Browsing the iPod in
+> Finder or the Music app is fine — just don't let Apple's software **auto-sync** it:
+> a sync rebuilds the library from your computer and would drop manually-added tracks
+> (keep the iPod in "manually manage music" mode).
 
 ## Features
 
@@ -25,9 +27,29 @@ edits its SQLite library, signs it (hashAB) and **generates cover art itself**.
 
 ## Install
 
+`ipodsync` is a command-line tool, so install it with **pipx** — it lands in an
+isolated environment while the `ipodsync` command stays available everywhere:
+
+```bash
+pipx install ipodsync
+```
+
+No pipx yet? `brew install pipx` (macOS) or `sudo apt install pipx` (Debian/Ubuntu),
+then `pipx ensurepath`.
+
+<details>
+<summary><code>pip install ipodsync</code> fails with <code>externally-managed-environment</code>?</summary>
+
+On modern Debian/Ubuntu (PEP 668) the system Python is locked, so a plain
+`pip install` into it is refused — that's an OS guard, not an ipodsync issue.
+Use `pipx` (above), or a virtualenv:
+
 ```bash
-pipx install ipodsync      # recommended (isolated), or: pip install ipodsync
+python3 -m venv ~/.venvs/ipodsync
+~/.venvs/ipodsync/bin/pip install ipodsync
+~/.venvs/ipodsync/bin/ipodsync --help
 ```
+</details>
 
 Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 

{ipodsync-0.1.0 → ipodsync-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipodsync"
-version = "0.1.0"
+version = "0.1.2"
 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"
@@ -19,6 +19,11 @@ classifiers = [
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Multimedia :: Sound/Audio",
 ]
 dependencies = [

{ipodsync-0.1.0 → ipodsync-0.1.2}/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.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "find_ipod",

{ipodsync-0.1.0 → ipodsync-0.1.2}/src/ipodsync/cli.py

@@ -8,7 +8,8 @@
     ipodsync cover PID [--image IMG]   # attach a cover to a track
 
 Export is read-only for the device. add/rm/cover write to the database (they back up .itlp).
-Do not open this iPod in iTunes.
+Browsing the iPod in Finder/Music is fine; just don't let Apple's software auto-sync it,
+or a sync will drop manually-added tracks.
 """
 from __future__ import annotations
 
@@ -255,39 +256,57 @@ def cmd_cover(ipod, args):
 
 
 def main() -> int:
-    ap = argparse.ArgumentParser()
-    sub = ap.add_subparsers(dest="cmd", required=True)
-    sub.add_parser("list")
-    pe = sub.add_parser("export")
-    pe.add_argument("dest")
-    pe.add_argument("--pid", type=int)
-    pe.add_argument("--by-album", action="store_true")
-    pe.add_argument("--no-tag", action="store_true")
-    pr = sub.add_parser("rm")
-    pr.add_argument("pid", type=int)
-    pr.add_argument("--delete-file", action="store_true")
-    pa = sub.add_parser("add")
-    pa.add_argument("file", help="path to MP3")
-    pa.add_argument("--title")
-    pa.add_argument("--artist")
-    pa.add_argument("--album")
-    pa.add_argument("--no-cover", action="store_true",
-                    help="don't attach the embedded cover")
-    sub.add_parser("status")
-    pw = sub.add_parser("wait")
-    pw.add_argument("--timeout", type=float, default=120)
-    pw.add_argument("--interval", type=float, default=2)
-
-    sub.add_parser("playlists")
-    pc = sub.add_parser("pl-create"); pc.add_argument("name")
-    ppa = sub.add_parser("pl-add")
-    ppa.add_argument("playlist", type=int); ppa.add_argument("track", type=int, nargs="+")
-    ppr = sub.add_parser("pl-rm")
-    ppr.add_argument("playlist", type=int); ppr.add_argument("track", type=int)
-    ppd = sub.add_parser("pl-del"); ppd.add_argument("playlist", type=int)
-    pcv = sub.add_parser("cover")
-    pcv.add_argument("pid", type=int)
+    ap = argparse.ArgumentParser(
+        prog="ipodsync",
+        description="Upload music to an iPod nano 6G/7G without iTunes (macOS + Linux). "
+                    "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.")
+    sub = ap.add_subparsers(dest="cmd", required=True, metavar="<command>")
+
+    sub.add_parser("list", help="show tracks on the iPod")
+
+    pe = sub.add_parser("export", help="download tracks from the iPod (read-only)")
+    pe.add_argument("dest", help="destination directory")
+    pe.add_argument("--pid", type=int, help="export only this track (by pid)")
+    pe.add_argument("--by-album", action="store_true", help="lay out as Artist/Album/")
+    pe.add_argument("--no-tag", action="store_true", help="don't write ID3/MP4 tags")
+
+    pr = sub.add_parser("rm", help="remove a track from the iPod")
+    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.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")
+
+    pw = sub.add_parser("wait", help="block until an iPod is ready")
+    pw.add_argument("--timeout", type=float, default=120, help="seconds to wait (0 = forever)")
+    pw.add_argument("--interval", type=float, default=2, help="poll interval, seconds")
+
+    sub.add_parser("playlists", help="list playlists")
+    pc = sub.add_parser("pl-create", help="create a playlist")
+    pc.add_argument("name", help="playlist name")
+    ppa = sub.add_parser("pl-add", help="add tracks to a playlist")
+    ppa.add_argument("playlist", type=int, help="playlist pid")
+    ppa.add_argument("track", type=int, nargs="+", help="track pid(s)")
+    ppr = sub.add_parser("pl-rm", help="remove a track from a playlist")
+    ppr.add_argument("playlist", type=int, help="playlist pid")
+    ppr.add_argument("track", type=int, help="track pid")
+    ppd = sub.add_parser("pl-del", help="delete a playlist")
+    ppd.add_argument("playlist", type=int, help="playlist pid")
+
+    pcv = sub.add_parser("cover", help="attach a cover to an existing track")
+    pcv.add_argument("pid", type=int, help="track pid")
     pcv.add_argument("--image", help="cover image file (otherwise the track's APIC is used)")
+
     args = ap.parse_args()
 
     # commands that don't require a ready iPod