calliope.spotify

Access data from the Spotify music streaming service.

This module wraps the Spotipy library.

Authentication

You will need a Spotify API key to authenticate with Spotify. The credentials should be provided when creating the calliope.spotify.SpotifyContext.

The first time calliope.spotify.SpotifyContext.authenticate() is called, it will open a browser window to authorize with Spotify, and will return the access token via a local HTTP server or by asking to paste the redirected URI:

$ cpe spotify export
Couldn't read cache at: /home/sam/.cache/calliope/spotify/credentials.json
Enter the URL you were redirected to:

The authorization code will be saved in the cache so future API access will work without a prompt, until the cached code expires.

Caching

By default, all new HTTP requests are saved to disk. Cache expiry is done following etags and cache-control headers provided by the Spotify API.

Submodules

Package Contents

Classes

ContentResolver

Interface for modules that can resolve playable tracks.

FeatMode

Action to take for tracks which have "featured artists" listed.

SpotifyArtistInfo

Represents a single item in a Calliope playlist.

SpotifyContext

Interface for modules that can resolve playable tracks.

Functions

select_best(item, candidates)

Automatically select the best match Item from a list of candidates for a given item.

drop_none_values(dct)

Delete all fields with None value from dct.

get_isrcs(el)

Find the ISRCs of item and return them as list

get_nested(sequence, keys)

Get the value from a nested dict/list data structure, returning None if one

normalize_creator_title(creator, title[, feat_mode])

Remove featuring artists from title and append them to the artist string

parse_sort_date(date_str)

Parse a potentially incomplete date string of the format YYYY-MM-DD and

resolve(api, playlist[, select_func, update])

export(spotify[, user_id])

Export all playlists for given user.

export_library_tracks(spotify)

Export all library tracks for the current user

export_library_albums(spotify)

Export all library albums for the current user

export_library_artists(spotify)

Export all library artists for the current user

import_library(context, playlist)

Import items into the current user's spotify library. Supported types are

import_(context, playlist[, user_id])

Import a playlist to Spotify.

top_artists(spotify, count, time_range)

Return top artists for the authenticated user.

Attributes

Item

class calliope.spotify.ContentResolver

Interface for modules that can resolve playable tracks.

abstract authenticate()
abstract resolve_content(playlist)
Parameters:

playlist (calliope.playlist.Playlist) –

Return type:

calliope.playlist.Playlist

calliope.spotify.Item
calliope.spotify.select_best(item, candidates)

Automatically select the best match Item from a list of candidates for a given item.

For each candidate, a number of weighted priorities is computed, which comprise its overall priority. The item with the best priority is automatically selected if it is higher than 90%.

Parameters:

  • item (calliope.playlist.Item) – A calliope playlist item to match

  • candidates (List[calliope.playlist.Item]) – A list of candidates

Returns:

The best match Item or None if no good match was found.

Return type:

Optional[calliope.playlist.Item]

class calliope.spotify.FeatMode(*args, **kwds)

Bases: enum.Enum

Action to take for tracks which have “featured artists” listed.

KEEP
DROP
TO_CREATOR
TO_TITLE
calliope.spotify.drop_none_values(dct)

Delete all fields with None value from dct.

Parameters:

dct (calliope.playlist.Item) –

Return type:

calliope.playlist.Item

calliope.spotify.get_isrcs(el)

Find the ISRCs of item and return them as list

calliope.spotify.get_nested(sequence, keys)

Get the value from a nested dict/list data structure, returning None if one of the keys is invalid.

Parameters:

  • sequence (Dict) –

  • keys (Iterable) –

calliope.spotify.normalize_creator_title(creator, title, feat_mode=FeatMode.TO_CREATOR)

Remove featuring artists from title and append them to the artist string

Parameters:

  • creator (Optional[str]) –

  • title (Optional[str]) –

Return type:

Tuple[Optional[str], Optional[str]]

calliope.spotify.parse_sort_date(date_str)

Parse a potentially incomplete date string of the format YYYY-MM-DD and return a datetime.date object with conservative defaults for missing data.

Parameters:

date_str (Optional[str]) –

Return type:

Optional[datetime.date]

class calliope.spotify.SpotifyArtistInfo(data=None)

Bases: calliope.playlist.Item

Represents a single item in a Calliope playlist.

Initialize self. See help(type(self)) for accurate signature.

class calliope.spotify.SpotifyContext(client_id, client_secret, redirect_uri, caching=True)

Bases: calliope.interface.ContentResolver

Interface for modules that can resolve playable tracks.

Context for accessing Spotify Web API.

The authenticate() function must be called to obtain a spotipy.client.Spotify object.

This class implements the calliope.interface.ContentResolver interface.

Parameters:

  • client_id – API client ID

  • client_secret – API key

  • redirect_uri – Redirect URI for web-based authentication flow

  • caching (bool) – Enables caching to $XDG_CACHE_HOME/calliope/spotify

authenticate()

Authenticate against the Spotify API.

See above for details on how this works.

Return type:

spotipy.client.Spotify

resolve_content(*args, **kwargs)
calliope.spotify.resolve(api, playlist, select_func=None, update=False)
Parameters:
Return type:

Iterable[calliope.playlist.Item]

calliope.spotify.export(spotify, user_id=None)

Export all playlists for given user.

Parameters:

  • user_id (str) – Optional, defaults to authenticated user.

  • spotify (SpotifyContext) –

calliope.spotify.export_library_tracks(spotify)

Export all library tracks for the current user

Parameters:

spotify (SpotifyContext) –

calliope.spotify.export_library_albums(spotify)

Export all library albums for the current user

Parameters:

spotify (SpotifyContext) –

calliope.spotify.export_library_artists(spotify)

Export all library artists for the current user

Parameters:

spotify (SpotifyContext) –

calliope.spotify.import_library(context, playlist)

Import items into the current user’s spotify library. Supported types are tracks, albums and artists.

Parameters:
calliope.spotify.import_(context, playlist, user_id=None)

Import a playlist to Spotify.

Parameters:
calliope.spotify.top_artists(spotify, count, time_range)

Return top artists for the authenticated user.

Parameters:
Return type:

calliope.playlist.Playlist