Item

Implements endpoints for getting items from the Spotify API.

Classes:

SpotifyAPIItems(authoriser, wrangler[, cache])

class musify.libraries.remote.spotify.api.item.SpotifyAPIItems(authoriser, wrangler, cache=None)

Bases: SpotifyAPIBase, ABC

Methods:

extend_items(response[, kind, key, leave_bar])	Extend the items for a given API response.
get_items(values[, kind, limit, extend])	GET: /{kind}s - Get information for given values.
get_user_items([user, kind, limit])	GET: /{kind}s - Get saved items for a given user.
extend_tracks(values[, features, analysis, ...])	GET: /audio-features and/or GET: /audio-analysis - Get audio features/analysis for given track/s.
get_tracks(values[, features, analysis, limit])	GET: /{kind}s + GET: /audio-features and/or GET: /audio-analysis
get_artist_albums(values[, types, limit])	GET: /artists/{ID}/albums - Get all albums associated with the given artist/s.

extend_items(response, kind=None, key=None, leave_bar=None)

Extend the items for a given API response. The function requests each page of the collection returning a list of all items found across all pages for this URL.

Updates the value of the items key in-place by extending the value of the items key with new results.

If a cache has been configured for this API, will also persist the items in any collection to the cache.

If a RemoteResponse, this function will not refresh itself with the new response. The user must call refresh manually after execution.

Parameters:

• response (MutableMapping[str, Any] | RemoteResponse) – A remote API JSON response for an items type endpoint or a RemoteResponse which contains this response. Must include required keys: total and either next or href, plus optional keys previous, limit, items etc.

• kind (RemoteObjectType | str | None (default: None)) – The type of response being extended. Optional, used only for logging.

• key (RemoteObjectType | None (default: None)) – The type of response of the child objects. Used when selecting nested data for certain responses (e.g. user’s followed artists).

• leave_bar (bool | None (default: None)) – When a progress bar is displayed, toggle whether this bar should continue to be displayed after the operation is finished. When None, allow the logger to decide this setting.

Returns:

list[dict[str, Any]] – API JSON responses for each item

get_items(values, kind=None, limit=50, extend=True)

GET: /{kind}s - Get information for given values.

values may be:

• A string representing a URL/URI/ID.

• A MutableSequence of strings representing URLs/URIs/IDs of the same type.

• A remote API JSON response for a collection including:

  • some items under an items key,

  • a valid ID value under an id key,

  • a valid item type value under a type key if kind is None.

• A MutableSequence of remote API JSON responses for a collection including the same structure as above.

• A RemoteResponse of the appropriate type for this RemoteAPI which holds a valid API JSON response as described above.

• A Sequence of RemoteResponses as above.

If JSON response(s) given, this update each response given by merging with the new response and replacing the items with the new results.

If RemoteResponse values are given, this function will call refresh on them.

Parameters:

• values (Union[str, MutableSequence[str], MutableMapping[str, Any], MutableSequence[MutableMapping[str, Any]], RemoteResponse, Sequence[RemoteResponse]]) – The values representing some remote objects. See description for allowed value types. These items must all be of the same type of item i.e. all tracks OR all artists etc.

• kind (RemoteObjectType | None (default: None)) – Item type if given string is ID.

• limit (int (default: 50)) – When requests can be batched, size of batches to request. This value will be limited to be between 1 and 50 or 20 if getting albums.

• extend (bool (default: True)) – When True and the given kind is a collection of items, extend the response to include all items in this collection.

Returns:

list[dict[str, Any]] – API JSON responses for each item.

Raises:

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

get_user_items(user=None, kind=RemoteObjectType.PLAYLIST, limit=50)

GET: /{kind}s - Get saved items for a given user.

Parameters:

• user (str | None (default: None)) – The ID of the user to get playlists for. If None, use the currently authenticated user.

• kind (RemoteObjectType (default: <RemoteObjectType.PLAYLIST: 1>)) – Item type to retrieve for the user. Spotify only supports PLAYLIST types for non-authenticated users.

• limit (int (default: 50)) – Size of each batch of items to request in the collection items request. This value will be limited to be between 1 and 50.

Returns:

list[dict[str, Any]] – API JSON responses for each collection.

Raises:

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

• RemoteObjectTypeError – Raised a user is given and the kind is not PLAYLIST. Or when the given kind is not a valid collection.

