__init__
Spotify Web API Python3 Library
Overview
This API provides Python programmers the ability to retrieve information from the Spotify Web API from any program written in Python 3. It also allows player control via Spotify Connect devices.
More information about the Spotify Web API can be found on the Spotify Developer Portal page.
IMPORTANT This API assumes you will adhere to all of the terms set forth in the Spotify Developer Terms of Use. The developers of this API are not responsible for misuse of the underlying Spotify Web API.
Features
This API supports all of the features of the Spotify Web API including access to all end points, and support for user authorization with scope(s). Check out the Spotify Web API documentation page for more details.
The following features are supported by this API.
- Authorization: Token generation (Authorization Code, Authorization Code PKCE, Client Credentials) with Scope(s), auto token storage and renewal.
- Albums: Get Album(s), Get Album Tracks, User Favorites (Get,Add,Remove,Check), Get New Releases.
- Artists: Get Artist(s), Get Artist's Albums, Get Artist's Top Tracks, Get Related Artists.
- Audiobooks: Get Audiobook(s), Get Audiobook Chapters, User Favorites (Get,Add,Remove,Check).
- Categories: Get Several Browse Categories, Get Single Browse Category.
- Chapters: Get a Chapter, Get Several Chapters.
- Episodes: Get Episode(s), User Favorites (Get,Add,Remove,Check).
- Genres: Get Available Genre Seeds.
- Markets: Get Available Markets.
- Player: Get Playback State, Transfer Playback, Get Available Devices, Get Currently Playing Track, Start/Resume/Pause/Skip/Seek/Repeat/Shuffle/Volume Playback, Get Recently Played Tracks, Get the User's Queue, Add Item to Playback Queue.
- Playlists: Get Playlist(s), Change Playlist Details, Get/Update/Add/Remove Playlist Items, Get Favorites, Get User's Playlists, Create Playlist, Get Featured Playlists, Get Category's Playlists, Get Playlist Cover Image, Add Custom Playlist Cover Image
- Search: Search for Albums/Artists/Audiobooks/Episodes/Playlists/Shows/Tracks.
- Shows: Get Show(s), Get Show Episodes, User Favorites (Get,Add,Remove,Check).
- Tracks: Get Track(s), User Favorites (Get,Add,Remove,Check), Get Track(s) Audio Features, Recommendations, Analysis.
- Users: Get Current/Another User's Profile, Get Top Items, Favorites (Follow,Unfollow,Check) Artists/Playlist/Users.
- Supports caching of rarely changed configuration data: Categories, Devices, Genres, Markets, UserProfile, etc.
- ... and more
Requirements and Dependencies
The following requirements must be met in order to utilize this API:
- You must have a Spotify account (free or premium). Note that some API functions require a PREMIUM account in order to work. Check the Spotify Developer Documentation pages for more details.
- You will need to create a Spotify App in order to access the Spotify Web API. An App provides the Client ID and Client Secret needed to request an access token by implementing any of the OAuth2 authorization flows. More information about creating an application can be found on the Spotify Getting started with Web API page.
The following Python-related requirements must be met in order to utilize this API:
- Python 3.4 or greater (Python 2 not supported).
- oauthlib (==3.2.2) - for OAuth support.
- platformdirs (==4.1.0) - for platform dependent directory support.
- smartinspectPython (==3.0.30) - for diagnostics and logging support.
- requests (==2.31.0) - for web service request support.
- requests_oauthlib (==1.3.1) - for OAuth support.
- urllib3 (==2.1.0) - for web service request support.
Documentation
Documentation is located in the package library under the 'docs' folder; use the index.html as your starting point. You can also view the latest docs on the readthedocs web-site.
Installation
This module can be easily installed via pip:
$ python3 -m pip install spotifywebapipython
Quick-Start Sample Code
Almost every method is documented with sample code; just click on the "Sample Code" links under the method, and use the "Copy to Clipboard" functionality to copy / paste.
Check out the following classes to get you started:
spotifywebapipython.spotifyclient.SpotifyClient- main client class.
Licensing
This project is licensed and distributed under the terms of the MIT End-User License Agreement (EULA) license.
Logging / Tracing Support
The SmartInspectPython package (installed with this package) can be used to easily debug your applications that utilize this API.
The following topics and code samples will get you started on how to enable logging support.
Note that logging support can be turned on and off without changing code or restarting the application.
Click on the topics below to expand the section and reveal more information.
Configure Logging Support Settings File
Add the following lines to a new file (e.g. "smartinspect.cfg") in your application startup / test directory.
Note the file name can be whatever you like, just specify it on the call to SiAuto.Si.LoadConfiguration() when initializing the logger.
; smartinspect.cfg
; SmartInspect Logging Configuration General settings.
; - "Enabled" parameter to turn logging on (True) or off (False).
; - "Level" parameter to control the logging level (Debug|Verbose|Message|Warning|Error).
; - "AppName" parameter to control the application name.
Enabled = False
Level = Verbose
DefaultLevel = Debug
AppName = My Application Name
; SmartInspect Logging Configuration Output settings.
; - Log to SmartInspect Console Viewer running on the specified network address.
Connections = tcp(host=192.168.1.1,port=4228,timeout=5000,reconnect=true,reconnect.interval=10s,async.enabled=true)
; - Log to a file, keeping 14 days worth of logs.
;Connections = "file(filename=\"./tests/logfiles/logfile.log\", rotate=daily, maxparts=14, append=true)"
; - Log to an encrypted file, keeping 14 days worth of logs.
;Connections = "file(filename=\"./tests/logfiles/logfileEncrypted.sil\", encrypt=true, key=""1234567890123456"", rotate=daily, maxparts=14, append=true)"
; set defaults for new sessions
; note that session defaults do not apply to the SiAuto.Main session, since
; this session was already added before a configuration file can be loaded.
; session defaults only apply to newly added sessions and do not affect existing sessions.
SessionDefaults.Active = True
SessionDefaults.Level = Message
SessionDefaults.ColorBG = 0xFFFFFF
; configure some individual session properties.
; note that this does not add the session to the sessionmanager; it simply
; sets the property values IF the session name already exists.
Session.Main.Active = True
Session.Main.ColorBG = 0xFFFFFF
Initialize Logging Support, MAIN module
Add the following lines to your program startup module.
This will import the necessary package modules, and initialize logging support.
NOTE - This code should only be executed one time!
# load SmartInspect settings from a configuration settings file.
from smartinspectpython.siauto import *
siConfigPath:str = "./tests/smartinspect.cfg"
SIAuto.Si.LoadConfiguration(siConfigPath)
# start monitoring the configuration file for changes, and reload it when it changes.
# this will check the file for changes every 60 seconds.
siConfig:SIConfigurationTimer = SIConfigurationTimer(SIAuto.Si, siConfigPath)
# get smartinspect logger reference.
_logsi:SISession = SIAuto.Main
# log system environment and application startup parameters.
_logsi.LogSeparator(SILevel.Fatal)
_logsi.LogAppDomain(SILevel.Verbose)
_logsi.LogSystem(SILevel.Verbose)
Initialize Logging Support, CLASS or sub-modules
Add the following lines to your program supporting modules.
This will import the necessary package modules, and initialize the shared logging session.
# get smartinspect logger reference.
from smartinspectpython.siauto import *
_logsi:SISession = SIAuto.Main
More Information on SmartInspect
You can use SmartInspectPython by itself to create log files for your own applications.
Use the following PIP command to install the SmartInspectPython package from PyPi.org:
$ python3 -m pip install smartinspectpython
The SmarrtInspect Redistributable Console Viewer (free) is required to view SmartInspect Log (.sil) formatted log files, as well capture packets via the TcpProtocol or PipeProtocol connections. The Redistributable Console Viewer can be downloaded from the Code-Partners Software Downloads Page. Note that the "Redistributable Console Viewer" is a free product, while the "SmartInspect Full Setup" is the Professional level viewer that adds a few more bells and whistles for a fee. Also note that a Console Viewer is NOT required to view plain text (non .sil) formatted log files.
Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
- Fork the Project
- Create your Feature Branch
git checkout -b feature/AmazingFeature - Commit your Changes
git commit -m 'Add some AmazingFeature' - Push to the Branch
git push origin feature/AmazingFeature - Open a Pull Request
View Change Log
Change Log
All notable changes to this project are listed here.
Change are listed in reverse chronological order (newest to oldest).
[ 1.0.66 ] - 2024/06/25
- Updated
ZeroconfResponseclass to convert thestatusandspotifyErrorvalues to numeric from string. Some Spotify Connect devices return them as strings, while other return them as numerics.
[ 1.0.65 ] - 2024/06/25
- Updated
ZeroconfConnect.Connectmethod to account for "ERROR-INVALID-PUBLICKEY" statuses returned for some devices. This will retry the connection request with the PublicKey value returned from the initial request.
[ 1.0.64 ] - 2024/06/24
- Updated
SpotifyClient.GetSpotifyConnectDevicesmethod to correctly set the currently active device.
[ 1.0.63 ] - 2024/06/24
- Updated
ZeroconfConnectclass to process the Spotify Zeroconf API status code from the JSON response instead of processing the HTTP request status code. It has been found that some Spotify Connect manufacturers return different HTTP status codes than other manufacturers; but the Spotify Connectstatus,statusStringandspotifyErrorJSON properties seem to be consistent across the board. - Updated
SpotifyClient.GetSpotifyConnectDevicesmethod to filter out duplicate Spotify Connect Device entries for devices that have been grouped together. For example, the "Bose-ST10-1" and "Bose-ST10-2" are grouped as a stereo pair; there will be two Zeroconf discovery result entries with different instance names, but their Zeroconf getInfo endpoint url will be the same. When this happens, it causes the values to show up as duplicates if we process both of them.
[ 1.0.62 ] - 2024/06/21
- Updated
SpotifyDiscovery.DiscoverDevicesmethod to properly free Zeroconf resources after service discovery, and prevent possible memory leaks and crashes due to running out of resources.
[ 1.0.61 ] - 2024/06/21
- Added
ZeroconfGetInfo.IsInDeviceListproperty that returns the status of active device list verification process (Verification not Performed, Verified Active, Verified Inactive).
[ 1.0.60 ] - 2024/06/21
- Updated
ZeroconfConnectclass to process all responses as JSON responses. It was found that some Spotify Zeroconf API capable devices were not properly setting theContent-Typein the returned http response header. - Updated
SpotifyDiscoveryclass to process the individual Spotify Connect instance names that were discovered via Zeroconf. Prior logic was adding a device for every IPV4 address that was found for an instance, assuming that each instance only contained one IP address; some services contain multiple IP addressess for the same instance name (specifically, theSpotifyConnectadd-on, which runs in a docker container). - Updated
SpotifyDiscoveryclass to rename theHostIpv4Addressproperty (and method arguments) toHostIpAddress. The address specified in this argument can be an IP address (e.g. "192.168.1.81") or an alias (e.g. "bose.speaker.kitchen"). - Updated
ZeroconfConnectclass to rename theHostIpv4Addressproperty (and method arguments) toHostIpAddress. The address specified in this argument can be an IP address (e.g. "192.168.1.81") or an alias (e.g. "bose.speaker.kitchen"). - Updated various
SpotifyClientmethods to utilize the defaultHostIpAddress(orServervalue if defaultHostIpAddresswas not discovered) when connecting to a Spotify Connect capable device. Methods updated were:PlayerActivateDevices,GetSpotifyConnectDevices,PlayerResolveDeviceId.
[ 1.0.59 ] - 2024/06/19
- Updated
SpotifyClientmethods that callPlayerResolveDeviceIdwith a new parameter that indicates if the device should be resolved (true) or not (False). This allows multiple methods that callPlayerResolveDeviceIdto be called from the same method, and only resolve the device one time. This was sone to ensure that device resolution did not occur more than once, as it's such a time consuming operation. Methods updated were:PlayerMediaPlayContext,PlayerMediaPlayTrackFavorites,PlayerMediaPlayTracks,PlayerTransferPlayback.
[ 1.0.58 ] - 2024/06/19
- Updated
SpotifyClient.PlayerResolveDeviceIdmethod callers to log a warning message if the specified device value could not be resolved and just return a null value.
[ 1.0.57 ] - 2024/06/19
- Updated
SpotifyClient.PlayerResolveDeviceIdmethod callers to gracefully handle theSpotifyApiErrorerror if the specified device value could not be resolved.
[ 1.0.56 ] - 2024/06/19
- Updated
SpotifyClient.PlayerResolveDeviceIdmethod to raise aSpotifyApiErrorerror if the specified device value could not be resolved.
[ 1.0.55 ] - 2024/06/19
- Updated
SpotifyConnectDevicesmodel to include aDateLastRefreshedproperty that indicates when the device list was last refreshed.
[ 1.0.54 ] - 2024/06/19
- Updated
SpotifyClient.GetSpotifyConnectDevicesmethod to store results to the configuration cache.
[ 1.0.53 ] - 2024/06/18
- Updated
ZeroconfConnect.Connectmethod to provide a small delay after processing the Spotify Zeroconf API command, which will give the device some time to process the change. - Updated
ZeroconfConnect.Disconnectmethod to provide a small delay after processing the Spotify Zeroconf API command, which will give the device some time to process the change.
[ 1.0.52 ] - 2024/06/18
- Updated
SpotifyClient.GetSpotifyConnectDevicesmethod to retrieve dynamic Spotify Connect devices as well as static devices. Dynamic devices are Spotify Connect devices that are not found in Zeroconf discovery process, but still exist in the player device list. These are usually Spotify Connect web or mobile players with temporary device id's.
[ 1.0.51 ] - 2024/06/18
- Added
SpotifyClient.GetSpotifyConnectDevicesmethod that gets information about all available Spotify Connect player devices (not just ones controlled by a user).
[ 1.0.50 ] - 2024/06/18
- Added
SpotifyClient.ZeroconfClientproperty that contains a reference to the Zeroconf client instance used to discover Spotify Connect devices. - Added
SpotifyDiscovery.ZeroconfClientproperty that contains a reference to the Zeroconf client instance used to discover Spotify Connect devices.
[ 1.0.49 ] - 2024/06/18
- Added
SpotifyClient.PlayerActivateDevicesmethod that activates all Spotify Connect player devices, and (optionally) switches the active user context to the current user context. Note that you can still activate individual devices using theZeroconfConnect.Connectmethod if you wish. - Added
SpotifyClient.PlayerResolveDeviceIdmethod that resolves a Spotify Connect device identifier from a specified device id, name, alias id, or alias name. This will ensure that the device id can be found on the network, as well as connect to the device (if necessary) with the current user context. - Updated various
SpotifyClientmethods to utilize the newSpotifyClient.PlayerResolveDeviceIdmethod so that device id's are automatically activated if they are currently deactivated but available on the local network. Methods updated were:PlayerMediaPlayContext,PlayerMediaPlayTrackFavorites,PlayerMediaPlayTracks,PlayerTransferPlayback. - Updated
SpotifyClientclass constructor so that Spotify Connect user context credentials (e.g. username and password) may be supplied for the resolution of device id / name. Note these credentials are only used for Spotify Connect device resolution, and are not used by method calls that are made to the underlying Spotify Web API. - Updated
SpotifyDiscoveryclass constructor so that aZeroconfinstance can be provided. This allows Home Assistant integrations to use the HA Zeroconf instance and avoid the log warnings of multiple Zeroconf instances in use. - Removed
SpotifyClientprocessing from theSpotifyDiscoveryclass, as the processing was moved into theSpotifyClientclass itself.
[ 1.0.48 ] - 2024/06/10
- Forgot to re-build prior to deploying!
[ 1.0.47 ] - 2024/06/10
- Moved all Spotify Zeroconf API related classes to a new namespace called
zeroconfapi. Classes moved were:ZeroconfResponse,ZeroconfGetInfo,ZeroconfGetInfoAlias,ZeroconfGetInfoDrmMediaFormat. - Added
ZeroconfConnectclass that contains various methods that support interfacing with the Spotify Zeroconf API. - Added
ZeroconfConnect.Connectmethod that calls theaddUserSpotify Zeroconf API endpoint to issue a call to SpConnectionLoginBlob. If successful, the associated device id is added to the Spotify Connect active device list for the specified user account. - Added
ZeroconfConnect.Disconnectmethod that calls theresetUsersSpotify Zeroconf API endpoint to issue a call to SpConnectionLogout; the currently logged in user (if any) will be logged out of Spotify Connect, and the device id removed from the active Spotify Connect device list. - Added
ZeroconfConnect.GetInformationmethod that calls thegetInfoSpotify Zeroconf API endpoint to return information about the device. - Removed
SpotifyClient.ZeroconfAddUsermethod, and replaced it with methodZeroconfConnect.Connect. - Removed
SpotifyClient.ZeroconfResetUsersmethod, and replaced it with methodZeroconfConnect.Disconnect. - Removed
SpotifyClient.ZeroconfGetInformationmethod, and replaced it with methodZeroconfConnect.GetInformation.
[ 1.0.46 ] - 2024/06/07
- Updated the following requirements due to Home Assistant dependency issues: 'oauthlib>=3.2.2', 'platformdirs>=4.1.0', 'requests>=2.31.0', 'requests_oauthlib>=1.3.1', 'zeroconf>=0.132.2'.
[ 1.0.45 ] - 2024/06/07
- Updated
zeroconfrequirements to "zeroconf>=0.132.2". This was causing installation issues with other components that utilize zeroconf.
[ 1.0.44 ] - 2024/06/07
- Added
SpotifyDiscovery.DiscoveredResultsclass property that will contain an array ofZeroconfDiscoveryResultitems that contain discovery details for each service that was discovered. - Added model
ZeroconfDiscoveryResultclass that contains detailed Zeroconf ServiceInfo details that were discovered via Zeroconf. - Added model
ZeroconfPropertyclass that contains Zeroconf ServiceInfo property details that were discovered via Zeroconf. - Added model
ZeroconfResponseclass that contains Zeroconf basic response variables. - Added model
ZeroconfGetInfoclass that contains Zeroconf action=getInfo response variables. - Added model
ZeroconfGetInfoAliasclass that contains Zeroconf action=getInfo Alias response variables. - Added model
ZeroconfGetInfoDrmMediaFormatclass that contains Zeroconf action=getInfo DRM Media format response variables. - Added logic to handle
503 Server Errorresponses from the Spotify Web API. - Added support for Spotify DJ playlist retrieval. As the Spotify Web API does not support retrieving the DJ playlist (
spotify:playlist:37i9dQZF1EYkqdzj48dyYq), it simply returns a manually built representation of the playlist. Note that playlist tracks cannot be retrieved either for the DJ playlist, as the Spotify Web API does not support it.
[ 1.0.43 ] - 2024/04/21
- Added device name support to the following player methods that take a
deviceIdargument for player functions. You can now specify either a device id or device name in thedeviceIdargument to target a specific Spotify Connect Player device.SpotifyClientmethods updated were:AddPlayerQueueItem,PlayerMediaPause,PlayerMediaPlayContext,PlayerMediaPlayTrackFavorites,PlayerMediaPlayTracks,PlayerMediaResume,PlayerMediaSeek,PlayerMediaSkipNext,PlayerMediaSkipPrevious,PlayerSetRepeatMode,PlayerSetShuffleMode,PlayerSetVolume,PlayerTransferPlayback. - Added
SpotifyClient.PlayerConvertDeviceNameToIdmethod that converts a Spotify Connect player device name to it's equivalent id value if the value is a device name. If the value is a device id, then the value is returned as-is.
[ 1.0.42 ] - 2024/04/05
- Added
Device.IsMutedproperty to indicate if volume is zero (muted) or not (unmuted). - Added
PlayerPlayState.IsMutedproperty to indicate if player device volume is zero (muted) or not (unmuted). - Updated
SpotifyClient.PlayerMediaPlayTrackFavoritesmethod to set the shuffle mode prior to starting play of the track list. Prior to this change, the first track would always play first regardless of the shuffle setting; now it is part of the shuffle.
[ 1.0.41 ] - 2024/04/02
- Added
ArtistInfomodel that contains artist bio information. - Added
ArtistInfoTourEventmodel that contains artist on tour event information. - Added
SpotifyClient.GetArtistInfomethod to retrieve artist bio information for a specified Artist id. - Added
SpotifyClient.PlayerMediaPlayTrackFavoritesmethod to play all tracks contained in the current users track favorites. - Added
SpotifyClient.RemovePlaylistmethod to remove a playlist by calling theUnfollowPlaylistmethod.
[ 1.0.40 ] - 2024/03/26
- Updated
SpotifyClient.PlayerVerifyDeviceDefaultmethod to check for a nullDevice.Idvalue when determining if an active device was set. - Added
delayargument to variousSpotifyClientplayer command-related methods, which allows the Spotify Web API a little bit of time to process the change before returning from the method. Methods updated:PlayerMediaPause,PlayerMediaPlayContext,PlayerMediaPlayTracks,PlayerMediaResume,PlayerMediaSeek,PlayerMediaSkipNext,PlayerMediaSkipPrevious,PlayerSetRepeatMode,PlayerSetShuffleMode,PlayerSetVolume,PlayerTransferPlayback,PlayerVerifyDeviceDefault. Default delay is 250 milliseconds, but you can adjust accordingly (including removing the delay if you wish).
[ 1.0.39 ] - 2024/03/26
- Updated
PlayerPlayState.__init__model to properly parse the Actions property.
[ 1.0.38 ] - 2024/03/26
- Updated
Device.__init__model to validate the following properties were initialized from Spotify Web API results, and to set defaults if not: IsActive = False, IsPrivateSession = False, IsRestricted = False, SupportsVolume = False, VolumePercent = 0. - Updated
PlayerPlayState.__init__model to validate the following properties were initialized from Spotify Web API results, and to set defaults if not: Actions = PlayerActions(), Device = Device(), CurrentlyPlayingType = 'unknown', IsPlaying = False, ProgressMS = 0, RepeatState = 'off', ShuffleState = 'off', SmartShuffle = 'off', Timestamp = 0. - Updated
PlayerActions.__init__model to validate the following properties were initialized from Spotify Web API results, and to set defaults if not: InterruptingPlayback = False, Pausing = False, Resuming = False, Seeking = False, SkippingNext = False, SkippingPrev = False, TogglingRepeatContext = False, TogglingRepeatTrack = False, TogglingShuffle = False, TransferringPlayback = False.
[ 1.0.37 ] - 2024/03/19
- Updated
SpotifyClient.FollowArtistsmethod to make theidsargument optional; if not supplied, the currently playing track artist id value is used instead. - Updated
SpotifyClient.UnfollowArtistsmethod to make theidsargument optional; if not supplied, the currently playing track artist id value is used instead. - Updated
SpotifyClient.SaveAlbumFavoritesmethod to make theidsargument optional; if not supplied, the currently playing track album id value is used instead. - Updated
SpotifyClient.RemoveAlbumFavoritesmethod to make theidsargument optional; if not supplied, the currently playing track album id value is used instead. - Updated
SpotifyClient.CreatePlaylistmethod to add theimagePathargument, which assigns an image to the created playlist. - Updated
SpotifyClient.ChangePlaylistDetailsmethod to add theimagePathargument, which assigns an image to the updated playlist details.
[ 1.0.36 ] - 2024/03/19
- Fixed
SpotifyClient.SaveTrackFavoritesmethod for a bug introduced with v1.0.35 update causeing 'object of type 'bool' has no len()' exceptions. - Fixed
SpotifyClient.RemoveTrackFavoritesmethod for a bug introduced with v1.0.35 update causeing 'object of type 'bool' has no len()' exceptions. - Fixed
SpotifyClient.AddPlaylistItemsmethod for a bug introduced with v1.0.35 update causeing 'object of type 'bool' has no len()' exceptions. - Fixed
SpotifyClient.RemovePlaylistItemsmethod for a bug introduced with v1.0.35 update causeing 'object of type 'bool' has no len()' exceptions.
[ 1.0.35 ] - 2024/03/18
- Updated
SpotifyClient.SaveTrackFavoritesmethod to make theidsargument optional; if not supplied, the currently playing id value is used instead. - Updated
SpotifyClient.RemoveTrackFavoritesmethod to make theidsargument optional; if not supplied, the currently playing id value is used instead. - Updated
SpotifyClient.AddPlaylistItemsmethod to make theurisargument optional; if not supplied, the currently playing uri value is used instead. - Updated
SpotifyClient.RemovePlaylistItemsmethod to make theurisargument optional; if not supplied, the currently playing uri value is used instead.
[ 1.0.34 ] - 2024/03/18
- Fixed
SpotifyClient.CreatePlaylistmethod to properly pass the Public and Collaborative parameters to the Spotify Web API. Prior to this, any created playlists were being marked with Public=True.
[ 1.0.33 ] - 2024/03/02
- Added
Device.SelectItemNameAndIdproperty to return a string that can be used in a selection list in the form of "Name (Id)". - Added
Device.GetIdFromSelectItemmethod to return the Id portion of aSelectItemNameAndIdproperty value. - Added
Device.GetNameFromSelectItemmethod to return the Name portion of aSelectItemNameAndIdproperty value.
[ 1.0.32 ] - 2024/02/28
- Updated
PlayerQueueInfoto correctly return theSummaryproperty value when the queue is empty. - Removed
SpotifyClient.SearchPlaylistsmethod argumentspotifyOwnedOnly, as it can be replaced by other functionality (e.g.GetCategoryPlaylists).
[ 1.0.31 ] - 2024/02/27
- Updated all models that used a
root.get('...',[])syntax to useroot.get('...',None)instead, as Spotify Web API will sometimes return anullinstead of an[](empty array) for a key item value. This was causing methods to fail with'NoneType' object is not iterableerrors.
[ 1.0.30 ] - 2024/02/23
- Updated
SpotifyClient.SearchPlaylistsmethod with argumentspotifyOwnedOnlyto filter found items by owner. This simulates the spotify "content generated for you" functionality provided by the Spotify AI engine.
[ 1.0.29 ] - 2024/02/23
- Added
ContainsIdmethod to the following classes:AlbumPageSimplified,AudiobookPageSimplified,ChapterPageSimplified,EpisodePageSimplified,PlaylistPageSimplified,ShowPageSimplified, andTrackPageSimplified. - Updated
SpotifyClient.GetPlayerRecentTracksmethod with auto-pagination support to retrieve ALL available items (or up to a limit total).
[ 1.0.28 ] - 2024/02/21
- Added
SpotifyClient.SearchAlbumsmethod to search Spotify for matching Album criteria. - Added
SpotifyClient.SearchArtistsmethod to search Spotify for matching Artist criteria. - Added
SpotifyClient.SearchAudiobooksmethod to search Spotify for matching Audiobook criteria. - Added
SpotifyClient.SearchEpisodesmethod to search Spotify for matching Episode criteria. - Added
SpotifyClient.SearchPlaylistsmethod to search Spotify for matching Playlist criteria. - Added
SpotifyClient.SearchShowsmethod to search Spotify for matching Show criteria. - Added
SpotifyClient.SearchTracksmethod to search Spotify for matching Track criteria. - Updated
SpotifyClientmethods to add auto-pagination to retrieve ALL available items (or up to a limit total). Methods modified were:GetAlbumFavorites,GetAlbumNewReleases,GetArtistAlbums,GetArtistsFollowed,GetCategoryPlaylists,GetFeaturedPlaylists,GetPlaylistFavorites,GetPlaylistsForUser,GetPlaylistItems,GetAlbumTracks,GetAudiobookChapters,GetAudiobookFavorites,GetBrowseCategorys,GetEpisodeFavorites,GetShowEpisodes,GetShowFavorites,GetTrackFavorites,GetUsersTopArtists,GetUsersTopTracks. - Renamed
SpotifyClient.GetBrowseCategorysmethod toGetBrowseCategorysList. - Renamed
SpotifyClient.GetBrowseCategorysByPagemethod toGetBrowseCategorys. - Added
Category.Uriproperty to simulate a Spotify-like Uri value for a category. This is a helper property - no value with this name is returned from the Spotify Web API. - Updated
PageObjectmodel with property setters for theCursorBefore,CursorAfter,Limit,OffsetandTotalproperties. This allows a user to modify the values when performing custom paging operations. - Updated all
SpotifyClientmethods that utilize amarketargument to ensure that a market value was either supplied or implied (using an authorization access token with a user profile). The Spotify Web API was returning null results for some methods that did not supply a market value while using a public access token (e.g. no country code default).
[ 1.0.27 ] - 2024/02/20
- Updated
SpotifyClient.GetPlayerRecentTracksmethod to retrieve the last 24 hours of play history if neitherafterorbeforearguments were specified.
[ 1.0.26 ] - 2024/02/15
- Added
SpotifyClient.ToStringmethod to display a string representation of the class. - Added
SpotifyClient.ConfigurationCacheproperty to store static configuration objects. - Added
SpotifyClient.ClearConfigurationCachemethod to clear the configuration cache. - Updated
SpotifyClientmethods to add returned results to theConfigurationCachefor faster access:GetBrowseCategory,GetBrowseCategorys,GetGenres,GetMarkets,GetPlayerDevice,GetPlayerDevices,GetUsersCurrentProfile. This increases performance when accessing Spotify information that rarely changes.
[ 1.0.25 ] - 2024/02/10
- Updated urllib3 requirements to "urllib3>=1.21.1,<1.27", to ensure urllib3 version 2.0 is not used. Home Assistant requires urllib3 version less than 2. This was causing intermittent issues with calling requests resulting in **kwargs errors when used in Home Assistant!
[ 1.0.24 ] - 2024/02/10
- Updated
SpotifyClient.MakeRequestmethod to pass ALL parameters in the various request methods. Prior to this fix, there were urllib3 request issues with **KWARGS while using the api in a Home Assistant integration.
[ 1.0.23 ] - 2024/02/09
- Updated
SpotifyClient.MakeRequestmethod to use json library to create JSON request body, instead of the urllib3request(...,json=...)method. The urllib3requestclass seems to have issues processing json data.
[ 1.0.22 ] - 2024/02/09
- Added
SpotifyClient.GetIdFromUrimethod to return the Id portion of a Uri value. - Added
SpotifyClient.GetTypeFromUrimethod to return the Type portion of a Uri value. - Updated
SpotifyClient.GetPlayerDevicemethod to return a selected device by id or name. - Added
SpotifyDiscoveryclass that discovers Spotify Connect devices via Zeroconf. - Updated
UserProfileSimplifiedmethod to default theDisplayNameproperty to theIdproperty value if a display name was not set.
[ 1.0.21 ] - 2024/02/08
- Added
SearchResponse.GetSpotifyOwnedPlaylistsmethod that gets a list of all playlist items in the underlying search response that have an owner ofspotify:user:spotify. These are playlists that are generated for you by the spotify ai engine. - Added
additionalTypesargument toSpotifyClient.GetPlayerPlaybackStatemethod. - Added
additionalTypesargument toSpotifyClient.GetPlayerNowPlayingmethod. - Updated
SpotifyClient.GetPlayerDevicesmethod to return the list of devices in sorted order by Name.
[ 1.0.20 ] - 2024/02/07
- Added
PlayHistoryPage.GetTracksmethod that gets a list of all tracks contained in the underlyingPlayHistorylist. This is a convenience method so one does not have to loop through thePlayHistoryarray ofTrackobjects to get the list of tracks.
[ 1.0.19 ] - 2024/02/07
- Updated
TrackPageSavedmodel to parse aTrackobject instead of aTrackSimplifiedobject. TheTrackobject contains the extraAlbum,ExternalIdsandPopularityproperties. - Updated
TrackRecommendationsmodel to parse aTrackobject instead of aTrackSimplifiedobject. TheTrackobject contains the extraAlbum,ExternalIdsandPopularityproperties. - Added
AlbumPageSaved.GetAlbumsmethod that gets a list of all albums contained in the underlyingItemslist. This is a convenience method so one does not have to loop through theItemsarray ofAlbumSavedobjects to get the list of albums. - Added
TrackPageSaved.GetTracksmethod that gets a list of all tracks contained in the underlyingItemslist. This is a convenience method so one does not have to loop through theItemsarray ofTrackSavedobjects to get the list of tracks. - Added
EpisodePageSaved.GetEpisodesmethod that gets a list of all episodes contained in the underlyingItemslist. This is a convenience method so one does not have to loop through theItemsarray ofEpisodeSavedobjects to get the list of episodes. - Added
ShowPageSaved.GetShowsmethod that gets a list of all shows contained in the underlyingItemslist. This is a convenience method so one does not have to loop through theItemsarray ofShowSavedobjects to get the list of shows. - Added an
ImageUrlproperty to all models that have anImagescollection. The new property returns the first image url in theImageslist, if images are defined; otherwise, null. This is a convenience method so one does not have to loop through theImagesarray ofImageObjectobjects to get an image url.
[ 1.0.18 ] - 2024/02/05
- Updated
SpotifyClientmethods to set the request header authorization key directly, rather than assigning a new dictionary to the value. - Updated
SpotifyClient.MakeRequestmethod to apply token refresh changes to the request authorization header if present. Prior to this fix, the request was still referencing the expired token value. - Added
SpotifyAuthToken.HeaderKeyproperty for request header access. - Added
SpotifyAuthToken.HeaderValueproperty for request header access. - Removed
SpotifyAuthToken.GetHeadersmethod, as it was no longer required.
[ 1.0.17 ] - 2024/02/04
- Updated
SpotifyClientto correctly support thetokenUpdatercallable to update a token for an external provider. - Updated
AuthClientto correctly support thetokenUpdatercallable to update a token for an external provider.
[ 1.0.16 ] - 2024/02/02
- Updated numerous classes with a
ToDictionarymethod to allow dictionary representation of data.
[ 1.0.15 ] - 2024/02/02
- Updated
SpotifyClientmethods with better logging information. - Updated
AuthClientmethods with better logging information.
[ 1.0.14 ] - 2024/02/01
- Updated
SpotifyClientmethods to add basic validation for required parameter values.
[ 1.0.13 ] - 2024/02/01
- Updated
SpotifyClient._CheckResponseForErrorsmethod to use json library to parse JSON response, instead of the urllib3HTTPResponse.json()method. The urllib3HTTPResponseclass can return missing attributes and methods when processing redirects.
[ 1.0.12 ] - 2024/02/01
- Updated
SpotifyClient._CheckResponseForErrorsmethod with better logging information.
[ 1.0.11 ] - 2024/02/01
- Updated
SpotifyClient._CheckResponseForErrorsmethod with better logging information.
[ 1.0.10 ] - 2024/02/01
- Added
SpotifyClient.SetAuthTokenFromTokenmethod to allow the authorization token to be used from an existing OAuth2 token. - Removed
SpotifyClient.SetAuthTokenFromSessionmethod in favor of theSetAuthTokenFromTokenmethod. - Updated scope processing to pass a space-delimited string of scopes instead of an array of strings. It appears that the Spotify Web API will accept both, but API documentation states that a space-delimited string is preferred.
[ 1.0.9 ] - 2024/01/31
- Updated
SpotifyClient.SetAuthTokenFromSessionmethod to correct a bug related to Home Assistant OAuth2Session object.
[ 1.0.8 ] - 2024/01/31
- Added
SpotifyClient.SetAuthTokenFromSessionmethod to allow the authorization token to be used from an existing OAuth2Session.
[ 1.0.7 ] - 2024/01/29
- Allow customization of the redirect uri host and port values in the token authorization process.
[ 1.0.6 ] - 2024/01/29
- Changed urllib3 requirements to a non-specific version so it could run with Home Assistant addons.
[ 1.0.5 ] - 2024/01/29
- Changed Development Status to 5 - Production / Stable.
[ 1.0.4 ] - 2024/01/29
- Removed invalid requirement from setup.py.
[ 1.0.3 ] - 2024/01/29
- Added
SpotifyAuthToken.ProfileIdproperty that indicates the token profile that was loaded.
[ 1.0.2 ] - 2024/01/29
- Corrected the
SpotifyClient.GetTrackRecommendationsmethod to process themarket,maxSpeechiness, andtargetSpeechinessarguments correctly. - Updated
SpotifyClient.SetAuthTokenAuthorizationCodemethod to use a 120 second timeout value while waiting for an authorize response from the user. - Updated
SpotifyClient.SetAuthTokenAuthorizationCodePkcemethod to use a 120 second timeout value while waiting for an authorize response from the user.
[ 1.0.1 ] - 2024/01/17
- Version 1 initial release.