X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/9b0c5df39edd3adfa7f38885b4fa3f4b0ccbef53..7f22c0211d8f3cc0efc56533b98354cc8f3aecac:/twitter/api.py

diff --git a/twitter/api.py b/twitter/api.py
index 42d9e53..608b08f 100644
--- a/twitter/api.py
+++ b/twitter/api.py
@@ -34,8 +34,11 @@ class TwitterHTTPError(TwitterError):
       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())
+        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__(
@@ -124,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()
@@ -140,6 +144,7 @@ class Twitter(TwitterCall):
           user="billybob",
           text="I think yer swell!")
 
+
     Searching Twitter::
 
       twitter_search = Twitter(domain="search.twitter.com")
@@ -150,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()
 
@@ -163,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))
+            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", "TwitterHTTPError"]