spotifytools package¶

Submodules¶

spotifytools.artist module¶

class spotifytools.artist.Artist(name, oauth=None)¶: Bases: object

spotifytools.artist.get_album_data_by_artist(artist_id, oauth, country='US', limit=50)¶

Gets a list of artist’s albums

Parameters

artist_id (str) – Artist’s name / title
oauth (str) – OAuth Token retrieved from Spotify
country (str (default is “US”)) – Country code from within search should be executed
limit (int (default is 50)) – Limit of albums to search; current max is 50

Returns

List of album names for artist

Return type

list of str

spotifytools.artist.get_artist_external_url(artist_name, oauth)¶

Gets the external_url for a specified artist

Parameters

artist_name (str) – Artist’s name / title
oauth (str) – OAuth Token retrieved from Spotify

Returns

External Spotify URL for artist

Return type

str

spotifytools.artist.get_artist_id(artist_name, oauth)¶

Returns the id for a specified artist

Parameters

artist_name (str) – Artist’s name / title
oauth (str) – OAuth Token retrieved from Spotify

Returns

Spotify ID for artist

Return type

str

spotifytools.artist.query_artist(artist_name, oauth)¶

Gets Spotify data of an artist in json format

Parameters

artist_name (str) – Artist’s name / title
oauth (str) – OAuth Token retrieved from Spotify

Returns

Contains artist data returned from Spotify API

Return type

dict

spotifytools.exceptions module¶

Defines specific exceptions to throw

exception spotifytools.exceptions.PlaylistNotInitializedError(msg=None)¶

Bases: Exception

Exception to raise if a playlist cannot be created in Spotify

exception spotifytools.exceptions.UnsuccessfulGetRequest(msg=None)¶

Bases: Exception

Exception to raise if a GET request to the API fails

spotifytools.general module¶

Functions supporting use of the Spotify API

spotifytools.general.generate_random_string(length)¶

spotifytools.general.get_json_response_dict(oauth, search_url)¶

Returns a json dict from a REST GET request

Parameters

oauth (str) – OAuth Token retrieved from Spotify
search_url (str) – URL to query

Returns

Data returned from search_url GET request

Return type

dict

spotifytools.general.get_random_character()¶

spotifytools.general.print_pretty_json(json_data_loads)¶

Prints a formatted json to stdout

Parameters: json_data_loads (dict) – json formatted as a dict by json library
Returns: Prints to stdout
Return type: None

spotifytools.parser module¶

Parses a file containing a list of delimited tracks into a list of Track objects

spotifytools.parser.parse_file_playlist(fname, delimiter=',')¶

Generates a list of Tracks from a list delimited as [artist, song]

Parameters

fname (str) – file name to parse into list
delimiter (str (default is “,”)) – string which splits artist and song name

Return type

list of Tracks

spotifytools.parser.parse_string_playlist(content, delimiter=',')¶

Generates a list of Tracks from a block of text delimited as [artist, song]

Parameters

content (str) – Text containing tracks separated by new lines
delimiter (str (default is “,”)) – string which splits artist and song name

Return type

list of Tracks

spotifytools.playlist module¶

Class for interacting with Playlists through the Spotify API

class spotifytools.playlist.Playlist(name='Unnamed Playlist', tracks=None, playlist_id=None)¶

Bases: object

spotify_add_track(oauth, track_id, quiet=False)¶

Adds a track to a playlist on Spotify via the Track ID

Parameters

oauth (str) – OAuth Token retrieved from Spotify
track_id (str) – ID corresponding to track to add to Playlist
quiet (bool (default is False)) – If true, suppress output; no functional difference

Returns

True upon success, else False

Return type

bool

spotify_add_tracks(oauth_token, quiet=False)¶

Adds tracks in self.tracks to the playlist in Spotify. If any tracks are missed, append them to the missed_tracks list

Parameters

oauth_token (str) – OAuth Token retrieved from Spotify
quiet (bool (default is False)) – If true, suppress output; no functional difference

Returns

List includes Tracks unable to be added to the playlist

Return type

list(Tracks)

spotify_init(oauth, description='Playlist generated from Spotify API')¶

Creates a new playlist for the logged-in user on Spotify and updates the Playlist object attributes accordingly

Parameters

oauth (str) – OAuth Token retrieved from Spotify
description (str) – Playlist description

Raises

PlaylistNotInitializedError – Raised if Playlist cannot be created in Spotify

Return type

None

spotifytools.playlist_generator module¶

spotifytools.token_refresh module¶

Functions interacting with keys JSON file. Keys file format should be:

{
    "client_id": "<Your Client ID>",
    "client_secret": "<Your Client Secret ID>",
    "access_token": "<Access Token>",
    "refresh_token": "<Refresh Token>"
}

spotifytools.token_refresh.get_access_token(keys_filename='keys.json')¶

Gets the access_token value from the keys JSON file

Parameters: keys_filename (str (default is “keys.json”)) – Filename of keys JSON
Returns: Value of access_token from keys JSON
Return type: str

spotifytools.token_refresh.refresh_spotify_access_token(keys_filename='keys.json', output_file=None)¶

Refreshes the access token in a json file with the contents:

{
    "client_id": "client id",
    "client_secret": "client secret",
    "access_token": "access token",
    "refresh_token": "refresh token"
}

Parameters

keys_filename (str (default is “keys.json”)) – Path to json file
output_file (str (default is None)) – Path to save updated json file; if None, update the file that was loaded

Returns

Value for access_token is modified for the file in place or in output_file

Return type

None

spotifytools.track module¶

Class for interacting with Tracks through the Spotify API

class spotifytools.track.Track(song, artist, href=None, external_url=None, track_id=None)¶

Bases: object

spotify_query(oauth, lev_partial_ratio=75, market='US', limit=10)¶

Finds a track via a Spotify search

Parameters

oauth (str) – OAuth Token retrieved from Spotify
lev_partial_ratio (int [0-100]) – Levenshtein distance ratio
market (str (default is “US”)) – Country market
limit (int (default is 10)) – Limit of tracks to query; max is 10 as of v1 of API

Returns

True if track is found, else False; mutates Track object with Spotify data if found

Return type

bool

view_top_results(oauth, market='US', limit=10)¶

Prints a track’s top search results from a Spotify query

Parameters

oauth (str) – OAuth Token retrieved from Spotify
market (str (default is “US”)) – Country market
limit (int (default is 10)) – Limit of tracks to query; max is 10 as of v1 of API

Returns

Prints results to stdout

Return type

None

spotifytools.track_searcher module¶

Script which returns the top search results for each track in a playlist.csv style file

spotifytools package¶

Submodules¶

spotifytools.artist module¶

spotifytools.exceptions module¶

spotifytools.general module¶

spotifytools.parser module¶

spotifytools.playlist module¶

spotifytools.playlist_generator module¶

spotifytools.token_refresh module¶

spotifytools.track module¶

spotifytools.track_searcher module¶

Module contents¶

Table of Contents

This Page