Merge pull request #3 from PTCInc/rlabbeptc/issue2

Multistatus response during add

Author: rlabbeptc

README.md

@@ -1,6 +1,6 @@
 # Kepware Configuration API SDK for Python
 
-This is a package SDK to create Python modules to conduct operations with the Kepware Configuration API. THis package is designed to work with all versions of Kepware that support the Configuration API including Thingworx Kepware Server (TKS), Thingworx Kepware Edge (TKE) and KEPServerEX (KEP).
+This is a package SDK to create Python modules to conduct operations with the Kepware Configuration API. This package is designed to work with all versions of Kepware that support the Configuration API including Thingworx Kepware Server (TKS), Thingworx Kepware Edge (TKE) and KEPServerEX (KEP).
 
 ## Prerequisites
 

dist/kepconfig-1.0b4-py3-none-any.whl

@@ -7,6 +7,9 @@
 r""":mod:`ua_server` exposes an API to allow modifications (add, delete, modify) to 
 OPC UA Server endpoints within the Kepware Administration through the Kepware Configuration API
 """
+from typing import Union
+
+
 UA_ROOT = '/admin/ua_endpoints'
 
 def _create_url(endpoint = None):
@@ -21,7 +24,7 @@ def _create_url(endpoint = None):
     else:
         return '{}/{}'.format(UA_ROOT,endpoint)
 
-def add_endpoint(server, DATA):
+def add_endpoint(server, DATA) -> Union[bool, list]:
     '''Add an "endpoint" or multiple "endpoint" objects to Kepware UA Server by passing a 
     list of endpoints to be added all at once.
 
@@ -34,13 +37,24 @@ def add_endpoint(server, DATA):
     RETURNS:
     True - If a "HTTP 201 - Created" is received from Kepware
 
+    List - If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
+    endpoints added that failed.
+
+    False - If a non-expected "2xx successful" code is returned
+
     EXCEPTIONS:
     KepHTTPError - If urllib provides an HTTPError
     KepURLError - If urllib provides an URLError
     '''
 
     r = server._config_add(server.url + _create_url(), DATA)
-    if r.code == 201: return True 
+    if r.code == 201: return True
+    elif r.code == 207:
+        errors = [] 
+        for item in r.payload:
+            if item['code'] != 201:
+                errors.append(item)
+        return errors
     else: return False
 
 def del_endpoint(server, endpoint):

dist/kepconfig-1.0b4.tar.gz

@@ -7,6 +7,9 @@
 r""":mod:`user_groups` exposes an API to allow modifications (add, delete, modify) to 
 user_groups within the Kepware Administration User Manager through the Kepware Configuration API
 """
+from typing import Union
+
+
 USERGROUPS_ROOT = '/admin/server_usergroups'
 ENABLE_PROPERTY = 'libadminsettings.USERMANAGER_GROUP_ENABLED'
 
@@ -22,7 +25,7 @@ def _create_url(user_group = None):
     else:
         return '{}/{}'.format(USERGROUPS_ROOT,user_group)
 
-def add_user_group(server, DATA):
+def add_user_group(server, DATA) -> Union[bool, list]:
     '''Add a "user_group" or multiple "user_group" objects to Kepware User Manager by passing a 
     list of user groups to be added all at once.
 
@@ -35,13 +38,24 @@ def add_user_group(server, DATA):
     RETURNS:
     True - If a "HTTP 201 - Created" is received from Kepware
 
+    List - If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
+    user groups added that failed.
+
+    False - If a non-expected "2xx successful" code is returned
+
     EXCEPTIONS:
     KepHTTPError - If urllib provides an HTTPError
     KepURLError - If urllib provides an URLError
     '''
 
     r = server._config_add(server.url + _create_url(), DATA)
     if r.code == 201: return True 
+    elif r.code == 207:
+        errors = [] 
+        for item in r.payload:
+            if item['code'] != 201:
+                errors.append(item)
+        return errors
     else: return False
 
 def del_user_group(server, user_group):

kepconfig/admin/ua_server.py

@@ -7,6 +7,9 @@
 r""":mod:`users` exposes an API to allow modifications (add, delete, modify) to 
 users within the Kepware Administration User Management through the Kepware Configuration API
 """
+from typing import Union
+
+
 USERS_ROOT = '/admin/server_users'
 ENABLE_PROPERTY = 'libadminsettings.USERMANAGER_USER_ENABLED'
 
@@ -22,7 +25,7 @@ def _create_url(user = None):
     else:
         return '{}/{}'.format(USERS_ROOT,user)
 
-def add_user(server, DATA):
+def add_user(server, DATA) -> Union[bool, list]:
     '''Add a "user" or multiple "user" objects to Kepware User Manager by passing a 
     list of users to be added all at once.
 
@@ -35,13 +38,24 @@ def add_user(server, DATA):
     RETURNS:
     True - If a "HTTP 201 - Created" is received from Kepware
 
+    List - If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
+    users added that failed.
+
+    False - If a non-expected "2xx successful" code is returned
+
     EXCEPTIONS:
     KepHTTPError - If urllib provides an HTTPError
     KepURLError - If urllib provides an URLError
     '''
 
     r = server._config_add(server.url + _create_url(), DATA)
     if r.code == 201: return True 
+    elif r.code == 207:
+        errors = [] 
+        for item in r.payload:
+            if item['code'] != 201:
+                errors.append(item)
+        return errors
     else: return False
 
 def del_user(server, user):

kepconfig/admin/user_groups.py

@@ -272,14 +272,6 @@ def __connect(self,request_obj):
                 data.code = server.code
                 data.reason = server.reason
                 return data
-                # if request_obj.method == 'GET':
-                #     data.payload = json.loads(codecs.decode(server.read(),'utf-8-sig'))
-                #     data.code = server.code
-                #     data.reason = server.reason
-                #     return data
-                # else:
-                #     return server
-                    # return 'HTTP Code: {} - {}'.format(server.code,server.reason)
         except error.HTTPError as err:
             payload = json.loads(codecs.decode(err.read(),'utf-8-sig'))
             # print('HTTP Code: {}\n{}'.format(err.code,payload), file=sys.stderr)
@@ -289,7 +281,7 @@ def __connect(self,request_obj):
             raise KepError.KepURLError(err.reason, request_obj.get_full_url())
 
     # Fucntion used to ensure special characters are handled in the URL
-    # Ex. = Space will be turned to %20
+    # Ex: Space will be turned to %20
     def __url_validate(self, url):
         parsed_url = parse.urlparse(url)
         updated_path = parse.quote(parsed_url.path)

kepconfig/admin/users.py

@@ -11,6 +11,7 @@
 
 
 import inspect
+from typing import Union
 
 CHANNEL_ROOT = '/project/channels'
 
@@ -26,7 +27,7 @@ def _create_url(channel = None):
     else:
         return '{}/{}'.format(CHANNEL_ROOT,channel)
 
-def add_channel(server, DATA):
+def add_channel(server, DATA) -> Union[bool, list]:
     '''Add a "channel" or multiple "channel" objects to Kepware. Can be used to pass children of a channel object 
     such as devices and tags/tag groups. This allows you to create a channel, it's devices and tags 
     all in one function, if desired.
@@ -41,14 +42,26 @@ def add_channel(server, DATA):
 
     RETURNS:
     True - If a "HTTP 201 - Created" is received from Kepware
+    
+    List - If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
+    channels added that failed.
+
+    False - If a non-expected "2xx successful" code is returned
+        
 
     EXCEPTIONS:
     KepHTTPError - If urllib provides an HTTPError
     KepURLError - If urllib provides an URLError
     '''
 
     r = server._config_add(server.url + _create_url(), DATA)
-    if r.code == 201: return True 
+    if r.code == 201: return True
+    elif r.code == 207:
+        errors = [] 
+        for item in r.payload:
+            if item['code'] != 201:
+                errors.append(item)
+        return errors
     else: return False
 
 def del_channel(server, channel):

kepconfig/connection.py

@@ -9,6 +9,7 @@
 device objects within the Kepware Configuration API
 """
 
+from typing import Union
 import kepconfig
 from . import channel
 import inspect
@@ -27,7 +28,7 @@ def _create_url(device = None):
     else:
         return '{}/{}'.format(DEVICE_ROOT,device)
 
-def add_device(server, dev_channel, DATA):
+def add_device(server, dev_channel, DATA) -> Union[bool, list]:
     '''Add a "device" object to a channel in Kepware. Can be used to pass children of a device object 
     such as tags and tag groups. This allows you to create a device and tags 
     all in one function, if desired.
@@ -44,14 +45,25 @@ def add_device(server, dev_channel, DATA):
     
     RETURNS:
     True - If a "HTTP 201 - Created" is received from Kepware
+    
+    List  - If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
+    devices added that failed.
+
+    False - If a non-expected "2xx successful" code is returned
 
     EXCEPTIONS:
     KepHTTPError - If urllib provides an HTTPError
     KepURLError - If urllib provides an URLError
     '''
 
     r = server._config_add(server.url + channel._create_url(dev_channel) + _create_url(), DATA)
-    if r.code == 201: return True 
+    if r.code == 201: return True
+    elif r.code == 207:
+        errors = [] 
+        for item in r.payload:
+            if item['code'] != 201:
+                errors.append(item)
+        return errors
     else: return False
 
 def del_device(server, device_path):