plistsync.core.playlist¶

Playlist collections.

This module defines the PlaylistCollection class, which represents a collection of tracks as a playlist. To support playlist management on different platforms, we define a number of protocols which each service-specific implementation may adhere to.

The main idea here is to have an abstraction to allow updates/edit playlist in a generic way.

Usage Example:¶

Create a custom playlist collection by subclassing PlaylistCollection and implementing the required methods.

class MyPlaylistCollection(PlaylistCollection):

Overview¶

Classes¶
`PlaylistIDs`	Unique identifiers for a playlist.
`PlaylistInfo`	Unified metadata for a playlist, independent of any specific service.
`Snapshot`	Represents a snapshot of a playlist’s state.
`Playlist`	Abstract base class defining the core playlist interface.
`OfflinePlaylist`	A offline (in memory) playlist with no service synchronization.
`ServicePlaylist`	Abstract base class for playlists synchronized with music services.
`MultiRequestServicePlaylist`	Playlist for APIs where modifications have to be split into mulitple requests.

Module Contents¶

class plistsync.core.playlist.PlaylistIDs¶

Bases: TypedDict

Unique identifiers for a playlist.

Each identifier in this object uniquely identifies a playlist within a specific service. While it is unlikely that multiple IDs are set at the same time, this may be possible in the future.

spotify_id: str¶

Spotify ID of the playlist.

Unique within the Spotify service.

tidal_id: str¶

Tidal playlist ID.

Unique within the Tidal service.

plex_id: int¶

Plex ratingKey

Unique within a plex server.

traktor_id: str¶

Traktor uuid

Unique within a single nml file.

class plistsync.core.playlist.PlaylistInfo¶

Bases: TypedDict

Unified metadata for a playlist, independent of any specific service.

This object captures descriptive information about a playlist that is consistent across services or platforms.

Unlike PlaylistIDs, which uniquely identify a playlist, PlaylistInfo contains human-readable metadata such as the playlist’s name, description, and other relevant attributes.

Fields may be partially populated depending on the source service.

name: str¶: The display name of the playlist.

description: str | None¶: Optional textual description of the playlist.

class plistsync.core.playlist.Snapshot¶

Bases: Generic[T]

Represents a snapshot of a playlist’s state.

class plistsync.core.playlist.Playlist¶

Bases: Generic[T], plistsync.core.collection.Collection[T], plistsync.core.collection.TrackStream[T], abc.ABC

Abstract base class defining the core playlist interface.

This class provides a minimal protocol for playlist-like objects without assuming any specific storage model (local files, remote APIs, in-memory, etc.). It defines the essential properties that all playlists must support: metadata access (info, name, description), track list access (tracks), and unique identifiers (ids).

Concrete implementations should subclass this and implement the abstract properties. Use this as a base when building playlist abstractions for specific music services or local file formats.

property info: PlaylistInfo¶

Abstractmethod:

Get this playlist’s information.

property tracks: list[T]¶

Abstractmethod:

Get the list of tracks in the playlist.

property ids: PlaylistIDs¶

Abstractmethod:

Get the unique identifiers of the playlist.

property name: str¶: The name of the playlist.

property description: str | None¶: The description of the playlist, if available.

get_snapshot() → Snapshot[T]¶: Get a snapshot of the current state of the playlist.

class plistsync.core.playlist.OfflinePlaylist(name: str, description: str | None = None, tracks: collections.abc.Sequence[plistsync.core.track.Track] | None = None)¶

Bases: Playlist[plistsync.core.track.Track]

A offline (in memory) playlist with no service synchronization.

This class provides a concrete implementation of Playlist for managing playlists in memory without any connection to online music services. It is useful for testing, temporary playlist manipulation, or as an intermediate representation during playlist conversions.

property ids: PlaylistIDs¶: Get the unique identifiers of the playlist.

property info: PlaylistInfo¶: Get this playlist’s information.

property tracks: list[plistsync.core.track.Track]¶: Get the list of tracks in the playlist.

class plistsync.core.playlist.ServicePlaylist¶

Bases: Generic[T], Playlist[T], abc.ABC

Abstract base class for playlists synchronized with music services.

Extends Playlist with methods to manage the lifecycle and state synchronization between a in memory representation and its service counterpart (e.g., on Spotify, Tidal). By convention, every ServicePlaylist instance corresponds to an existing “remote” playlist, and has a library and/or api associated. If the “remote” playlist is deleted, the specific “ServicePlaylist” instance should be discarded in favor of an OfflinePlaylist to retain the data.

Provides two synchronization strategies:

edit() – transactional edits with automatic local rollback
update() – bulk update by comparing remote and local snapshots

delete() → OfflinePlaylist¶

Delete the playlist from the remote service and return an offline copy.

Removes the playlist from the connected remote service and returns a new OfflinePlaylist instance containing the playlist’s metadata and tracks as they existed before deletion. This allows the data to be preserved or migrated elsewhere even after the remote resource is gone.

update()¶

Update the playlist on the remote service.

Creates the playlist if it doesn’t exist, or updates it to match the current local state.

Performance Note¶

Less efficient than edit() for changes, as it retrieves the full remote state before committing. Use the edit() context manager for better performance/fewer API requests.

edit()¶

Context manager for transactional playlist edits with automatic rollback.

Enables safe modifications to a remote playlist by capturing the current state before entering the block. On successful exit, commits the changes to the remote service. If an exception occurs, restores the local state to its pre-edit condition.

Usage¶

with playlist.edit():
    playlist.tracks.append(new_track)
    playlist.name = "Updated Name"
# Changes committed to remote on success
# Local state restored on error (remote rollback not implemented)

class plistsync.core.playlist.MultiRequestServicePlaylist¶

Bases: ServicePlaylist[T], abc.ABC

Playlist for APIs where modifications have to be split into mulitple requests.

Subclass this and implement:

_remote_insert_track() - Add one or multiple track(s)
_remote_delete_track() - Remove one or multiple track(s)
_remote_update_metadata() - Update name/description
_track_key() - Stable identifier for track equality

This base class handles diff computation, batching consecutive operations, and rolling back on failure. It also translates the diff between two playlist states into the appropriate sequence of remote API calls.

Use this when the service API needs multiple calls to set a playlist to a new state (Most services will need this. For example, adding tracks usually has a different endpoint than changing a playlist’s description.)