archive
/
spotipy
mirror of https://github.com/c0de-archive/spotipy.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #184 from Acrobot/patch-1 

Fix quote formatting according to PEP 257
This commit is contained in:
Paul Lamere 2017-09-17 11:48:58 -04:00 committed by GitHub
parent 618994c0f0 7a5243dd64
commit c06cba6849
1 changed files with 100 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
spotipy/client.py
View File

@ -9,8 +9,8 @@ import time
import six import six
''' A simple and thin Python library for the Spotify Web API """ A simple and thin Python library for the Spotify Web API
''' """
class SpotifyException(Exception): class SpotifyException(Exception):
@ -30,7 +30,7 @@ class SpotifyException(Exception):
class Spotify(object): class Spotify(object):
''' """
Example usage:: Example usage::
import spotipy import spotipy
@ -46,7 +46,7 @@ class Spotify(object):
user = sp.user('plamere') user = sp.user('plamere')
print(user) print(user)
''' """
trace = False # Enable tracing? trace = False # Enable tracing?
trace_out = False trace_out = False
@ -54,7 +54,7 @@ class Spotify(object):
def __init__(self, auth=None, requests_session=True, def __init__(self, auth=None, requests_session=True,
client_credentials_manager=None, proxies=None, requests_timeout=None): client_credentials_manager=None, proxies=None, requests_timeout=None):
''' """
Create a Spotify API object. Create a Spotify API object.
:param auth: An authorization token (optional) :param auth: An authorization token (optional)
@ -69,7 +69,7 @@ class Spotify(object):
Definition of proxies (optional) Definition of proxies (optional)
:param requests_timeout: :param requests_timeout:
Tell Requests to stop waiting for a response after a given number of seconds Tell Requests to stop waiting for a response after a given number of seconds
''' """
self.prefix = 'https://api.spotify.com/v1/' self.prefix = 'https://api.spotify.com/v1/'
self._auth = auth self._auth = auth
self.client_credentials_manager = client_credentials_manager self.client_credentials_manager = client_credentials_manager
@ -190,22 +190,22 @@ class Spotify(object):
return self._internal_call('PUT', url, payload, kwargs) return self._internal_call('PUT', url, payload, kwargs)
def next(self, result): def next(self, result):
''' returns the next result given a paged result """ returns the next result given a paged result
Parameters: Parameters:
- result - a previously returned paged result - result - a previously returned paged result
''' """
if result['next']: if result['next']:
return self._get(result['next']) return self._get(result['next'])
else: else:
return None return None
def previous(self, result): def previous(self, result):
''' returns the previous result given a paged result """ returns the previous result given a paged result
Parameters: Parameters:
- result - a previously returned paged result - result - a previously returned paged result
''' """
if result['previous']: if result['previous']:
return self._get(result['previous']) return self._get(result['previous'])
else: else:
@ -218,49 +218,49 @@ class Spotify(object):
print('warning:' + msg.format(*args), file=sys.stderr) print('warning:' + msg.format(*args), file=sys.stderr)
def track(self, track_id): def track(self, track_id):
''' returns a single track given the track's ID, URI or URL """ returns a single track given the track's ID, URI or URL
Parameters: Parameters:
- track_id - a spotify URI, URL or ID - track_id - a spotify URI, URL or ID
''' """
trid = self._get_id('track', track_id) trid = self._get_id('track', track_id)
return self._get('tracks/' + trid) return self._get('tracks/' + trid)
def tracks(self, tracks, market = None): def tracks(self, tracks, market = None):
''' returns a list of tracks given a list of track IDs, URIs, or URLs """ returns a list of tracks given a list of track IDs, URIs, or URLs
Parameters: Parameters:
- tracks - a list of spotify URIs, URLs or IDs - tracks - a list of spotify URIs, URLs or IDs
- market - an ISO 3166-1 alpha-2 country code. - market - an ISO 3166-1 alpha-2 country code.
''' """
tlist = [self._get_id('track', t) for t in tracks] tlist = [self._get_id('track', t) for t in tracks]
return self._get('tracks/?ids=' + ','.join(tlist), market = market) return self._get('tracks/?ids=' + ','.join(tlist), market = market)
def artist(self, artist_id): def artist(self, artist_id):
''' returns a single artist given the artist's ID, URI or URL """ returns a single artist given the artist's ID, URI or URL
Parameters: Parameters:
- artist_id - an artist ID, URI or URL - artist_id - an artist ID, URI or URL
''' """
trid = self._get_id('artist', artist_id) trid = self._get_id('artist', artist_id)
return self._get('artists/' + trid) return self._get('artists/' + trid)
def artists(self, artists): def artists(self, artists):
''' returns a list of artists given the artist IDs, URIs, or URLs """ returns a list of artists given the artist IDs, URIs, or URLs
Parameters: Parameters:
- artists - a list of artist IDs, URIs or URLs - artists - a list of artist IDs, URIs or URLs
''' """
tlist = [self._get_id('artist', a) for a in artists] tlist = [self._get_id('artist', a) for a in artists]
return self._get('artists/?ids=' + ','.join(tlist)) return self._get('artists/?ids=' + ','.join(tlist))
def artist_albums(self, artist_id, album_type=None, country=None, limit=20, def artist_albums(self, artist_id, album_type=None, country=None, limit=20,
offset=0): offset=0):
''' Get Spotify catalog information about an artist's albums """ Get Spotify catalog information about an artist's albums
Parameters: Parameters:
- artist_id - the artist ID, URI or URL - artist_id - the artist ID, URI or URL
@ -268,70 +268,70 @@ class Spotify(object):
- country - limit the response to one particular country. - country - limit the response to one particular country.
- limit - the number of albums to return - limit - the number of albums to return
- offset - the index of the first album to return - offset - the index of the first album to return
''' """
trid = self._get_id('artist', artist_id) trid = self._get_id('artist', artist_id)
return self._get('artists/' + trid + '/albums', album_type=album_type, return self._get('artists/' + trid + '/albums', album_type=album_type,
country=country, limit=limit, offset=offset) country=country, limit=limit, offset=offset)
def artist_top_tracks(self, artist_id, country='US'): def artist_top_tracks(self, artist_id, country='US'):
''' Get Spotify catalog information about an artist's top 10 tracks """ Get Spotify catalog information about an artist's top 10 tracks
by country. by country.
Parameters: Parameters:
- artist_id - the artist ID, URI or URL - artist_id - the artist ID, URI or URL
- country - limit the response to one particular country. - country - limit the response to one particular country.
''' """
trid = self._get_id('artist', artist_id) trid = self._get_id('artist', artist_id)
return self._get('artists/' + trid + '/top-tracks', country=country) return self._get('artists/' + trid + '/top-tracks', country=country)
def artist_related_artists(self, artist_id): def artist_related_artists(self, artist_id):
''' Get Spotify catalog information about artists similar to an """ Get Spotify catalog information about artists similar to an
identified artist. Similarity is based on analysis of the identified artist. Similarity is based on analysis of the
Spotify community's listening history. Spotify community's listening history.
Parameters: Parameters:
- artist_id - the artist ID, URI or URL - artist_id - the artist ID, URI or URL
''' """
trid = self._get_id('artist', artist_id) trid = self._get_id('artist', artist_id)
return self._get('artists/' + trid + '/related-artists') return self._get('artists/' + trid + '/related-artists')
def album(self, album_id): def album(self, album_id):
''' returns a single album given the album's ID, URIs or URL """ returns a single album given the album's ID, URIs or URL
Parameters: Parameters:
- album_id - the album ID, URI or URL - album_id - the album ID, URI or URL
''' """
trid = self._get_id('album', album_id) trid = self._get_id('album', album_id)
return self._get('albums/' + trid) return self._get('albums/' + trid)
def album_tracks(self, album_id, limit=50, offset=0): def album_tracks(self, album_id, limit=50, offset=0):
''' Get Spotify catalog information about an album's tracks """ Get Spotify catalog information about an album's tracks
Parameters: Parameters:
- album_id - the album ID, URI or URL - album_id - the album ID, URI or URL
- limit - the number of items to return - limit - the number of items to return
- offset - the index of the first item to return - offset - the index of the first item to return
''' """
trid = self._get_id('album', album_id) trid = self._get_id('album', album_id)
return self._get('albums/' + trid + '/tracks/', limit=limit, return self._get('albums/' + trid + '/tracks/', limit=limit,
offset=offset) offset=offset)
def albums(self, albums): def albums(self, albums):
''' returns a list of albums given the album IDs, URIs, or URLs """ returns a list of albums given the album IDs, URIs, or URLs
Parameters: Parameters:
- albums - a list of album IDs, URIs or URLs - albums - a list of album IDs, URIs or URLs
''' """
tlist = [self._get_id('album', a) for a in albums] tlist = [self._get_id('album', a) for a in albums]
return self._get('albums/?ids=' + ','.join(tlist)) return self._get('albums/?ids=' + ','.join(tlist))
def search(self, q, limit=10, offset=0, type='track', market=None): def search(self, q, limit=10, offset=0, type='track', market=None):
''' searches for an item """ searches for an item
Parameters: Parameters:
- q - the search query - q - the search query
@ -340,15 +340,15 @@ class Spotify(object):
- type - the type of item to return. One of 'artist', 'album', - type - the type of item to return. One of 'artist', 'album',
'track' or 'playlist' 'track' or 'playlist'
- market - An ISO 3166-1 alpha-2 country code or the string from_token. - market - An ISO 3166-1 alpha-2 country code or the string from_token.
''' """
return self._get('search', q=q, limit=limit, offset=offset, type=type, market=market) return self._get('search', q=q, limit=limit, offset=offset, type=type, market=market)
def user(self, user): def user(self, user):
''' Gets basic profile information about a Spotify User """ Gets basic profile information about a Spotify User
Parameters: Parameters:
- user - the id of the usr - user - the id of the usr
''' """
return self._get('users/' + user) return self._get('users/' + user)
def current_user_playlists(self, limit=50, offset=0): def current_user_playlists(self, limit=50, offset=0):
@ -360,23 +360,23 @@ class Spotify(object):
return self._get("me/playlists", limit=limit, offset=offset) return self._get("me/playlists", limit=limit, offset=offset)
def user_playlists(self, user, limit=50, offset=0): def user_playlists(self, user, limit=50, offset=0):
''' Gets playlists of a user """ Gets playlists of a user
Parameters: Parameters:
- user - the id of the usr - user - the id of the usr
- limit - the number of items to return - limit - the number of items to return
- offset - the index of the first item to return - offset - the index of the first item to return
''' """
return self._get("users/%s/playlists" % user, limit=limit, return self._get("users/%s/playlists" % user, limit=limit,
offset=offset) offset=offset)
def user_playlist(self, user, playlist_id=None, fields=None): def user_playlist(self, user, playlist_id=None, fields=None):
''' Gets playlist of a user """ Gets playlist of a user
Parameters: Parameters:
- user - the id of the user - user - the id of the user
- playlist_id - the id of the playlist - playlist_id - the id of the playlist
- fields - which fields to return - fields - which fields to return
''' """
if playlist_id is None: if playlist_id is None:
return self._get("users/%s/starred" % (user), fields=fields) return self._get("users/%s/starred" % (user), fields=fields)
plid = self._get_id('playlist', playlist_id) plid = self._get_id('playlist', playlist_id)
@ -384,7 +384,7 @@ class Spotify(object):
def user_playlist_tracks(self, user, playlist_id=None, fields=None, def user_playlist_tracks(self, user, playlist_id=None, fields=None,
limit=100, offset=0, market=None): limit=100, offset=0, market=None):
''' Get full details of the tracks of a playlist owned by a user. """ Get full details of the tracks of a playlist owned by a user.
Parameters: Parameters:
- user - the id of the user - user - the id of the user
@ -393,27 +393,27 @@ class Spotify(object):
- limit - the maximum number of tracks to return - limit - the maximum number of tracks to return
- offset - the index of the first track to return - offset - the index of the first track to return
- market - an ISO 3166-1 alpha-2 country code. - market - an ISO 3166-1 alpha-2 country code.
''' """
plid = self._get_id('playlist', playlist_id) plid = self._get_id('playlist', playlist_id)
return self._get("users/%s/playlists/%s/tracks" % (user, plid), return self._get("users/%s/playlists/%s/tracks" % (user, plid),
limit=limit, offset=offset, fields=fields, limit=limit, offset=offset, fields=fields,
market=market) market=market)
def user_playlist_create(self, user, name, public=True): def user_playlist_create(self, user, name, public=True):
''' Creates a playlist for a user """ Creates a playlist for a user
Parameters: Parameters:
- user - the id of the user - user - the id of the user
- name - the name of the playlist - name - the name of the playlist
- public - is the created playlist public - public - is the created playlist public
''' """
data = {'name': name, 'public': public} data = {'name': name, 'public': public}
return self._post("users/%s/playlists" % (user,), payload=data) return self._post("users/%s/playlists" % (user,), payload=data)
def user_playlist_change_details( def user_playlist_change_details(
self, user, playlist_id, name=None, public=None, self, user, playlist_id, name=None, public=None,
collaborative=None): collaborative=None):
''' Changes a playlist's name and/or public/private state """ Changes a playlist's name and/or public/private state
Parameters: Parameters:
- user - the id of the user - user - the id of the user
@ -421,7 +421,7 @@ class Spotify(object):
- name - optional name of the playlist - name - optional name of the playlist
- public - optional is the playlist public - public - optional is the playlist public
- collaborative - optional is the playlist collaborative - collaborative - optional is the playlist collaborative
''' """
data = {} data = {}
if isinstance(name, six.string_types): if isinstance(name, six.string_types):
data['name'] = name data['name'] = name
@ -433,37 +433,37 @@ class Spotify(object):
payload=data) payload=data)
def user_playlist_unfollow(self, user, playlist_id): def user_playlist_unfollow(self, user, playlist_id):
''' Unfollows (deletes) a playlist for a user """ Unfollows (deletes) a playlist for a user
Parameters: Parameters:
- user - the id of the user - user - the id of the user
- name - the name of the playlist - name - the name of the playlist
''' """
return self._delete("users/%s/playlists/%s/followers" % (user, playlist_id)) return self._delete("users/%s/playlists/%s/followers" % (user, playlist_id))
def user_playlist_add_tracks(self, user, playlist_id, tracks, def user_playlist_add_tracks(self, user, playlist_id, tracks,
position=None): position=None):
''' Adds tracks to a playlist """ Adds tracks to a playlist
Parameters: Parameters:
- user - the id of the user - user - the id of the user
- playlist_id - the id of the playlist - playlist_id - the id of the playlist
- tracks - a list of track URIs, URLs or IDs - tracks - a list of track URIs, URLs or IDs
- position - the position to add the tracks - position - the position to add the tracks
''' """
plid = self._get_id('playlist', playlist_id) plid = self._get_id('playlist', playlist_id)
ftracks = [self._get_uri('track', tid) for tid in tracks] ftracks = [self._get_uri('track', tid) for tid in tracks]
return self._post("users/%s/playlists/%s/tracks" % (user, plid), return self._post("users/%s/playlists/%s/tracks" % (user, plid),
payload=ftracks, position=position) payload=ftracks, position=position)
def user_playlist_replace_tracks(self, user, playlist_id, tracks): def user_playlist_replace_tracks(self, user, playlist_id, tracks):
''' Replace all tracks in a playlist """ Replace all tracks in a playlist
Parameters: Parameters:
- user - the id of the user - user - the id of the user
- playlist_id - the id of the playlist - playlist_id - the id of the playlist
- tracks - the list of track ids to add to the playlist - tracks - the list of track ids to add to the playlist
''' """
plid = self._get_id('playlist', playlist_id) plid = self._get_id('playlist', playlist_id)
ftracks = [self._get_uri('track', tid) for tid in tracks] ftracks = [self._get_uri('track', tid) for tid in tracks]
payload = {"uris": ftracks} payload = {"uris": ftracks}
@ -473,7 +473,7 @@ class Spotify(object):
def user_playlist_reorder_tracks( def user_playlist_reorder_tracks(
self, user, playlist_id, range_start, insert_before, self, user, playlist_id, range_start, insert_before,
range_length=1, snapshot_id=None): range_length=1, snapshot_id=None):
''' Reorder tracks in a playlist """ Reorder tracks in a playlist
Parameters: Parameters:
- user - the id of the user - user - the id of the user
@ -482,7 +482,7 @@ class Spotify(object):
- range_length - optional the number of tracks to be reordered (default: 1) - range_length - optional the number of tracks to be reordered (default: 1)
- insert_before - the position where the tracks should be inserted - insert_before - the position where the tracks should be inserted
- snapshot_id - optional playlist's snapshot ID - snapshot_id - optional playlist's snapshot ID
''' """
plid = self._get_id('playlist', playlist_id) plid = self._get_id('playlist', playlist_id)
payload = {"range_start": range_start, payload = {"range_start": range_start,
"range_length": range_length, "range_length": range_length,
@ -494,7 +494,7 @@ class Spotify(object):
def user_playlist_remove_all_occurrences_of_tracks( def user_playlist_remove_all_occurrences_of_tracks(
self, user, playlist_id, tracks, snapshot_id=None): self, user, playlist_id, tracks, snapshot_id=None):
''' Removes all occurrences of the given tracks from the given playlist """ Removes all occurrences of the given tracks from the given playlist
Parameters: Parameters:
- user - the id of the user - user - the id of the user
@ -502,7 +502,7 @@ class Spotify(object):
- tracks - the list of track ids to add to the playlist - tracks - the list of track ids to add to the playlist
- snapshot_id - optional id of the playlist snapshot - snapshot_id - optional id of the playlist snapshot
''' """
plid = self._get_id('playlist', playlist_id) plid = self._get_id('playlist', playlist_id)
ftracks = [self._get_uri('track', tid) for tid in tracks] ftracks = [self._get_uri('track', tid) for tid in tracks]
@ -514,7 +514,7 @@ class Spotify(object):
def user_playlist_remove_specific_occurrences_of_tracks( def user_playlist_remove_specific_occurrences_of_tracks(
self, user, playlist_id, tracks, snapshot_id=None): self, user, playlist_id, tracks, snapshot_id=None):
''' Removes all occurrences of the given tracks from the given playlist """ Removes all occurrences of the given tracks from the given playlist
Parameters: Parameters:
- user - the id of the user - user - the id of the user
@ -523,7 +523,7 @@ class Spotify(object):
[ { "uri":"4iV5W9uYEdYUVa79Axb7Rh", "positions":[2] }, [ { "uri":"4iV5W9uYEdYUVa79Axb7Rh", "positions":[2] },
{ "uri":"1301WleyT98MSxVHPZCA6M", "positions":[7] } ] { "uri":"1301WleyT98MSxVHPZCA6M", "positions":[7] } ]
- snapshot_id - optional id of the playlist snapshot - snapshot_id - optional id of the playlist snapshot
''' """
plid = self._get_id('playlist', playlist_id) plid = self._get_id('playlist', playlist_id)
ftracks = [] ftracks = []
@ -539,18 +539,18 @@ class Spotify(object):
payload=payload) payload=payload)
def user_playlist_follow_playlist(self, playlist_owner_id, playlist_id): def user_playlist_follow_playlist(self, playlist_owner_id, playlist_id):
''' """
Add the current authenticated user as a follower of a playlist. Add the current authenticated user as a follower of a playlist.
Parameters: Parameters:
- playlist_owner_id - the user id of the playlist owner - playlist_owner_id - the user id of the playlist owner
- playlist_id - the id of the playlist - playlist_id - the id of the playlist
''' """
return self._put("users/{}/playlists/{}/followers".format(playlist_owner_id, playlist_id)) return self._put("users/{}/playlists/{}/followers".format(playlist_owner_id, playlist_id))
def user_playlist_is_following(self, playlist_owner_id, playlist_id, user_ids): def user_playlist_is_following(self, playlist_owner_id, playlist_id, user_ids):
''' """
Check to see if the given users are following the given playlist Check to see if the given users are following the given playlist
Parameters: Parameters:
@ -558,19 +558,19 @@ class Spotify(object):
- playlist_id - the id of the playlist - playlist_id - the id of the playlist
- user_ids - the ids of the users that you want to check to see if they follow the playlist. Maximum: 5 ids. - user_ids - the ids of the users that you want to check to see if they follow the playlist. Maximum: 5 ids.
''' """
return self._get("users/{}/playlists/{}/followers/contains?ids={}".format(playlist_owner_id, playlist_id, ','.join(user_ids))) return self._get("users/{}/playlists/{}/followers/contains?ids={}".format(playlist_owner_id, playlist_id, ','.join(user_ids)))
def me(self): def me(self):
''' Get detailed profile information about the current user. """ Get detailed profile information about the current user.
An alias for the 'current_user' method. An alias for the 'current_user' method.
''' """
return self._get('me/') return self._get('me/')
def current_user(self): def current_user(self):
''' Get detailed profile information about the current user. """ Get detailed profile information about the current user.
An alias for the 'me' method. An alias for the 'me' method.
''' """
return self.me() return self.me()
def current_user_playing_track(self): def current_user_playing_track(self):
@ -579,69 +579,69 @@ class Spotify(object):
return self._get('me/player/currently-playing') return self._get('me/player/currently-playing')
def current_user_saved_albums(self, limit=20, offset=0): def current_user_saved_albums(self, limit=20, offset=0):
''' Gets a list of the albums saved in the current authorized user's """ Gets a list of the albums saved in the current authorized user's
"Your Music" library "Your Music" library
Parameters: Parameters:
- limit - the number of albums to return - limit - the number of albums to return
- offset - the index of the first album to return - offset - the index of the first album to return
''' """
return self._get('me/albums', limit=limit, offset=offset) return self._get('me/albums', limit=limit, offset=offset)
def current_user_saved_tracks(self, limit=20, offset=0): def current_user_saved_tracks(self, limit=20, offset=0):
''' Gets a list of the tracks saved in the current authorized user's """ Gets a list of the tracks saved in the current authorized user's
"Your Music" library "Your Music" library
Parameters: Parameters:
- limit - the number of tracks to return - limit - the number of tracks to return
- offset - the index of the first track to return - offset - the index of the first track to return
''' """
return self._get('me/tracks', limit=limit, offset=offset) return self._get('me/tracks', limit=limit, offset=offset)
def current_user_followed_artists(self, limit=20, after=None): def current_user_followed_artists(self, limit=20, after=None):
''' Gets a list of the artists followed by the current authorized user """ Gets a list of the artists followed by the current authorized user
Parameters: Parameters:
- limit - the number of tracks to return - limit - the number of tracks to return
- after - ghe last artist ID retrieved from the previous request - after - ghe last artist ID retrieved from the previous request
''' """
return self._get('me/following', type='artist', limit=limit, return self._get('me/following', type='artist', limit=limit,
after=after) after=after)
def current_user_saved_tracks_delete(self, tracks=None): def current_user_saved_tracks_delete(self, tracks=None):
''' Remove one or more tracks from the current user's """ Remove one or more tracks from the current user's
"Your Music" library. "Your Music" library.
Parameters: Parameters:
- tracks - a list of track URIs, URLs or IDs - tracks - a list of track URIs, URLs or IDs
''' """
tlist = [] tlist = []
if tracks is not None: if tracks is not None:
tlist = [self._get_id('track', t) for t in tracks] tlist = [self._get_id('track', t) for t in tracks]
return self._delete('me/tracks/?ids=' + ','.join(tlist)) return self._delete('me/tracks/?ids=' + ','.join(tlist))
def current_user_saved_tracks_contains(self, tracks=None): def current_user_saved_tracks_contains(self, tracks=None):
''' Check if one or more tracks is already saved in """ Check if one or more tracks is already saved in
the current Spotify user’s “Your Music” library. the current Spotify user’s “Your Music” library.
Parameters: Parameters:
- tracks - a list of track URIs, URLs or IDs - tracks - a list of track URIs, URLs or IDs
''' """
tlist = [] tlist = []
if tracks is not None: if tracks is not None:
tlist = [self._get_id('track', t) for t in tracks] tlist = [self._get_id('track', t) for t in tracks]
return self._get('me/tracks/contains?ids=' + ','.join(tlist)) return self._get('me/tracks/contains?ids=' + ','.join(tlist))
def current_user_saved_tracks_add(self, tracks=None): def current_user_saved_tracks_add(self, tracks=None):
''' Add one or more tracks to the current user's """ Add one or more tracks to the current user's
"Your Music" library. "Your Music" library.
Parameters: Parameters:
- tracks - a list of track URIs, URLs or IDs - tracks - a list of track URIs, URLs or IDs
''' """
tlist = [] tlist = []
if tracks is not None: if tracks is not None:
tlist = [self._get_id('track', t) for t in tracks] tlist = [self._get_id('track', t) for t in tracks]
@ -649,27 +649,27 @@ class Spotify(object):
def current_user_top_artists(self, limit=20, offset=0, def current_user_top_artists(self, limit=20, offset=0,
time_range='medium_term'): time_range='medium_term'):
''' Get the current user's top artists """ Get the current user's top artists
Parameters: Parameters:
- limit - the number of entities to return - limit - the number of entities to return
- offset - the index of the first entity to return - offset - the index of the first entity to return
- time_range - Over what time frame are the affinities computed - time_range - Over what time frame are the affinities computed
Valid-values: short_term, medium_term, long_term Valid-values: short_term, medium_term, long_term
''' """
return self._get('me/top/artists', time_range=time_range, limit=limit, return self._get('me/top/artists', time_range=time_range, limit=limit,
offset=offset) offset=offset)
def current_user_top_tracks(self, limit=20, offset=0, def current_user_top_tracks(self, limit=20, offset=0,
time_range='medium_term'): time_range='medium_term'):
''' Get the current user's top tracks """ Get the current user's top tracks
Parameters: Parameters:
- limit - the number of entities to return - limit - the number of entities to return
- offset - the index of the first entity to return - offset - the index of the first entity to return
- time_range - Over what time frame are the affinities computed - time_range - Over what time frame are the affinities computed
Valid-values: short_term, medium_term, long_term Valid-values: short_term, medium_term, long_term
''' """
return self._get('me/top/tracks', time_range=time_range, limit=limit, return self._get('me/top/tracks', time_range=time_range, limit=limit,
offset=offset) offset=offset)
@ -682,11 +682,11 @@ class Spotify(object):
return self._get('me/player/recently-played', limit=limit) return self._get('me/player/recently-played', limit=limit)
def current_user_saved_albums_add(self, albums=[]): def current_user_saved_albums_add(self, albums=[]):
''' Add one or more albums to the current user's """ Add one or more albums to the current user's
"Your Music" library. "Your Music" library.
Parameters: Parameters:
- albums - a list of album URIs, URLs or IDs - albums - a list of album URIs, URLs or IDs
''' """
alist = [self._get_id('album', a) for a in albums] alist = [self._get_id('album', a) for a in albums]
r = self._put('me/albums?ids=' + ','.join(alist)) r = self._put('me/albums?ids=' + ','.join(alist))
return r return r
@ -707,7 +707,7 @@ class Spotify(object):
def featured_playlists(self, locale=None, country=None, timestamp=None, def featured_playlists(self, locale=None, country=None, timestamp=None,
limit=20, offset=0): limit=20, offset=0):
''' Get a list of Spotify featured playlists """ Get a list of Spotify featured playlists
Parameters: Parameters:
- locale - The desired language, consisting of a lowercase ISO - locale - The desired language, consisting of a lowercase ISO
@ -727,13 +727,13 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0 - offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of (the first object). Use with limit to get the next set of
items. items.
''' """
return self._get('browse/featured-playlists', locale=locale, return self._get('browse/featured-playlists', locale=locale,
country=country, timestamp=timestamp, limit=limit, country=country, timestamp=timestamp, limit=limit,
offset=offset) offset=offset)
def new_releases(self, country=None, limit=20, offset=0): def new_releases(self, country=None, limit=20, offset=0):
''' Get a list of new album releases featured in Spotify """ Get a list of new album releases featured in Spotify
Parameters: Parameters:
- country - An ISO 3166-1 alpha-2 country code. - country - An ISO 3166-1 alpha-2 country code.
@ -744,12 +744,12 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0 - offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of (the first object). Use with limit to get the next set of
items. items.
''' """
return self._get('browse/new-releases', country=country, limit=limit, return self._get('browse/new-releases', country=country, limit=limit,
offset=offset) offset=offset)
def categories(self, country=None, locale=None, limit=20, offset=0): def categories(self, country=None, locale=None, limit=20, offset=0):
''' Get a list of new album releases featured in Spotify """ Get a list of new album releases featured in Spotify
Parameters: Parameters:
- country - An ISO 3166-1 alpha-2 country code. - country - An ISO 3166-1 alpha-2 country code.
@ -763,13 +763,13 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0 - offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of (the first object). Use with limit to get the next set of
items. items.
''' """
return self._get('browse/categories', country=country, locale=locale, return self._get('browse/categories', country=country, locale=locale,
limit=limit, offset=offset) limit=limit, offset=offset)
def category_playlists(self, category_id=None, country=None, limit=20, def category_playlists(self, category_id=None, country=None, limit=20,
offset=0): offset=0):
''' Get a list of new album releases featured in Spotify """ Get a list of new album releases featured in Spotify
Parameters: Parameters:
- category_id - The Spotify category ID for the category. - category_id - The Spotify category ID for the category.
@ -782,13 +782,13 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0 - offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of (the first object). Use with limit to get the next set of
items. items.
''' """
return self._get('browse/categories/' + category_id + '/playlists', return self._get('browse/categories/' + category_id + '/playlists',
country=country, limit=limit, offset=offset) country=country, limit=limit, offset=offset)
def recommendations(self, seed_artists=None, seed_genres=None, def recommendations(self, seed_artists=None, seed_genres=None,
seed_tracks=None, limit=20, country=None, **kwargs): seed_tracks=None, limit=20, country=None, **kwargs):
''' Get a list of recommended tracks for one to five seeds. """ Get a list of recommended tracks for one to five seeds.
Parameters: Parameters:
- seed_artists - a list of artist IDs, URIs or URLs - seed_artists - a list of artist IDs, URIs or URLs
@ -807,7 +807,7 @@ class Spotify(object):
- min/max/target_<attribute> - For the tuneable track attributes listed - min/max/target_<attribute> - For the tuneable track attributes listed
in the documentation, these values provide filters and targeting on in the documentation, these values provide filters and targeting on
results. results.
''' """
params = dict(limit=limit) params = dict(limit=limit)
if seed_artists: if seed_artists:
params['seed_artists'] = ','.join( params['seed_artists'] = ','.join(
@ -831,23 +831,23 @@ class Spotify(object):
return self._get('recommendations', **params) return self._get('recommendations', **params)
def recommendation_genre_seeds(self): def recommendation_genre_seeds(self):
''' Get a list of genres available for the recommendations function. """ Get a list of genres available for the recommendations function.
''' """
return self._get('recommendations/available-genre-seeds') return self._get('recommendations/available-genre-seeds')
def audio_analysis(self, track_id): def audio_analysis(self, track_id):
''' Get audio analysis for a track based upon its Spotify ID """ Get audio analysis for a track based upon its Spotify ID
Parameters: Parameters:
- track_id - a track URI, URL or ID - track_id - a track URI, URL or ID
''' """
trid = self._get_id('track', track_id) trid = self._get_id('track', track_id)
return self._get('audio-analysis/' + trid) return self._get('audio-analysis/' + trid)
def audio_features(self, tracks=[]): def audio_features(self, tracks=[]):
''' Get audio features for one or multiple tracks based upon their Spotify IDs """ Get audio features for one or multiple tracks based upon their Spotify IDs
Parameters: Parameters:
- tracks - a list of track URIs, URLs or IDs, maximum: 50 ids - tracks - a list of track URIs, URLs or IDs, maximum: 50 ids
''' """
if isinstance(tracks, str): if isinstance(tracks, str):
trackid = self._get_id('track', tracks) trackid = self._get_id('track', tracks)
results = self._get('audio-features/?ids=' + trackid) results = self._get('audio-features/?ids=' + trackid)
@ -862,10 +862,10 @@ class Spotify(object):
return results return results
def audio_analysis(self, id): def audio_analysis(self, id):
''' Get audio analysis for a track based upon its Spotify ID """ Get audio analysis for a track based upon its Spotify ID
Parameters: Parameters:
- id - a track URIs, URLs or IDs - id - a track URIs, URLs or IDs
''' """
id = self._get_id('track', id) id = self._get_id('track', id)
return self._get('audio-analysis/'+id) return self._get('audio-analysis/'+id)