X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/d20da7f3e83b0c68402d46ef96c463c307cd9e2f..7f22c0211d8f3cc0efc56533b98354cc8f3aecac:/twitter/api.py diff --git a/twitter/api.py b/twitter/api.py index 337369b..608b08f 100644 --- a/twitter/api.py +++ b/twitter/api.py @@ -17,11 +17,29 @@ 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 +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, auth, format, domain, uri="", agent=None, @@ -55,8 +73,11 @@ class TwitterCall(object): secure_str = '' if self.secure: secure_str = 's' - uriBase = "http%s://%s/%s.%s" %( - secure_str, self.domain, uri, self.format) + 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'): @@ -90,9 +111,7 @@ class TwitterCall(object): if (e.code == 304): return [] else: - raise TwitterError( - "Twitter sent status %i for URL: %s.%s using parameters: (%s)\ndetails: %s" %( - e.code, uri, self.format, self.encoded_args, e.fp.read())) + raise TwitterHTTPError(e, uri, self.format, self.encoded_args) class Twitter(TwitterCall): """ @@ -108,7 +127,8 @@ class Twitter(TwitterCall): Examples:: - twitter = Twitter("hello@foo.com", "password123") + twitter = Twitter( + auth=OAuth(token, token_key, con_secret, con_secret_key))) # Get the public timeline twitter.statuses.public_timeline() @@ -124,6 +144,7 @@ class Twitter(TwitterCall): user="billybob", text="I think yer swell!") + Searching Twitter:: twitter_search = Twitter(domain="search.twitter.com") @@ -134,10 +155,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() @@ -147,37 +170,77 @@ 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, secure=True, auth=None): + self, email=None, password=None, format="json", + domain="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:: + + twitter = Twitter(auth=OAuth( + token, token_secret, consumer_key, consumer_secret)) + + + Alternately you can pass `email` and `password` parameters but + this authentication mode will be deactive by Twitter very soon + and is not recommended:: + + twitter = Twitter(email="blah@blah.com", password="foobar") + + + `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 email is not None or password is not None: - if auth is not None: - raise ValueError, "can't specify 'email' or 'password' and 'auth' params" + 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 TwitterError("Unknown data format '%s'" %(format)) + 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, "", agent, + self, auth, format, domain, uri, agent, secure=secure) -__all__ = ["Twitter", "TwitterError"] +__all__ = ["Twitter", "TwitterError", "TwitterHTTPError"]