spotipy/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased [3.0.0-alpha]

While this is unreleased, please only add v3 features here. Rebasing master onto v3 doesn't require a changelog update.

Added

• Scope - An enum which contains all of the authorization scopes (see here).

Changed

• Made CacheHandler an abstract base class
• Modified the return structure of the audio_features function (wrapping the Get Audio Features for Several Tracks API) to conform to the return structure of the similar methods listed below. The functions wrapping these APIs do not unwrap the single key JSON response, and this is currently the only function that does this.
  • Get Several Tracks
  • Get Multiple Artists
  • Get Multiple Albums
• Renamed the auth parameter of Spotify.__init__ to access_token for better clarity.
• Removed the client_credentials_manager and oauth_manager parameters because they are redundant.
• Replaced the set_auth and auth_manager properties with standard attributes.
• Replaced string concatenations and str.format() with f-strings

Fixed

• Fixed playlist_add_items() to accept only URIs and URLs and not IDs, since 'track' and 'episode' cannot be inferred from ID only

Removed

• Removed the following deprecated methods from Spotify:

  • playlist_tracks
  • user_playlist
  • user_playlist_tracks
  • user_playlist_change_details
  • user_playlist_unfollow
  • user_playlist_add_tracks
  • user_playlist_replace_tracks
  • user_playlist_reorder_tracks
  • user_playlist_remove_all_occurrences_of_tracks
  • user_playlist_remove_specific_occurrences_of_tracks
  • user_playlist_follow_playlist
  • user_playlist_is_following

• Removed the deprecated as_dict parameter from the get_access_token method of SpotifyOAuth and SpotifyPKCE.

• Removed the deprecated get_cached_token and _save_token_info methods of SpotifyOAuth and SpotifyPKCE.

• Removed SpotifyImplicitGrant.

• Removed prompt_for_user_token.

Unreleased [2.x.x]

Added

