Merge pull request #4 from amigocloud/project_tokens

Project Tokens Support

Author: jcmonroy

README.rst

@@ -34,6 +34,15 @@ This library uses API token to authenticate you. To generate or access your API
     from amigocloud import AmigoCloud
     amigocloud = AmigoCloud(token='R:dlNDEiOWciP3y26kG2cHklYpr2HIPK40HD32r1')
 
+You could also use a project token. Remember that project tokens can only be used to query endpoints relative to the project it belongs to.
+If the project URL doesn't match its project, `AmigoCloudError` will be thrown.
+
+.. code:: python
+
+    from amigocloud import AmigoCloud
+    amigocloud = AmigoCloud(token='C:Ndl3xGWeasYt9rqyuVsByf5HPMAGyte10y1Mub',
+                            project_url='users/123/projects/1234')
+
 
 You can use a READ token if you only want to do requests that won't alter data. Otherwise, you'll need to use more permissive tokens.
 
@@ -50,6 +59,15 @@ can use full urls or relative API urls:
     amigocloud.get('/me')
     amigocloud.get('https://www.amigocloud.com/api/v1/me')
 
+For convenience, when using project tokens, urls are relative to the project's url (unless it starts with `/`):
+
+.. code:: python
+
+    # All three will do the same request:
+    amigocloud.get('datasets')
+    amigocloud.get('/users/123/projects/1234/datasets')
+    amigocloud.get('https://www.amigocloud.com/api/v1/users/123/projects/1234/datasets')
+
 Creating a new AmigoCloud project from Python is as simple as:
 
 .. code:: python
@@ -84,7 +102,8 @@ Websocket connection
 ~~~~~~~~~~~~~~~~~~~~
 
 The websocket connection is started when the AmigoCloud object is
-instantiated, and it is closed when the object is destroyed.
+instantiated, and it is closed when the object is destroyed. You always
+need to use a user token for websockets.
 
 Make sure to read `our help page about our websocket events <http://help.amigocloud.com/hc/en-us/articles/204246154>`__ before continue reading.
 

VERSION.txt

@@ -1 +1 @@
-1.1
+1.2

amigocloud/amigocloud.py

@@ -41,23 +41,39 @@ class AmigoCloud(object):
         https://www.amigocloud.com/accounts/tokens
     """
 
-    def __init__(self, token=None, base_url=BASE_URL, use_websockets=True,
-                 websocket_port=None):
+    error_msg = {
+        'logged_in_websockets': ('You must be logged in with a user token '
+                                 'to start receiving websocket events.')
+    }
 
+    def __init__(self, token=None, project_url=None, base_url=BASE_URL,
+                 use_websockets=True, websocket_port=None):
+        """
+        :param str token: AmigoCloud API Token
+        :param str project_url: Specify it if you are using a project token
+        :param str base_url: points to https://www.amigocloud.com by default
+        :param bool use_websockets: True by default. Parameter will be ignored
+            when using Project Tokens
+        :param int websocket_port: Standard websocket port by default
+        """
         # Urls
         if base_url.endswith('/'):
             self.base_url = base_url[:-1]
         else:
             self.base_url = base_url
         self.api_url = self.base_url + '/api/v1'
 
+        self._token = None
+        self._user_id = None
+        self._project_id = None
+        self._project_url = None
+
         # Auth
-        self.logout()
         if token:
-            self.authenticate(token)
+            self.authenticate(token, project_url)
 
         # Websockets
-        if use_websockets:
+        if use_websockets and not project_url:
             self.socketio = SocketIO(self.base_url, websocket_port)
             self.amigosocket = self.socketio.define(BaseNamespace,
                                                     '/amigosocket')
@@ -73,22 +89,30 @@ def build_url(self, url):
         # User wants to use the api_url
         if url.startswith('/'):
             return self.api_url + url
-        return '%s/%s' % (self.api_url, url)
+        return os.path.join(self._project_url or self.api_url, url)
 
     def check_for_errors(self, response):
         try:
             response.raise_for_status()
         except requests.exceptions.HTTPError as exc:
-            raise AmigoCloudError(exc.message, exc.response)
+            raise AmigoCloudError(str(exc), exc.response)
 
-    def authenticate(self, token):
+    def authenticate(self, token, project_url=None):
         self._token = token
-        response = self.get('/me')
-        self._user_id = response['id']
+        self._project_url = (self.build_url(project_url) if project_url
+                             else None)
+        if not self._project_url:
+            response = self.get('/me')
+            self._user_id = response['id']
+        else:
+            response = self.get('')
+            self._project_id = response['id']
 
     def logout(self):
         self._token = None
         self._user_id = None
+        self._project_id = None
+        self._project_url = None
 
     def get(self, url, params=None, raw=False, stream=False, **request_kwargs):
         """
@@ -308,8 +332,7 @@ def listen_user_events(self):
         """
 
         if not self._user_id:
-            msg = 'You must be logged in to start receiving websocket events.'
-            raise AmigoCloudError(msg)
+            raise AmigoCloudError(self.error_msg['logged_in_websockets'])
 
         response = self.get('/me/start_websocket_session')
         websocket_session = response['websocket_session']
@@ -323,8 +346,7 @@ def listen_dataset_events(self, owner_id, project_id, dataset_id):
         """
 
         if not self._user_id:
-            msg = 'You must be logged in to start receiving websocket events.'
-            raise AmigoCloudError(msg)
+            raise AmigoCloudError(self.error_msg['logged_in_websockets'])
 
         url = '/users/%s/projects/%s/datasets/%s/start_websocket_session'
         response = self.get(url % (owner_id, project_id, dataset_id))

setup.py

@@ -8,7 +8,7 @@
 with open('VERSION.txt', 'r') as v:
     version = v.read().strip()
 
-with open('REQUIREMENTS.txt', 'r') as r:
+with open('requirements.txt', 'r') as r:
     requires = r.read().split()
 
 with open('README.rst', 'r') as r: