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.

Package Contents

Classes

Item

Represents a single item in a Calliope playlist.

FeatMode

Generic enumeration.

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=FeatMode.TO_CREATOR)

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=None, update=False)

export(spotify, user_id = None)

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 = None)

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(self)
__hash__(self)

Return hash(self).

__str__(self)

Return str(self).

add_warning(self, 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
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.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(self)

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
Return type

calliope.playlist.Playlist