use Tasklist instead of just a list

Author: clhuang

README.rst

@@ -170,6 +170,8 @@ Check `this`__ for further information.
 __ https://docs.scaleapi.com/#list-all-tasks
 
 Retrieve a list of tasks, with optional filter by date/type. Paginated with limit/offset.
+The return value is a ``scaleapi.Tasklist``, which acts as a list, but also has fields
+for the total number of tasks, the limit and offset, and whether or not there's more.
 
 .. code-block :: python
 
@@ -180,6 +182,11 @@ Retrieve a list of tasks, with optional filter by date/type. Paginated with limi
         limit=100,
         offset=200)
 
+    print(tasks.total)    # 1000
+    print(tasks.limit)    # 100
+    print(tasks.offset)   # 200
+    print(tasks.has_more) # True
+
 Error handling
 ==============
 

scaleapi/__init__.py

@@ -1,3 +1,4 @@
+from collections import namedtuple
 import requests
 
 from .tasks import Task
@@ -15,6 +16,8 @@
                                  'objects_to_annotate', 'with_labels'},
                   'datacollection': {'attachment', 'attachment_type', 'fields'}}
 SCALE_ENDPOINT = 'https://api.scaleapi.com/v1/'
+DEFAULT_LIMIT = 100
+DEFAULT_OFFSET = 0
 
 
 def validate_payload(task_type, kwargs):
@@ -35,6 +38,16 @@ class ScaleInvalidRequest(ScaleException, ValueError):
     pass
 
 
+class Tasklist(list):
+    def __init__(self, docs, total, limit, offset, has_more):
+        super(Tasklist, self).__init__(docs)
+        self.docs = docs
+        self.total = total
+        self.limit = limit
+        self.offset = offset
+        self.has_more = has_more
+
+
 class ScaleClient(object):
     def __init__(self, api_key):
         self.api_key = api_key
@@ -102,8 +115,10 @@ def tasks(self, **kwargs):
             if key not in allowed_kwargs:
                 raise ScaleInvalidRequest('Illegal parameter %s for ScaleClient.tasks()'
                                           % key, None)
-        return [Task(json, self) for json in
-                self._getrequest('tasks', params=kwargs)['docs']]
+        response = self._getrequest('tasks', params=kwargs)
+        docs = [Task(json, self) for json in response['docs']]
+        return Tasklist(docs, response['total'], response['limit'],
+                        response['offset'], response['has_more'])
 
     def create_categorization_task(self, **kwargs):
         validate_payload('categorization', kwargs)

setup.py

@@ -2,7 +2,7 @@
 setup(
     name = 'scaleapi',
     packages = ['scaleapi'],
-    version = '0.1.3',
+    version = '0.1.4',
     description = 'The official Python client library for the Scale API, the API for human labor.',
     author = 'Calvin Huang',
     author_email = 'c@lvin.me',

tests/test_client.py

@@ -159,11 +159,12 @@ def test_task_retrieval():
 
 def test_task_retrieval_time():
     task = make_a_task()
+    time.sleep(0.5)
     start_time = datetime.utcnow().isoformat()
-    time.sleep(1)
+    time.sleep(0.5)
     end_time = datetime.utcnow().isoformat()
     tasks = client.tasks(start_time=start_time, end_time=end_time)
-    assert tasks == []
+    assert tasks.docs == []
 
 
 def test_task_retrieval_fail():