modified docstring for playlist_add_items to no longer accept IDs

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Unreleased
 
 // Add new changes below this line
+-   Modified docstring for playlist_add_items() to accept "only URIs or URLs",
+    with intended deprecation for IDs in v3
 
 ### Added
 

docs/conf.py

@@ -11,14 +11,15 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import spotipy
+import sys
+import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('.'))
-import spotipy
 
 # -- General configuration -----------------------------------------------------
 
@@ -172,14 +173,14 @@ htmlhelp_basename = 'spotipydoc'
 # -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
+    # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # 'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
+    # The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+    # 'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
+    # Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # 'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

examples/add_tracks_to_playlist.py

@@ -11,7 +11,7 @@ scope = 'playlist-modify-public'
 
 def get_args():
     parser = argparse.ArgumentParser(description='Adds track to user playlist')
-    parser.add_argument('-t', '--tids', action='append',
+    parser.add_argument('-u', '--uris', action='append',
                         required=True, help='Track ids')
     parser.add_argument('-p', '--playlist', required=True,
                         help='Playlist to add track to')
@@ -22,7 +22,7 @@ def main():
     args = get_args()
 
     sp = spotipy.Spotify(auth_manager=SpotifyOAuth(scope=scope))
-    sp.playlist_add_items(args.playlist, args.tids)
+    sp.playlist_add_items(args.playlist, args.uris)
 
 
 if __name__ == '__main__':

examples/artist_discography.py

@@ -1,4 +1,4 @@
-#Shows the list of all songs sung by the artist or the band
+# Shows the list of all songs sung by the artist or the band
 import argparse
 import logging
 
@@ -34,7 +34,7 @@ def show_album_tracks(album):
         results = sp.next(results)
         tracks.extend(results['items'])
     for i, track in enumerate(tracks):
-        logger.info('%s. %s', i+1, track['name'])
+        logger.info('%s. %s', i + 1, track['name'])
 
 
 def show_artist_albums(artist):
@@ -60,6 +60,7 @@ def show_artist(artist):
     if len(artist['genres']) > 0:
         logger.info('Genres: %s', ','.join(artist['genres']))
 
+
 def main():
     args = get_args()
     artist = get_artist(args.artist)

examples/follow_playlist.py

@@ -3,21 +3,25 @@ import argparse
 import spotipy
 from spotipy.oauth2 import SpotifyOAuth
 
+
 def get_args():
     parser = argparse.ArgumentParser(description='Follows a playlist based on playlist ID')
     parser.add_argument('-p', '--playlist', required=True, help='Playlist ID')
 
     return parser.parse_args()
 
+
 def main():
     args = get_args()
 
     if args.playlist is None:
         # Uses the Spotify Global Top 50 playlist
-      spotipy.Spotify(auth_manager=SpotifyOAuth()).current_user_follow_playlist('37i9dQZEVXbMDoHDwVN2tF')
+        spotipy.Spotify(auth_manager=SpotifyOAuth()).current_user_follow_playlist(
+            '37i9dQZEVXbMDoHDwVN2tF')
 
     else:
         spotipy.Spotify(auth_manager=SpotifyOAuth()).current_user_follow_playlist(args.playlist)
 
+
 if __name__ == '__main__':
     main()

examples/playlist_add_items.py

@@ -10,4 +10,3 @@ sp = spotipy.Spotify(auth_manager=SpotifyOAuth(client_id="YOUR_APP_CLIENT_ID",
                                                ))
 
 sp.playlist_add_items('playlist_id', ['list_of_items'])
-

examples/simple3.py

@@ -1,4 +1,4 @@
-#Shows the name of the artist/band and their image by giving a link
+# Shows the name of the artist/band and their image by giving a link
 import sys
 
 from spotipy.oauth2 import SpotifyClientCredentials

spotipy/client.py

@@ -846,8 +846,27 @@ class Spotify(object):
                 - tracks - a list of track URIs, URLs or IDs
                 - position - the position to add the tracks
         """
+        tracks = [self._get_uri("track", tid) for tid in tracks]
         return self.playlist_add_items(playlist_id, tracks, position)
 
+    def user_playlist_add_episodes(
+        self, user, playlist_id, episodes, position=None
+    ):
+        warnings.warn(
+            "You should use `playlist_add_items(playlist_id, episodes)` instead",
+            DeprecationWarning,
+        )
+        """ Adds episodes to a playlist
+
+            Parameters:
+                - user - the id of the user
+                - playlist_id - the id of the playlist
+                - episodes - a list of track URIs, URLs or IDs
+                - position - the position to add the episodes
+        """
+        episodes = [self._get_uri("episode", tid) for tid in episodes]
+        return self.playlist_add_items(playlist_id, episodes, position)
+
     def user_playlist_replace_tracks(self, user, playlist_id, tracks):
         """ Replace all tracks in a playlist for a user
 
@@ -1032,7 +1051,7 @@ class Spotify(object):
 
             Parameters:
                 - playlist_id - the id of the playlist
-                - items - a list of track/episode URIs, URLs or IDs
+                - items - a list of track/episode URIs or URLs
                 - position - the position to add the tracks
         """
         plid = self._get_id("playlist", playlist_id)