Merge a8a356b5d7 into c52a29f6d2

spotipy/client.py

@@ -400,14 +400,10 @@ class Spotify:
         return self._get("artists/?ids=" + ",".join(tlist))
 
     def artist_albums(
-        self, artist_id, album_type=None, include_groups=None, country=None, limit=20, offset=0
+        self, artist_id, album_type=None, include_groups=None, market=None, limit=20, offset=0
     ):
         """ 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',
@@ -431,12 +427,12 @@ class Spotify:
         return self._get(
             "artists/" + trid + "/albums",
             include_groups=include_groups,
-            country=country,
+            market=market,
             limit=limit,
             offset=offset,
         )
 
-    def artist_top_tracks(self, artist_id, country="US"):
+    def artist_top_tracks(self, artist_id, market="US"):
         """ Get Spotify catalog information about an artist's top 10 tracks
             by country.
 
@@ -446,7 +442,7 @@ class Spotify:
         """
 
         trid = self._get_id("artist", artist_id)
-        return self._get("artists/" + trid + "/top-tracks", country=country)
+        return self._get("artists/" + trid + "/top-tracks", market=market)
 
     def artist_related_artists(self, artist_id):
         """ Get Spotify catalog information about artists similar to an
@@ -590,7 +586,13 @@ class Spotify:
         tlist = [self._get_id("episode", e) for e in episodes]
         return self._get("episodes/?ids=" + ",".join(tlist), market=market)
 
-    def search(self, q, limit=10, offset=0, type="track", market=None):
+    def search(self,
+               q,
+               limit=10,
+               offset=0,
+               type="track",
+               market=None,
+               include_external_audio=False):
         """ searches for an item
 
             Parameters:
@@ -604,7 +606,18 @@ class Spotify:
                          pass in a comma separated string; e.g., 'track,album,episode'.
                 - market - An ISO 3166-1 alpha-2 country code or the string
                            from_token.
+                - include_external_audo - if true, the response will include any relevant
+                                          audio content that is hosted externally.
         """
+        if include_external_audio:
+            return self._get("search",
+                             q=q,
+                             limit=limit,
+                             offset=offset,
+                             type=type,
+                             market=market,
+                             include_external="audio",
+                             )
         return self._get(
             "search", q=q, limit=limit, offset=offset, type=type, market=market
         )
@@ -712,7 +725,7 @@ class Spotify:
         self,
         playlist_id,
         fields=None,
-        limit=100,
+        limit=50,
         offset=0,
         market=None,
         additional_types=("track", "episode")
@@ -1177,6 +1190,7 @@ class Spotify:
         )
 
     def playlist_replace_items(self, playlist_id, items):
+        # TODO: find out where the docs for this endpoint are
         """ Replace all tracks/episodes in a playlist
 
             Parameters:
@@ -1198,6 +1212,7 @@ class Spotify:
         range_length=1,
         snapshot_id=None,
     ):
+        # TODO: find out if it still works
         """ Reorder tracks in a playlist
 
             Parameters:
@@ -1234,6 +1249,7 @@ class Spotify:
         """
 
         plid = self._get_id("playlist", playlist_id)
+        # TODO: aren't episodes also a possible uri type?
         ftracks = [self._get_uri("track", tid) for tid in items]
         payload = {"tracks": [{"uri": track} for track in ftracks]}
         if snapshot_id:
@@ -1245,6 +1261,7 @@ class Spotify:
     def playlist_remove_specific_occurrences_of_items(
         self, playlist_id, items, snapshot_id=None
     ):
+        # TODO: find out if it still works
         """ Removes all occurrences of the given tracks from the given playlist
 
             Parameters:
@@ -1287,7 +1304,7 @@ class Spotify:
         )
 
     def playlist_is_following(
-        self, playlist_id, user_ids
+        self, playlist_id, user_ids=None
     ):
         """
         Check to see if the given users are following the given playlist
@@ -1295,10 +1312,18 @@ class Spotify:
         Parameters:
             - playlist_id - the id of the playlist
             - user_ids - the ids of the users that you want to check to see
-                if they follow the playlist. Maximum: 5 ids.
+                if they follow the playlist. Maximum: 1 ID.
 
         """
-        endpoint = f"playlists/{playlist_id}/followers/contains?ids={','.join(user_ids)}"
+        endpoint = f"playlists/{playlist_id}/followers/contains"
+        if user_ids:
+            warnings.warn(
+                "You're using `playlist_is_following(..., user_ids='...')` "
+                "which will be removed in future versions. "
+                "Please adjust your code accordingly by not using the argument `user_ids`.",
+                DeprecationWarning,
+            )
+            return self._get(endpoint, ids=",".join(user_ids))
         return self._get(endpoint)
 
     def me(self):
@@ -1672,8 +1697,6 @@ class Spotify:
         """ Get a list of new album releases featured in Spotify
 
             Parameters:
-                - country - An ISO 3166-1 alpha-2 country code.
-
                 - limit - The maximum number of items to return. Default: 20.
                   Minimum: 1. Maximum: 50
 
@@ -1681,8 +1704,14 @@ class Spotify:
                   (the first object). Use with limit to get the next set of
                   items.
         """
+        if country:
+            warnings.warn(
+                "You're using `new_releases(..., country=...)`, "
+                "which was removed by Spotify and thus will be ignored.",
+                DeprecationWarning,
+            )
         return self._get(
-            "browse/new-releases", country=country, limit=limit, offset=offset
+            "browse/new-releases", limit=limit, offset=offset
         )
 
     def category(self, category_id, country=None, locale=None):
@@ -1696,9 +1725,14 @@ class Spotify:
                   language code and an ISO 3166-1 alpha-2 country code, joined
                   by an underscore.
         """
+        if country:
+            warnings.warn(
+                "You're using `new_releases(..., country=...)`, "
+                "which was removed by Spotify and thus will be ignored.",
+                DeprecationWarning,
+            )
         return self._get(
             "browse/categories/" + category_id,
-            country=country,
             locale=locale,
         )
 
@@ -1718,9 +1752,14 @@ class Spotify:
                   (the first object). Use with limit to get the next set of
                   items.
         """
+        if country:
+            warnings.warn(
+                "You're using `new_releases(..., country=...)`, "
+                "which was removed by Spotify and thus will be ignored.",
+                DeprecationWarning,
+            )
         return self._get(
             "browse/categories",
-            country=country,
             locale=locale,
             limit=limit,
             offset=offset,
@@ -1751,9 +1790,14 @@ class Spotify:
             "which is marked as deprecated by Spotify.",
             DeprecationWarning,
         )
+        if country:
+            warnings.warn(
+                "You're using `new_releases(..., country=...)`, "
+                "which was removed by Spotify and thus will be ignored.",
+                DeprecationWarning,
+            )
         return self._get(
             "browse/categories/" + category_id + "/playlists",
-            country=country,
             limit=limit,
             offset=offset,
         )