Merge pull request ClearBlade#6 from ClearBlade/collection-management

ms1752 · web-flow · commit 506d1edc2d76 · 2018-02-08T21:41:51.000-07:00
add collection managment, and first pass at permissions
diff --git a/README.md b/README.md
@@ -579,6 +579,71 @@ from clearblade.ClearBladeCore import Developer
 # Log in as Big Boi
 bigboi = Developer("antwan.a.patton@outkast.com", "th3w@yY0uM0v3")
 ```
+---
+### Collections
+First you are able to get a list of all current collections within a system.
+
+> Definition: `Developer.getAllCollections(system)`  
+> Returns: List of collections. Each collection is a dictionary containing the collection name and collectionID.  
+
+As a developer, you get full management access to any collection within a system. To create a cloud collection, you need to specify the system it's going to live in, and the name of the new collection you are creating.
+
+> Definition: `Developer.newCollection(system, name)`  
+> Returns: A Collection object of the newly created Collection
+
+You can also add columns to any Collection. Note: the Collection object you supply should be initialized with a `collectionID` (rather than `collectionName`) in order to add columns. The Collection object returned from `Developer.newCollection` is initialized this way for you for ease of use.
+
+> Definition: `Developer.addColumnToCollection(system, collectionObject, columnName, columnType)`  
+> Returns: Nothing
+
+Finally, you are able to set the CRUD permissions for a collection via a specific role name. Note: like `addColumnToCollection` you will need to use a Collection object initialized with a `collectionID`
+
+> Definition: `Developer.setPermissionsForCollection(system, collectionObject, Permissions.READ + Permissions.UPDATE, roleName)`  
+> Returns: Nothing
+
+#### Examples
+Creating a new Collection and adding a custom column.
+
+```python
+from clearblade.ClearBladeCore import System, Developer
+
+# System credentials
+SystemKey = "9abbd2970baabf8aa6d2a9abcc47"
+SystemSecret = "9ABBD2970BA6AABFE6E8AEB8B14F"
+
+mySystem = System(SystemKey, SystemSecret)
+
+# Log in as Steve
+steve = Developer("steve@clearblade.com", "r0s@_p@rks")
+
+# Create new Collection named Tools
+toolsCollection = steve.newCollection(mySystem, "Tools")
+
+# Add a column to the collection called last_location with a type of string
+steve.addColumnToCollection(mySystem, toolsCollection, "last_location", "string")
+```
+
+Updating CRUD permissions for a Collection on a specific role.
+
+```python
+from clearblade.ClearBladeCore import System, Developer, Collections, Permissions
+
+# System credentials
+SystemKey = "9abbd2970baabf8aa6d2a9abcc47"
+SystemSecret = "9ABBD2970BA6AABFE6E8AEB8B14F"
+
+mySystem = System(SystemKey, SystemSecret)
+
+# Log in as Steve
+steve = Developer("steve@clearblade.com", "r0s@_p@rks")
+
+# Create a Collection object from an existing collection with an id of 8a94dda70bb4c2c59b8298d686f401
+collectionObj = mySystem.Collection(steve, collectionID="8a94dda70bb4c2c59b8298d686f401")
+
+# Give the Authenticated role Read and Delete permissions to this collection
+michael.setPermissionsForCollection(mySystem, collectionObj, Permissions.READ + Permissions.DELETE, "Authenticated")
+```
+
 ---
 ### Devices
 As a developer, you get full CRUD access to the device table. 
diff --git a/clearblade/Collections.py b/clearblade/Collections.py
@@ -8,8 +8,12 @@ class Collection():
     def __init__(self, system, authenticatedUser, collectionID="", collectionName=""):
         if collectionID:
             self.url = system.url + '/api/v/1/data/' + collectionID
+            self.collectionID = collectionID
+            self.collectionName = None
         elif collectionName:
             self.url = system.url + '/api/v/1/collection/' + system.systemKey + "/" + collectionName
+            self.collectionName = collectionName
+            self.collectionID = None
         else:
             cbLogs.error("You must supply either a collection name or id.")  # beep
             exit(-1)
@@ -69,3 +73,44 @@ def updateItems(self, query, data):
 
     def deleteItems(self, query):
         return restcall.delete(self.url, headers=self.headers, params={"query": json.dumps(query.filters)}, sslVerify=self.sslVerify)
+
+
+###########################
+#   DEVELOPER ENDPOINTS   #
+###########################
+
+def DEVgetAllCollections(developer, system):
+    url = system.url + "/admin/allcollections"
+    params = {
+        "appid": system.systemKey
+    }
+    resp = restcall.get(url, headers=developer.headers, params=params, sslVerify=system.sslVerify)
+    return resp
+
+def DEVnewCollection(developer, system, name):
+    url = system.url + "/admin/collectionmanagement"
+    data = {
+        "appID": system.systemKey,
+        "name": name
+    }
+    resp = restcall.post(url, headers=developer.headers, data=data, sslVerify=system.sslVerify)
+    cbLogs.info("Successfully created collection: " + name)
+    return Collection(system, developer, collectionID=resp["collectionID"])
+
+def DEVaddColumnToCollection(developer, system, collection, columnName, columnType):
+    if not collection.collectionID:
+        cbLogs.error("You must supply the collection id when adding a column to a collection.")
+        exit(-1)
+    url = system.url + "/admin/collectionmanagement"
+    data = {
+        "id": collection.collectionID,
+        "addColumn": {
+            "id": collection.collectionID,
+            "name": columnName,
+            "type": columnType
+        }
+    }
+    resp = restcall.put(url, headers=developer.headers, data=data, sslVerify=system.sslVerify)
+    cbLogs.info("Successfully added column: " + columnName)
+    return resp
+
diff --git a/clearblade/Developers.py b/clearblade/Developers.py
@@ -1,8 +1,9 @@
 from __future__ import absolute_import
 from . import restcall
 from . import cbLogs
+from . import Collections
 from . import Devices
-
+from . import Permissions
 
 def registerDev(fname, lname, org, email, password, url="https://platform.clearblade.com"):
     newDevCredentials = {
@@ -65,6 +66,19 @@ def logout(self):
     # ~~~~~~~~~~~~~~~~~~~~~~ #
     ##########################
 
+    #################
+    #  Collections  #
+    #################
+
+    def getAllCollections(self, system):
+        return Collections.DEVgetAllCollections(self, system)
+
+    def newCollection(self, system, name):
+        return Collections.DEVnewCollection(self, system, name)
+
+    def addColumnToCollection(self, system, collection, columnName, columnType):
+        return Collections.DEVaddColumnToCollection(self, system, collection, columnName, columnType)
+
     ###############
     #   Devices   #
     ###############
@@ -83,3 +97,11 @@ def updateDevice(self, system, name, updates):
 
     def deleteDevice(self, system, name):
         return Devices.DEVdeleteDevice(self, system, name)
+
+    #################
+    #  Permissions  #
+    #################
+
+    def setPermissionsForCollection(self, system, collection, permissionsLevel, roleName):
+        return Permissions.DEVsetPermissionsForCollection(self, system, collection, permissionsLevel, roleName)
+
diff --git a/clearblade/Permissions.py b/clearblade/Permissions.py
@@ -0,0 +1,32 @@
+from __future__ import absolute_import
+from . import cbLogs
+from . import restcall
+
+
+READ = 1
+CREATE = 2
+UPDATE = 4
+DELETE = 8
+
+###########################
+#   DEVELOPER ENDPOINTS   #
+###########################
+
+def DEVsetPermissionsForCollection(developer, system, collection, permissionsLevel, roleName):
+    url = system.url + "/admin/user/" + system.systemKey + "/roles"
+    data = {
+        "id": roleName,
+        "changes": {
+            "collections": [{
+                "itemInfo": {
+                    "name": collection.collectionName,
+                    "id": collection.collectionID
+                },
+                "permissions": permissionsLevel
+            }]
+        }
+    }
+    resp = restcall.put(url, headers=developer.headers, data=data, sslVerify=system.sslVerify)
+    cbLogs.info("Successfully updated permissions for role: " + roleName)
+    return resp
+    
diff --git a/setup.py b/setup.py
@@ -4,10 +4,10 @@
     name='clearblade',
     packages=['clearblade'],
     install_requires=['requests', 'paho-mqtt>=1.3.0'],
-    version='2.1',
+    version='2.2',
     description='A Python SDK for interacting with the ClearBlade Platform.',
     url='https://github.com/ClearBlade/ClearBlade-Python-SDK',
-    download_url='https://github.com/ClearBlade/ClearBlade-Python-SDK/archive/v2.0.tar.gz',
+    download_url='https://github.com/ClearBlade/ClearBlade-Python-SDK/archive/v2.2.tar.gz',
     keywords=['clearblade', 'iot', 'sdk'],
     maintainer='Aaron Allsbrook',
     maintainer_email='dev@clearblade.com'
