kepconfig.adv_tags.link_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"""`link_tags` exposes an API to allow modifications (add, delete, modify) to 
 11link 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
 20LINK_TAGS_ROOT = '/link_tags'
 21
 22def _get_link_tags_url(tag: str = None) -> str:
 23    '''Creates url object for the "link_tags" branch of Kepware's project tree.
 24    
 25    Returns the link tag specific url when a value is passed as the tag name.
 26    '''
 27    if tag is None:
 28        return LINK_TAGS_ROOT
 29    else:
 30        return f'{LINK_TAGS_ROOT}/{_url_parse_object(tag)}'
 31
 32def add_link_tag(server: server, adv_tag_group_path: str, DATA: Union[dict, list]) -> Union[bool, list]:
 33    '''Add `"link_tag"` or multiple `"link_tag"` objects to a specific path in Kepware.
 34    Can be used to pass a list of link 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 link 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 link 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    link 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_link_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_link_tag(server: server, link_tag_path: str, DATA: dict, force: bool = False) -> bool:
 61    '''Modify a `"link_tag"` object and its properties in Kepware.
 62
 63    :param server: instance of the `server` class
 64    :param link_tag_path: path identifying location and link tag to modify. Standard Kepware address decimal 
 65    notation string including the link tag such as "_advancedtags.AdvTagGroup1.LinkTag1"
 66    :param DATA: Dict of the `link_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    link_tag_data = server._force_update_check(force, DATA)
 75    path_obj = adv_tags._adv_tag_path_split(link_tag_path, isItem=True)
 76    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_link_tags_url(path_obj['item'])
 77
 78    r = server._config_update(url, link_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_link_tag(server: server, link_tag_path: str) -> bool:
 85    '''Delete `"link_tag"` object at a specific path in Kepware.
 86
 87    :param server: instance of the `server` class
 88    :param link_tag_path: path identifying location and link tag to delete. Standard Kepware address decimal 
 89    notation string including the link tag such as "_advancedtags.AdvTagGroup1.LinkTag1"
 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(link_tag_path, isItem=True)
 97    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_link_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_link_tag(server: server, link_tag_path: str) -> dict:
106    '''Returns the properties of the `"link_tag"` object at a specific path in Kepware.
107
108    :param server: instance of the `server` class
109    :param link_tag_path: path identifying location and link tag to retrieve. Standard Kepware address decimal 
110    notation string including the link tag such as "_advancedtags.AdvTagGroup1.LinkTag1"
111
112    :return: Dict of data for the link 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(link_tag_path, isItem=True)
118    url = adv_tags._create_adv_tags_base_url(server.url, path_obj) + _get_link_tags_url(path_obj['item'])
119
120    r = server._config_get(url)
121    return r.payload
122
123def get_all_link_tags(server: server, adv_tag_group_path: str, *, options: dict = None) -> list:
124    '''Returns the properties of all `"link_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 link 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 link tags. Options are `filter`,
130        `sortOrder`, `sortProperty`, `pageNumber`, and `pageSize`
131
132    :return: List of data for all link 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_link_tags_url()
139
140    r = server._config_get(url, params=options)
141    return r.payload