Merge pull request #1 from PTCInc/Beta3

Beta3

Author: KepwareSalesAE

LICENSE

@@ -1,7 +1,6 @@
 MIT License
 
-
-Copyright (c) 2020, PTC Inc. and/or all its affiliates. All rights reserved.
+Copyright (c) PTC Inc. and/or all its affiliates. All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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 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
 
@@ -12,24 +12,38 @@ The client libraries are supported on Python 3.6 or later. All HTTP communicatio
 
 SDK allows for *GET*, *ADD*, *DELETE*, and *MODIFY* functions for the following Kepware configuration objects:
 
-- **Project Properties** *(Get and Modify Only)*
-- **Connectivity** *(Channel, Devices, Tags, Tag Groups)*
-- **IoT Gateway** *(Agents, IoT Items)*
+| Features      | TKS/KEP       | TKE           |
+| :----------:  | :----------:  | :----------:  |
+| **Project Properties** <br /> *(Get and Modify Only)* | Y | Y |
+| **Connectivity** <br /> *(Channel, Devices, Tags, Tag Groups)* | Y | Y |
+| **IoT Gateway** <br /> *(Agents, IoT Items)* | Y | Y |
+| **Datalogger** <br /> *(Log Groups, Items, Mapping, Triggers, Reset Mapping Service)* | Y | Y |
+| **Administration** <br /> *(User Groups, Users, UA Endpoints)* | Y* | Y |
+
+Note (*) - UA Endpoints supported for Kepware Edge only
 
 Methods to read the following logs:
 
-- **Event Log**
-- **API Transaction Log**
+| Logs          | TKS/KEP       | TKE           |
+| :----------:  | :----------:  | :----------:  |
+| **Event Log** | Y | Y |
+| **API Transaction Log** | Y | Y |
+
+Configuration API *Services* implemented:
+
+| Services      | TKS/KEP       | TKE           |
+| :----------:  | :----------:  | :----------:  |
+| **TagGeneration** <br /> *(not supported by all drivers)* | Y | Y |
+| **ReinitializeRuntime** | Y* | Y |
 
-Additionally the following *Services* are implemented:
+Note (*) - Reinitialize service was implemented for Kepware Server v6.8+
 
-- **TagGeneration** *(not supported by all drivers)*
-- **ReinitializeRuntime** *(Thingworx Kepware Edge and Kepware Server 6.8+)*
+Generic REST methods are provided to use for functions not developed in SDK package. These are found in the Server Class in [connection.py](/kepconfig/connection.py)
 
 ## Known Limitations
 
 - Other property configruation for more complex drivers are not explicitly defined
-- Other supported plug-ins (Datalogger, Scheduler, etc) are not defined
+- Other supported plug-ins (EFM Exporter, Scheduler, etc) are not defined
 - When using hostnames (not IP addresses) for connections, delays may occur under certain network configurations as the connection may attempt IPv6 connections first. IPv6 is not supported by Kepware servers at this time.
 
 ## Installation
@@ -42,6 +56,8 @@ pip install kepconfig-<version>-py3-none-any.whl -f ./ --no-index
 
 ## Key Concepts
 
+NOTE: Samples can also be found in the [samples](samples) folder.
+
 ### Create server connection
 
 ```python
@@ -54,7 +70,7 @@ server = connection.server(host = '127.0.0.1', port = 57412, user = 'Administrat
 
 ```
 
-For certificate validation, the SDK uses the OS/systems trusted CA certificate store. The connection leverages uses the "create_default_context()" function as part of urllib as described at the following links:
+For certificate validation, the SDK uses the OS/systems trusted CA certificate store. The connection uses the "create_default_context()" function as part of urllib as described at the following links:
 
 - [ssl.create_default_context](https://docs.python.org/3/library/ssl.html#ssl.create_default_context)
 - [ssl.SSLContext.load_default_certs](https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_default_certs)
@@ -64,7 +80,7 @@ For Windows OSes, the Kepware server's instance certificate can be loaded into t
 
 ### Create an object
 
-Objects such as channels or devices can be created either sigularly or with children included.
+Objects such as channels or devices can be created either singularly or with children included.
 
 ### Ex: Add Single channel
 
@@ -98,5 +114,7 @@ result = tag.add_tag(server, tag_path, tag_info))
 ## Need More Information
 
 **Visit:**
