Updates to support query options for collections

Author: rlabbeptc

kepconfig/admin/ua_server.py

@@ -9,6 +9,7 @@
 """
 from typing import Union
 from ..error import KepHTTPError, KepError
+from ..connection import server
 
 
 UA_ROOT = '/admin/ua_endpoints'
@@ -132,11 +133,14 @@ def get_endpoint(server, endpoint) -> dict:
     r = server._config_get(server.url + _create_url(endpoint))
     return r.payload
 
-def get_all_endpoints(server) -> list:
+def get_all_endpoints(server: server, *, options: dict = None) -> list:
     '''Returns list of all endpoint objects and their properties. Returned object is JSON list.
     
     INPUTS:
-    "server" - instance of the "server" class
+    server - instance of the "server" class
+
+    options - (optional) Dict of parameters to filter, sort or pagenate the list of UA endpoints. Options are 'filter', 
+    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'.
     
     RETURNS:
     list - data for all endpoints requested
@@ -146,5 +150,5 @@ def get_all_endpoints(server) -> list:
     KepURLError - If urllib provides an URLError
     '''
 
-    r = server._config_get(server.url + _create_url())
+    r = server._config_get(f'{server.url}{_create_url()}', params= options)
     return r.payload

kepconfig/admin/user_groups.py

@@ -9,6 +9,7 @@
 """
 from typing import Union
 from ..error import KepHTTPError, KepError
+from ..connection import server
 
 
 USERGROUPS_ROOT = '/admin/server_usergroups'
@@ -132,12 +133,15 @@ def get_user_group(server, user_group) -> dict:
     r = server._config_get(server.url + _create_url(user_group))
     return r.payload
 
-def get_all_user_groups(server) -> list:
+def get_all_user_groups(server: server, *, options: dict = None) -> list:
     '''Returns list of all user_group objects and their properties. Returned object is JSON list.
     
     INPUTS:
-    "server" - instance of the "server" class
+    server - instance of the "server" class
     
+    options - (optional) Dict of parameters to filter, sort or pagenate the list of user groups. Options are 'filter', 
+    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'.
+
     RETURNS:
     list - data for all user_groups requested
 
@@ -146,7 +150,7 @@ def get_all_user_groups(server) -> list:
     KepURLError - If urllib provides an URLError
     '''
 
-    r = server._config_get(server.url + _create_url())
+    r = server._config_get(f'{server.url}{_create_url()}', params= options)
     return r.payload
 
 def enable_user_group(server, user_group) -> bool:

kepconfig/admin/users.py

