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¶
`PlaylistID`	Immutable base for service-specific playlist identifiers.
`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.
`ServicePlaylist`	Abstract base class for playlists synchronized with music services.
`MultiRequestServicePlaylist`	Playlist for APIs where modifications have to be split into mulitple requests.
`OfflinePlaylist`	A offline (in memory) playlist with no service synchronization.

Module Contents¶

class plistsync.core.playlist.PlaylistID¶

Bases: abc.ABC

Immutable base for service-specific playlist identifiers.

Should contain a unique identifier for a playlist within a specific service. Should not be passed down to the API layer of a service. There, the native, service-specific representation should be used, e.g. a simple id string for spotify, or the int id for plex.

We need this abstraction to allow us to load and save playlists in a generic way — i.e. to implement the loading logic only once but have it work for all services.

classmethod parse(value: str) → Self¶

Abstractmethod:

Parse from user input (URL, URI, or raw id).

property serial: str¶

Abstractmethod:

Plistsync’s internal string-representation of service specific ID.

Should at least look like service_name:your_custom:format but recommended to be similar to e.g. spotify:playlist:actual_id.

By convention, to get the _canonical_ representation that the service API understands, you should define __str__ or __int__ methods to get the shorter and convenient values.

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 id: PlaylistID¶

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.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.)

class plistsync.core.playlist.OfflinePlaylist(id_serial: str, info: PlaylistInfo, tracks: collections.abc.Sequence[plistsync.core.track.OfflineTrack] | None = None)¶

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

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 id: PlaylistID¶: PlaylistID retreived from serializid string.

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

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