kepconfig.adv_tags.cumulative_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"""`cumulative_tags` exposes an API to allow modifications (add, delete, modify) to 
 11cumulative 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
 20CUMULATIVE_TAGS_ROOT = '/cumulative_tags'
 21
 22def _get_cumulative_tags_url(tag: str = None) -> str:
 23    '''Creates url object for the "cumulative_tags" branch of Kepware's project tree.
 24    
 25    Returns the cumulative tag specific url when a value is passed as the tag name.
 26    '''
 27    if tag is None:
 28        return CUMULATIVE_TAGS_ROOT
 29    else:
 30        return f'{CUMULATIVE_TAGS_ROOT}/{_url_parse_object(tag)}'
 31
 32def add_cumulative_tag(server: server, adv_tag_group_path: str, DATA: Union[dict, list]) -> Union[bool, list]:
 33    '''Add `"cumulative_tag"` or multiple `"cumulative_tag"` objects to a specific path in Kepware.
 34    Can be used to pass a list of cumulative 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 cumulative 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 cumulative 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    cumulative 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_cumulative_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 = [item for item in r.payload if item['code'] != 201]
 56        return errors
 57    else:
 58        raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 59
 60def modify_cumulative_tag(server: server, cumulative_tag_path: str, DATA: dict, force: bool = False) -> bool:
 61    '''Modify a `"cumulative_tag"` object and its properties in Kepware.
 62
 63    :param server: instance of the `server` class
 64    :param cumulative_tag_path: path identifying location and cumulative tag to modify. Standard Kepware address decimal 
 65    notation string including the cumulative tag such as "_advancedtags.AdvTagGroup1.CumulativeTag1"
 66    :param DATA: Dict of the `cumulative_tag` properties to be modified
 67    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 68
 69    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 70
 71    :raises KepHTTPError: If urllib provides an HTTPError
 72    :raises KepURLError: If urllib provides an URLError
 73    '''
 74    cum_tag_data = server._force_update_check(force, DATA)
 75    path_obj = adv_tags._adv_tag_path_split(cumulative_tag_path, isItem=True)
 76    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_cumulative_tags_url(path_obj['item'])
 77
 78    r = server._config_update(url, cum_tag_data)
 79    if r.code == 200:
 80        return True
 81    else:
 82        raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 83
 84def del_cumulative_tag(server: server, cumulative_tag_path: str) -> bool:
 85    '''Delete `"cumulative_tag"` object at a specific path in Kepware.
 86
 87    :param server: instance of the `server` class
 88    :param cumulative_tag_path: path identifying location and cumulative tag to delete. Standard Kepware address decimal 
 89    notation string including the cumulative tag such as "_advancedtags.AdvTagGroup1.CumulativeTag1"
 90
 91    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 92
 93    :raises KepHTTPError: If urllib provides an HTTPError
 94    :raises KepURLError: If urllib provides an URLError
 95    '''
 96    path_obj = adv_tags._adv_tag_path_split(cumulative_tag_path, isItem=True)
 97    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_cumulative_tags_url(path_obj['item'])
 98
 99    r = server._config_del(url)
100    if r.code == 200:
101        return True
102    else:
103        raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
104
105def get_cumulative_tag(server: server, cumulative_tag_path: str) -> dict:
106    '''Returns the properties of the `"cumulative_tag"` object at a specific path in Kepware.
107
108    :param server: instance of the `server` class
109    :param cumulative_tag_path: path identifying location and cumulative tag to retrieve. Standard Kepware address decimal 
110    notation string including the cumulative tag such as "_advancedtags.AdvTagGroup1.CumulativeTag1"
111
112    :return: Dict of data for the cumulative tag requested
113
114    :raises KepHTTPError: If urllib provides an HTTPError
115    :raises KepURLError: If urllib provides an URLError
116    '''
117    path_obj = adv_tags._adv_tag_path_split(cumulative_tag_path, isItem=True)
118    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_cumulative_tags_url(path_obj['item'])
119
120    r = server._config_get(url)
121    return r.payload
122
123def get_all_cumulative_tags(server: server, adv_tag_group_path: str, *, options: dict = None) -> list:
124    '''Returns the properties of all `"cumulative_tag"` objects at a specific path in Kepware.
125
126    :param server: instance of the `server` class
127    :param adv_tag_group_path: path identifying location to retrieve cumulative tag list. Standard Kepware address decimal
128    notation string such as "_advancedtags.AdvTagGroup1" or "_advancedtags.AdvTagGroup1.AdvTagGroupChild"
129    :param options: *(optional)* Dict of parameters to filter, sort or paginate the list of cumulative tags. Options are `filter`,
130        `sortOrder`, `sortProperty`, `pageNumber`, and `pageSize`
131
132    :return: List of data for all cumulative tags
133
134    :raises KepHTTPError: If urllib provides an HTTPError
135    :raises KepURLError: If urllib provides an URLError
136    '''
137    path_obj = adv_tags._adv_tag_path_split(adv_tag_group_path, isItem=False)
138    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_cumulative_tags_url()
139
140    r = server._config_get(url, params=options)
141    return r.payload