• Added examples for audiobooks, shows and episodes methods to examples directory
• Use newer string formatters (https://pyformat.info)
• Marked recommendation_genre_seeds as deprecated

Fixed

• Fixed scripts in examples directory that didn't run correctly
• Updated documentation for Client.current_user_top_artists to indicate maximum number of artists limit

Removed

[2.25.0] - 2025-03-01

Added

• Added unit tests for queue functions
• Added detailed function docstrings to 'util.py', including descriptions and special sections that lists arguments, returns, and raises.
• Updated order of instructions for Python and pip package manager installation in TUTORIAL.md
• Updated TUTORIAL.md instructions to match current layout of Spotify Developer Dashboard
• Added test_artist_id, test_artist_url, and test_artists_mixed_ids to non_user_endpoints test.py
• Added rate/request limit to FAQ
• Added custom urllib3.Retry class for printing a warning when a rate/request limit is reached.
• Added personalized_playlist.py, track_recommendations.py, and audio_features_analysis.py to /examples.
• Discord badge in README
• Added SpotifyBaseException and moved all exceptions to exceptions.py
• Marked the following methods as deprecated:
  • artist_related_artists
  • recommendations
  • audio_features
  • audio_analysis
  • featured_playlists
  • category_playlists
• Added FAQ entry for inaccessible playlists
• Type annotations to spotipy.cache_handler

Changed

• Split test and lint workflows

Fixed

• Audiobook integration tests
• Edited docstrings for certain functions in client.py for functions that are no longer in use and have been replaced.
• current_user_unfollow_playlist() now supports playlist IDs, URLs, and URIs rather than previously where it only supported playlist IDs.

Removed

• mock no longer listed as a test dependency. Only built-in unittest.mock is actually used.

[2.24.0] - 2024-05-30

Added

• Added MemcacheCacheHandler, a cache handler that stores the token info using pymemcache.
• Added support for audiobook endpoints: get_audiobook, get_audiobooks, and get_audiobook_chapters.
• Added integration tests for audiobook endpoints.
• Added update field to current_user_follow_playlist.

Changed

• Fixed error obfuscation when Spotify class is being inherited and an error is raised in the Child's __init__
• Replaced artist_albums(album_type=...) with artist_albums(include_groups=...) due to an API change.
• Updated _regex_spotify_url to ignore /intl-<countrycode> in Spotify links
• Improved README, docs and examples

Fixed

• Readthedocs build
• Split test_current_user_save_and_usave_tracks unit test

Removed

• Drop support for EOL Python 3.7

[2.23.0] - 2023-04-07

Added

• Added optional encoder_cls argument to CacheFileHandler, which overwrite default encoder for token before writing to disk
• Integration tests for searching multiple types in multiple markets (non-user endpoints)
• Publish to PyPI action

Fixed

• Fixed the regex for matching playlist URIs with the format spotify:user:USERNAME:playlist:PLAYLISTID.
• search_markets now factors the counts of all types in the total rather than just the first type (#534)

[2.22.1] - 2023-01-23

Added

• Add alternative module installation instruction to README
• Added Comment to README - Getting Started for user to add URI to app in Spotify Developer Dashboard.
• Added playlist_add_tracks.py to example folder

Changed

• Modified docstring for playlist_add_items() to accept "only URIs or URLs", with intended deprecation for IDs in v3

Fixed

• Path traversal vulnerability that may lead to type confusion in URI handling code
• Update contributing.md

[2.22.0] - 2022-12-10

Added

• Integration tests via GHA (non-user endpoints)
• Unit tests for new releases, passing limit parameter with minimum and maximum values of 1 and 50
• Unit tests for categories, omitting country code to test global releases
• Added CODE_OF_CONDUCT.md

Fixed

• Incorrect category_id input for test_category
• Assertion value for test_categories_limit_low and test_categories_limit_high
• Pin GitHub Actions Runner to Ubuntu 20 for Py27
• Fixed potential error where found variable in test_artist_related_artists is undefined if for loop never evaluates to true
• Fixed false positive test test_new_releases which looks up the wrong property of the JSON response object and always evaluates to true

[2.21.0] - 2022-09-26

Added

• Added market parameter to album and albums to address (#753
• Added show_featured_artists.py to /examples.
• Expanded contribution and license sections of the documentation.
• Added FlaskSessionCacheHandler, a cache handler that stores the token info in a flask session.
• Added Python 3.10 in GitHub Actions

Fixed

• Updated the documentation to specify ISO-639-1 language codes.
• Fix AttributeError for text attribute of the Response object
• Require redis v3 if python2.7 (fixes readthedocs)

[2.20.0] - 2022-06-18

Added

• Added RedisCacheHandler, a cache handler that stores the token info in Redis.
• Changed URI handling in client.Spotify._get_id() to remove queries if provided by error.
• Added a new parameter to RedisCacheHandler to allow custom keys (instead of the default token_info key)
• Simplify check for existing token in RedisCacheHandler

Changed

• Removed Python 3.5 and added Python 3.9 in GitHub Action

[2.19.0] - 2021-08-12

Added

• Added MemoryCacheHandler, a cache handler that simply stores the token info in memory as an instance attribute of this class.
• If a network request returns an error status code but the response body cannot be decoded into JSON, then fall back on decoding the body into a string.
• Added DjangoSessionCacheHandler, a cache handler that stores the token in the session framework provided by Django. Web apps using spotipy with Django can directly use this for cache handling.

Fixed

• Fixed a bug in CacheFileHandler.__init__: The documentation says that the username will be retrieved from the environment, but it wasn't.
• Fixed a bug in the initializers for the auth managers that produced a spurious warning message if you provide a cache handler, and you set a value for the "SPOTIPY_CLIENT_USERNAME" environment variable.
• Use generated MIT license and fix license type in pip show

[2.18.0] - 2021-04-13

Added

• Enabled using both short and long IDs for playlist_change_details
• Added a cache handler to SpotifyClientCredentials
• Added the following endpoints
  • Spotify.current_user_saved_episodes
  • Spotify.current_user_saved_episodes_add
  • Spotify.current_user_saved_episodes_delete
  • Spotify.current_user_saved_episodes_contains
  • Spotify.available_markets

Changed

• Add support for a list of scopes rather than just a comma separated string of scopes

Fixed

• Fixed the bugs in SpotifyOAuth.refresh_access_token and SpotifyPKCE.refresh_access_token which raised the incorrect exception upon receiving an error response from the server. This addresses #645.
• Fixed a bug in RequestHandler.do_GET in which the non-existent state attribute of SpotifyOauthError is accessed. This bug occurs when the user clicks "cancel" in the permissions dialog that opens in the browser.
• Cleaned up the documentation for SpotifyClientCredentials.__init__, SpotifyOAuth.__init__, and SpotifyPKCE.__init__.

[2.17.1] - 2021-02-28

Fixed

• allowed_methods requires urllib3>=1.26.0

[2.17.0] - 2021-02-28

Changed

• moved os.remove(session_cache_path()) inside try block to avoid TypeError on app.py example file
• A warning will no longer be emitted when the cache file does not exist at the specified path
• The docs for the auth parameter of Spotify.init use the term "access token" instead of "authorization token"
• Changed docs for search to mention that you can provide multiple types to search for
• The query parameters of requests are now logged
• Deprecate specifying cache_path or username directly to SpotifyOAuth, SpotifyPKCE, and SpotifyImplicitGrant constructors, instead directing users to use the CacheFileHandler cache handler
• Removed requirement for examples/app.py to specify port multiple times (only SPOTIPY_REDIRECT_URI needs to contain the port)

Added

• Added log messages for when the access and refresh tokens are retrieved and when they are refreshed
• Support market optional parameter in track
• Added CacheHandler abstraction to allow users to cache tokens in any way they see fit

Fixed

• Fixed Spotify.user_playlist_reorder_tracks calling Spotify.playlist_reorder_tracks with an incorrect parameter order
• Fixed deprecated Urllib3 Retry(method_whitelist=...) in favor of Retry(allowed_methods=...)

[2.16.1] - 2020-10-24

Fixed

• playlist_tracks example code no longer prints extra characters on final loop iteration
• SpotifyException now thrown when a request fails & has no response (#571, #581)
• Added scope, playlist-read-private, to examples that access user playlists using the spotipy api: current_user_playlists() (#591)
• Enable retries for POST, DELETE, PUT (#577)

Changed

• both inline and starting import lists are sorted using isort module
• changed Max Retries exception code from 599 to 429

[2.16.0] - 2020-09-16

Added

• open_browser can be passed to the constructors of SpotifyOAuth and SpotifyPKCE to make it easier to authorize in browserless environments

[2.15.0] - 2020-09-08

Added

• SpotifyPKCE.parse_auth_response_url, mirroring that method in SpotifyOAuth

Changed

• Specifying a cache_path or username is now optional

Fixed

• Using SpotifyPKCE.get_authorization_url will now generate a code challenge if needed

[2.14.0] - 2020-08-29

Added

• (experimental) Support to search multiple/all markets at once.
• Support to test whether the current user is following certain users or artists
• Proper replacements for all deprecated playlist endpoints (See https://developer.spotify.com/community/news/2018/06/12/changes-to-playlist-uris/ and below)
• Allow for OAuth 2.0 authorization by instructing the user to open the URL in a browser instead of opening the browser.
• Reason for 403 error in SpotifyException
• Support for the PKCE Auth Flow
• Support to advertise different language to Spotify
• Added 'collaborative' parameter to user_playlist_create method.
• Enforce CHANGELOG update on PR
• Adds additional_types parameter to retrieve currently playing podcast episode
• Support to get info about a single category

Deprecated

• user_playlist_change_details in favor of playlist_change_details
• user_playlist_unfollow in favor of current_user_unfollow_playlist
• user_playlist_add_tracks in favor of playlist_add_items
• user_playlist_replace_tracks in favor of playlist_replace_items
• user_playlist_reorder_tracks in favor of playlist_reorder_items
• user_playlist_remove_all_occurrences_of_tracks in favor of playlist_remove_all_occurrences_of_items
• user_playlist_remove_specific_occurrences_of_tracks in favor of playlist_remove_specific_occurrences_of_items
• user_playlist_follow_playlist in favor of current_user_follow_playlist
• user_playlist_is_following in favor of playlist_is_following
• playlist_tracks in favor of playlist_items

Fixed

• fixed issue where episode URIs were being converted to track URIs in playlist calls

[2.13.0] - 2020-06-25

Added

• Added SpotifyImplicitGrant as an auth manager option. It provides user authentication without a client secret but sacrifices the ability to refresh the token without user input. (However, read the class docstring for security advisory.)
• Added built-in verification of the state query parameter
• Added two new attributes: error and error_description to SpotifyOauthError exception class to show authorization/authentication web api errors details.
• Added SpotifyStateError subclass of SpotifyOauthError
• Allow extending SpotifyClientCredentials and SpotifyOAuth
• Added the market parameter to album_tracks

Deprecated

• Deprecated util.prompt_for_user_token in favor of spotipy.Spotify(auth_manager=SpotifyOAuth())

[2.12.0] - 2020-04-26

Added

• Added a method to update the auth token.

Fixed

• Logging regression due to the addition of logging.basicConfig() which was unneeded.

[2.11.2] - 2020-04-19

Changed

• Updated the documentation to give more details on the authorization process and reflect 2020 Spotify Application jargon and practices.

• The local webserver is only started for localhost redirect_uri which specify a port, i.e. it is started for http://localhost:8080 or http://127.0.0.1:8080, not for http://localhost.

Fixed

• Issue where using http://localhost as redirect_uri would cause the authorization process to hang.

[2.11.1] - 2020-04-11

Fixed

• Fixed miscellaneous issues with parsing of callback URL

[2.11.0] - 2020-04-11

Added

• Support for shows/podcasts and episodes
• Added CONTRIBUTING.md

Changed

• Client retry logic has changed as it now uses urllib3's Retry in conjunction with requests Session
• The session is customizable as it allows for:
  • status_forcelist
  • retries
  • status_retries
  • backoff_factor
• Spin up a local webserver to autofill authentication URL
• Use session in SpotifyAuthBase
• Logging used instead of print statements

Fixed

• Close session when Spotipy object is unloaded
• Propagate refresh token error

[2.10.0] - 2020-03-18

Added

• Support for add_to_queue
  • Parameters:
    • track uri, id, or url
    • device id. If None, then the active device is used.
• Add CHANGELOG and LICENSE to released package

[2.9.0] - 2020-02-15

Added

• Support position_ms optional parameter in start_playback
• Add requests_timeout parameter to authentication methods
• Make cache optional in get_access_token

[2.8.0] - 2020-02-12

Added

• Support for playlist_cover_image
• Support after and before parameter in current_user_recently_played
• CI for unit tests
• Automatic token refresh
• auth_manager and oauth_manager optional parameters added to Spotify's init.
• Optional username parameter to be passed to SpotifyOAuth, to infer a cache_path automatically
• Optional as_dict parameter to control SpotifyOAuth's get_access_token output type. However, this is going to be deprecated in the future, and the method will always return a token string
• Optional show_dialog parameter to be passed to SpotifyOAuth

Changed

• Both SpotifyClientCredentials and SpotifyOAuth inherit from a common SpotifyAuthBase which handles common parameters and logics.

[2.7.1] - 2020-01-20

Changed

• PyPi release mistake without pulling last merge first

[2.7.0] - 2020-01-20

Added

• Support for playlist_tracks
• Support for playlist_upload_cover_image

Changed

• user_playlist_tracks doesn't require a user anymore (accepts None)

Deprecated

• Deprecated user_playlist and user_playlist_tracks

[2.6.3] - 2020-01-16

Fixed

• Fixed broken doc in 2.6.2

[2.6.2] - 2020-01-16

Fixed

• Fixed broken examples in README, examples and doc

Changed

• Allow session keepalive
• Bump requests to 2.20.0

[2.6.1] - 2020-01-13

Fixed

• Fixed inconsistent behaviour with some API methods when a full HTTP URL is passed.
• Fixed invalid calls to logging warn method

Removed

• mock no longer needed for install. Only used in tox.

[2.6.0] - 2020-01-12

Added

• Support for playlist to get a playlist without specifying a user
• Support for current_user_saved_albums_delete
• Support for current_user_saved_albums_contains
• Support for user_unfollow_artists
• Support for user_unfollow_users
• Lint with flake8 using GitHub action

Changed

• Fix typos in doc
• Start following SemVer properly

Changed

• Made instructions in the CONTRIBUTING.md file more clear such that it is easier to onboard and there are no conflicts with TUTORIAL.md

[2.5.0] - 2020-01-11

Added follow and player endpoints

[2.4.4] - 2017-01-04

Python 3 fix

[2.4.3] - 2017-01-02

Fixed proxy issue in standard auth flow

[2.4.2] - 2017-01-02

Support getting audio features for a single track

[2.4.1] - 2017-01-02

Incorporated proxy support

[2.4.0] - 2016-12-31

Incorporated a number of PRs

[2.3.8] - 2016-03-31

Added recs, audio features, user top lists

[2.3.7] - 2015-08-10

Added current_user_followed_artists

[2.3.6] - 2015-06-03

Support for offset/limit with album_tracks API

[2.3.5] - 2015-04-28

Fixed bug in auto retry logic

[2.3.3] - 2015-04-01

Added client credential flow

[2.3.2] - 2015-03-31

Added auto retry logic

[2.3.0] - 2015-01-05

Added session support added by akx.

[2.2.0] - 2014-11-15

Added support for user_playlist_tracks

[2.1.0] - 2014-10-25

Added support for new_releases and featured_playlists

[2.0.2] - 2014-08-25

Moved to spotipy at pypi

[1.2.0] - 2014-08-22

Upgraded APIs and docs to make it be a real library

[1.310.0] - 2014-08-20

Added playlist replace and remove methods. Added auth tests. Improved API docs

[1.301.0] - 2014-08-19

Upgraded version number to take precedence over previously botched release (sigh)

[1.50.0] - 2014-08-14

Refactored util out of examples and into the main package

[1.49.0] - 2014-07-23

Support for "Your Music" tracks (add, delete, get), with examples

[1.45.0] - 2014-07-07

Support for related artists' endpoint. Don't use cache auth codes when scope changes

[1.44.0] - 2014-07-03

Added show tracks.py example

[1.43.0] - 2014-06-27

Fixed JSON handling issue

[1.42.0] - 2014-06-19

Removed dependency on simplejson

[1.40.0] - 2014-06-12

Initial public release.

[1.4.2] - 2014-06-21

Added support for retrieving starred playlists

[1.1.0] - 2014-06-17

Updates to match released API

[1.1.0] - 2014-05-18

Repackaged for saner imports

[1.0.0] - 2017-04-05

Initial release