extend_tracks(values, features=False, analysis=False, limit=50)

GET: /audio-features and/or GET: /audio-analysis - Get audio features/analysis for given track/s.

values may be:

• A string representing a URL/URI/ID of type ‘track’.

• A MutableSequence of strings representing URLs/URIs/IDs of the type ‘track’.

• A remote API JSON response for a track including:

  • some items under an items key,

  • a valid ID value under an id key.

• A MutableSequence of remote API JSON responses for a set of tracks including the same structure as above.

• A RemoteResponse of the appropriate type for this RemoteAPI which holds a valid API JSON response as described above.

• A Sequence of RemoteResponses as above.

If JSON response(s) given, this updates each response given by adding the results under the audio_features and audio_analysis keys as appropriate.

If RemoteResponse values are given, this function will call refresh on them.

Parameters:

• values (Union[str, MutableSequence[str], MutableMapping[str, Any], MutableSequence[MutableMapping[str, Any]], RemoteResponse, Sequence[RemoteResponse]]) – The values representing some remote track/s. See description for allowed value types.

• features (bool (default: False)) – When True, get audio features.

• analysis (bool (default: False)) – When True, get audio analysis.

• limit (int (default: 50)) – Size of batches to request when getting audio features. This value will be limited to be between 1 and 50.

Returns:

list[dict[str, Any]] – API JSON responses for each item. Mapped to audio_features and audio_analysis keys as appropriate.

Raises:

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

get_tracks(values, features=False, analysis=False, limit=50, *_, **__)

GET: /{kind}s + GET: /audio-features and/or GET: /audio-analysis

Get track(s) info and any audio features/analysis. Mostly just a wrapper for get_items and extend_tracks functions.

values may be:

• A string representing a URL/URI/ID of type ‘track’.

• A MutableSequence of strings representing URLs/URIs/IDs of the type ‘track’.

• A remote API JSON response for a track including:

  • some items under an items key,

  • a valid ID value under an id key.

• A MutableSequence of remote API JSON responses for a set of tracks including the same structure as above.

• A RemoteResponse of the appropriate type for this RemoteAPI which holds a valid API JSON response as described above.

• A Sequence of RemoteResponses as above.

If JSON response(s) given, this updates each response given by adding the results under the audio_features and audio_analysis keys as appropriate.

Parameters:

• values (Union[str, MutableSequence[str], MutableMapping[str, Any], MutableSequence[MutableMapping[str, Any]], RemoteResponse, Sequence[RemoteResponse]]) – The values representing some remote track/s. See description for allowed value types.

• features (bool (default: False)) – When True, get audio features.

• analysis (bool (default: False)) – When True, get audio analysis.

• limit (int (default: 50)) – Size of batches to request when getting audio features. This value will be limited to be between 1 and 50.

Returns:

list[dict[str, Any]] – API JSON responses for each item, or the original response if the input values are API responses.

Raises:

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

get_artist_albums(values, types=(), limit=50)

GET: /artists/{ID}/albums - Get all albums associated with the given artist/s.

values may be:

• A string representing a URL/URI/ID of type ‘artist’.

• A MutableSequence of strings representing URLs/URIs/IDs of the type ‘artist’.

• A remote API JSON response for an artist including a valid ID value under an id key.

• A MutableSequence of remote API JSON responses for a set of artists including the same structure as above.

• A RemoteResponse of the appropriate type for this RemoteAPI which holds a valid API JSON response as described above.

• A Sequence of RemoteResponses as above.

If JSON response(s) given, this updates each response given by adding the results under the albums key.

If RemoteResponse values are given, this function will call refresh on them.

Parameters:

• values (Union[str, MutableSequence[str], MutableMapping[str, Any], MutableSequence[MutableMapping[str, Any]], RemoteResponse, Sequence[RemoteResponse]]) – The values representing some remote artist/s. See description for allowed value types.

• types (Collection[str] (default: ())) – The types of albums to return. Select from {"album", "single", "compilation", "appears_on"}.

• limit (int (default: 50)) – Size of batches to request. This value will be limited to be between 1 and 50.

Returns:

dict[str, list[dict[str, Any]]] – A map of the Artist ID to a list of the API JSON responses for each album.

Raises:

RemoteObjectTypeError – Raised when the item types of the input values are not all artists or IDs.