kepconfig.adv_tags.average_tags

  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
  7# Note: The code within this file was created in total or in part
  8#  with the use of AI tools.
  9
 10r"""`average_tags` exposes an API to allow modifications (add, delete, modify) to 
 11average tag objects within the Kepware Configuration API
 12"""
 13
 14from ..connection import server
 15from ..error import KepError, KepHTTPError
 16from ..utils import _url_parse_object
 17from typing import Union
 18from .. import adv_tags
 19
 20AVERAGE_TAGS_ROOT = '/average_tags'
 21
 22def _get_average_tags_url(tag: str = None) -> str:
 23    '''Creates url object for the "average_tags" branch of Kepware's project tree.
 24    
 25    Returns the average tag specific url when a value is passed as the tag name.
 26    '''
 27    if tag is None:
 28        return AVERAGE_TAGS_ROOT
 29    else:
 30        return f'{AVERAGE_TAGS_ROOT}/{_url_parse_object(tag)}'
 31
 32def add_average_tag(server: server, adv_tag_group_path: str, DATA: Union[dict, list]) -> Union[bool, list]:
 33    '''Add `"average_tag"` or multiple `"average_tag"` objects to a specific path in Kepware.
 34    Can be used to pass a list of average tags to be added at one path location.
 35
 36    :param server: instance of the `server` class
 37    :param adv_tag_group_path: path identifying where to add average tag(s). Standard Kepware address decimal 
 38    notation string such as "_advancedtags.AdvTagGroup1" or "_advancedtags.AdvTagGroup1.AdvTagGroupChild"
 39    :param DATA: Dict or List of Dicts of the average tag(s) to add
 40
 41    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 42    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 43    average tags added that failed.
 44
 45    :raises KepHTTPError: If urllib provides an HTTPError
 46    :raises KepURLError: If urllib provides an URLError
 47    '''
 48    path_obj = adv_tags._adv_tag_path_split(adv_tag_group_path, isItem=False)
 49    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_average_tags_url()
 50
 51    r = server._config_add(url, DATA)
 52    if r.code == 201:
 53        return True
 54    elif r.code == 207:
 55        errors = []
 56        for item in r.payload:
 57            if item['code'] != 201:
 58                errors.append(item)
 59        return errors
 60    else:
 61        raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 62
 63def modify_average_tag(server: server, avg_tag_path: str, DATA: dict, force: bool = False) -> bool:
 64    '''Modify an `"average_tag"` object and its properties in Kepware.
 65
 66    :param server: instance of the `server` class
 67    :param avg_tag_path: path identifying location and average tag to modify. Standard Kepware address decimal 
 68    notation string including the average tag such as "_advancedtags.AdvTagGroup1.AvgTag1"
 69    :param DATA: Dict of the `average_tag` properties to be modified
 70    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 71
 72    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 73
 74    :raises KepHTTPError: If urllib provides an HTTPError
 75    :raises KepURLError: If urllib provides an URLError
 76    '''
 77    avg_tag_data = server._force_update_check(force, DATA)
 78    path_obj = adv_tags._adv_tag_path_split(avg_tag_path, isItem=True)
 79    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_average_tags_url(path_obj['item'])
 80
 81    r = server._config_update(url, avg_tag_data)
 82    if r.code == 200:
 83        return True
 84    else:
 85        raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 86
 87def del_average_tag(server: server, avg_tag_path: str) -> bool:
 88    '''Delete `"average_tag"` object at a specific path in Kepware.
 89
 90    :param server: instance of the `server` class
 91    :param avg_tag_path: path identifying location and average tag to delete. Standard Kepware address decimal 
 92    notation string including the average tag such as "_advancedtags.AdvTagGroup1.AvgTag1"
 93
 94    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 95
 96    :raises KepHTTPError: If urllib provides an HTTPError
 97    :raises KepURLError: If urllib provides an URLError
 98    '''
 99    path_obj = adv_tags._adv_tag_path_split(avg_tag_path, isItem=True)
100    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_average_tags_url(path_obj['item'])
101
102    r = server._config_del(url)
103    if r.code == 200:
104        return True
105    else:
106        raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
107
108def get_average_tag(server: server, avg_tag_path: str) -> dict:
109    '''Returns the properties of the `"average_tag"` object at a specific path in Kepware.
110
111    :param server: instance of the `server` class
112    :param avg_tag_path: path identifying location and average tag to retrieve. Standard Kepware address decimal 
113    notation string including the average tag such as "_advancedtags.AdvTagGroup1.AvgTag1"
114
115    :return: Dict of data for the average tag requested
116
117    :raises KepHTTPError: If urllib provides an HTTPError
118    :raises KepURLError: If urllib provides an URLError
119    '''
120    path_obj = adv_tags._adv_tag_path_split(avg_tag_path, isItem=True)
121    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_average_tags_url(path_obj['item'])
122
123    r = server._config_get(url)
124    return r.payload
125
126def get_all_average_tags(server: server, adv_tag_group_path: str, *, options: dict = None) -> list:
127    '''Returns the properties of all `"average_tag"` objects at a specific path in Kepware.
128
129    :param server: instance of the `server` class
130    :param adv_tag_group_path: path identifying location to retrieve average tag list. Standard Kepware address decimal
131    notation string such as "_advancedtags.AdvTagGroup1" or "_advancedtags.AdvTagGroup1.AdvTagGroupChild"
132    :param options: *(optional)* Dict of parameters to filter, sort or paginate the list of average tags. Options are `filter`,
133        `sortOrder`, `sortProperty`, `pageNumber`, and `pageSize`
134
135    :return: List of data for all average tags
136
137    :raises KepHTTPError: If urllib provides an HTTPError
138    :raises KepURLError: If urllib provides an URLError
139    '''
140    path_obj = adv_tags._adv_tag_path_split(adv_tag_group_path, isItem=False)
141    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_average_tags_url()
142
143    r = server._config_get(url, params=options)
144    return r.payload