pypodlib 0.1.0__tar.gz

pypodlib-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# MkDocs build output
+site/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Local build/install flags
+*.local

pypodlib-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 pyPodLib contributors
+
+pyPodLib is derived from the iOpenPod project
+(https://github.com/TheRealSavi/iOpenPod), Copyright (c) John Gibbons,
+licensed under the MIT License, which grants permission to copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies of the Software.
+
+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.

pypodlib-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: pypodlib
+Version: 0.1.0
+Summary: Communicate with iPod Classic/Nano/Mini devices — detect and identify the device, read and write the iTunesDB library, and sync media — without iTunes.
+Project-URL: Homepage, https://la22e.github.io/pyPodLib/
+Project-URL: Repository, https://github.com/La22e/pyPodLib
+Author: La22e
+License: MIT
+License-File: LICENSE
+Keywords: ipod,ipod-classic,ipod-manager,ipod-sync,itunes,itunes-alternative,itunesdb,music-library,music-sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Requires-Python: >=3.11
+Requires-Dist: libusb-package>=1.0.30.0
+Requires-Dist: pycryptodome>=3.20.0
+Requires-Dist: pyusb>=1.3.1
+Requires-Dist: wasmtime>=30.0.0
+Provides-Extra: artwork
+Requires-Dist: mutagen>=1.47.0; extra == 'artwork'
+Requires-Dist: numpy>=2.0.0; extra == 'artwork'
+Requires-Dist: pillow>=10.0.0; extra == 'artwork'
+Description-Content-Type: text/markdown
+
+# pyPodLib
+
+Read, write, and sync iPod Classic/Nano/Mini libraries from Python — no
+iTunes required.
+
+pyPodLib is a pure-Python library extracted from
+[iOpenPod](https://github.com/TheRealSavi/iOpenPod) (MIT, © John Gibbons).
+It keeps the battle-tested iTunesDB / iTunesCDB parsing and writing engine,
+device detection, and sync logic, and exposes it as a headless library.
+
+## Features
+
+- **Device detection** — scan for connected iPods and identify model,
+  generation, capacity, colour, serial, and checksum type (`scan_ipods`,
+  `identify_ipod_at_path`).
+- **Read** — parse the full library: tracks, user playlists, podcast
+  playlists, smart playlists (dataset 2/3/5), play counts, artwork refs.
+- **Write** — save edits back with the correct per-device signature
+  (HASH58 via FireWire GUID, HASH72 via AES, HASHAB via WebAssembly,
+  NONE for pre-2007 devices), plus SQLite DBs for Nano 6G/7G and
+  iTunesPrefs protection.
+- **Sync** — plan and execute media sync, with optional artwork and
+  transcode support.
+- **Testable without hardware** — create "virtual iPods" (a folder
+  identity + seeded database) for round-trip tests
+  (`pypodlib.device.create_virtual_ipod`).
+
+## Install
+
+```console
+pip install pypodlib                          # core (device + library read/write)
+pip install 'pypodlib[artwork]'               # + embedded-art extraction/encoding
+```
+
+Runtime dependencies: `pyusb` / `libusb-package` (USB identification),
+`pycryptodome` (HASH72 signing), `wasmtime` (HASHAB signing).
+
+## Documentation
+
+Full documentation: [la22e.github.io/pyPodLib](https://la22e.github.io/pyPodLib/)
+
+## Quick start
+
+```python
+import pypodlib
+
+ipod = pypodlib.connect("/media/user/IPOD")        # or pypodlib.scan_ipods()[0]
+print(ipod.model_number, ipod.generation, ipod.capacity)
+
+lib = ipod.library()
+print(len(lib.tracks), "tracks")
+
+track = lib.tracks[0]
+track.title = "New Title"
+track.rating = 80                                 # 4 stars
+ipod.save()                                       # writes iTunesDB + signature
+```
+
+### Low-level access
+
+Every layer stays importable:
+
+```python
+from pypodlib.device import scan_for_ipods, identify_ipod_at_path
+from pypodlib.itunesdb_parser import parse_itunesdb, load_ipod_library
+from pypodlib.itunesdb_writer import write_itunesdb, detect_checksum_type
+from pypodlib.sync._db_io import read_existing_database, write_database
+```
+
+### Virtual iPods (no hardware)
+
+```python
+from pypodlib.device import create_virtual_ipod, available_virtual_ipod_models
+
+import tempfile
+root = tempfile.mkdtemp()
+info = create_virtual_ipod(root, "MC297")   # iPod Classic 7th Gen (HASH58)
+ipod = pypodlib.connect(root)
+ipod.library()
+ipod.save()                                  # round-trips through real writer
+```
+
+## Limitations
+
+- Requires a mounted iPod volume (or a virtual iPod root) — USB enumeration
+  is used for identification only.
+- Photo sync and embedded-art encoding need the `artwork` extra
+  (`numpy`, `Pillow`, `mutagen`).
+- Video/ffmpeg transcoding requires an `ffmpeg`/`ffprobe` binary.
+- Smart playlists are re-evaluated on save (matching iTunes behaviour).
+
+## License
+
+MIT. pyPodLib is derived from iOpenPod (MIT, © John Gibbons).

pypodlib-0.1.0/README.md

@@ -0,0 +1,94 @@
+# pyPodLib
+
+Read, write, and sync iPod Classic/Nano/Mini libraries from Python — no
+iTunes required.
+
+pyPodLib is a pure-Python library extracted from
+[iOpenPod](https://github.com/TheRealSavi/iOpenPod) (MIT, © John Gibbons).
+It keeps the battle-tested iTunesDB / iTunesCDB parsing and writing engine,
+device detection, and sync logic, and exposes it as a headless library.
+
+## Features
+
+- **Device detection** — scan for connected iPods and identify model,
+  generation, capacity, colour, serial, and checksum type (`scan_ipods`,
+  `identify_ipod_at_path`).
+- **Read** — parse the full library: tracks, user playlists, podcast
+  playlists, smart playlists (dataset 2/3/5), play counts, artwork refs.
+- **Write** — save edits back with the correct per-device signature
+  (HASH58 via FireWire GUID, HASH72 via AES, HASHAB via WebAssembly,
+  NONE for pre-2007 devices), plus SQLite DBs for Nano 6G/7G and
+  iTunesPrefs protection.
+- **Sync** — plan and execute media sync, with optional artwork and
+  transcode support.
+- **Testable without hardware** — create "virtual iPods" (a folder
+  identity + seeded database) for round-trip tests
+  (`pypodlib.device.create_virtual_ipod`).
+
+## Install
+
+```console
+pip install pypodlib                          # core (device + library read/write)
+pip install 'pypodlib[artwork]'               # + embedded-art extraction/encoding
+```
+
+Runtime dependencies: `pyusb` / `libusb-package` (USB identification),
+`pycryptodome` (HASH72 signing), `wasmtime` (HASHAB signing).
+
+## Documentation
+
+Full documentation: [la22e.github.io/pyPodLib](https://la22e.github.io/pyPodLib/)
+
+## Quick start
+
+```python
+import pypodlib
+
+ipod = pypodlib.connect("/media/user/IPOD")        # or pypodlib.scan_ipods()[0]
+print(ipod.model_number, ipod.generation, ipod.capacity)
+
+lib = ipod.library()
+print(len(lib.tracks), "tracks")
+
+track = lib.tracks[0]
+track.title = "New Title"
+track.rating = 80                                 # 4 stars
+ipod.save()                                       # writes iTunesDB + signature
+```
+
+### Low-level access
+
+Every layer stays importable:
+
+```python
+from pypodlib.device import scan_for_ipods, identify_ipod_at_path
+from pypodlib.itunesdb_parser import parse_itunesdb, load_ipod_library
+from pypodlib.itunesdb_writer import write_itunesdb, detect_checksum_type
+from pypodlib.sync._db_io import read_existing_database, write_database
+```
+
+### Virtual iPods (no hardware)
+
+```python
+from pypodlib.device import create_virtual_ipod, available_virtual_ipod_models
+
+import tempfile
+root = tempfile.mkdtemp()
+info = create_virtual_ipod(root, "MC297")   # iPod Classic 7th Gen (HASH58)
+ipod = pypodlib.connect(root)
+ipod.library()
+ipod.save()                                  # round-trips through real writer
+```
+
+## Limitations
+
+- Requires a mounted iPod volume (or a virtual iPod root) — USB enumeration
+  is used for identification only.
+- Photo sync and embedded-art encoding need the `artwork` extra
+  (`numpy`, `Pillow`, `mutagen`).
+- Video/ffmpeg transcoding requires an `ffmpeg`/`ffprobe` binary.
+- Smart playlists are re-evaluated on save (matching iTunes behaviour).
+
+## License
+
+MIT. pyPodLib is derived from iOpenPod (MIT, © John Gibbons).

pypodlib-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pypodlib"
+version = "0.1.0"
+description = "Communicate with iPod Classic/Nano/Mini devices — detect and identify the device, read and write the iTunesDB library, and sync media — without iTunes."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    {name = "La22e"},
+]
+keywords = [
+    "ipod", "ipod-classic", "itunes", "itunesdb", "music-sync",
+    "ipod-manager", "music-library", "ipod-sync", "itunes-alternative",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Sound/Audio :: Players",
+]
+dependencies = [
+    "pyusb>=1.3.1",
+    "libusb-package>=1.0.30.0",
+    "pycryptodome>=3.20.0",
+    "wasmtime>=30.0.0",
+]
+
+[project.optional-dependencies]
+artwork = [
+    "numpy>=2.0.0",
+    "pillow>=10.0.0",
+    "mutagen>=1.47.0",
+]
+
+[project.urls]
+Homepage = "https://la22e.github.io/pyPodLib/"
+Repository = "https://github.com/La22e/pyPodLib"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.15.0",
+    "pytest>=8.3.5",
+    "ruff>=0.11.7",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.28",
+    "mkdocs-gen-files",
+    "mkdocs-literate-nav",
+    "mkdocs-section-index",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pypodlib"]
+include = [
+    "/src/pypodlib/**/*.py",
+    "/src/pypodlib/itunesdb_writer/wasm/calcHashAB.wasm",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+addopts = "-p no:cacheprovider"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 320
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]

pypodlib-0.1.0/src/pypodlib/__init__.py

@@ -0,0 +1,45 @@
+"""
+pypodlib — communicate with iPod Classic/Nano/Mini devices from Python.
+
+pyPodLib is a pure-Python library that reads and writes the iPod's on-disk
+library (iTunesDB / iTunesCDB) without iTunes.  It can:
+
+- detect and identify a connected iPod (model, generation, capacity, colour)
+- read tracks, playlists, podcasts, smart playlists and play counts
+- write the database back with the correct per-device checksum signature
+- copy media files onto the device and regenerate the database
+
+Typical usage::
+
+    import pypodlib
+
+    ipod = pypodlib.connect("/media/user/IPOD")           # or scan_ipods()[0]
+    print(ipod.model.family, ipod.model.generation)
+
+    lib = ipod.library()
+    for track in lib.tracks:
+        print(track.title, track.artist)
+
+    lib.tracks[0].rating = 5
+    ipod.save()
+
+The low-level modules remain importable directly (``pypodlib.device``,
+``pypodlib.itunesdb_parser``, ``pypodlib.itunesdb_writer``, ...).
+"""
+
+from __future__ import annotations
+
+from .api import IPod, Library, Playlist, Track, connect, library_from_path, scan_ipods
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "connect",
+    "scan_ipods",
+    "library_from_path",
+    "IPod",
+    "Library",
+    "Track",
+    "Playlist",
+]