-- [Kepware.com](https://www.kepware.com/)
-- [Configuration API Info](https://www.kepware.com/en-us/products/kepserverex/features/configuration-api/)
+
+[Kepware.com](https://www.kepware.com/)
+[Configuration API Info](https://www.kepware.com/en-us/products/kepserverex/features/configuration-api/)
+[PTC.com](https://www.ptc.com/)

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

@@ -0,0 +1,8 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2020, PTC Inc. and/or all its affiliates. All rights reserved.
+# See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+from . import users, user_groups,ua_server

dist/kepconfig-1.0b3.tar.gz

@@ -0,0 +1,136 @@
+# -------------------------------------------------------------------------
+# Copyright (c), PTC Inc. and/or all its affiliates. All rights reserved.
+# See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+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
+"""
+UA_ROOT = '/admin/ua_endpoints'
+
+def _create_url(endpoint = None):
+    '''Creates url object for the "server_users" branch of Kepware's project tree. Used 
+    to build a part of Kepware Configuration API URL structure
+
+    Returns the user specific url when a value is passed as the user name.
+    '''
+    
+    if endpoint == None:
+        return UA_ROOT
+    else:
+        return '{}/{}'.format(UA_ROOT,endpoint)
+
+def add_endpoint(server, DATA):
+    '''Add an "endpoint" or multiple "endpoint" objects to Kepware UA Server by passing a 
+    list of endpoints to be added all at once.
+
+    INPUTS:
+    "server" - instance of the "server" class
+
+    "DATA" - properly JSON object (dict) of the endpoint
+    expected by Kepware Configuration API
+
+    RETURNS:
+    True - If a "HTTP 201 - Created" is received from Kepware
+
+    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 
+    else: return False
+
+def del_endpoint(server, endpoint):
+    '''Delete a "endpoint" object in Kepware UA Server
+    
+    INPUTS:
+    "server" - instance of the "server" class
+
+    "endpoint" - name of endpoint
+    
+    RETURNS:
+    True - If a "HTTP 200 - OK" is received from Kepware
+
+    EXCEPTIONS:
+    KepHTTPError - If urllib provides an HTTPError
+    KepURLError - If urllib provides an URLError
+    '''
+
+    r = server._config_del(server.url + _create_url(endpoint))
+    if r.code == 200: return True 
+    else: return False
+
+def modify_endpoint(server, DATA, endpoint = None):
+    '''Modify a endpoint object and it's properties in Kepware UA Server. If a "endpoint" is not provided as an input,
+    you need to identify the endpoint in the 'common.ALLTYPES_NAME' property field in the "DATA". It will 
+    assume that is the endpoint that is to be modified.
+
+    INPUTS:
+    "server" - instance of the "server" class
+
+    "DATA" - properly JSON object (dict) of the endpoint properties to be modified.
+
+    "endpoint" (optional) - name of endpoint to modify. Only needed if not existing in  "DATA"
+    
+    RETURNS:
+    True - If a "HTTP 200 - OK" is received from Kepware
+
+    EXCEPTIONS:
+    KepHTTPError - If urllib provides an HTTPError
+    KepURLError - If urllib provides an URLError
+    '''
+    
+    # channel_data = server._force_update_check(force, DATA)
+    if endpoint == None:
+        try:
+            r = server._config_update(server.url + _create_url(DATA['common.ALLTYPES_NAME']), DATA)
+            if r.code == 200: return True 
+            else: return False
+        except KeyError as err:
+            print('Error: No UA Endpoint identified in DATA | Key Error: {}'.format(err))
+            return False
+        # except Exception as e:
+        #     return 'Error: Error with {}: {}'.format(inspect.currentframe().f_code.co_name, str(e))
+    else:
+        r = server._config_update(server.url + _create_url(endpoint), DATA)
+        if r.code == 200: return True 
+        else: return False
+
+def get_endpoint(server, endpoint):
+    '''Returns the properties of the endpoint object. Returned object is JSON.
+    
+    INPUTS:
+    "server" - instance of the "server" class
+
+    "endpoint" - name of endpoint
+    
+    RETURNS:
+    JSON - data for the endpoint requested
+
+    EXCEPTIONS:
+    KepHTTPError - If urllib provides an HTTPError
+    KepURLError - If urllib provides an URLError
+    '''
+
+    r = server._config_get(server.url + _create_url(endpoint))
+    return r.payload
+
+def get_all_endpoints(server):
+    '''Returns list of all endpoint objects and their properties. Returned object is JSON list.
+    
+    INPUTS:
+    "server" - instance of the "server" class
+    
+    RETURNS:
+    JSON - data for all endpoints requested
+
+    EXCEPTIONS:
+    KepHTTPError - If urllib provides an HTTPError
+    KepURLError - If urllib provides an URLError
+    '''
+
+    r = server._config_get(server.url + _create_url())
+    return r.payload