Playlist

Implements endpoints for manipulating playlists with the Spotify API.

Classes:

SpotifyAPIPlaylists(authoriser, wrangler[, ...])

API endpoints for processing collections i.e. playlists, albums, shows, and audiobooks.

class musify.libraries.remote.spotify.api.playlist.SpotifyAPIPlaylists(authoriser, wrangler, cache=None)

Bases: SpotifyAPIBase

API endpoints for processing collections i.e. playlists, albums, shows, and audiobooks

Methods:

load_user_playlists()	Load and store user playlists data for the currently authorised user in this API object
get_playlist_url(playlist)	Determine the type of the given playlist and return its API URL.
create_playlist(name[, public, collaborative])	POST: /users/{user_id}/playlists - Create an empty playlist for the current user with the given name.
add_to_playlist(playlist, items[, limit, ...])	POST: /playlists/{playlist_id}/tracks - Add list of tracks to a given playlist.
follow_playlist(playlist, *args, **kwargs)	PUT - Follow a given playlist.
delete_playlist(playlist)	DELETE: /playlists/{playlist_id}/followers - Unfollow a given playlist.
clear_from_playlist(playlist[, items, limit])	DELETE: /playlists/{playlist_id}/tracks - Clear tracks from a given playlist.

async load_user_playlists()

Load and store user playlists data for the currently authorised user in this API object

Return type:

None

async get_playlist_url(playlist)

Determine the type of the given playlist and return its API URL. If type cannot be determined, attempt to find the playlist in the list of the currently authorised user’s loaded playlists.

If you find this method is giving unexpected results when giving the name of a playlist. You may reload the currently loaded user’s playlists by calling load_user_playlists()

Parameters:

playlist (GenericAlias[RemoteResponse]) – One of the following to identify the playlist URL: - playlist URL/URI/ID, - the name of the playlist in the current user’s playlists, - the API response of a playlist. - a RemoteResponse object representing a remote playlist.

Returns:

URL – The playlist URL.

Raises:

RemoteIDTypeError – Raised when the function cannot determine the item type of the input playlist. Or when it does not recognise the type of the input playlist parameter.

async create_playlist(name, public=True, collaborative=False, *_, **__)

POST: /users/{user_id}/playlists - Create an empty playlist for the current user with the given name.

Parameters:

• name (str) – Name of playlist to create.

• public (bool (default: True)) – Set playlist availability as public if True and private if False.

• collaborative (bool (default: False)) – Set playlist to collaborative i.e. other users may edit the playlist.

Returns:

dict[str, Any] – API JSON response for the created playlist.

async add_to_playlist(playlist, items, limit=100, skip_dupes=True)

POST: /playlists/{playlist_id}/tracks - Add list of tracks to a given playlist.

Parameters:

• playlist (GenericAlias[RemoteResponse]) – One of the following to identify the playlist to add to: - playlist URL/URI/ID, - the name of the playlist in the current user’s playlists, - the API response of a playlist. - a RemoteResponse object representing a remote playlist.

• items (Sequence[str]) – List of URLs/URIs/IDs of the tracks to add.

• limit (int (default: 100)) – Size of each batch of IDs to add. This value will be limited to be between 1 and 100.

• skip_dupes (bool (default: True)) – Skip duplicates.

Returns:

int – The number of tracks added to the playlist.

Raises:

• RemoteIDTypeError – Raised when the input playlist does not represent a playlist URL/URI/ID.

• RemoteObjectTypeError – Raised when the item types of the input items are not all tracks or IDs.

async follow_playlist(playlist, *args, **kwargs)

PUT - Follow a given playlist.

Parameters:

playlist (GenericAlias[RemoteResponse]) – One of the following to identify the playlist to clear: - playlist URL/URI/ID, - the name of the playlist in the current user’s playlists, - the API response of a playlist. - a RemoteResponse object representing a remote playlist.

Returns:

URL – API URL for playlist.

async delete_playlist(playlist)

DELETE: /playlists/{playlist_id}/followers - Unfollow a given playlist. WARNING: This function will destructively modify your remote playlists.

Parameters:

playlist (GenericAlias[RemoteResponse]) – One of the following to identify the playlist to delete: - playlist URL/URI/ID, - the name of the playlist in the current user’s playlists, - the API response of a playlist. - a RemoteResponse object representing a remote playlist.

Returns:

URL – API URL for playlist.

async clear_from_playlist(playlist, items=None, limit=100)

DELETE: /playlists/{playlist_id}/tracks - Clear tracks from a given playlist. WARNING: This function can destructively modify your remote playlists.

Parameters:

• playlist (GenericAlias[RemoteResponse]) – One of the following to identify the playlist to clear from : - playlist URL/URI/ID, - the name of the playlist in the current user’s playlists, - the API response of a playlist. - a RemoteResponse object representing a remote playlist.

• items (Sequence[str] | None (default: None)) – List of URLs/URIs/IDs of the tracks to remove. If None, clear all songs from the playlist.

• limit (int (default: 100)) – Size of each batch of IDs to clear in a single request. This value will be limited to be between 1 and 100.

Returns:

int – The number of tracks cleared from the playlist.

Raises:

• RemoteIDTypeError – Raised when the input playlist does not represent a playlist URL/URI/ID.

• RemoteObjectTypeError – Raised when the item types of the input items are not all tracks or IDs.