@@ -9,6 +9,7 @@
 """
 from typing import Union
 from ..error import KepError, KepHTTPError
+from ..connection import server
 
 
 USERS_ROOT = '/admin/server_users'
@@ -132,11 +133,14 @@ def get_user(server, user) -> dict:
     r = server._config_get(server.url + _create_url(user))
     return r.payload
 
-def get_all_users(server) -> list:
+def get_all_users(server: server, *, options: dict = None) -> list:
     '''Returns list of all user objects and their properties. Returned object is JSON list.
     
     INPUTS:
-    "server" - instance of the "server" class
+    server - instance of the "server" class
+
+    options - (optional) Dict of parameters to filter, sort or pagenate the list of users. Options are 'filter', 
+    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'.
     
     RETURNS:
     list - data for all users requested
@@ -146,7 +150,7 @@ def get_all_users(server) -> list:
     KepURLError - If urllib provides an URLError
     '''
 
-    r = server._config_get(server.url + _create_url())
+    r = server._config_get(f'{server.url}{_create_url()}', params= options)
     return r.payload
 
 def enable_user(server, user) -> bool:

kepconfig/connection.py

@@ -16,7 +16,6 @@
 from .error import KepError, KepHTTPError, KepURLError
 import socket
 import ssl
-import sys
 
 class KepServiceResponse:
     '''A class to represent a return object when calling a "service" API of Kepware. This is
@@ -82,7 +81,7 @@ class server:
     Methods:
 
     "reinitialize()" - reinitialize the Kepware server
-    "get_trans_log()" - retrieve the Configuration API transaction logs
+    "get_transaction_log()" - retrieve the Configuration API transaction logs
     "get_event_log()" - retrieve the Kepware Event Log
     "get_project_properties()" - retrieve the Kepware Project Properties
     "modify_project_properties()" - modify the Kepware Project Properties
@@ -206,32 +205,38 @@ def reinitialize(self, job_ttl = None) -> KepServiceResponse:
         except Exception as err:
             raise err
 
-    def get_trans_log(self, start = None, end = None, limit = None) -> list:
+    def get_transaction_log(self, limit: int = None, start: datetime.datetime = None, end: datetime.datetime = None) -> list:
         ''' Get the Transaction Log from the Kepware instance.
 
-        "start" (optional) - datetime.datetime type and should be UTC
+        limit (optional) -  number of event log entries to request
+        
+        start (optional) - datetime.datetime type and should be UTC
 
-        "end" (optional) - datetime.datetime type and should be UTC
+        end (optional) - datetime.datetime type and should be UTC
 
-        "limit" (optional) -  number of event log entries to request
         '''
         query = self.__create_query(start, end, limit)
-        url = self.url + self.__trans_log_url + '?' + parse.urlencode(query)
-        r = self._config_get(url)
+        url = f'{self.url}{self.__trans_log_url}'
+        r = self._config_get(url, params= query)
         return r.payload
 
-    def get_event_log(self, limit = None, start = None, end = None) -> list:
+    def get_event_log(self, limit: int = None, start: datetime.datetime = None, end: datetime.datetime = None, *, options: dict = None) -> list:
         ''' Get the Event Log from the Kepware instance.
 
-        "start" (optional) - datetime.datetime type and should be UTC
+        start (optional) - datetime.datetime type and should be UTC
+
+        end (optional) - datetime.datetime type and should be UTC
 
-        "end" (optional) - datetime.datetime type and should be UTC
+        limit (optional) - number of event log entries to request
 
-        "limit" (optional) - number of event log entries to request
+        options - (optional) Dict of parameters to filter, sort or pagenate the list of transactions. Options are 'event', 
+        'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'
         '''
         query = self.__create_query(start, end, limit)
-        url = self.url + self.__event_log_url + '?' + parse.urlencode(query)
-        r = self._config_get(url)
+        if options is not None:
+            query = {**query, **options}
+        url = f'{self.url}{self.__event_log_url}'
+        r = self._config_get(url, params= query)
         return r.payload
 
     def get_project_properties(self) -> dict:
@@ -399,8 +404,15 @@ def _config_update(self, url, DATA = None):
         return r
 
     #Function used to Read an object from Kepware (HTTP GET) and return the JSON response
-    def _config_get(self, url):
-        '''Conducts an GET method at *url* to retrieve an objects properties in the Kepware Configuration.'''
+    def _config_get(self, url, *, params = None):
+        '''
+        Conducts an GET method at *url* to retrieve an objects properties with query parameters in 
+        the Kepware Configuration.
+        '''
+        # Add parameters when necessary
+        if params is not None and params != {}:
+            qparams = parse.urlencode(params)
+            url = f'{url}?{qparams}'
         url_obj = self.__url_validate(url)
         q = request.Request(url_obj, method='GET')
         r = self.__connect(q)

kepconfig/connectivity/channel.py

@@ -11,9 +11,10 @@
 
 
 import inspect
+from ..connection import server
 from ..error import KepHTTPError, KepError
 from typing import Union
-from. import device
+from . import device
 
 CHANNEL_ROOT = '/project/channels'
 
@@ -29,7 +30,7 @@ def _create_url(channel = None):
     else:
         return '{}/{}'.format(CHANNEL_ROOT,channel)
 
-def add_channel(server, DATA) -> Union[bool, list]:
+def add_channel(server: 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.
@@ -65,7 +66,7 @@ def add_channel(server, DATA) -> Union[bool, list]:
     else: 
         raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 
-def del_channel(server, channel) -> bool:
+def del_channel(server: server, channel) -> bool:
     '''Delete a "channel" object in Kepware. This will delete all children as well
     
     INPUTS:
@@ -86,7 +87,7 @@ def del_channel(server, channel) -> bool:
     else: 
         raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 
-def modify_channel(server, DATA, channel = None, force = False) -> bool:
+def modify_channel(server: server, DATA, channel = None, force = False) -> bool:
     '''Modify a channel object and it's properties in Kepware. If a "channel" is not provided as an input,
     you need to identify the channel in the 'common.ALLTYPES_NAME' property field in the "DATA". It will 
     assume that is the channel that is to be modified.
@@ -125,7 +126,7 @@ def modify_channel(server, DATA, channel = None, force = False) -> bool:
         else: 
             raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 
-def get_channel(server, channel)  -> dict:
+def get_channel(server: server, channel)  -> dict:
     '''Returns the properties of the channel object. Returned object is JSON.
     
     INPUTS:
@@ -144,24 +145,30 @@ def get_channel(server, channel)  -> dict:
     r = server._config_get(server.url + _create_url(channel))
     return r.payload
 
-def get_all_channels(server) -> list:
+def get_all_channels(server: server, *, options: dict = None) -> list:
     '''Returns list of all channel objects and their properties. Returned object is JSON list.
     
     INPUTS:
-    "server" - instance of the "server" class
+    
+    server - instance of the "server" class
+    
+    options - (optional) Dict of parameters to filter, sort or pagenate the list of channels. Options are 'filter', 
+    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'
     
     RETURNS:
     list - data for the channel requested
 
     EXCEPTIONS:
+
     KepHTTPError - If urllib provides an HTTPError
+
     KepURLError - If urllib provides an URLError
     '''
 
-    r = server._config_get(server.url + _create_url())
+    r = server._config_get(server.url + _create_url(), params= options)
     return r.payload
 
-def get_channel_structure(server, channel) -> dict:
+def get_channel_structure(server: server, channel) -> dict:
     '''Returns the properties of "channel" and includes all "devices" and the "tag" and "tag group" objects for a 
     channel in Kepware. Returned object is a dict of channel properties including a device list with 
     tag lists and tag group lists.

kepconfig/connectivity/device.py

@@ -9,7 +9,7 @@
 device objects within the Kepware Configuration API
 """
 
