twitter/api.py

   1 import urllib2
   2
   3 from twitter.twitter_globals import POST_ACTIONS
   4 from twitter.auth import NoAuth
   5
   6 def _py26OrGreater():
   7     import sys
   8     return sys.hexversion > 0x20600f0
   9
  10 if _py26OrGreater():
  11     import json
  12 else:
  13     import simplejson as json
  14
  15 class TwitterError(Exception):
  16     """
  17     Base Exception thrown by the Twitter object when there is a
  18     general error interacting with the API.
  19     """
  20     pass
  21
  22 class TwitterHTTPError(TwitterError):
  23     """
  24     Exception thrown by the Twitter object when there is an
  25     HTTP error interacting with twitter.com.
  26     """
  27     def __init__(self, e, uri, format, uriparts):
  28       self.e = e
  29       self.uri = uri
  30       self.format = format
  31       self.uriparts = uriparts
  32
  33     def __str__(self):
  34         return (
  35             "Twitter sent status %i for URL: %s.%s using parameters: "
  36             "(%s)\ndetails: %s" %(
  37                 self.e.code, self.uri, self.format, self.uriparts,
  38                 self.e.fp.read()))
  39
  40 class TwitterResponse(object):
  41     """
  42     Response from a twitter request. Behaves like a list or a string
  43     (depending on requested format) but it has a few other interesting
  44     attributes.
  45
  46     `headers` gives you access to the response headers as an
  47     httplib.HTTPHeaders instance. You can do
  48     `response.headers.getheader('h')` to retrieve a header.
  49     """
  50     def __init__(self, headers):
  51         self.headers = headers
  52
  53     @property
  54     def rate_limit_remaining(self):
  55         """
  56         Remaining requests in the current rate-limit.
  57         """
  58         return int(self.headers.getheader('X-RateLimit-Remaining'))
  59
  60     @property
  61     def rate_limit_reset(self):
  62         """
  63         Time in UTC epoch seconds when the rate limit will reset.
  64         """
  65         return int(self.headers.getheader('X-RateLimit-Reset'))
  66
  67
  68 def wrap_response(response, headers):
  69     response_typ = type(response)
  70     if response_typ is bool:
  71         # HURF DURF MY NAME IS PYTHON AND I CAN'T SUBCLASS bool.
  72         response_typ = int
  73
  74     class WrappedTwitterResponse(response_typ, TwitterResponse):
  75         __doc__ = TwitterResponse.__doc__
  76
  77         def __init__(self, response):
  78             if response_typ is not int:
  79                 response_typ.__init__(self, response)
  80             TwitterResponse.__init__(self, headers)
  81
  82     return WrappedTwitterResponse(response)
  83
  84
  85
  86 class TwitterCall(object):
  87     def __init__(
  88         self, auth, format, domain, uri="", agent=None,
  89         uriparts=None, secure=True):
  90         self.auth = auth
  91         self.format = format
  92         self.domain = domain
  93         self.uri = uri
  94         self.agent = agent
  95         self.uriparts = uriparts
  96         self.secure = secure
  97
  98     def __getattr__(self, k):
  99         try:
 100             return object.__getattr__(self, k)
 101         except AttributeError:
 102             return TwitterCall(
 103                 auth=self.auth, format=self.format, domain=self.domain,
 104                 agent=self.agent, uriparts=self.uriparts + (k,),
 105                 secure=self.secure)
 106
 107     def __call__(self, **kwargs):
 108         # Build the uri.
 109         uriparts = []
 110         for uripart in self.uriparts:
 111             # If this part matches a keyword argument, use the
 112             # supplied value otherwise, just use the part.
 113             uriparts.append(unicode(kwargs.pop(uripart, uripart)))
 114         uri = u'/'.join(uriparts)
 115
 116         method = "GET"
 117         for action in POST_ACTIONS:
 118             if uri.endswith(action):
 119                 method = "POST"
 120                 break
 121
 122         # If an id kwarg is present and there is no id to fill in in
 123         # the list of uriparts, assume the id goes at the end.
 124         id = kwargs.pop('id', None)
 125         if id:
 126             uri += "/%s" %(id)
 127
 128         secure_str = ''
 129         if self.secure:
 130             secure_str = 's'
 131         dot = ""
 132         if self.format:
 133             dot = "."
 134         uriBase = "http%s://%s/%s%s%s" %(
 135                     secure_str, self.domain, uri, dot, self.format)
 136
 137         headers = {}
 138         if self.auth:
 139             headers.update(self.auth.generate_headers())
 140             arg_data = self.auth.encode_params(uriBase, method, kwargs)
 141             if method == 'GET':
 142                 uriBase += '?' + arg_data
 143                 body = None
 144             else:
 145                 body = arg_data
 146
 147         req = urllib2.Request(uriBase, body, headers)
 148
 149         try:
 150             handle = urllib2.urlopen(req)
 151             if "json" == self.format:
 152                 res = json.loads(handle.read().decode('utf8'))
 153                 return wrap_response(res, handle.headers)
 154             else:
 155                 return wrap_response(
 156                     handle.read().decode('utf8'), handle.headers)
 157         except urllib2.HTTPError as e:
 158             if (e.code == 304):
 159                 return []
 160             else:
 161                 raise TwitterHTTPError(e, uri, self.format, arg_data)
 162
 163 class Twitter(TwitterCall):
 164     """
 165     The minimalist yet fully featured Twitter API class.
 166
 167     Get RESTful data by accessing members of this class. The result
 168     is decoded python objects (lists and dicts).
 169
 170     The Twitter API is documented here:
 171
 172       http://dev.twitter.com/doc
 173
 174
 175     Examples::
 176
 177       twitter = Twitter(
 178           auth=OAuth(token, token_key, con_secret, con_secret_key)))
 179
 180       # Get the public timeline
 181       twitter.statuses.public_timeline()
 182
 183       # Get a particular friend's timeline
 184       twitter.statuses.friends_timeline(id="billybob")
 185
 186       # Also supported (but totally weird)
 187       twitter.statuses.friends_timeline.billybob()
 188
 189       # Send a direct message
 190       twitter.direct_messages.new(
 191           user="billybob",
 192           text="I think yer swell!")
 193
 194       # Get the members of a particular list of a particular friend
 195       twitter.user.listname.members(user="billybob", listname="billysbuds")
 196
 197
 198     Searching Twitter::
 199
 200       twitter_search = Twitter(domain="search.twitter.com")
 201
 202       # Find the latest search trends
 203       twitter_search.trends()
 204
 205       # Search for the latest News on #gaza
 206       twitter_search.search(q="#gaza")
 207
 208
 209     Using the data returned
 210     -----------------------
 211
 212     Twitter API calls return decoded JSON. This is converted into
 213     a bunch of Python lists, dicts, ints, and strings. For example::
 214
 215       x = twitter.statuses.public_timeline()
 216
 217       # The first 'tweet' in the timeline
 218       x[0]
 219
 220       # The screen name of the user who wrote the first 'tweet'
 221       x[0]['user']['screen_name']
 222
 223
 224     Getting raw XML data
 225     --------------------
 226
 227     If you prefer to get your Twitter data in XML format, pass
 228     format="xml" to the Twitter object when you instantiate it::
 229
 230       twitter = Twitter(format="xml")
 231
 232       The output will not be parsed in any way. It will be a raw string
 233       of XML.
 234
 235     """
 236     def __init__(
 237         self, format="json",
 238         domain="twitter.com", secure=True, auth=None,
 239         api_version=''):
 240         """
 241         Create a new twitter API connector.
 242
 243         Pass an `auth` parameter to use the credentials of a specific
 244         user. Generally you'll want to pass an `OAuth`
 245         instance::
 246
 247             twitter = Twitter(auth=OAuth(
 248                     token, token_secret, consumer_key, consumer_secret))
 249
 250
 251         `domain` lets you change the domain you are connecting. By
 252         default it's twitter.com but `search.twitter.com` may be
 253         useful too.
 254
 255         If `secure` is False you will connect with HTTP instead of
 256         HTTPS.
 257
 258         The value of `agent` is sent in the `X-Twitter-Client`
 259         header. This is deprecated. Instead Twitter determines the
 260         application using the OAuth Client Key and Client Key Secret
 261         parameters.
 262
 263         `api_version` is used to set the base uri. By default it's
 264         nothing, but if you set it to '1' your URI will start with
 265         '1/'.
 266         """
 267         if not auth:
 268             auth = NoAuth()
 269
 270         if (format not in ("json", "xml", "")):
 271             raise ValueError("Unknown data format '%s'" %(format))
 272
 273         uriparts = ()
 274         if api_version:
 275             uriparts += (str(api_version),)
 276
 277         TwitterCall.__init__(
 278             self, auth=auth, format=format, domain=domain,
 279             secure=secure, uriparts=uriparts)
 280
 281
 282 __all__ = ["Twitter", "TwitterError", "TwitterHTTPError", "TwitterResponse"]