@@ -9,8 +9,8 @@ import time
import six
'''
'''
"""
"""
class SpotifyException ( Exception ) :
@@ -30,7 +30,7 @@ class SpotifyException(Exception):
class Spotify ( object ) :
'''
"""
Example usage::
import spotipy
@@ -46,7 +46,7 @@ class Spotify(object):
user = sp.user( ' plamere ' )
print(user)
'''
"""
trace = False # Enable tracing?
trace_out = False
@@ -54,7 +54,7 @@ class Spotify(object):
def __init__ ( self , auth = None , requests_session = True ,
client_credentials_manager = None , proxies = None , requests_timeout = None ) :
'''
"""
Create a Spotify API object.
:param auth: An authorization token (optional)
@@ -69,7 +69,7 @@ class Spotify(object):
Definition of proxies (optional)
:param requests_timeout:
Tell Requests to stop waiting for a response after a given number of seconds
'''
"""
self . prefix = ' https://api.spotify.com/v1/ '
self . _auth = auth
self . client_credentials_manager = client_credentials_manager
@@ -190,22 +190,22 @@ class Spotify(object):
return self . _internal_call ( ' PUT ' , url , payload , kwargs )
def next ( self , result ) :
'''
"""
Parameters:
- result - a previously returned paged result
'''
"""
if result [ ' next ' ] :
return self . _get ( result [ ' next ' ] )
else :
return None
def previous ( self , result ) :
'''
"""
Parameters:
- result - a previously returned paged result
'''
"""
if result [ ' previous ' ] :
return self . _get ( result [ ' previous ' ] )
else :
@@ -218,49 +218,49 @@ class Spotify(object):
print ( ' warning: ' + msg . format ( * args ) , file = sys . stderr )
def track ( self , track_id ) :
'''
"""
Parameters:
- track_id - a spotify URI, URL or ID
'''
"""
trid = self . _get_id ( ' track ' , track_id )
return self . _get ( ' tracks/ ' + trid )
def tracks ( self , tracks , market = None ) :
'''
"""
Parameters:
- tracks - a list of spotify URIs, URLs or IDs
- market - an ISO 3166-1 alpha-2 country code.
'''
"""
tlist = [ self . _get_id ( ' track ' , t ) for t in tracks ]
return self . _get ( ' tracks/?ids= ' + ' , ' . join ( tlist ) , market = market )
def artist ( self , artist_id ) :
'''
"""
Parameters:
- artist_id - an artist ID, URI or URL
'''
"""
trid = self . _get_id ( ' artist ' , artist_id )
return self . _get ( ' artists/ ' + trid )
def artists ( self , artists ) :
'''
"""
Parameters:
- artists - a list of artist IDs, URIs or URLs
'''
"""
tlist = [ self . _get_id ( ' artist ' , a ) for a in artists ]
return self . _get ( ' artists/?ids= ' + ' , ' . join ( tlist ) )
def artist_albums ( self , artist_id , album_type = None , country = None , limit = 20 ,
offset = 0 ) :
'''
"""
Parameters:
- artist_id - the artist ID, URI or URL
@@ -268,70 +268,70 @@ class Spotify(object):
- country - limit the response to one particular country.
- limit - the number of albums to return
- offset - the index of the first album to return
'''
"""
trid = self . _get_id ( ' artist ' , artist_id )
return self . _get ( ' artists/ ' + trid + ' /albums ' , album_type = album_type ,
country = country , limit = limit , offset = offset )
def artist_top_tracks ( self , artist_id , country = ' US ' ) :
'''
"""
by country.
Parameters:
- artist_id - the artist ID, URI or URL
- country - limit the response to one particular country.
'''
"""
trid = self . _get_id ( ' artist ' , artist_id )
return self . _get ( ' artists/ ' + trid + ' /top-tracks ' , country = country )
def artist_related_artists ( self , artist_id ) :
'''
"""
identified artist. Similarity is based on analysis of the
Spotify community ' s listening history.
Parameters:
- artist_id - the artist ID, URI or URL
'''
"""
trid = self . _get_id ( ' artist ' , artist_id )
return self . _get ( ' artists/ ' + trid + ' /related-artists ' )
def album ( self , album_id ) :
'''
"""
Parameters:
- album_id - the album ID, URI or URL
'''
"""
trid = self . _get_id ( ' album ' , album_id )
return self . _get ( ' albums/ ' + trid )
def album_tracks ( self , album_id , limit = 50 , offset = 0 ) :
'''
"""
Parameters:
- album_id - the album ID, URI or URL
- limit - the number of items to return
- offset - the index of the first item to return
'''
"""
trid = self . _get_id ( ' album ' , album_id )
return self . _get ( ' albums/ ' + trid + ' /tracks/ ' , limit = limit ,
offset = offset )
def albums ( self , albums ) :
'''
"""
Parameters:
- albums - a list of album IDs, URIs or URLs
'''
"""
tlist = [ self . _get_id ( ' album ' , a ) for a in albums ]
return self . _get ( ' albums/?ids= ' + ' , ' . join ( tlist ) )
def search ( self , q , limit = 10 , offset = 0 , type = ' track ' , market = None ) :
'''
"""
Parameters:
- q - the search query
@@ -340,15 +340,15 @@ class Spotify(object):
- type - the type of item to return. One of ' artist ' , ' album ' ,
' track ' or ' playlist '
- 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 )
def user ( self , user ) :
'''
"""
Parameters:
- user - the id of the usr
'''
"""
return self . _get ( ' users/ ' + user )
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 )
def user_playlists ( self , user , limit = 50 , offset = 0 ) :
'''
"""
Parameters:
- user - the id of the usr
- limit - the number of items to return
- offset - the index of the first item to return
'''
"""
return self . _get ( " users/ %s /playlists " % user , limit = limit ,
offset = offset )
def user_playlist ( self , user , playlist_id = None , fields = None ) :
'''
"""
Parameters:
- user - the id of the user
- playlist_id - the id of the playlist
- fields - which fields to return
'''
"""
if playlist_id is None :
return self . _get ( " users/ %s /starred " % ( user ) , fields = fields )
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 ,
limit = 100 , offset = 0 , market = None ) :
'''
"""
Parameters:
- user - the id of the user
@@ -393,28 +393,31 @@ class Spotify(object):
- limit - the maximum number of tracks to return
- offset - the index of the first track to return
- market - an ISO 3166-1 alpha-2 country code.
'''
"""
plid = self . _get_id ( ' playlist ' , playlist_id )
return self . _get ( " users/ %s /playlists/ %s /tracks " % ( user , plid ) ,
limit = limit , offset = offset , fields = fields ,
market = market )
def user_playlist_create ( self , user , name , public = True , description = ' ' ) :
'''
"""
Parameters:
- user - the id of the user
- name - the name of the playlist
- public - is the created playlist public
- description - the description of the playlist
'''
"""
data = { ' name ' : name , ' public ' : public , ' description ' : description }
return self . _post ( " users/ %s /playlists " % ( user , ) , payload = data )
def user_playlist_change_details (
self , user , playlist_id , name = None , public = None ,
collaborative = None , description = None ) :
'''
"""
Parameters:
- user - the id of the user
@@ -423,7 +426,8 @@ class Spotify(object):
- public - optional is the playlist public
- collaborative - optional is the playlist collaborative
- description - optional description of the playlist
'''
"""
data = { }
if isinstance ( name , six . string_types ) :
data [ ' name ' ] = name
@@ -437,37 +441,37 @@ class Spotify(object):
payload = data )
def user_playlist_unfollow ( self , user , playlist_id ) :
'''
"""
Parameters:
- user - the id of the user
- name - the name of the playlist
'''
"""
return self . _delete ( " users/ %s /playlists/ %s /followers " % ( user , playlist_id ) )
def user_playlist_add_tracks ( self , user , playlist_id , tracks ,
position = None ) :
'''
"""
Parameters:
- user - the id of the user
- playlist_id - the id of the playlist
- tracks - a list of track URIs, URLs or IDs
- position - the position to add the tracks
'''
"""
plid = self . _get_id ( ' playlist ' , playlist_id )
ftracks = [ self . _get_uri ( ' track ' , tid ) for tid in tracks ]
return self . _post ( " users/ %s /playlists/ %s /tracks " % ( user , plid ) ,
payload = ftracks , position = position )
def user_playlist_replace_tracks ( self , user , playlist_id , tracks ) :
'''
"""
Parameters:
- user - the id of the user
- playlist_id - the id of the playlist
- tracks - the list of track ids to add to the playlist
'''
"""
plid = self . _get_id ( ' playlist ' , playlist_id )
ftracks = [ self . _get_uri ( ' track ' , tid ) for tid in tracks ]
payload = { " uris " : ftracks }
@@ -477,7 +481,7 @@ class Spotify(object):
def user_playlist_reorder_tracks (
self , user , playlist_id , range_start , insert_before ,
range_length = 1 , snapshot_id = None ) :
'''
"""
Parameters:
- user - the id of the user
@@ -486,7 +490,7 @@ class Spotify(object):
- range_length - optional the number of tracks to be reordered (default: 1)
- insert_before - the position where the tracks should be inserted
- snapshot_id - optional playlist ' s snapshot ID
'''
"""
plid = self . _get_id ( ' playlist ' , playlist_id )
payload = { " range_start " : range_start ,
" range_length " : range_length ,
@@ -498,7 +502,7 @@ class Spotify(object):
def user_playlist_remove_all_occurrences_of_tracks (
self , user , playlist_id , tracks , snapshot_id = None ) :
'''
"""
Parameters:
- user - the id of the user
@@ -506,7 +510,7 @@ class Spotify(object):
- tracks - the list of track ids to add to the playlist
- snapshot_id - optional id of the playlist snapshot
'''
"""
plid = self . _get_id ( ' playlist ' , playlist_id )
ftracks = [ self . _get_uri ( ' track ' , tid ) for tid in tracks ]
@@ -518,7 +522,7 @@ class Spotify(object):
def user_playlist_remove_specific_occurrences_of_tracks (
self , user , playlist_id , tracks , snapshot_id = None ) :
'''
"""
Parameters:
- user - the id of the user
@@ -527,7 +531,7 @@ class Spotify(object):
[ { " uri " : " 4iV5W9uYEdYUVa79Axb7Rh " , " positions " :[2] },
{ " uri " : " 1301WleyT98MSxVHPZCA6M " , " positions " :[7] } ]
- snapshot_id - optional id of the playlist snapshot
'''
"""
plid = self . _get_id ( ' playlist ' , playlist_id )
ftracks = [ ]
@@ -543,18 +547,18 @@ class Spotify(object):
payload = payload )
def user_playlist_follow_playlist ( self , playlist_owner_id , playlist_id ) :
'''
"""
Add the current authenticated user as a follower of a playlist.
Parameters:
- playlist_owner_id - the user id of the playlist owner
- playlist_id - the id of the playlist
'''
"""
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 ) :
'''
"""
Check to see if the given users are following the given playlist
Parameters:
@@ -562,85 +566,90 @@ class Spotify(object):
- 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.
'''
"""
return self . _get ( " users/ {} /playlists/ {} /followers/contains?ids= {} " . format ( playlist_owner_id , playlist_id , ' , ' . join ( user_ids ) ) )
def me ( self ) :
'''
"""
An alias for the ' current_user ' method.
'''
"""
return self . _get ( ' me/ ' )
def current_user ( self ) :
'''
"""
An alias for the ' me ' method.
'''
"""
return self . me ( )
def current_user_playing_track ( self ) :
''' Get information about the current users currently playing track.
'''
return self . _get ( ' me/player/currently-playing ' )
def current_user_saved_albums ( self , limit = 20 , offset = 0 ) :
'''
"""
" Your Music " library
Parameters:
- limit - the number of albums to return
- offset - the index of the first album to return
'''
"""
return self . _get ( ' me/albums ' , limit = limit , offset = offset )
def current_user_saved_tracks ( self , limit = 20 , offset = 0 ) :
'''
"""
" Your Music " library
Parameters:
- limit - the number of tracks to return
- offset - the index of the first track to return
'''
"""
return self . _get ( ' me/tracks ' , limit = limit , offset = offset )
def current_user_followed_artists ( self , limit = 20 , after = None ) :
'''
"""
Parameters:
- limit - the number of tracks to return
- after - ghe last artist ID retrieved from the previous request
'''
"""
return self . _get ( ' me/following ' , type = ' artist ' , limit = limit ,
after = after )
def current_user_saved_tracks_delete ( self , tracks = None ) :
'''
"""
" Your Music " library.
Parameters:
- tracks - a list of track URIs, URLs or IDs
'''
"""
tlist = [ ]
if tracks is not None :
tlist = [ self . _get_id ( ' track ' , t ) for t in tracks ]
return self . _delete ( ' me/tracks/?ids= ' + ' , ' . join ( tlist ) )
def current_user_saved_tracks_contains ( self , tracks = None ) :
'''
"""
the current Spotify user’
Parameters:
- tracks - a list of track URIs, URLs or IDs
'''
"""
tlist = [ ]
if tracks is not None :
tlist = [ self . _get_id ( ' track ' , t ) for t in tracks ]
return self . _get ( ' me/tracks/contains?ids= ' + ' , ' . join ( tlist ) )
def current_user_saved_tracks_add ( self , tracks = None ) :
'''
"""
" Your Music " library.
Parameters:
- tracks - a list of track URIs, URLs or IDs
'''
"""
tlist = [ ]
if tracks is not None :
tlist = [ self . _get_id ( ' track ' , t ) for t in tracks ]
@@ -648,43 +657,65 @@ class Spotify(object):
def current_user_top_artists ( self , limit = 20 , offset = 0 ,
time_range = ' medium_term ' ) :
'''
"""
Parameters:
- limit - the number of entities to return
- offset - the index of the first entity to return
- time_range - Over what time frame are the affinities computed
Valid-values: short_term, medium_term, long_term
'''
"""
return self . _get ( ' me/top/artists ' , time_range = time_range , limit = limit ,
offset = offset )
def current_user_top_tracks ( self , limit = 20 , offset = 0 ,
time_range = ' medium_term ' ) :
'''
"""
Parameters:
- limit - the number of entities to return
- offset - the index of the first entity to return
- time_range - Over what time frame are the affinities computed
Valid-values: short_term, medium_term, long_term
'''
"""
return self . _get ( ' me/top/tracks ' , time_range = time_range , limit = limit ,
offset = offset )
def current_user_recently_played ( self , limit = 50 ) :
''' Get the current user ' s recently played tracks
Parameters:
- limit - the number of entities to return
'''
return self . _get ( ' me/player/recently-played ' , limit = limit )
def current_user_saved_albums_add ( self , albums = [ ] ) :
'''
"""
" Your Music " library.
Parameters:
- albums - a list of album URIs, URLs or IDs
'''
"""
alist = [ self . _get_id ( ' album ' , a ) for a in albums ]
r = self . _put ( ' me/albums?ids= ' + ' , ' . join ( alist ) )
return r
def user_follow_artists ( self , ids = [ ] ) :
''' Follow one or more artists
Parameters:
- ids - a list of artist IDs
'''
return self . _put ( ' me/following?type=artist&ids= ' + ' , ' . join ( ids ) )
def user_follow_users ( self , ids = [ ] ) :
''' Follow one or more users
Parameters:
- ids - a list of user IDs
'''
return self . _put ( ' me/following?type=user&ids= ' + ' , ' . join ( ids ) )
def featured_playlists ( self , locale = None , country = None , timestamp = None ,
limit = 20 , offset = 0 ) :
'''
"""
Parameters:
- locale - The desired language, consisting of a lowercase ISO
@@ -704,13 +735,13 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of
items.
'''
"""
return self . _get ( ' browse/featured-playlists ' , locale = locale ,
country = country , timestamp = timestamp , limit = limit ,
offset = offset )
def new_releases ( self , country = None , limit = 20 , offset = 0 ) :
'''
"""
Parameters:
- country - An ISO 3166-1 alpha-2 country code.
@@ -721,12 +752,12 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of
items.
'''
"""
return self . _get ( ' browse/new-releases ' , country = country , limit = limit ,
offset = offset )
def categories ( self , country = None , locale = None , limit = 20 , offset = 0 ) :
'''
"""
Parameters:
- country - An ISO 3166-1 alpha-2 country code.
@@ -740,13 +771,13 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of
items.
'''
"""
return self . _get ( ' browse/categories ' , country = country , locale = locale ,
limit = limit , offset = offset )
def category_playlists ( self , category_id = None , country = None , limit = 20 ,
offset = 0 ) :
'''
"""
Parameters:
- category_id - The Spotify category ID for the category.
@@ -759,13 +790,13 @@ class Spotify(object):
- offset - The index of the first item to return. Default: 0
(the first object). Use with limit to get the next set of
items.
'''
"""
return self . _get ( ' browse/categories/ ' + category_id + ' /playlists ' ,
country = country , limit = limit , offset = offset )
def recommendations ( self , seed_artists = None , seed_genres = None ,
seed_tracks = None , limit = 20 , country = None , * * kwargs ) :
'''
"""
Parameters:
- seed_artists - a list of artist IDs, URIs or URLs
@@ -784,7 +815,7 @@ class Spotify(object):
- min/max/target_<attribute> - For the tuneable track attributes listed
in the documentation, these values provide filters and targeting on
results.
'''
"""
params = dict ( limit = limit )
if seed_artists :
params [ ' seed_artists ' ] = ' , ' . join (
@@ -808,23 +839,23 @@ class Spotify(object):
return self . _get ( ' recommendations ' , * * params )
def recommendation_genre_seeds ( self ) :
'''
'''
"""
"""
return self . _get ( ' recommendations/available-genre-seeds ' )
def audio_analysis ( self , track_id ) :
'''
"""
Parameters:
- track_id - a track URI, URL or ID
'''
"""
trid = self . _get_id ( ' track ' , track_id )
return self . _get ( ' audio-analysis/ ' + trid )
def audio_features ( self , tracks = [ ] ) :
'''
"""
Parameters:
- tracks - a list of track URIs, URLs or IDs, maximum: 50 ids
'''
"""
if isinstance ( tracks , str ) :
trackid = self . _get_id ( ' track ' , tracks )
results = self . _get ( ' audio-features/?ids= ' + trackid )
@@ -839,13 +870,172 @@ class Spotify(object):
return results
def audio_analysis ( self , id ) :
'''
"""
Parameters:
- id - a track URIs, URLs or IDs
'''
"""
id = self . _get_id ( ' track ' , id )
return self . _get ( ' audio-analysis/ ' + id )
def devices ( self ) :
''' Get a list of user ' s available devices.
'''
return self . _get ( " me/player/devices " )
def current_playback ( self , market = None ) :
''' Get information about user ' s current playback.
Parameters:
- market - an ISO 3166-1 alpha-2 country code.
'''
return self . _get ( " me/player " , market = market )
def currently_playing ( self , market = None ) :
''' Get user ' s currently playing track.
Parameters:
- market - an ISO 3166-1 alpha-2 country code.
'''
return self . _get ( " me/player/currently-playing " , market = market )
def transfer_playback ( self , device_id , force_play = True ) :
''' Transfer playback to another device.
Note that the API accepts a list of device ids, but only
actually supports one.
Parameters:
- device_id - transfer playback to this device
- force_play - true: after transfer, play. false:
keep current state.
'''
data = {
' device_ids ' : [ device_id ] ,
' play ' : force_play
}
return self . _put ( " me/player " , payload = data )
def start_playback ( self , device_id = None , context_uri = None , uris = None , offset = None ) :
''' Start or resume user ' s playback.
Provide a `context_uri` to start playback or a album,
artist, or playlist.
Provide a `uris` list to start playback of one or more
tracks.
Provide `offset` as { " position " : <int>} or { " uri " : " <track uri> " }
to start playback at a particular offset.
Parameters:
- device_id - device target for playback
- context_uri - spotify context uri to play
- uris - spotify track uris
- offset - offset into context by index or track
'''
if context_uri is not None and uris is not None :
self . _warn ( ' specify either context uri or uris, not both ' )
return
if uris is not None and not isinstance ( uris , list ) :
self . _warn ( ' uris must be a list ' )
return
data = { }
if context_uri is not None :
data [ ' context_uri ' ] = context_uri
if uris is not None :
data [ ' uris ' ] = uris
if offset is not None :
data [ ' offset ' ] = offset
return self . _put ( self . _append_device_id ( " me/player/play " , device_id ) , payload = data )
def pause_playback ( self , device_id = None ) :
''' Pause user ' s playback.
Parameters:
- device_id - device target for playback
'''
return self . _put ( self . _append_device_id ( " me/player/pause " , device_id ) )
def next_track ( self , device_id = None ) :
''' Skip user ' s playback to next track.
Parameters:
- device_id - device target for playback
'''
return self . _post ( self . _append_device_id ( " me/player/next " , device_id ) )
def previous_track ( self , device_id = None ) :
''' Skip user ' s playback to previous track.
Parameters:
- device_id - device target for playback
'''
return self . _post ( self . _append_device_id ( " me/player/previous " , device_id ) )
def seek_track ( self , position_ms , device_id = None ) :
''' Seek to position in current track.
Parameters:
- position_ms - position in milliseconds to seek to
- device_id - device target for playback
'''
if not isinstance ( position_ms , int ) :
self . _warn ( ' position_ms must be an integer ' )
return
return self . _put ( self . _append_device_id ( " me/player/seek?position_ms= %s " % position_ms , device_id ) )
def repeat ( self , state , device_id = None ) :
''' Set repeat mode for playback.
Parameters:
- state - `track`, `context`, or `off`
- device_id - device target for playback
'''
if state not in [ ' track ' , ' context ' , ' off ' ] :
self . _warn ( ' invalid state ' )
return
self . _put ( self . _append_device_id ( " me/player/repeat?state= %s " % state , device_id ) )
def volume ( self , volume_percent , device_id = None ) :
''' Set playback volume.
Parameters:
- volume_percent - volume between 0 and 100
- device_id - device target for playback
'''
if not isinstance ( volume_percent , int ) :
self . _warn ( ' volume must be an integer ' )
return
if volume_percent < 0 or volume_percent > 100 :
self . _warn ( ' volume must be between 0 and 100, inclusive ' )
return
self . _put ( self . _append_device_id ( " me/player/volume?volume_percent= %s " % volume_percent , device_id ) )
def shuffle ( self , state , device_id = None ) :
''' Toggle playback shuffling.
Parameters:
- state - true or false
- device_id - device target for playback
'''
if not isinstance ( state , bool ) :
self . _warn ( ' state must be a boolean ' )
return
state = str ( state ) . lower ( )
self . _put ( self . _append_device_id ( " me/player/shuffle?state= %s " % state , device_id ) )
def _append_device_id ( self , path , device_id ) :
''' Append device ID to API path.
Parameters:
- device_id - device id to append
'''
if device_id :
if ' ? ' in path :
path + = " &device_id= %s " % device_id
else :
path + = " ?device_id= %s " % device_id
return path
def _get_id ( self , type , id ) :
fields = id . split ( ' : ' )
if len ( fields ) > = 3 :
Paul Lamere
GitHub