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,21 +173,21 @@ htmlhelp_basename = 'spotipydoc'
 # -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'spotipy.tex', 'spotipy Documentation',
-   'Paul Lamere', 'manual'),
+    ('index', 'spotipy.tex', 'spotipy Documentation',
+     'Paul Lamere', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -229,9 +230,9 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'spotipy', 'spotipy Documentation',
-   'Paul Lamere', 'spotipy', 'One line description of project.',
-   'Miscellaneous'),
+    ('index', 'spotipy', 'spotipy Documentation',
+     'Paul Lamere', 'spotipy', 'One line description of project.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.

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/app.py

@@ -13,7 +13,7 @@ Prerequisites
     export FLASK_ENV=development
     // so that you can invoke the app outside of the file's directory include
     export FLASK_APP=/path/to/spotipy/examples/app.py
- 
+
     // on Windows, use `SET` instead of `export`
 
 Run app.py

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')
-      
+        # Uses the Spotify Global Top 50 playlist
+        spotipy.Spotify(auth_manager=SpotifyOAuth()).current_user_follow_playlist(
+            '37i9dQZEVXbMDoHDwVN2tF')
+
     else:
-      spotipy.Spotify(auth_manager=SpotifyOAuth()).current_user_follow_playlist(args.playlist)
-    
+        spotipy.Spotify(auth_manager=SpotifyOAuth()).current_user_follow_playlist(args.playlist)
+
+
 if __name__ == '__main__':
     main()

examples/headless.py

@@ -5,4 +5,4 @@ from spotipy.oauth2 import SpotifyOAuth
 # set open_browser=False to prevent Spotipy from attempting to open the default browser
 spotify = spotipy.Spotify(auth_manager=SpotifyOAuth(open_browser=False))
 
-print(spotify.me())
+print(spotify.me())

examples/multiple_accounts.py

@@ -7,4 +7,4 @@ while True:
     username = input("Type the Spotify user ID to use: ")
     token = util.prompt_for_user_token(username, show_dialog=True)
     sp = spotipy.Spotify(token)
-    pprint(sp.me())
+    pprint(sp.me())

examples/my_playlists.py

@@ -8,4 +8,4 @@ sp = spotipy.Spotify(auth_manager=SpotifyOAuth(scope=scope))
 
 results = sp.current_user_playlists(limit=50)
 for i, item in enumerate(results['items']):
-    print("%d %s" % (i, item['name']))
+    print("%d %s" % (i, item['name']))

examples/my_top_tracks.py

@@ -13,4 +13,4 @@ for sp_range in ranges:
     results = sp.current_user_top_tracks(time_range=sp_range, limit=50)
     for i, item in enumerate(results['items']):
         print(i, item['name'], '//', item['artists'][0]['name'])
-    print()
+    print()

examples/playlist_add_items.py

@@ -7,7 +7,6 @@ sp = spotipy.Spotify(auth_manager=SpotifyOAuth(client_id="YOUR_APP_CLIENT_ID",
                                                client_secret="YOUR_APP_CLIENT_SECRET",
                                                redirect_uri="YOUR_APP_REDIRECT_URI",
                                                scope="playlist-modify-private"
-                                                ))
+                                               ))
 
 sp.playlist_add_items('playlist_id', ['list_of_items'])
-

examples/playlist_tracks.py

@@ -12,10 +12,10 @@ while True:
                                  offset=offset,
                                  fields='items.track.id,total',
                                  additional_types=['track'])
-    
+
     if len(response['items']) == 0:
         break
-    
+
     pprint(response['items'])
     offset = offset + len(response['items'])
-    print(offset, "/", response['total'])
+    print(offset, "/", response['total'])

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

examples/user_playlists.py

@@ -16,4 +16,4 @@ sp = spotipy.Spotify(auth_manager=SpotifyOAuth())
 playlists = sp.user_playlists(username)
 
 for playlist in playlists['items']:
-    print(playlist['name'])
+    print(playlist['name'])

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)