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¶
Package Contents¶
Classes¶
Represents a single item in a Calliope playlist. |
|
Generic enumeration. |
|
Represents a single item in a Calliope playlist. |
|
Context for accessing Spotify Web API. |
Functions¶
|
Automatically select the best match Item from a list of candidates for a given item. |
|
Delete all fields with None value from dct. |
|
Find the ISRCs of item and return them as list |
|
Get the value from a nested dict/list data structure, returning None if one |
|
Remove featuring artists from title and append them to the artist string |
|
Parse a potentially incomplete date string of the format YYYY-MM-DD and |
|
|
|
Export all playlists for given user. |
|
Export all library tracks for the current user |
|
Export all library albums for the current user |
|
Export all library artists for the current user |
|
Import items into the current user's spotify library. Supported types are |
|
Import a playlist to Spotify. |
|
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.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 aspotipy.client.Spotify
object.- Parameters
config (calliope.config.Configuration) – Provides
spotify.client_id
,spotify.client_secret
andspotify.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