Reference¶

Session management¶

Client¶

class spotifython.Client(authentication: Authentication, cache_dir: Optional[str] = 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: spotifython.uri.URI | spotifython.abc.Playable, device_id: Optional[str] = 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: spotifython.uri.URI | str, **kwargs) → Album¶

return Album object with the given uri

Parameters: uri – uri of the album

get_artist(uri: spotifython.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: spotifython.uri.URI | str, check_outdated: bool = True, **kwargs) → Type[spotifython.playlist.Playlist | spotifython.user.User | spotifython.episode.Episode | spotifython.track.Track | spotifython.album.Album | spotifython.artist.Artist | spotifython.show.Show]¶: return the element with the matching uri :param uri: uri of the element :param check_outdated: see get_playlist()

get_element_from_data(data: Optional[dict] = None, check_outdated: bool = False) → Type[spotifython.playlist.Playlist | spotifython.user.User | spotifython.episode.Episode | spotifython.track.Track | spotifython.album.Album | spotifython.artist.Artist | spotifython.show.Show]¶: return the element with the matching uri :param data: dict with spotify data you got from caching something yourself :param check_outdated: whether to check if the element is outdated by refetching it

get_episode(uri: spotifython.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: spotifython.uri.URI | str, check_outdated: bool = True, **kwargs) → Playlist¶

return Playlist object with the given uri

Parameters

uri – uri of the playlist
check_outdated – whether to check if the playlist is outdated; True can lead to excessive api calls if the snapshot id is not found

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

return Show object with the given uri

Parameters: uri – uri of the Show

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

return Track object with the given uri

Parameters: uri – uri of the track

get_user(uri: str | spotifython.uri.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: Optional[str] = None)¶

skip to next track in queue

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

pause(device_id: Optional[str] = None)¶

pause playback

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

play(elements: Optional[list[spotifython.uri.URI | spotifython.abc.Playable | str]] = None, context: Optional[Union[URI, PlayContext, str]] = None, offset: Optional[int] = None, position_ms: Optional[int] = None, device_id: Optional[str] = None)¶

resume playback or play specified resource only one of elements 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: Optional[str] = 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 elements

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 episodes

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: Optional[str] = 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¶

class spotifython.Authentication(client_id: Optional[str] = None, client_secret: Optional[str] = None, scope: Optional[Union[Scope, str]] = None, show_dialog: bool = False, refresh_token: Optional[str] = None, token: Optional[str] = None, token_expires: float = 0.0)¶

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.

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: Optional[str] = None, snapshot_id: Optional[str] = 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}]

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: Optional[str] = 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}]

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

property name: str¶

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

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

property uri: URI¶

Show¶

class spotifython.Show(uri: URI, cache: Cache, name: Optional[str] = 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}]

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

property name: str¶

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

property uri: URI¶

Track¶

class spotifython.Track(uri: URI, cache: Cache, name: Optional[str] = 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}]

property name: str¶

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

property uri: URI¶

Episode¶

class spotifython.Episode(uri: URI, cache: Cache, name: Optional[str] = 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}]

property name: str¶

property show: Show¶

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

property uri: URI¶

Artist¶

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

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

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: Optional[str] = None, **kwargs)¶

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

property display_name: str¶: Same as name

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

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: []

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.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.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