From b4c26eb9e44539da642e04cc130933de19ea8eec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Bruckert?= Date: Thu, 22 May 2025 19:22:18 +0100 Subject: [PATCH] Add documentation warnings to doc --- CHANGELOG.md | 1 + spotipy/client.py | 102 ++++++++++++++++++++++++++++++++++++++++------ spotipy/oauth2.py | 16 ++++++-- spotipy/util.py | 22 ++++++---- 4 files changed, 117 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cb013f2..3b3e287 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ Add your changes below. ### Added - Adds `additional_types` parameter to retrieve currently playing episode +- Add deprecation warnings to documentation ### Fixed diff --git a/spotipy/client.py b/spotipy/client.py index 17b60c1..c5166da 100644 --- a/spotipy/client.py +++ b/spotipy/client.py @@ -404,6 +404,10 @@ class Spotify: ): """ Get Spotify catalog information about an artist's albums + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `artist_albums(..., include_groups='...')` instead. + Parameters: - artist_id - the artist ID, URI or URL - include_groups - the types of items to return. One or more of 'album', 'single', @@ -449,6 +453,9 @@ class Spotify: identified artist. Similarity is based on analysis of the Spotify community's listening history. + .. deprecated:: + This endpoint has been removed by Spotify and is no longer available. + Parameters: - artist_id - the artist ID, URI or URL """ @@ -680,6 +687,10 @@ class Spotify: ): """ Get full details of the tracks of a playlist. + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_items(playlist_id, ..., additional_types=('track',))` instead. + Parameters: - playlist_id - the playlist ID, URI or URL - fields - which fields to return @@ -752,18 +763,22 @@ class Spotify: ) def user_playlist(self, user, playlist_id=None, fields=None, market=None): - warnings.warn( - "You should use `playlist(playlist_id)` instead", - DeprecationWarning, - ) - """ Gets a single playlist of a user + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist(playlist_id)` instead. + Parameters: - user - the id of the user - playlist_id - the id of the playlist - fields - which fields to return """ + warnings.warn( + "You should use `playlist(playlist_id)` instead", + DeprecationWarning, + ) + if playlist_id is None: return self._get(f"users/{user}/starred") return self.playlist(playlist_id, fields=fields, market=market) @@ -777,13 +792,12 @@ class Spotify: offset=0, market=None, ): - warnings.warn( - "You should use `playlist_tracks(playlist_id)` instead", - DeprecationWarning, - ) - """ Get full details of the tracks of a playlist owned by a user. + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_tracks(playlist_id)` instead. + Parameters: - user - the id of the user - playlist_id - the id of the playlist @@ -792,6 +806,10 @@ class Spotify: - offset - the index of the first track to return - market - an ISO 3166-1 alpha-2 country code. """ + warnings.warn( + "You should use `playlist_tracks(playlist_id)` instead", + DeprecationWarning, + ) return self.playlist_tracks( playlist_id, limit=limit, @@ -844,6 +862,10 @@ class Spotify: Changes a playlist's name and/or public/private state + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_change_details(playlist_id, ...)` instead. + Parameters: - user - the id of the user - playlist_id - the id of the playlist @@ -865,6 +887,10 @@ class Spotify: Unfollows (deletes) a playlist for a user + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `current_user_unfollow_playlist(playlist_id)` instead. + Parameters: - user - the id of the user - name - the name of the playlist @@ -882,6 +908,10 @@ class Spotify: Adds tracks to a playlist + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_add_items(playlist_id, tracks)` instead. + Parameters: - user - the id of the user - playlist_id - the id of the playlist @@ -903,6 +933,10 @@ class Spotify: Adds episodes to a playlist + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_add_items(playlist_id, episodes)` instead. + Parameters: - user - the id of the user - playlist_id - the id of the playlist @@ -922,6 +956,10 @@ class Spotify: Replace all tracks in a playlist for a user + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_replace_items(playlist_id, tracks)` instead. + Parameters: - user - the id of the user - playlist_id - the id of the playlist @@ -946,6 +984,10 @@ class Spotify: Reorder tracks in a playlist from a user + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_reorder_items(playlist_id, ...)` instead. + Parameters: - user - the id of the user - playlist_id - the id of the playlist @@ -970,6 +1012,10 @@ class Spotify: """ This function is no longer in use, please use the recommended function in the warning! Removes all occurrences of the given tracks from the given playlist + + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_remove_all_occurrences_of_items(playlist_id, tracks)` instead. Parameters: - user - the id of the user @@ -992,6 +1038,10 @@ class Spotify: """ This function is no longer in use, please use the recommended function in the warning! Removes all occurrences of the given tracks from the given playlist + + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_remove_specific_occurrences_of_items(playlist_id, tracks)` instead. Parameters: - user - the id of the user @@ -1029,6 +1079,10 @@ class Spotify: Add the current authenticated user as a follower of a playlist. + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `current_user_follow_playlist(playlist_id)` instead. + Parameters: - playlist_owner_id - the user id of the playlist owner - playlist_id - the id of the playlist @@ -1046,6 +1100,10 @@ class Spotify: Check to see if the given users are following the given playlist + .. deprecated:: + This method is deprecated and may be removed in a future version. Use + `playlist_is_following(playlist_id, user_ids)` instead. + Parameters: - playlist_owner_id - the user id of the playlist owner - playlist_id - the id of the playlist @@ -1575,6 +1633,9 @@ class Spotify: ): """ Get a list of Spotify featured playlists + .. deprecated:: + This endpoint has been removed by Spotify and is no longer available. + Parameters: - locale - The desired language, consisting of a lowercase ISO 639-1 alpha-2 language code and an uppercase ISO 3166-1 alpha-2 @@ -1671,6 +1732,9 @@ class Spotify: ): """ Get a list of playlists for a specific Spotify category + .. deprecated:: + This endpoint has been removed by Spotify and is no longer available. + Parameters: - category_id - The Spotify category ID for the category. @@ -1708,6 +1772,9 @@ class Spotify: (at least one of `seed_artists`, `seed_tracks` and `seed_genres` are needed) + .. deprecated:: + This endpoint has been removed by Spotify and is no longer available. + Parameters: - seed_artists - a list of artist IDs, URIs or URLs - seed_tracks - a list of track IDs, URIs or URLs @@ -1768,17 +1835,24 @@ class Spotify: return self._get("recommendations", **params) def recommendation_genre_seeds(self): + """ Get a list of genres available for the recommendations function. + + .. deprecated:: + This endpoint has been removed by Spotify and is no longer available. + """ warnings.warn( "You're using `recommendation_genre_seeds(...)`, " "which is marked as deprecated by Spotify.", DeprecationWarning, ) - """ Get a list of genres available for the recommendations function. - """ return self._get("recommendations/available-genre-seeds") def audio_analysis(self, track_id): """ Get audio analysis for a track based upon its Spotify ID + + .. deprecated:: + This endpoint has been removed by Spotify and is no longer available. + Parameters: - track_id - a track URI, URL or ID """ @@ -1792,6 +1866,10 @@ class Spotify: def audio_features(self, tracks=[]): """ Get audio features for one or multiple tracks based upon their Spotify IDs + + .. deprecated:: + This endpoint has been removed by Spotify and is no longer available. + Parameters: - tracks - a list of track URIs, URLs or IDs, maximum: 100 ids """ diff --git a/spotipy/oauth2.py b/spotipy/oauth2.py index 371dd16..23e3faf 100644 --- a/spotipy/oauth2.py +++ b/spotipy/oauth2.py @@ -186,7 +186,7 @@ class SpotifyClientCredentials(SpotifyAuthBase): Else fetches a new token and returns it Parameters: - - as_dict - a boolean indicating if returning the access token + - as_dict: (deprecated) a boolean indicating if returning the access token as a token_info dictionary, otherwise it will be returned as a string. """ @@ -484,8 +484,8 @@ class SpotifyOAuth(SpotifyAuthBase): """ Gets the access token for the app given the code Parameters: - - code - the response code - - as_dict - a boolean indicating if returning the access token + - code: the response code + - as_dict: (deprecated) a boolean indicating if returning the access token as a token_info dictionary, otherwise it will be returned as a string. """ @@ -578,6 +578,11 @@ class SpotifyOAuth(SpotifyAuthBase): return token_info def get_cached_token(self): + """ Gets the cached token for the app + + .. deprecated:: + This method is deprecated and may be removed in a future version. + """ warnings.warn("Calling get_cached_token directly on the SpotifyOAuth object will be " + "deprecated. Instead, please specify a CacheFileHandler instance as " + "the cache_handler in SpotifyOAuth and use the CacheFileHandler's " + @@ -1204,6 +1209,11 @@ class SpotifyImplicitGrant(SpotifyAuthBase): return token_info def get_cached_token(self): + """ Gets the cached token for the app + + .. deprecated:: + This method is deprecated and may be removed in a future version. + """ warnings.warn("Calling get_cached_token directly on the SpotifyImplicitGrant " + "object will be deprecated. Instead, please specify a " + "CacheFileHandler instance as the cache_handler in SpotifyOAuth " + diff --git a/spotipy/util.py b/spotipy/util.py index 7fd9d59..bf9715f 100644 --- a/spotipy/util.py +++ b/spotipy/util.py @@ -37,15 +37,11 @@ def prompt_for_user_token( oauth_manager=None, show_dialog=False ): - warnings.warn( - "'prompt_for_user_token' is deprecated." - "Use the following instead: " - " auth_manager=SpotifyOAuth(scope=scope)" - " spotipy.Spotify(auth_manager=auth_manager)", - DeprecationWarning - ) - """Prompt the user to login if necessary and returns a user token - suitable for use with the spotipy.Spotify constructor. + """ Prompt the user to login if necessary and returns a user token + suitable for use with the spotipy.Spotify constructor. + + .. deprecated:: + This method is deprecated and may be removed in a future version. Parameters: - username - the Spotify username. (optional) @@ -57,6 +53,14 @@ def prompt_for_user_token( - oauth_manager - OAuth manager object. (optional) - show_dialog - If True, a login prompt always shows or defaults to False. (optional) """ + warnings.warn( + "'prompt_for_user_token' is deprecated." + "Use the following instead: " + " auth_manager=SpotifyOAuth(scope=scope)" + " spotipy.Spotify(auth_manager=auth_manager)", + DeprecationWarning + ) + if not oauth_manager: if not client_id: client_id = os.getenv("SPOTIPY_CLIENT_ID")