X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/45688301124a0a22f04d9ec032fc0423718743fc..1cc9ab0b8a70466bf8cf684fdab28aad342696c8:/twitter/api.py?ds=sidebyside diff --git a/twitter/api.py b/twitter/api.py index 52db973..1e249d5 100644 --- a/twitter/api.py +++ b/twitter/api.py @@ -1,11 +1,11 @@ -from base64 import b64encode -from urllib import urlencode - -import httplib +import urllib2 from exceptions import Exception +from twitter.twitter_globals import POST_ACTIONS +from twitter.auth import UserPassAuth, NoAuth + def _py26OrGreater(): import sys return sys.hexversion > 0x20600f0 @@ -17,89 +17,106 @@ else: class TwitterError(Exception): """ - Exception thrown by the Twitter object when there is an - error interacting with twitter.com. + Base Exception thrown by the Twitter object when there is a + general error interacting with the API. """ pass -# These actions require POST http requests instead of GET -_POST_ACTIONS = [ - "create", "update", "destroy", "new", "follow", "leave", - ] +class TwitterHTTPError(TwitterError): + """ + Exception thrown by the Twitter object when there is an + HTTP error interacting with twitter.com. + """ + def __init__(self, e, uri, format, encoded_args): + self.e = e + self.uri = uri + self.format = format + self.encoded_args = encoded_args + + def __str__(self): + return ( + "Twitter sent status %i for URL: %s.%s using parameters: " + "(%s)\ndetails: %s" %( + self.e.code, self.uri, self.format, self.encoded_args, + self.e.fp.read())) class TwitterCall(object): def __init__( - self, username, password, format, domain, uri="", agent=None): - self.username = username - self.password = password + self, auth, format, domain, uri="", agent=None, + encoded_args=None, secure=True): + self.auth = auth self.format = format self.domain = domain self.uri = uri self.agent = agent + self.encoded_args = encoded_args + self.secure = secure + def __getattr__(self, k): try: return object.__getattr__(self, k) except AttributeError: return TwitterCall( - self.username, self.password, self.format, self.domain, - self.uri + "/" + k, self.agent) + self.auth, self.format, self.domain, + self.uri + "/" + k, self.agent, self.encoded_args, self.secure) + def __call__(self, **kwargs): - uri = self.uri + uri = self.uri.strip("/") method = "GET" - for action in _POST_ACTIONS: + for action in POST_ACTIONS: if self.uri.endswith(action): method = "POST" + if (self.agent): + kwargs["source"] = self.agent break - if (self.agent): - kwargs["source"] = self.agent - - id = kwargs.pop('id', None) - if id: - uri += "/%s" %(id) - - encoded_kwargs = urlencode(kwargs.items()) + + secure_str = '' + if self.secure: + secure_str = 's' + dot = "" + if self.format != '': + dot = "." + uriBase = "http%s://%s/%s%s%s" %( + secure_str, self.domain, uri, dot, self.format) + + if (not self.encoded_args): + if kwargs.has_key('id'): + uri += "/%s" %(kwargs['id']) + + self.encoded_args = self.auth.encode_params(uriBase, method, kwargs) + argStr = "" - if kwargs and (method == "GET"): - argStr = "?" + encoded_kwargs + argData = None + if (method == "GET"): + if self.encoded_args: + argStr = "?%s" %(self.encoded_args) + else: + argData = self.encoded_args headers = {} if (self.agent): headers["X-Twitter-Client"] = self.agent - if (self.username): - headers["Authorization"] = "Basic " + b64encode("%s:%s" %( - self.username, self.password)) - if method == "POST": - headers["Content-type"] = "application/x-www-form-urlencoded" - headers["Content-length"] = len(encoded_kwargs) + if self.auth is not None: + headers.update(self.auth.generate_headers()) + + req = urllib2.Request(uriBase+argStr, argData, headers) - c = httplib.HTTPConnection(self.domain) try: - c.putrequest(method, "%s.%s%s" %( - uri, self.format, argStr)) - for item in headers.iteritems(): - c.putheader(*item) - c.endheaders() - if method == "POST": - c.send(encoded_kwargs) - r = c.getresponse() - - if (r.status == 304): - return [] - elif (r.status != 200): - raise TwitterError( - "Twitter sent status %i for URL: %s.%s using parameters: (%s)\ndetails: %s" %( - r.status, uri, self.format, encoded_kwargs, r.read())) + handle = urllib2.urlopen(req) if "json" == self.format: - return json.loads(r.read()) + return json.loads(handle.read()) + else: + return handle.read() + except urllib2.HTTPError, e: + if (e.code == 304): + return [] else: - return r.read() - finally: - c.close() + raise TwitterHTTPError(e, uri, self.format, self.encoded_args) class Twitter(TwitterCall): """ The minimalist yet fully featured Twitter API class. - + Get RESTful data by accessing members of this class. The result is decoded python objects (lists and dicts). @@ -107,27 +124,27 @@ class Twitter(TwitterCall): http://apiwiki.twitter.com/ http://groups.google.com/group/twitter-development-talk/web/api-documentation - + Examples:: - + twitter = Twitter("hello@foo.com", "password123") - + # Get the public timeline twitter.statuses.public_timeline() - + # Get a particular friend's timeline twitter.statuses.friends_timeline(id="billybob") - + # Also supported (but totally weird) twitter.statuses.friends_timeline.billybob() - + # Send a direct message twitter.direct_messages.new( user="billybob", text="I think yer swell!") Searching Twitter:: - + twitter_search = Twitter(domain="search.twitter.com") # Find the latest search trends @@ -136,10 +153,12 @@ class Twitter(TwitterCall): # Search for the latest News on #gaza twitter_search.search(q="#gaza") - Using the data returned:: - Twitter API calls return decoded JSON. This is converted into - a bunch of Python lists, dicts, ints, and strings. For example, + Using the data returned + ----------------------- + + Twitter API calls return decoded JSON. This is converted into + a bunch of Python lists, dicts, ints, and strings. For example:: x = twitter.statuses.public_timeline() @@ -148,27 +167,69 @@ class Twitter(TwitterCall): # The screen name of the user who wrote the first 'tweet' x[0]['user']['screen_name'] - - Getting raw XML data:: - - If you prefer to get your Twitter data in XML format, pass - format="xml" to the Twitter object when you instantiate it: - + + + Getting raw XML data + -------------------- + + If you prefer to get your Twitter data in XML format, pass + format="xml" to the Twitter object when you instantiate it:: + twitter = Twitter(format="xml") - + The output will not be parsed in any way. It will be a raw string of XML. + """ def __init__( - self, email=None, password=None, format="json", domain="twitter.com", - agent=None): + self, email=None, password=None, format="json", + domain="api.twitter.com", agent=None, secure=True, auth=None, + api_version=''): """ - Create a new twitter API connector using the specified - credentials (email and password). Format specifies the output - format ("json" (default) or "xml"). + Create a new twitter API connector. + + Pass an `auth` parameter to use the credentials of a specific + user. Generally you'll want to pass an `OAuth` + instance. Alternately you can pass `email` and `password` + parameters but this authentication mode will be deactive by + Twitter in the future and is not recommended. + + `domain` lets you change the domain you are connecting. By + default it's twitter.com but `search.twitter.com` may be + useful too. + + If `secure` is False you will connect with HTTP instead of + HTTPS. + + The value of `agent` is sent in the `X-Twitter-Client` + header. This is deprecated. Instead Twitter determines the + application using the OAuth Client Key and Client Key Secret + parameters. + + `api_version` is used to set the base uri. By default it's + nothing, but if you set it to '1' your URI will start with + '1/'. """ - if (format not in ("json", "xml")): - raise TwitterError("Unknown data format '%s'" %(format)) - TwitterCall.__init__(self, email, password, format, domain) + + if email is not None or password is not None: + if auth: + raise ValueError( + "Can't specify 'email'/'password' and 'auth' params" + " simultaneously.") + auth = UserPassAuth(email, password) + + if not auth: + auth = NoAuth() + + if (format not in ("json", "xml", "")): + raise ValueError("Unknown data format '%s'" %(format)) + + uri = "" + if api_version: + uri = str(api_version) + + TwitterCall.__init__( + self, auth, format, domain, uri, agent, + secure=secure) -__all__ = ["Twitter", "TwitterError"] +__all__ = ["Twitter", "TwitterError", "TwitterHTTPError"]