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 via a calliope.config.Configuration instance 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

• calliope.spotify.schema

Package Contents

Classes

Item	Represents a single item in a Calliope playlist.
FeatMode	Generic enumeration.
SpotifyArtistInfo	Represents a single item in a Calliope playlist.
SpotifyContext	Context for accessing Spotify Web API.

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.

class calliope.spotify.Item(data=None)

Bases: dict

Represents a single item in a Calliope playlist.

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

id()

__hash__()

Return hash(self).

__str__()

Return str(self).

add_warning(namespace, message)

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

Bases: enum.Enum

Generic enumeration.

Derive from this class to define new enumerations.

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(config, caching=True)

Context for accessing Spotify Web API.

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

Parameters

• config (calliope.config.Configuration) – Provides spotify.client_id, spotify.client_secret and spotify.redirect_uri

• 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

calliope.spotify.resolve(api, playlist, select_func=None, update=False)

Parameters

• api (spotipy.Spotify) –

• playlist (calliope.playlist.Playlist) –

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

• context (SpotifyContext) –

• playlist (calliope.playlist.Playlist) –

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

Import a playlist to Spotify.

Parameters

• user_id (Optional[str]) – Optional, defaults to authenticated user. Requires appropriate permissions.

• context (SpotifyContext) –

• playlist (calliope.playlist.Playlist) –

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

Return top artists for the authenticated user.

Parameters

• spotify (SpotifyContext) –

• count (int) –

• time_range (str) –

Return type

calliope.playlist.Playlist