From c119d1ce5b54d42ead132b1b4d0231ba59442eee Mon Sep 17 00:00:00 2001
From: Domenico Iezzi <domenico.iezzi.201@gmail.com>
Date: Tue, 22 Jan 2019 23:09:13 +0100
Subject: [PATCH] Improve list() documentation and test case

---
 gpapi/googleplay.py | 25 +++++++++++++++++--------
 test/test.py        |  8 +++++---
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/gpapi/googleplay.py b/gpapi/googleplay.py
index 69f0559..68c05c4 100644
--- a/gpapi/googleplay.py
+++ b/gpapi/googleplay.py
@@ -428,18 +428,27 @@ class GooglePlayAPI(object):
         return utils.parseProtobufObj(data.payload.browseResponse)
 
     def list(self, cat, ctr=None, nb_results=None, offset=None):
-        """List apps for a specfic category *cat*.
+        """List all possible subcategories for a specific category. If
+        also a subcategory is provided, list apps from this category.
 
-        If ctr (subcategory ID) is None, returns a list of valid subcategories.
-
-        If ctr is provided, list apps within this subcategory."""
+        Args:
+            cat (str): category id
+            ctr (str): subcategory id
+            nb_results (int): if a subcategory is specified, limit number
+                of results to this number
+            offset (int): if a subcategory is specified, start counting from this
+                result
+        Returns:
+            A list of categories. If subcategory is specified, a list of apps in this
+            category.
+        """
         path = LIST_URL + "?c=3&cat={}".format(requests.utils.quote(cat))
         if ctr is not None:
             path += "&ctr={}".format(requests.utils.quote(ctr))
         if nb_results is not None:
-            path += "&n={}".format(requests.utils.quote(nb_results))
+            path += "&n={}".format(requests.utils.quote(str(nb_results)))
         if offset is not None:
-            path += "&o={}".format(requests.utils.quote(offset))
+            path += "&o={}".format(requests.utils.quote(str(offset)))
         data = self.executeRequestApi2(path)
         clusters = []
         docs = []
@@ -451,8 +460,8 @@ class GooglePlayAPI(object):
             return [c.docid for c in clusters]
         else:
             apps = []
-            for d in data.payload.listResponse.doc:
-                for c in d.child: # category
+            for d in data.payload.listResponse.doc: # categories
+                for c in d.child: # sub-category
                     for a in c.child: # app
                         apps.append(utils.parseProtobufObj(a))
             return apps
diff --git a/test/test.py b/test/test.py
index 21155cd..495b7ee 100644
--- a/test/test.py
+++ b/test/test.py
@@ -88,12 +88,14 @@ for doc in browseCat:
 
 # LIST
 cat = "MUSIC_AND_AUDIO"
-print("\nList %s subcategories\n" % cat)
+print("\nList {} subcategories\n".format(cat))
 catList = server.list(cat)
 for c in catList:
     print(c)
 
-print("\nList %s apps for %s category\n" % (catList[0], cat))
-appList = server.list(cat, catList[0])
+limit = 4
+print("\nList only {} apps from subcat {} for {} category\n".format(
+    limit, catList[0], cat))
+appList = server.list(cat, catList[0], 4, 1)
 for app in appList:
     print(app["docid"])