Reference¶

Session management¶

Client¶

class spotifython.Client(authentication: Authentication, cache_dir: str | None = None)¶

standard interface to the api

Parameters:

authentication – Authentication object for client authentication
cache_dir – global path to the directory that this library should cache data in (note that sensitive data you request may be cached, set to None to disable caching)

add_to_queue(element: URI | Playable, device_id: str | None = None)¶

add uri to queue

Parameters:

element – resource to add to queue
device_id – device to target (None to use currently active device

Raises:

SpotifyException – errors according to http response status

property devices: list[dict[str, str | bool | int]]¶: return a list of all devices registered in spotify connect

get_album(uri: URI | str, **kwargs) → Album¶

return Album object with the given uri

Parameters:: uri – uri of the album

get_artist(uri: URI | str, **kwargs) → Artist¶

return Artist object with the given uri

Parameters:: uri – uri of the artist

get_authentication_data() → dict[str, str | int | None]¶

Dump the authentication data for safe caching

Returns:: { “client_id”: client_id, “client_secret”: client_secret, “scope”: str(scope), “refresh_token”: refresh_token, “show_dialog”: show_dialog, “token”: token, “expires”: int(expires) }

get_element(uri: URI | str, **kwargs) → Type[Playlist | User | Episode | Track | Album | Artist | Show]¶: return the element with the matching uri :param uri: uri of the element

get_element_from_data(data: dict | None = None, **kwargs) → Type[Playlist | User | Episode | Track | Album | Artist | Show]¶: return the element with the matching uri :param data: dict with spotify data you got from caching something yourself

get_episode(uri: URI | str, **kwargs) → Episode¶

return Episode object with the given uri

Parameters:: uri – uri of the episode

get_playing() → dict | None¶

returns information to playback state

Returns:: dict with is_playing, device, repeat_state, shuffle_state, context(playlist), item(track), actions

get_playlist(uri: URI | str, **kwargs) → Playlist¶

return Playlist object with the given uri

Parameters:: uri – uri of the playlist

get_show(uri: URI | str, **kwargs) → Show¶

return Show object with the given uri

Parameters:: uri – uri of the Show

get_track(uri: str | URI, **kwargs) → Track¶

return Track object with the given uri

Parameters:: uri – uri of the track

get_user(uri: str | URI, **kwargs) → User¶

return User object with the given uri

Parameters:: uri – uri of the user

property me: Me¶

get the profile of the user who is authenticated

Returns:: user profile

next(device_id: str | None = None)¶

skip to next track in queue

Parameters:: device_id –
Raises:: SpotifyException – errors according to http response status

pause(device_id: str | None = None)¶

pause playback

Parameters:: device_id – device to target (None to use currently active device
Raises:: SpotifyException – errors according to http response status

resume playback or play specified resource only one of albums and context may be specified

Parameters:

elements – list of spotify uris or Playable types to play (None to resume playing)
context – uri or PlayContext to use as context (e.g. playlist or album)
offset – number of song in resource to start playing (only used if context_uri is set)
position_ms – position in song to seek (only used if context_uri is set)
device_id – device to target (None to use currently active device

Raises:

SpotifyException – errors according to http response status

prev(device_id: str | None = None)¶

skip to previous track in queue

Parameters:: device_id –
Raises:: SpotifyException – errors according to http response status

property saved_tracks: SavedTracks¶

get tracks of current user

Returns:: list of tracks saved in the user profile

search(query: str, element_type: str, limit: int = 5, offset: int = 0) → dict[str, list[spotifython.abc.Cacheable]]¶

search for item

Parameters:

query – string to search
element_type – comma-separated list of return types; possible values: “album” “artist” “playlist” “track” “episode” “show”
limit – number of results to return per type
offset – offset of results per type

Returns:

dict with types as keys and lists as albums

search_album(query: str, limit: int = 5, offset: int = 0) → list[spotifython.album.Album]¶

search for album

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found albums

search_artist(query: str, limit: int = 5, offset: int = 0) → list[spotifython.artist.Artist]¶

search for artist

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found artists

search_episode(query: str, limit: int = 5, offset: int = 0) → list[spotifython.episode.Episode]¶

search for episode

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found albums

search_playable(query: str, limit: int = 5, offset: int = 0) → list[spotifython.abc.Playable]¶

search for playable

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found playables

search_playlist(query: str, limit: int = 5, offset: int = 0) → list[spotifython.playlist.Playlist]¶

search for playlist

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found playlists

search_show(query: str, limit: int = 5, offset: int = 0) → list[spotifython.show.Show]¶

search for show

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found users

search_track(query: str, limit: int = 5, offset: int = 0) → list[spotifython.track.Track]¶

search for track

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found tracks

search_user(query: str, limit: int = 5, offset: int = 0) → list[spotifython.user.User]¶

search for user

Parameters:

query – string to search
limit – number of results to return
offset – offset of results

Returns:

list of the found users

set_playback_shuffle(state: bool = True, device_id: str | None = None)¶

set shuffle mode on the specified device

Parameters:

state – whether to activate shuffle
device_id – device to target (None to use active device

Raises:

SpotifyException – errors according to http response status

transfer_playback(device_id: str, play: bool = False)¶

transfer playback to new device

Parameters:

device_id – id of targeted device
play – whether to start playing on new device

property user_playlists: list[spotifython.playlist.Playlist]¶

get playlists of current user

Returns:: list of playlists saved in the user profile

Authentication¶

Store the data needed to interact with the Spotify API. Not all arguments are needed. Options are (client_id, client_secret, scope), (client_id, client_secret, scope, refresh_token), (token, token_expires)

Parameters:

client_id – the Client ID of the application
client_secret – the Client Secret of the application (click on “SHOW CLIENT SECRET”)
scope – the Scope object or string reflecting the permissions you need
show_dialog – whether to query the user every time a new refresh token is requested
token_expires – timestamp when the token expires

classmethod from_dict(data: dict)¶

Parameters:: data – dict generated in to_dict()
Returns:: Authentication

to_dict() → dict¶

Call this function before exiting and store the data somewhere safe.

Returns:: dict with organised data for caching

Scope¶

class spotifython.Scope(user_read_playback_position: bool = False, user_read_email: bool = False, playlist_modify_private: bool = False, playlist_read_private: bool = False, user_library_modify: bool = False, playlist_read_collaborative: bool = False, user_follow_read: bool = False, user_read_playback_state: bool = False, user_read_currently_playing: bool = False, user_read_private: bool = False, playlist_modify_public: bool = False, playlist_read_public: bool = False, user_library_read: bool = False, user_top_read: bool = False, ugc_image_upload: bool = False, user_follow_modify: bool = False, user_modify_playback_state: bool = False, user_read_recently_played: bool = False)¶

A class to organise the scopes for the spotify api. Take a look at the api documentation for more information.

static contains(scope_str1: str, scope_str2: str) → bool¶: checks if the second scope string is contained in the first one

get_permissions() → list[str]¶

static is_equal(scope_str1: str, scope_str2: str) → bool¶

Data representation¶

URI¶

class spotifython.URI(uri_string: str)¶

A simple wrapper for the uri sting.

property id: str¶

Returns:: id of the element

Returns:: type of the element

Playlist¶

class spotifython.Playlist(uri: URI, cache: Cache, name: str | None = None, check_outdated: bool = True, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.get_playlist() instead.

property description: str¶

property images: list[dict[str, (<class 'str'>, <class 'int'>, None)]]¶

get list of the image registered with spotify in different sizes

Returns:: [{‘height’: (int | None), ‘width’: (int | None), ‘url’: str}]

is_expired() → bool¶

property items: list[spotifython.track.Track | spotifython.episode.Episode | spotifython.abc.Playable]¶

property name: str¶

property owner: User¶

property public: bool¶

search(*strings: str) → list[spotifython.abc.Playable]¶

Search for the strings in the song titles. Only returns exact matches for all strings.

Parameters:: strings – strings to search for
Returns:: list of Tracks and Episodes

property snapshot_id: str¶

to_dict(short: bool = False, minimal: bool = False) → dict¶

property uri: URI¶

Album¶

class spotifython.Album(uri: URI, cache: Cache, name: str | None = None, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.get_album() instead.

property artists: list[spotifython.artist.Artist]¶

property images: list[dict[str, (<class 'str'>, <class 'int'>, None)]]¶

get list of the image registered with spotify in different sizes

Returns:: [{‘height’: (int | None), ‘width’: (int | None), ‘url’: str}]

is_expired() → bool¶

property items: list[spotifython.track.Track]¶

property name: str¶

static save(albums: list[spotifython.album.Album])¶: add the given albums to saved albums of the current user

to_dict(short: bool = False, minimal: bool = False) → dict¶

property tracks: list[spotifython.track.Track]¶

static unsave(albums: list[spotifython.album.Album])¶: remove the given albums from saved albums of the current user. fails silently if the album is not saved

property uri: URI¶

Show¶

class spotifython.Show(uri: URI, cache: Cache, name: str | None = None, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.get_show() instead.

property description: str¶

property episodes: list[spotifython.episode.Episode]¶

property images: list[dict[str, (<class 'str'>, <class 'int'>, None)]]¶

get list of the image registered with spotify in different sizes

Returns:: [{‘height’: (int | None), ‘width’: (int | None), ‘url’: str}]

is_expired() → bool¶

property items: list[spotifython.episode.Episode]¶

property name: str¶

static save(shows: list[spotifython.show.Show])¶: add the given albums to saved albums of the current user

to_dict(short: bool = False, minimal: bool = False) → dict¶

static unsave(shows: list[spotifython.show.Show])¶: remove the given albums from saved albums of the current user. fails silently if the show is not saved

property uri: URI¶

Track¶

class spotifython.Track(uri: URI, cache: Cache, name: str | None = None, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.get_track() instead.

property album: Album¶

property artists: list[spotifython.artist.Artist]¶

property images: list[dict[str, (<class 'int'>, <class 'str'>, None)]]¶

get list of the image registered with spotify in different sizes

Returns:: [{‘height’: (int | None), ‘width’: (int | None), ‘url’: str}]

is_expired() → bool¶

property name: str¶

static save(tacks: list[spotifython.track.Track])¶: add the given tracks to saved tracks of the current user

to_dict(short: bool = False, minimal: bool = False) → dict¶

static unsave(tacks: list[spotifython.track.Track])¶: remove the given tracks from saved tracks of the current user. fails silently if the track is not saved

property uri: URI¶

Episode¶

class spotifython.Episode(uri: URI, cache: Cache, name: str | None = None, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.get_episode() instead.

property images: list[dict[str, (<class 'str'>, <class 'int'>, None)]]¶

get list of the image registered with spotify in different sizes

Returns:: [{‘height’: (int | None), ‘width’: (int | None), ‘url’: str}]

is_expired() → bool¶

property name: str¶

static save(episodes: list[spotifython.episode.Episode])¶: add the given albums to saved albums of the current user

property show: Show¶

to_dict(short: bool = False, minimal: bool = False) → dict¶

static unsave(episodes: list[spotifython.episode.Episode])¶: remove the given albums from saved albums of the current user. fails silently if the episode is not saved

property uri: URI¶

Artist¶

class spotifython.Artist(uri: URI, cache: Cache, name: str | None = None, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.get_artist() instead.

is_expired() → bool¶

property name: str¶

to_dict(short: bool = False, minimal: bool = False) → dict¶

property uri: URI¶

User¶

class spotifython.User(uri: URI, cache: Cache, display_name: str | None = None, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.get_user() instead.

property display_name: str¶: Same as name

is_expired() → bool¶

property name: str¶

property playlists: list[spotifython.playlist.Playlist]¶

to_dict(short: bool = False, minimal: bool = False) → dict¶

property uri: URI¶

Me¶

class spotifython.Me(cache: Cache, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.Client.me() instead.

property display_name: str¶: Same as name

is_expired() → bool¶

property name: str¶

property playlists: list[spotifython.playlist.Playlist]¶

property saved_tracks: SavedTracks¶

to_dict(short: bool = False, minimal: bool = False) → dict¶

property uri: str¶

Saved Tracks¶

class spotifython.SavedTracks(cache: Cache, **kwargs)¶

Do not create an object of this class yourself. Use spotifython.client.saved_tracks() instead.

property images: list[dict[str, (<class 'int'>, <class 'str'>, None)]]¶

The saved tracks have no image associated.

Returns:: []

is_expired() → bool¶

property items: list[spotifython.track.Track]¶

property name: str¶

to_dict(short: bool = False, minimal: bool = False) → dict¶

property uri: URI¶

Errors¶

exception spotifython.errors.BadRequestException¶: corresponds to a 400 error from the Spotify API

exception spotifython.errors.ForbiddenException¶: corresponds to a 403 error from the Spotify API

exception spotifython.errors.HttpError¶: base class for Http Exceptions from this library

exception spotifython.errors.InternalServerError¶: corresponds to a 500 error from the Spotify API

exception spotifython.errors.InvalidTokenData¶

exception spotifython.errors.InvalidTokenException¶: corresponds to a 401 error from the Spotify API

exception spotifython.errors.NotFoundException¶: corresponds to a 404 error from the Spotify API

exception spotifython.errors.NotModified¶: corresponds to a 304 error from the Spotify API

exception spotifython.errors.PayloadToLarge¶: corresponds to a 413 error from the Spotify API

exception spotifython.errors.SpotifyException¶: base class for Exceptions from this library

Reference¶

Session management¶

Client¶

Authentication¶

Scope¶

Data representation¶

URI¶

Playlist¶

Album¶

Show¶

Track¶

Episode¶

Artist¶

User¶

Me¶

Saved Tracks¶

Errors¶

spotifython

Navigation

Related Topics