Python fio client streaming/additional endpoints (#13)

* Python fio client streaming/additional endpoints

Add a utility to stream list methods via a python generator, also
added endpoints to update assets, get collabs/pending collabs, and
get project, team, etc.

* Better pagination

* Bump version

Author: michaeljguarino

frameioclient/client.py

@@ -1,6 +1,17 @@
 from .upload import FrameioUploader
 import requests
 
+class PaginatedResponse(object):
+  def __init__(results, page=0, page_size=0, total=0, total_pages=0):
+    self.results = results
+    self.page = int(page)
+    self.page_size = int(page_size)
+    self.total = int(total)
+    self.total_pages = int(total_pages)
+  
+  def __iter__(self):
+    return iter(self.results)
+
 class FrameioClient(object):
   def __init__(self, token, host='https://api.frame.io'):
     self.token = token
@@ -21,6 +32,14 @@ def _api_call(self, method, endpoint, payload={}):
     )
 
     if r.ok:
+      if r.headers.get('page-number'):
+        return PaginatedResponse(r.json(), 
+          page=r.headers['page-number'], 
+          page_size=r.headers['page-size'],
+          total_pages=r.headers['total-pages'],
+          total=r.headers['total']
+        )
+
       return r.json()
     return r.raise_for_status()
 
@@ -30,7 +49,7 @@ def get_me(self):
     """
     return self._api_call('get', '/me')
 
-  def get_teams(self, account_id):
+  def get_teams(self, account_id, **kwargs):
     """
     Get teams owned by the account. 
     (To return all teams, use get_all_teams())
@@ -39,27 +58,67 @@ def get_teams(self, account_id):
       account_id (string): The account id.
     """
     endpoint = '/accounts/{}/teams'.format(account_id)
+    return self._api_call('get', endpoint, kwargs)
+  
+  def get_team(self, team_id):
+    """
+    Get's a team by id
+
+    :Args:
+      team_id (string): the team's id
+    """
+    endpoint  = '/teams/{}'.format(team_id)
     return self._api_call('get', endpoint)
 
-  def get_all_teams(self):
+  def get_all_teams(self, **kwargs):
     """
     Get all teams for the authenticated user.
 
     :Args:
       account_id (string): The account id.
     """
     endpoint = '/teams'
-    return self._api_call('get', endpoint)
+    return self._api_call('get', endpoint, kwargs)
 
-  def get_projects(self, team_id):
+  def get_projects(self, team_id, **kwargs):
     """
     Get projects owned by the team.
 
     :Args:
       team_id (string): The team id.
     """
     endpoint = '/teams/{}/projects'.format(team_id)
+    return self._api_call('get', endpoint, kwargs)
+  
+  def get_project(self, project_id):
+    """
+    Get an individual project
+
+    :Args:
+      project_id (string): the project's id
+    """
+    endpoint = '/projects/{}'.format(project_id)
     return self._api_call('get', endpoint)
+  
+  def get_collaborators(self, project_id, **kwargs):
+    """
+    Get collaborators for a project
+
+    :Args:
+      project_id (string): the project's id
+    """
+    endpoint = "/projects/{}/collaborators".format(project_id)
+    return self._api_call('get', endpoint, kwargs)
+
+  def get_pending_collaborators(self, project_id, **kwargs):
+    """
+    Get pending collaborators for a project
+
+    :Args:
+      project_id (string): the project's id
+    """
+    endpoint = "/projects/{}/pending_collaborators".format(project_id)
+    return self._api_call('get', endpoint, kwargs)
 
   def create_project(self, team_id, **kwargs):
     """
@@ -100,15 +159,15 @@ def get_asset(self, asset_id):
     endpoint = '/assets/{}'.format(asset_id)
     return self._api_call('get', endpoint)
 
-  def get_asset_children(self, asset_id):
+  def get_asset_children(self, asset_id, **kwargs):
     """
     Get an asset's children.
 
     :Args:
       asset_id (string): The asset id.
     """
     endpoint = '/assets/{}/children'.format(asset_id)
-    return self._api_call('get', endpoint)
+    return self._api_call('get', endpoint, kwargs)
 
   def create_asset(self, parent_asset_id, **kwargs):
     """
@@ -131,6 +190,21 @@ def create_asset(self, parent_asset_id, **kwargs):
     """
     endpoint = '/assets/{}/children'.format(parent_asset_id)
     return self._api_call('post', endpoint, payload=kwargs)
+  
+  def update_asset(self, asset_id, **kwargs):
+    """
+    Updates an asset
+
+    :Args:
+      asset_id (string): the asset's id
+    :Kwargs:
+      the fields to update
+
+      Example::
+        client.update_asset("adeffee123342", name="updated_filename.mp4")
+    """
+    endpoint = '/assets/{}/children'.format(asset_id)
+    return self._api_call('put', endpoint, kwargs)
 
   def upload(self, asset, file):
     """
@@ -147,15 +221,15 @@ def upload(self, asset, file):
     uploader = FrameioUploader(asset, file)
     uploader.upload()
 
-  def get_comments(self, asset_id):
+  def get_comments(self, asset_id, **kwargs):
     """
     Get an asset's comments.
 
     :Args:
       asset_id (string): The asset id.
     """
     endpoint = '/assets/{}/comments'.format(asset_id)
-    return self._api_call('get', endpoint)
+    return self._api_call('get', endpoint, **kwargs)
 
   def create_comment(self, asset_id, **kwargs):
     """

frameioclient/utils.py

@@ -0,0 +1,19 @@
+def stream(func, page=1, page_size=20):
+    """
+    Accepts a lambda of a call to a client list method, and streams the results until
+    the list has been exhausted
+
+    :Args:
+        fun (function): A 1-arity function to apply during the stream
+
+        Example:: 
+            stream(lambda pagination: client.get_collaborators(project_id, **pagination))
+    """
+    total_pages = page
+    while page <= total_pages:
+        result_list = func(page=page, page_size=page_size)
+        total_pages = result_list.total_pages
+        for res in result_list:
+            yield res
+
+        page += 1

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
   name='frameioclient',
-  version='0.4.0',
+  version='0.5.0',
   description='Client library for the Frame.io API',
   long_description=long_description,
   long_description_content_type="text/markdown",