Playlist abstract

.git-blame-ignore-revs

@@ -4,4 +4,11 @@
 # Nbstripout
 12c56d5dcdd2695d3155720ebcc74c177cb78ece
 # Split collection into library and playlist
-9bfa3ae3cfd898b30b5f4266dab05e036d8922f8
+9bfa3ae3cfd898b30b5f4266dab05e036d8922f8
+# Large rename, removing collection suffix from playlist and library
+c50f8c5f3e990cf7411da67ef9836795ade1cbcf
+4261d8dee78e9148707480d4be77b697fe811e02
+bc9db09be00eb6afeb6317038be9a7e2db9d6e5f
+f81260544937fbfabe2f7ca7a8f6f6efe5378244
+e60e1ea0c23fa6bdd60452739403f1f6660bbc1c
+e1ffbee2263c377d1c410c891a8261d22db16f2b

CHANGELOG.md

@@ -7,15 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Upcoming
 
+### Breaking Changes
+
+#### Playlist Class Hierarchy Refactor
+
+The playlist class hierarchy has been redesigned for clearer separation of concerns:
+
+**Renamed Classes:**
+- `PlaylistCollection` → `Playlist` (base protocol)
+- `SpotifyPlaylistCollection` → `SpotifyPlaylist`
+- `TidalPlaylistCollection` → `TidalPlaylist`
+- `PlexPlaylistCollection` → `PlexPlaylist`
+- `NMLPlaylistCollection` → `NMLPlaylist`
+
+**Library Classes Renamed:**
+- `SpotifyLibraryCollection` → `SpotifyLibrary`
+- `TidalLibraryCollection` → `TidalLibrary`
+- `PlexLibrarySectionCollection` → `PlexLibrary`
+- `NMLLibraryCollection` → `NMLLibrary`
+
+**New Abstractions:**
+- `OfflinePlaylist` — In-memory playlist with no service synchronization
+- `ServicePlaylist` — Base for playlists synchronized with music services
+- `MultiRequestServicePlaylist` — For APIs requiring multi-request modifications
+- `PlaylistIDs` — Unified TypedDict for cross-service playlist identification
+
+**Method Changes:**
+| Old | New | Notes |
+|-----|-----|-------|
+| `remote_edit()` | `edit()` | Context manager for transactional edits |
+| `remote_delete()` | `delete()` | Returns `OfflinePlaylist` with last state |
+| `remote_create()` | `library.create_playlist()` | Factory method on library |
+| `remote_upsert()` | `update()` | Bulk sync to remote |
+| `remote_associated` | Removed | Service playlists always correspond to remote |
+
+**Migration:**
+```python
+# Old
+pl = SpotifyPlaylistCollection(library, "Name", "desc")
+pl.remote_create()
+with pl.remote_edit():
+    pl.tracks.append(track)
+
+# New
+pl = library.create_playlist("Name", "desc")
+with pl.edit():
+    pl.tracks.append(track)
+```
+
 - Auth commands are now available via `plistsync auth [service]` instead of `plistsync [service] auth`
-- Added `plistsync --version` command to show the currently installed version of the library
-- Renamed `_apply_diff` -> `_remote_commit` for clarity
+
+### Added
+
 - Split Playlist ABC into two classes: one for simple services, like filesystems, where states can be pushed via a single API call (`PlaylistCollection`) and one where multiple API calls are required (`MultiRequestPlaylistCollection`), e.g. when a playlists description cannot be pushed in the same call as track changes.
-- Added `PlaylistAssociationError` for playlist remote association checks, replacing `ValueError` with clearer messages and an `already_associated` attribute for programmatic inspection.
 - Added `allservices` dependency group to allow a loaded pip install with batteries included.
+- Added `plistsync --version` command to show the currently installed version of the library
 
 ### Fixed
 
+- Fixed lazy track loading when playlist has 0 tracks (`force=True` logic in `_load_tracks`)
 - In rare cases, spotify playlists can contain invalid items, which do not appear in the web interface (but through the api). We now filter and remove them.
 
 ## [0.5.1] - 2026-03-16

docs/details/advanced/matching.md

@@ -37,13 +37,13 @@ Imagine you have a track file on your local computer that you've recently bought
 
 ```python
 from plistsync.services.local import LocalTrack
-from plistsync.services.spotify import SpotifyLibraryCollection
+from plistsync.services.spotify import SpotifyLibrary
 
 # This represents a single track on your local filesystem
 source_track = LocalTrack("./path_to_source_track.mp3")
 
 # Access to spotify
-target_collection = SpotifyLibraryCollection()
+target_collection = SpotifyLibrary()
 
 # Perform the match operation to find the source_track in the target_collection
 matches = target_collection.match(source_track)

docs/details/core-concepts.md

@@ -98,4 +98,4 @@ Each service manages the platform-specific details so you don't have to:
 - **Data import/export** - Converting between platform formats and plistsync's standard Tracks/Collections
 - **Write-back** - Creating playlists, adding tracks, updating metadata on the target platform
 
-**Example**: Sync a Spotify "Road Trip" playlist → Tidal by letting services handle authentication → data extraction → track matching → playlist recreation automaticall
+**Example**: Sync a Spotify "Road Trip" playlist → Tidal by letting services handle authentication → data extraction → track matching → playlist recreation automatically