working implementation, better docs

Author: Jack Diederich

README.md

@@ -3,15 +3,10 @@
 This is a fork of a fork of a fork. See (http://github.com/OfflineLabs/python-oauth2) for that history. A number of notable differences exist between this code and its forefathers:
 
 * 0% unit test coverage.
-
 * Lightweight at less than 200 lines, including blanks and docstrings.
-
 * Completely removed all the OAuth 1.0 code.
-
 * Completely removed all non-stdlib dependencies (goodbye httplib2, you won't be missed!).
-
 * Implements a later version of the spec than it's parent.
-
 * I'm not sure which version but google's auth2 API accepts this implementation.
 
 # goo.gl URL shortener example
@@ -25,15 +20,50 @@ This is a fork of a fork of a fork. See (http://github.com/OfflineLabs/python-oa
 
     import urlprase
     import foauth2
-    client = foauth2.Client(client_id, client_secret)
+    client = foauth2.GooglAPI(client_id, client_secret)
     print "cut-n-paste the following URL to start the auth dance",
-    print client.authorization_url(auth_url, redirect_url=redirect_url, scope=scope)
+    print client.authorization_url()
     print "and copy the resulting link below"
     answer = raw_input()
 
     query_str = urlparse.urlparse(url_str).query
     params = urlparse.parse_qs(query_str, keep_blank_values=True)
     code = params['code'][0]
-    access_token, refresh_token = client.access_token(access_url, code=code, scope=scope)
+    access_token, refresh_token = client.redeem_token(code=code)
+
+    # make a short url
+    short_url = client.shorten('http://example.com')
+    print short_url
+    # get stats
+    print client.stats(short_url)
+
+GooglAPI inherits from the Client class.  You can use the client by itself but
+then you have to pass in the URI and scope for the end points as arguments to
+the authorize_url and redeem_code functions.  GooglAPI sets up the defaults:
+
+    class GooglAPI(Client):
+        user_agent = 'python-foauth2'
+        # OAuth API
+        auth_uri = 'https://accounts.google.com/o/oauth2/auth'
+        refresh_uri = 'https://accounts.google.com/o/oauth2/token'
+        scope = 'https://www.googleapis.com/auth/urlshortener'
+        # Shortener API
+ 	api_uri = 'https://www.googleapis.com/urlshortener/v1/url'
+
+You are responsible for storing the access and refresh key for later use.
+Here is the full (and not very exciting) version of foauth.GooglAPI that
+we use.  It has a custom redirect URI, includes our goo.gl api key,
+and saves the access & refresh tokens to a django model names AuthKey.
+Define your own refresh_token() replacement to store stuff where you like.
+
+class GooglAPI(foauth2.GooglAPI):
+    redirect_uri = 'http://hivefire.com/oauth'
+    api_uri = 'https://www.googleapis.com/urlshortener/v1/url?key=%s' % GOOGL_KEY
 
-    print "now you can use %r to GET short urls from goo.gl" % access_token
+    def refresh_token(self, *args, **kwargs):
+        access, refresh = super(GooglAPI, self).refresh_token(*args, **kwargs)
+        # save the updated access/refresh tokens
+        AuthKey.objects.filter(service='goo.gl').update(access_token=access,
+                                                        access_secret=refresh,
+                                                        acquired_date=datetime.datetime.now())
+        return access, refresh

foauth2.py

@@ -36,11 +36,6 @@
 import urllib2
 import urlparse
 
-try:
-    from urlparse import parse_qs, parse_qsl
-except ImportError:
-    from cgi import parse_qs, parse_qsl
-
 try:
     import simplejson
 except ImportError:
@@ -65,29 +60,32 @@ def __str__(self):
 
 class Client(object):
     """ Client for OAuth 2.0 'Bearer Token' """
+    redirect_uri = None
+    auth_uri = None
+    refresh_uri = None
+    user_agent = None
+    scope = None
 
-    def __init__(self, client_id, client_secret, redirect_uri=None,
-                 timeout=None):
-        self.client_id = client_id
-        self.client_secret = client_secret
-        self.redirect_uri = redirect_uri
-        self.timeout = timeout
+    def __init__(self, client_id, client_secret, access_token=None,
+                 refresh_token=None, timeout=None):
 
-        if self.client_id is None or self.client_secret is None:
+        if not client_id or not client_secret:
             raise ValueError("Client_id and client_secret must be set.")
 
-    @staticmethod
-    def _split_url_string(param_str):
-        """Turn URL string into parameters."""
-        parameters = parse_qs(param_str, keep_blank_values=False)
-        for key, val in parameters.iteritems():
-            parameters[key] = urllib.unquote(val[0])
-        return parameters
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.timeout = timeout
+        self.access_token = access_token
+        self.refresh_token = refresh_token
 
-    def authorization_url(self, uri, redirect_uri=None, scope=None):
+    def authorization_url(self, auth_uri=None, redirect_uri=None, scope=None):
         """ Get the URL to redirect the user for client authorization """
         if redirect_uri is None:
             redirect_uri = self.redirect_uri
+        if auth_uri is None:
+            auth_uri = self.auth_uri
+        if scope is None:
+            scope = self.scope
 
         params = {'client_id' : self.client_id,
                   'redirect_uri' : redirect_uri,
@@ -96,74 +94,127 @@ def authorization_url(self, uri, redirect_uri=None, scope=None):
         if scope:
             params['scope'] = scope
 
-        return '%s?%s' % (uri, urllib.urlencode(params))
+        return '%s?%s' % (auth_uri, urllib.urlencode(params))
 
-    def access_token(self, uri, redirect_uri=None, code=None, scope=None):
+    def redeem_code(self, refresh_uri=None, redirect_uri=None, code=None, scope=None):
         """Get an access token from the supplied code """
 
         # prepare required args
         if code is None:
             raise ValueError("Code must be set.")
         if redirect_uri is None:
             redirect_uri = self.redirect_uri
+        if refresh_uri is None:
+            refresh_uri = self.refresh_uri
+        if scope is None:
+            scope = self.scope
+
         data = {
             'client_id': self.client_id,
             'client_secret': self.client_secret,
             'code': code,
             'redirect_uri': redirect_uri,
             'grant_type' : 'authorization_code',
         }
+
         if scope is not None:
             data['scope'] = scope
         body = urllib.urlencode(data)
 
-        headers = {'content-type' : 'application/x-www-form-urlencoded',
-                   'user_agent' : 'HiveFire-OAuth2a',
-                  }
+        headers = {'Content-type' : 'application/x-www-form-urlencoded'}
+        if self.user_agent:
+            headers['user-agent'] = self.user_agent
 
-        response = self.request(uri, body=body, method='POST', headers=headers)
-        if not response.code == 200:
+        response = self._request(refresh_uri, body=body, method='POST', headers=headers)
+        if response.code != 200:
             raise Error(response.read())
         response_args = simplejson.loads(response.read())
 
         error = response_args.pop('error', None)
         if error is not None:
             raise Error(error)
 
-        return response_args['access_token'], response_args['refresh_token']
+        self.access_token = response_args['access_token']
+        self.refresh_token = response_args['refresh_token']
+        return self.access_token, self.refresh_token
 
-    def refresh(self, uri, refresh_token, secret_type=None):
+    def refresh_access_token(self, refresh_uri=None, refresh_token=None):
         """  Get a new access token from the supplied refresh token """
 
+        if refresh_uri is None:
+            refresh_uri = self.refresh_uri
         if refresh_token is None:
-            raise ValueError("Refresh_token must be set.")
+            refresh_token = self.refresh_token
 
         # prepare required args
         args = {
-            'type': 'refresh',
             'client_id': self.client_id,
             'client_secret': self.client_secret,
             'refresh_token': refresh_token,
+            'grant_type' : 'refresh_token',
         }
-
-        # prepare optional args
-        if secret_type is not None:
-            args['secret_type'] = secret_type
-
         body = urllib.urlencode(args)
-        headers = {
-            'Content-Type': 'application/x-www-form-urlencoded',
-        }
 
-        response = self.request(uri, method='POST', body=body, headers=headers)
-        if not response.code == 200:
+        headers = {'Content-type' : 'application/x-www-form-urlencoded'}
+        if self.user_agent:
+            headers['user-agent'] = self.user_agent
+
+        response = self._request(refresh_uri, method='POST', body=body, headers=headers)
+        if response.code != 200:
             raise Error(response.read())
+        response_args = simplejson.loads(response.read())
 
-        response_args = Client._split_url_string(content)
-        return response_args
+        self.access_token = response_args['access_token']
+        # server may or may not supply a new refresh token
+        self.refresh_token = response_args.get('refresh_token', self.refresh_token)
+        return self.access_token, self.refresh_token
 
-    def request(self, uri, body=None, headers=None, method='GET'):
-        if method == 'POST' and body is None:
+    def _request(self, uri, body=None, headers=None, method='GET'):
+        if method == 'POST' and not body:
             raise ValueError('POST requests must have a body')
+
         request = urllib2.Request(uri, body, headers)
         return urllib2.urlopen(request, timeout=self.timeout)
+
+    def request(self, uri, body, headers, method='GET'):
+        """ perform a HTTP request using OAuth authentication.
+            If the request fails because the access token is expired it will
+            try to refresh the token and try the request again.
+        """
+        headers['Authorization'] = 'Bearer %s' % self.access_token
+
+        try:
+            response = self._request(uri, body=body, headers=headers, method=method)
+        except urllib2.HTTPError as e:
+            if 400 <= e.code < 500:
+                # any 400 code is acceptable to signal that the access token is expired.
+                self.refresh_access_token()
+                headers['Authorization'] = 'Bearer %s' % self.access_token
+                response = self._request(uri, body=body, headers=headers, method=method)
+
+        if response.code == 200:
+            return simplejson.loads(response.read())
+        raise ValueError(response.read())
+
+class GooglAPI(Client):
+    user_agent = 'python-foauth2'
+    # OAuth API
+    auth_uri = 'https://accounts.google.com/o/oauth2/auth'
+    refresh_uri = 'https://accounts.google.com/o/oauth2/token'
+    scope = 'https://www.googleapis.com/auth/urlshortener'
+    # data API
+    api_uri = 'https://www.googleapis.com/urlshortener/v1/url'
+
+    def shorten(self, long_url):
+        data = simplejson.dumps({'longUrl' : long_url})
+        headers = {'Content-Type': 'application/json'}
+        json_d = self.request(self.api_uri, data, headers, 'POST')
+        return json_d['id']
+
+    def stats(self, short_url):
+        params = {'shortUrl': short_url,
+                  'projection' : 'ANALYTICS_CLICKS',
+                 }
+        stat_url = self.api_uri + '&' + urllib.urlencode(params)
+        headers = {'Content-Type': 'application/json'}
+        return self.request(stat_url, None, headers)