-from ..connection import KepServiceResponse
+from ..connection import KepServiceResponse, server
 from ..error import KepHTTPError, KepError
 from typing import Union
 import kepconfig
@@ -30,17 +30,17 @@ def _create_url(device = None):
     else:
         return '{}/{}'.format(DEVICE_ROOT,device)
 
-def add_device(server, dev_channel, DATA) -> Union[bool, list]:
+def add_device(server, channel_name, 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.
 
-    Additionally it can be used to pass a list of channelsdevices and it's children to be added all at once.
+    Additionally it can be used to pass a list of devices and it's children to be added all at once.
 
     INPUTS:
     "server" - instance of the "server" class
 
-    "dev_channel" - channel the device object exists
+    "channel_name" - channel the device object exists
 
     "DATA" - properly JSON object (dict) of the device and it's children 
     expected by Kepware Configuration API
@@ -56,7 +56,7 @@ def add_device(server, dev_channel, DATA) -> Union[bool, list]:
     KepURLError - If urllib provides an URLError
     '''
 
-    r = server._config_add(server.url + channel._create_url(dev_channel) + _create_url(), DATA)
+    r = server._config_add(server.url + channel._create_url(channel_name) + _create_url(), DATA)
     if r.code == 201: return True
     elif r.code == 207:
         errors = [] 
@@ -155,11 +155,14 @@ def get_device(server, device_path) -> dict:
     #     print('Error: Error with {}: {}'.format(inspect.currentframe().f_code.co_name, str(err)))
     #     raise err
 
-def get_all_devices(server, dev_channel) -> list:
+def get_all_devices(server: server, channel_name: str, *, options: dict = None) -> list:
     '''Returns list of all device objects and their properties within a channel. Returned object is JSON list.
     
     INPUTS:
-    "dev_channel" - channel the device object exists
+    channel_name - channel the device object exists
+
+    options - (optional) Dict of parameters to filter, sort or pagenate the list of devices. Options are 'filter', 
+    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'
 
     RETURNS:
     list - data for the devices requested
@@ -168,7 +171,7 @@ def get_all_devices(server, dev_channel) -> list:
     KepHTTPError - If urllib provides an HTTPError
     KepURLError - If urllib provides an URLError
     '''
-    r = server._config_get(server.url + channel._create_url(dev_channel) + _create_url())
+    r = server._config_get(f'{server.url}{channel._create_url(channel_name)}{_create_url()}', params= options)
     return r.payload
 
 def auto_tag_gen(server, device_path, job_ttl = None) -> KepServiceResponse: