Documentation for Mobileclient.get_promoted_songs() is misleading.

[zachreizner]

As I discovered while reading #633, the documentation for Mobileclient.get_promoted_songs() is misleading. The documentation as written reads:

Promoted tracks are determined in an unknown fashion, but positively-rated library tracks are common.

But it seems that it returns the complete list of store songs that have a positively-rated, in the exact order that "Thumbs-up" auto-playlist lists them. It even includes songs that have been explicitly added to the library.

[simon-weber]

I was pretty convinced in the past that it wasn't - see #282 - but maybe it changed? I'm hesitant to change it because a) I'm lazy, and b) I don't want to address another ticket if someone finds a counterexample in their library.

I think I'd be more willing to just deprecate it, to be honest.

[zachreizner]

How about a compromise? I'll submit a PR that deprecates this function and makes a new one called get_top_songs() with the documentation

Tops songs seem to be a auto-generated playlist of positively-rated songs (Thumbs up).

Does that sound good?

[simon-weber]

Sure, that sounds fine. Thanks!

[stevenengler]

Just figured I'd add that for me, the results from get_promoted_songs() are close but not exactly the same as what's shown in the "Thumbs Up" playlist. For example, my "Thumbs Up" playlist on the web has 580 items (mobile has 590), while get_promoted_songs() returns 510 items. Some of the ordering is different as well.

Edit: So different devices show different songs for the "Thumbs Up" playlist, and even get_promoted_songs() returns songs which are not in the "Thumbs Up" playlist on the web. So I'm just going to assume that get_promoted_songs() does give you the "Thumbs Up" playlist, but with all the same quirks as the official Google apps.

Edit 2: You get more similar results if you combine the songs from get_promoted_songs() with [x for x in api.get_all_songs() if 'rating' in x and int(x['rating'])==5]. You will have to remove duplicates by the storeId. Also note that get_promoted_songs() itself can return duplicates (you can also see this on the web).