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, **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

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, **kwargs) → Playlist

return Playlist object with the given uri

Parameters

uri – uri of the playlist

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

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

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

property type: Type[spotifython.playlist.Playlist | spotifython.user.User | spotifython.episode.Episode | spotifython.track.Track | spotifython.album.Album | spotifython.artist.Artist | spotifython.show.Show]
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[dict[str, spotifython.abc.Playable | str]]
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 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_artist() 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 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_artist() 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_artist() 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_artist() instead.

property display_name: str
property name: str
property playlists: list[spotifython.playlist.Playlist]
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