X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/aec689591a6382c274aeedcd4f4a89762f2f1f17..8031bb025fc77ffd0ebb7fa69fe2cf24ffe58844:/twitter/api.py

diff --git a/twitter/api.py b/twitter/api.py
index 5d75f87..6abdd97 100644
--- a/twitter/api.py
+++ b/twitter/api.py
@@ -1,7 +1,5 @@
 import urllib2
 
-from exceptions import Exception
-
 from twitter.twitter_globals import POST_ACTIONS
 from twitter.auth import NoAuth
 
@@ -39,6 +37,52 @@ class TwitterHTTPError(TwitterError):
                 self.e.code, self.uri, self.format, self.uriparts,
                 self.e.fp.read()))
 
+class TwitterResponse(object):
+    """
+    Response from a twitter request. Behaves like a list or a string
+    (depending on requested format) but it has a few other interesting
+    attributes.
+
+    `headers` gives you access to the response headers as an
+    httplib.HTTPHeaders instance. You can do
+    `response.headers.getheader('h')` to retrieve a header.
+    """
+    def __init__(self, headers):
+        self.headers = headers
+
+    @property
+    def rate_limit_remaining(self):
+        """
+        Remaining requests in the current rate-limit.
+        """
+        return int(self.headers.getheader('X-RateLimit-Remaining'))
+
+    @property
+    def rate_limit_reset(self):
+        """
+        Time in UTC epoch seconds when the rate limit will reset.
+        """
+        return int(self.headers.getheader('X-RateLimit-Reset'))
+
+
+def wrap_response(response, headers):
+    response_typ = type(response)
+    if response_typ is bool:
+        # HURF DURF MY NAME IS PYTHON AND I CAN'T SUBCLASS bool.
+        response_typ = int
+
+    class WrappedTwitterResponse(response_typ, TwitterResponse):
+        __doc__ = TwitterResponse.__doc__
+
+        def __init__(self, response):
+            if response_typ is not int:
+                response_typ.__init__(self, response)
+            TwitterResponse.__init__(self, headers)
+
+    return WrappedTwitterResponse(response)
+
+
+
 class TwitterCall(object):
     def __init__(
         self, auth, format, domain, uri="", agent=None,
@@ -66,8 +110,8 @@ class TwitterCall(object):
         for uripart in self.uriparts:
             # If this part matches a keyword argument, use the
             # supplied value otherwise, just use the part.
-            uriparts.append(kwargs.pop(uripart, uripart))
-        uri = '/'.join(uriparts)
+            uriparts.append(unicode(kwargs.pop(uripart, uripart)))
+        uri = u'/'.join(uriparts)
 
         method = "GET"
         for action in POST_ACTIONS:
@@ -105,10 +149,12 @@ class TwitterCall(object):
         try:
             handle = urllib2.urlopen(req)
             if "json" == self.format:
-                return json.loads(handle.read())
+                res = json.loads(handle.read().decode('utf8'))
+                return wrap_response(res, handle.headers)
             else:
-                return handle.read()
-        except urllib2.HTTPError, e:
+                return wrap_response(
+                    handle.read().decode('utf8'), handle.headers)
+        except urllib2.HTTPError as e:
             if (e.code == 304):
                 return []
             else:
@@ -233,4 +279,4 @@ class Twitter(TwitterCall):
             secure=secure, uriparts=uriparts)
 
 
-__all__ = ["Twitter", "TwitterError", "TwitterHTTPError"]
+__all__ = ["Twitter", "TwitterError", "TwitterHTTPError", "TwitterResponse"]