Merge branch 'devel' into 'master'

Resolve issue #17: pycm clean-up for open-sourcing

Closes #17

See merge request musicfox/pycm!13

pycm/album.py

@@ -1,33 +1,58 @@
-# import pycm.utilities as utilities
 from . import utilities
 
 
-def metadata(cmid):
+def charts(stype, cmid, start_date, end_date=None):
     """
-    Query the album metadata endpoint given the chartmetric
-    id. 
+    Query the charts for the given album of a selected streamer type. 
+
+    https://api.chartmetric.com/api/album/:id/:type/charts
     
-    https://api.chartmetric.com/api/album/:id
+    :param stype:           string streaming platform, choose from
+                            'applemusic', 'itunes' or 'amazon'
+    :param cmid:            string or int chartmetric album ID
+    :param start_date:      string start data in ISO format
+    :param end_date:        string end date in ISO format
+
+    :return:                list of dictionaries of the chart for
+                            the given album
+    """
+    urlhandle = f"/album/{cmid}/{stype}/charts"
+    params = {
+        "since": start_date,
+        "until": end_date,
+    }
+    data = utilities.RequestData(urlhandle, params=params)
+    return utilities.RequestGet(data)['data']
 
-    :param cmid:        string chartmetric.com entity ID
 
-    :returns:           dictionary of album metadata
+def get_album_ids(id_type, specific_id):
     """
+    Query all the related album IDs given a specific ID type.
 
-    urlhandle = f"/album/{cmid}"
+    https://api.chartmetric.com/api/album/:type/:id/get-ids
+
+    :param id_type:         string of the type of ID, choose from
+                            'chartmetric', 'upc', 'spotify', 'itunes', 'deezer'
+    :param specific_id:     specific ID corresponding to the id_type
+    
+    :return:                list of dictionaries with various types of ID
+    """
+    urlhandle = f"/album/{id_type}/{specific_id}/get-ids"
     data = utilities.RequestData(urlhandle, params=None)
     return utilities.RequestGet(data)
 
 
-def tunefind(cmid):
+def metadata(cmid):
     """
-    Query the album tunefind stats endpoint given the chartmetric id.
+    Query the album metadata endpoint given the chartmetric ID. 
+    
+    https://api.chartmetric.com/api/album/:id
 
-    https://api.chartmetric.com/api/album/:id/tunefind
+    :param cmid:        string or int Chartmetric album ID
 
-    :param cmid:        string chartmetric.com entity ID
+    :return:            dictionary of album metadata
     """
-    urlhandle = f"/album/{cmid}/tunefind"
+    urlhandle = f"/album/{cmid}"
     data = utilities.RequestData(urlhandle, params=None)
     return utilities.RequestGet(data)
 
@@ -44,14 +69,19 @@ def playlists(
     """
     Query the album playlist placement API endpoint.
 
-    https://api.chartmetric.com/api/album/:id/:streamingType/:status/playlists
-    :param cmid:        string chartmetric.com entity ID
+    https://api.chartmetric.com/api/album/:id/:platform/:status/playlists
+
+    :param cmid:        string or int Chartmetric album ID
     :param start_date:  string ISO date
     :param end_date:    string ISO date
-    :param stype:       string streaming platform 'spotify, 'applemusic', or 'deezer'
+    :param stype:       string streaming platform, choose from
+                        'spotify, 'applemusic', or 'deezer'
     :param status:      string 'current' or 'past'
     :param indie:       Boolean true if playlist created by major labels
-    :param limit:       number of entries to be returned
+    :param limit:       int number of entries to be returned,
+                        maximum acceptable is 100
+
+    :return:            list of dictionaries of playlists for the album
     """
     urlhandle = f"/album/{cmid}/{stype}/{status}/playlists"
     params = {
@@ -64,53 +94,20 @@ def playlists(
     return utilities.RequestGet(data)
 
 
-def charts(stype, cmid, start_date, end_date=None):
-    """
-    Query the charts for the given album of a selected streamer type. 
-
-    https://api.chartmetric.com/api/album/:id/:type/charts
-    :params stype:          string streaming platform 'applemusic', 'itunes' or 'amazon'
-    :params cmid:           chartmetric album id
-    :params start_date:     string start data in ISO format
-    :params end_date:       string end date in ISO format
-
-    :return:                list of dictionaries containing the charts of the given album
-    """
-    urlhandle = f"/album/{cmid}/{stype}/charts"
-    params = {
-        "since": start_date,
-        "until": end_date,
-    }
-    data = utilities.RequestData(urlhandle, params=params)
-    return utilities.RequestGet(data)['data']
-
-def get_album_ids(id_type, specific_id):
-    """
-    Query all the album ids given a specific id type.
-
-    https://api.chartmetric.com/api/album/:type/:id/get-ids
-    :params id_type:        string of the type of id requesting
-                            'chartmetric', 'upc', 'spotify', 'itunes', 'deezer'
-    :params specific_id:    specific id corresponding to the id_type
-    
-    :return:                list of dictionaries with various types of id
-    """
-    urlhandle = f"/album/{id_type}/{specific_id}/get-ids"
-    data = utilities.RequestData(urlhandle, params=None)
-    return utilities.RequestGet(data)
-
-
 def stats(cmid, stype, start_date=None, end_date=None):
     """
-    Query the statistics from the given streaming platform (popularity for Spotify).
+    Query the statistics from the given streaming platform,
+    specifically popularity for Spotify.
 
     https://api.chartmetric.com/api/album/:id/:platform/stats
-    :params cmid: Chartmetric album id
-    :params stype: string streaming platform type 'spotify'
-    :params start_date: string of start date in ISO format
-    :params end_date: string of end date in ISO format
+    
+    :param cmid:        string or int Chartmetric album ID
+    :param stype:       string streaming platform type, only 'spotify'
+    :param start_date:  string of start date in ISO format
+    :param end_date:    string of end date in ISO format
 
-    :return: list of dictionaries of the statistics of an album on a streaming platform
+    :return:            list of dictionaries of the statistics
+                        for an album on a streaming platform
     """
     urlhandle = f"/album/{cmid}/{stype}/stats"
     params = {
@@ -126,11 +123,26 @@ def tracks(cmid):
     Query the tracks included in a given album.
 
     https://api.chartmetric.com/api/album/:id/tracks
-    :params cmid: Chartmetric album id
+
+    :params cmid:   string or int Chartmetric album ID
    
-    :return: list of dictionaries of the tracks in an album
+    :return:        list of dictionaries of the tracks in an album
     """
     urlhandle = f"/album/{cmid}/tracks"
     data = utilities.RequestData(urlhandle, params=None)
     return utilities.RequestGet(data)
 
+
+def tunefind(cmid):
+    """
+    Query the album tunefind stats given the Chartmetric ID.
+
+    https://api.chartmetric.com/api/album/:id/tunefind
+
+    :param cmid:    string or int Chartmetric album ID
+
+    :return:        list of dictionaries of tunefind stats
+    """
+    urlhandle = f"/album/{cmid}/tunefind"
+    data = utilities.RequestData(urlhandle, params=None)
+    return utilities.RequestGet(data)