webclient cleanup, doc updates (close #144 #145)

HISTORY.rst

@@ -9,6 +9,8 @@ As of 1.0.0, `semantic versioning <http://semver.org/>`__ is used.
 +++++++++
 released 2013-XX-XX
 
+- add Mobileclient
+- remove broken Webclient.{create_playlist, change_playlist, copy_playlist, search, change_playlist_name}
 - add support for streaming All Access songs
 - add Webclient.get_registered_devices
 - add a toggle to turn off validation per client

README.rst

@@ -4,20 +4,19 @@ gmusicapi: an unofficial API for Google Play Music
 gmusicapi allows control of
 `Google Music <http://music.google.com>`__ with Python.
 
-
 .. code-block:: python
 
-    from gmusicapi import Webclient
+    from gmusicapi import Mobileclient
     
-    api = Webclient()
+    api = Mobileclient()
     api.login('user@gmail.com', 'my-password')
     # => True
-
+    
     library = api.get_all_songs()
     sweet_tracks = [track for track in library if track['artist'] == 'The Cat Empire']
-
+    
     playlist_id = api.create_playlist('Rad muzak')
-    api.change_playlist(playlist_id, sweet_tracks)
+    api.add_songs_to_playlist(playlist_id, sweet_tracks)
     
 **gmusicapi is not supported nor endorsed by Google.**
 
@@ -49,10 +48,11 @@ Status and updates
 .. image:: https://travis-ci.org/simon-weber/Unofficial-Google-Music-API.png?branch=develop
         :target: https://travis-ci.org/simon-weber/Unofficial-Google-Music-API
 
-The Webclient interface has gotten horrible to maintain lately, so I'm currently working on
+The project is in the middle of a major change at the moment: the Webclient interface has
+gotten horrible to maintain, so I'm working on
 switching the the Android app api. This will provide easy All Access support and easier
-maintainability going forward. Expect this release before August -- you can follow along 
-`here <https://github.com/simon-weber/Unofficial-Google-Music-API/pull/142>`__.
+maintainability going forward. At this point, prefer the Mobileclient to the Webclient
+whenever possible.
 
 Version 1.2.0 fixes a bug that fixes uploader_id formatting from a mac address.
 This change may cause another machine to be registered - you can safely remove the

docs/source/reference/webclient.rst

@@ -17,7 +17,6 @@ Getting songs and playlists
 .. automethod:: Webclient.get_all_songs
 .. automethod:: Webclient.get_all_playlist_ids
 .. automethod:: Webclient.get_playlist_songs
-.. automethod:: Webclient.search
 
 Song downloading and streaming
 ------------------------------
@@ -34,14 +33,10 @@ Song manipulation
 
 Playlist manipulation
 ---------------------
-.. automethod:: Webclient.create_playlist
-.. automethod:: Webclient.change_playlist_name
-.. automethod:: Webclient.copy_playlist
 .. automethod:: Webclient.delete_playlist
 
 Playlist content manipulation
 -----------------------------
-.. automethod:: Webclient.change_playlist
 .. automethod:: Webclient.add_songs_to_playlist
 .. automethod:: Webclient.remove_songs_from_playlist
 

example.py

@@ -3,22 +3,22 @@
 
 from getpass import getpass
 
-from gmusicapi import Webclient
+from gmusicapi import Mobileclient
 
 
 def ask_for_credentials():
     """Make an instance of the api and attempts to login with it.
     Return the authenticated api.
     """
 
-    # We're not going to upload anything, so the webclient is what we want.
-    api = Webclient()
+    # We're not going to upload anything, so the Mobileclient is what we want.
+    api = Mobileclient()
 
     logged_in = False
     attempts = 0
 
     while not logged_in and attempts < 3:
-        email = raw_input("Email: ")
+        email = raw_input('Email: ')
         password = getpass()
 
         logged_in = api.login(email, password)
@@ -36,56 +36,56 @@ def demonstrate():
         print "Sorry, those credentials weren't accepted."
         return
 
-    print "Successfully logged in."
+    print 'Successfully logged in.'
     print
 
     # Get all of the users songs.
     # library is a big list of dictionaries, each of which contains a single song.
-    print "Loading library...",
+    print 'Loading library...',
     library = api.get_all_songs()
-    print "done."
+    print 'done.'
 
-    print len(library), "tracks detected."
+    print len(library), 'tracks detected.'
     print
 
     # Show some info about a song. There is no guaranteed order;
     # this is essentially a random song.
     first_song = library[0]
     print "The first song I see is '{}' by '{}'.".format(
-        first_song["name"].encode('utf-8'),
-        first_song["artist"].encode('utf-8'))
+        first_song['title'].encode('utf-8'),
+        first_song['artist'].encode('utf-8'))
 
     # We're going to create a new playlist and add a song to it.
     # Songs are uniquely identified by 'song ids', so let's get the id:
-    song_id = first_song["id"]
+    song_id = first_song['id']
 
     print "I'm going to make a new playlist and add that song to it."
     print "I'll delete it when we're finished."
     print
-    playlist_name = raw_input("Enter a name for the playlist: ")
+    playlist_name = raw_input('Enter a name for the playlist: ')
 
     # Like songs, playlists have unique ids.
     # Google Music allows more than one playlist of the same name;
     # these ids are necessary.
     playlist_id = api.create_playlist(playlist_name)
-    print "Made the playlist."
+    print 'Made the playlist.'
     print
 
     # Now let's add the song to the playlist, using their ids:
     api.add_songs_to_playlist(playlist_id, song_id)
-    print "Added the song to the playlist."
+    print 'Added the song to the playlist.'
     print
 
     # We're all done! The user can now go and see that the playlist is there.
     # The web client syncs our changes in real time.
-    raw_input("You can now check on Google Music that the playlist exists.\n"
-              "When done, press enter to delete the playlist:")
+    raw_input('You can now check on Google Music that the playlist exists.\n'
+              'When done, press enter to delete the playlist:')
     api.delete_playlist(playlist_id)
-    print "Deleted the playlist."
+    print 'Deleted the playlist.'
 
     # It's good practice to logout when finished.
     api.logout()
-    print "All done!"
+    print 'All done!'
 
 if __name__ == '__main__':
     demonstrate()