Merge branch 'master' into dev-method

Conflicts:
	imgur-python/imgur/factory.py
	imgur-python/main.py

Author: jacob-pascual

README.md

@@ -1,20 +1,63 @@
-Imgur API Example Usage
-=======================
+imgurpython
+===========
 
-This is a demo application of the [Imgur API](http://api.imgur.com/). It can be used to interrogate the Imgur API and
-examine its responses, as a simple command line utility, and it can be used as a library for working with the Imgur API.
+A Python client for the [Imgur API](http://api.imgur.com/). Also includes a friendly demo application. It can be used to
+interact with the Imgur API and examine its responses, as a command line utility, and it can be used as a library
+within your projects.
 
-You must [register](http://api.imgur.com/oauth2/addclient) your client with the Imgur API, and provide the client ID to
-do *any* request to the API. If you want to perform actions on accounts, the user will have to authorize it through OAuth.
-The **secret** field is required for OAuth.
+You must [register](http://api.imgur.com/oauth2/addclient) your client with the Imgur API, and provide the Client-ID to
+make *any* request to the API (see the [Authentication](https://api.imgur.com/#authentication) note). If you want to
+perform actions on accounts, the user will have to authorize your application through OAuth2.
+
+Imgur API Documentation
+-----------------------
+
+Our developer documentation can be found [here](https://api.imgur.com/).
+
+Community
+---------
+
+The best way to reach out to Imgur for API support would be our
+[Google Group](https://groups.google.com/forum/#!forum/imgur), [Twitter](https://twitter.com/imgurapi), or via
+ api@imgur.com.
 
 Installation
 ------------
 
     pip install imgurpython
 
-Usage
------
+Configuration
+-------------
+
+Configuration is done through the **config.json** (placed in `imgur-python/data`) file in JSON format. The contents of the file should be a JSON
+object with the following properties:
+
+### client_id
+
+**Key**: 'client_id'
+
+**Type**: string [16 characters]
+
+**Description**: The Client-ID you got when you registered. Required for any API call.
+
+### secret
+
+**Key**: 'secret'
+
+**Type**: string [40 characters]
+
+**Description**: The client secret you got when you registered, needed fo OAuth2 authentication.
+
+### token_store
+
+**Key**: 'token_store'
+
+**Type**: object
+
+**Description**: Future configuration to control where the tokens are stored for persistent **insecure** storage of refresh tokens.
+
+Command Line Usage
+------------------
 
 > Usage:  python main.py (action) [options...]
 >
@@ -51,44 +94,14 @@ Usage
 > 
 > ### Authorized Actions
 > 
-> **upload-auth [access-token]**                
+> **upload-auth [access-token] [file]**
 > Upload a file to your account
 >
-> **comment [access-token] [hash] [text ...]**  
+> **comment [access-token] [hash] [text]**
 > Comment on a gallery post
 >
 > **vote-gallery [token] [hash] [direction]**   
-> Vote on a gallery post. Direction either 'up', 'down', or 'veto'
+> Vote on a gallery post. Direction can be either 'up', 'down', or 'veto'
 >
 > **vote-comment [token] [id] [direction]**     
-> Vote on a gallery comment. Direction either 'up', 'down', or 'veto'
-
-Config
-------
-
-Configuration is done through the **config.json** file in JSON format. The contents of the file should be a JSON
-object with the following properties:
-
-### client_id
-
-**Key**: 'client_id'
-
-**Type**: String [16 characters]
-
-**Description**: The client ID you got when you registered. Required for any API call. 
-
-### secret
-
-**Key**: 'secret'
-
-**Type**: String [40 characters]
-
-**Description**: The client secret you got when you registered, if you want to do OAuth authentication. 
-
-### token_store
-
-**Key**: 'token_store'
-
-**Type**: Object
-
-**Description**: Future configuration to control where the tokens are stored for persistent **insecure** storage of refresh tokens.
+> Vote on a gallery comment. Direction can be either 'up', 'down', or 'veto'

imgur-python/data/config.json.sample

@@ -2,4 +2,4 @@
     "client_id": "",
     "secret": "",
     "token_store": {}
-}
+}

imgur-python/docs/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

imgur-python/helpers/__init__.py

@@ -0,0 +1,14 @@
+import math
+
+
+def center_pad(s, length):
+    num_dashes = float(length - len(s) - 2) / 2
+    num_dashes_left = int(math.floor(num_dashes))
+    num_dashes_right = int(math.ceil(num_dashes))
+
+    return ('=' * num_dashes_left) + ' ' + s + ' ' + ('=' * num_dashes_right)
+
+
+def two_column_with_period(left, right, length):
+    num_periods = int(length - (len(left) + len(right) + 2))
+    return left + ' ' + ('.' * num_periods) + ' ' + right

imgur-python/helpers/format.py

@@ -1,20 +1,19 @@
 #!/usr/bin/env python3
 
-from .base import base as authbase
-import time as dt
+from .base import Base as AuthBase
 
-class accesstoken(authbase):
 
+class AccessToken(AuthBase):
     def __init__(self,  access, refresh, expire_time):
         self.access = access
         self.refresh = refresh
         self.expire_time = expire_time
 
     def need_to_authorize(self, time):
-        return (self.expire_time <= time)
+        return self.expire_time <= time
 
     def add_authorization_header(self, request):
-        request.add_header('Authorization', 'Bearer ' + self.access)
+        request.add_header('Authorization', 'Bearer %s' % self.access)
         return request
 
     def get_access_token(self):

imgur-python/imgur/auth/accesstoken.py

@@ -1,15 +1,18 @@
 #!/usr/bin/env python3
 
-class anonymous:
+from .base import Base as AuthBase
+
+
+class Anonymous(AuthBase):
     def __init__(self, client_id):
         self.client_id = client_id
 
-    def need_to_authorize(self):
+    def need_to_authorize(self, time):
         return False
 
-    def authorize(self):
+    def authorize(self, api, request_factory):
         pass
 
     def add_authorization_header(self, request):
-        request.add_header('Authorization', 'Client-ID ' + self.client_id)
-        return request
+        request.add_header('Authorization', 'Client-ID %s' % self.client_id)
+        return request

imgur-python/imgur/auth/anonymous.py

@@ -1,12 +1,14 @@
 #!/usr/bin/env python3
 
-class base:
+
+class Base:
     def need_to_authorize(self, time):
-        '''Do we need to refresh our authorization token?'''
+        """Do we need to refresh our authorization token?"""
         pass
-    def authorize(self, api, requestfactory):
-        '''Refresh our access token'''
+
+    def authorize(self, api, request_factory):
+        """Refresh our access token"""
         pass
+
     def add_authorization_header(self, request):
-        pass
-        
+        pass

imgur-python/imgur/auth/base.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-class expired(BaseException):
-    def __str__(self):
-        return "Access token invalid or expired."
 
+class Expired(BaseException):
+    def __str__(self):
+        return 'Access token invalid or expired.'

imgur-python/imgur/auth/expired.py

@@ -1,21 +1,22 @@
 #!/usr/bin/env python3
 
-import base64, os.path, time as dt
+import base64
+import os.path
+import time as dt
+from .imgur import Imgur
+from .ratelimit import RateLimit
+from .auth.anonymous import Anonymous
+from .auth.accesstoken import AccessToken
 
 try:
-    from urllib.request import Request as UrlLibRequest
-    from urllib.parse import urlencode as UrlLibEncode
+    from urllib.request import Request as urllibrequest
+    from urllib.parse import urlencode as urllibencode
 except ImportError:
-    from urllib2 import Request as UrlLibRequest
-    from urllib import urlencode as UrlLibEncode
-    
-from .imgur import imgur
-from .ratelimit import ratelimit
-from .auth.accesstoken import accesstoken
-from .auth.anonymous import anonymous
+    from urllib2 import Request as urllibrequest
+    from urllib import urlencode as urllibencode
 
-class factory:
 
+class Factory:
     API_URL = "https://api.imgur.com/"
 
     def __init__(self, config):
@@ -26,65 +27,72 @@ def __init__(self, config):
     def get_api_url(self):
         return self.API_URL
 
-    def build_api(self, auth = None, ratelimit = None):
+    def build_api(self, auth=None, rate_limit=None):
         if auth is None:
             auth = self.build_anonymous_auth()
-        if ratelimit is None:
-            ratelimit = self.build_rate_limit()
-        return imgur(self.config['client_id'], self.config['secret'], auth, ratelimit)
+
+        if rate_limit is None:
+            rate_limit = self.build_rate_limit()
+
+        return Imgur(self.config['client_id'], self.config['secret'], auth, rate_limit)
 
     def build_anonymous_auth(self):
-        return anonymous(self.config['client_id'])
+        return Anonymous(self.config['client_id'])
 
-    def build_oauth(self, access, refresh, expire_time = None):
+    @staticmethod
+    def build_oauth(access, refresh, expire_time=None):
         now = int(dt.time())
         if expire_time is None:
-            return accesstoken(access, refresh, now)
+            return AccessToken(access, refresh, now)
         else:
-            return accesstoken(access, refresh, expire_time)
+            return AccessToken(access, refresh, expire_time)
 
-    def build_request(self, endpoint, data = None, method = None):
-        '''Expects an endpoint like 'image.json' or a tuple like ('gallery', 'hot', 'viral', '0'). 
-        
-        Prepends 3/ and appends \.json to the tuple-form, not the endpoint form.'''
+    def build_request(self, endpoint, data=None, method=None):
+        """Expects an endpoint like 'image.json' or a tuple like ('gallery', 'hot', 'viral', '0').
+        Prepends 3/ and appends \.json to the tuple-form, not the endpoint form."""
         if isinstance(endpoint, str):
             url = self.API_URL + endpoint
         else:
             url = self.API_URL + '3/' + ('/'.join(endpoint)) + ".json"
 
-        req = UrlLibRequest(url)
+        req = urllibrequest(url)
         if data is not None:
-            req.add_data(UrlLibEncode(data).encode('utf-8'))
+            req.add_data(urllibencode(data).encode('utf-8'))
 
         if method is not None:
             # python urllib2 is broken... http://stackoverflow.com/a/111988
             req.get_method = lambda: method
+
         return req
-    
-    def build_rate_limit(self, limits = None):
-        '''If none, defaults to fresh rate limits. Else expects keys "client_limit", "user_limit", "user_reset"'''
+
+    @staticmethod
+    def build_rate_limit(limits=None):
+        """If none, defaults to fresh rate limits. Else expects keys \"client_limit\", \"user_limit\", \"user_reset\""""
         if limits is not None:
-            return ratelimit(limits['client_limit'], limits['user_limit'], limits['user_reset'])
+            return RateLimit(limits['client_limit'], limits['user_limit'], limits['user_reset'])
         else:
-            return ratelimit()
+            return RateLimit()
 
     def build_rate_limits_from_server(self, api):
-        '''Get the rate limits for this application and build a rate limit model from it.'''
+        """Get the rate limits for this application and build a rate limit model from it."""
         req = self.build_request('credits')
         res = api.retrieve(req)
-        return ratelimit(res['ClientRemaining'], res['UserRemaining'], res['UserReset'])
 
-    
-    def build_request_upload_from_path(self, path, params = dict()):
+        return RateLimit(res['ClientRemaining'], res['UserRemaining'], res['UserReset'])
+
+    def build_request_upload_from_path(self, path, params=dict()):
         fd = open(path, 'rb')
         contents = fd.read()
         b64 = base64.b64encode(contents)
+
         data = {
             'image': b64,
             'type': 'base64',
             'name': os.path.basename(path)
         }
+
         data.update(params)
+
         return self.build_request(('upload',), data)
 
     def build_request_oauth_token_swap(self, grant_type, token):
@@ -96,7 +104,7 @@ def build_request_oauth_token_swap(self, grant_type, token):
 
         if grant_type == 'authorization_code':
             data['code'] = token
-        if grant_type == 'pin':
+        elif grant_type == 'pin':
             data['pin'] = token
 
         return self.build_request('oauth2/token', data)
@@ -108,4 +116,5 @@ def build_request_oauth_refresh(self, refresh_token):
             'client_secret': self.config['secret'],
             'grant_type': 'refresh_token'
         }
+
         return self.build_request('oauth2/token', data)