Initial implementation of including metadata in API results via custom classes in service.py. See congress.py for example implementation. This is a possible solution to the problem described in issue #6.

Author: dcloud

sunlight/service.py

@@ -18,11 +18,15 @@
     from urllib.request import urlopen
     from urllib.error import HTTPError
     _str_type = str
+    from collections import UserDict
+    from collections import UserList
 else:
     from urllib import urlencode
     from urllib2 import urlopen
     from urllib2 import HTTPError
     _str_type = basestring
+    from UserList import UserList
+    from UserDict import IterableUserDict as UserDict
 
 
 def safe_encode(kwargs):
@@ -83,3 +87,25 @@ def get(self, top_level_object, **kwargs):
             ex.code = code
 
             raise ex
+
+
+class EntityList(UserList):
+    """
+    EntityList provides an iterable of API entities along with a _meta
+    dictionary that contains information about the query results. This could
+    include result count and pagination details.
+    """
+    def __init__(self, data=[], meta=None):
+        UserList.__init__(self, data)
+        self._meta = meta
+
+
+class EntityDict(UserDict):
+    """
+    EntityDict provides a dictionary representation of an API entity along
+    with a _meta dictionary that contains information about the query results.
+    This could include result count and pagination details.
+    """
+    def __init__(self, data={}, meta=None):
+        UserDict.__init__(self, data)
+        self._meta = meta

sunlight/services/congress.py

@@ -9,6 +9,8 @@
 """
 
 import sunlight.service
+from sunlight.service import EntityList
+from sunlight.service import EntityDict
 import json
 
 
@@ -86,7 +88,7 @@ def legislator(self, identifier, id_type=LEGISLATOR_ID_TYPES[0], **kwargs):
         kwargs.update(id_arg)
         results = self.get('legislators', **kwargs)
         if len(results):
-            return results[0]
+            return EntityDict(results[0], results._meta)
         return None
 
 
@@ -148,7 +150,7 @@ def bill(self, bill_id, **kwargs):
         })
         results = self.get('bills', **kwargs)
         if len(results):
-            return results[0]
+            return EntityDict(results[0], results._meta)
         return None
 
     def search_bills(self, query, **kwargs):
@@ -264,4 +266,6 @@ def _get_url(self, endpoint, apikey, **kwargs):
         return url
 
     def _decode_response(self, response):
-        return json.loads(response)['results']
+        data = json.loads(response)
+        results = data.pop('results')
+        return EntityList(results, data)