Playlist

Inheritance diagram of musify.libraries.remote.spotify.api.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, ABC

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

Methods:

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.

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

Parameters:

playlist (str | Mapping[str, Any] | 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:

str – 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.

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:

str – API URL for playlist.

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 (str | Mapping[str, Any] | 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 (Collection[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.

delete_playlist(playlist)

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

Parameters:

playlist (str | Mapping[str, Any] | 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:

str – API URL for playlist.

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 (str | Mapping[str, Any] | 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 (Collection[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.