spotipy/CHANGELOG.md

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## 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](https://github.com/plamere/spotipy/issues/652#issuecomment-797461311)).

### Changed

- Made `CacheHandler` an abstract base class
- Modified the return structure of the `audio_features` function (wrapping the [Get Audio Features for Several Tracks](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-several-audio-features) 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](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-several-tracks)
  - [Get Multiple Artists](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-multiple-artists)
  - [Get Multiple Albums](https://developer.spotify.com/documentation/web-api/reference/#endpoint-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
- Modified docstrings to use the reStructuredText format

### 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](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](https://github.com/spotipy-dev/spotipy/issues/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](https://github.com/plamere/spotipy/issues/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](https://github.com/plamere/spotipy/issues/571), [#581](https://github.com/plamere/spotipy/issues/581))
- Added scope, `playlist-read-private`, to examples that access user playlists using the spotipy api: current_user_playlists() ([#591](https://github.com/plamere/spotipy/issues/591))
- Enable retries for POST, DELETE, PUT ([#577](https://github.com/plamere/spotipy/issues/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](https://semver.org) 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