kepconfig.datalogger.log_items

  1# -------------------------------------------------------------------------
  2# Copyright (c) PTC Inc. and/or all its affiliates. All rights reserved.
  3# See License.txt in the project root for
  4# license information.
  5# --------------------------------------------------------------------------
  6
  7r"""`log_items` exposes an API to allow modifications (add, delete, modify) to 
  8log item (tag) objects in a Datalogger log group within the Kepware Configuration API
  9"""
 10from typing import Union
 11from . import log_group as Log_Group
 12from ..error import KepError, KepHTTPError
 13from ..connection import server
 14from ..utils import _url_parse_object
 15
 16LOG_ITEMS_ROOT = '/log_items'
 17
 18def _create_url(log_item = None):
 19    '''Creates url object for the "log_item" branch of Kepware's project tree. Used 
 20    to build a part of Kepware Configuration API URL structure
 21
 22    Returns the log_item specific url when a value is passed as the log_item name.
 23    '''
 24
 25    if log_item == None:
 26        return '{}'.format(LOG_ITEMS_ROOT)
 27    else:
 28        return '{}/{}'.format(LOG_ITEMS_ROOT, _url_parse_object(log_item))
 29
 30
 31def add_log_item(server: server, log_group: str, DATA: Union[dict, list]) -> Union[bool, list]:
 32    '''Add a `"log item"` or multiple `"log item"` objects to a log group in Kepware's Datalogger. It can 
 33    be used to pass a list of log items to be added all at once.
 34
 35    :param server: instance of the `server` class
 36    :param log_group: name of log group that the log items will be added
 37    :param DATA: Dict or a list of the log items to add through Kepware Configuration API
 38
 39    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 40    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 41    log items added that failed.
 42
 43    :raises KepHTTPError: If urllib provides an HTTPError
 44    :raises KepURLError: If urllib provides an URLError
 45    '''
 46
 47    r = server._config_add(server.url + Log_Group._create_url(log_group) + _create_url(), DATA)
 48    if r.code == 201: return True
 49    elif r.code == 207:
 50        errors = [] 
 51        for item in r.payload:
 52            if item['code'] != 201:
 53                errors.append(item)
 54        return errors 
 55    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 56
 57def del_log_item(server: server, log_group: str, log_item: str) -> bool:
 58    '''Delete a `"log item"` object of a log group in Kepware's Datalogger.
 59    
 60    :param server: instance of the `server` class
 61    :param log_group: name of log group that log item exists
 62    :param log_item: name of log item to delete
 63
 64    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 65
 66    :raises KepHTTPError: If urllib provides an HTTPError
 67    :raises KepURLError: If urllib provides an URLError
 68    '''
 69    r = server._config_del(server.url + Log_Group._create_url(log_group) + _create_url(log_item))
 70    if r.code == 200: return True 
 71    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 72
 73def modify_log_item(server: server, log_group: str, DATA: dict, *, log_item: str = None, force: bool = False) -> bool:
 74    '''Modify a `"log_item"` object and it's properties in Kepware. If a `"log_item"` is not provided as an input,
 75    you need to identify the log_item in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 76    assume that is the log_item that is to be modified.
 77
 78    :param server: instance of the `server` class
 79    :param log_group: name of log group that log item exists
 80    :param DATA: Dict of the log item properties to be modified.
 81    :param log_item: *(optional)* name of log item to modify. Only needed if not existing in `"DATA"`
 82    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 83
 84    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 85
 86    :raises KepHTTPError: If urllib provides an HTTPError
 87    :raises KepURLError: If urllib provides an URLError
 88    '''
 89    
 90    log_item_data = server._force_update_check(force, DATA)
 91    
 92    if log_item == None:
 93        try:
 94            r = server._config_update(server.url + Log_Group._create_url(log_group) + _create_url(log_item_data['common.ALLTYPES_NAME']), log_item_data)
 95            if r.code == 200: return True 
 96            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 97        except KeyError as err:
 98            err_msg ='Error: No log item identified in DATA | Key Error: {}'.format(err)
 99            raise KepError(err_msg)
100    else:
101        r = server._config_update(server.url + Log_Group._create_url(log_group) + _create_url(log_item), log_item_data)
102        if r.code == 200: return True 
103        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
104
105def get_log_item(server, log_group, log_item) -> dict:
106    '''Returns the properties of the `"log item"` object.
107    
108    :param server: instance of the `server` class
109    :param log_group: name of log group that log item exists
110    :param log_item: name of log item to retrieve
111
112    :return: Dict of properties for the log group requested
113
114    :raises KepHTTPError: If urllib provides an HTTPError
115    :raises KepURLError: If urllib provides an URLError
116    '''
117    r = server._config_get(server.url + Log_Group._create_url(log_group) + _create_url(log_item))
118    return r.payload
119
120def get_all_log_items(server: server, log_group: str, *, options: dict = None) -> list:
121    '''Returns the properties of all `"log item"` objects for a log group.
122    
123    :param server: instance of the `server` class
124    :param log_group: name of log group that log item exists
125    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of log groups. Options are 'filter', 
126    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'. Only used when exchange_name is not defined.
127
128    :return: list of properties for all log items in the log group requested
129
130    :raises KepHTTPError: If urllib provides an HTTPError
131    :raises KepURLError: If urllib provides an URLError
132    '''
133    r = server._config_get(f'{server.url}{Log_Group._create_url(log_group)}{_create_url()}', params= options)
134    return r.payload