kepconfig.connectivity.egd.name

  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
  8r"""`names` exposes an API to allow modifications (add, delete, modify) to 
  9name resolution objects for EGD devices within the Kepware Configuration API
 10"""
 11
 12from ...utils import _url_parse_object, path_split
 13from ...connection import server
 14from ...error import KepHTTPError, KepError
 15from typing import Union
 16from .. import channel, device
 17
 18NAMES_ROOT = '/name_resolution_groups/Name Resolutions/name_resolutions'
 19
 20def _create_url(device_path, name = None):
 21    '''Creates url object for the "name resolution" branch of Kepware's project 
 22    tree. Used to build a part of Kepware Configuration API URL structure
 23
 24    Returns the name resolution specific url when a value is passed.
 25    '''
 26    path_obj = path_split(device_path)
 27    device_root = channel._create_url(path_obj['channel']) + device._create_url(path_obj['device'])
 28
 29    if name == None:
 30        return '{}/{}'.format(device_root, NAMES_ROOT)
 31    else:
 32        return '{}/{}/{}'.format(device_root, NAMES_ROOT, _url_parse_object(name))
 33
 34def add_name_resolution(server: server, device_path: str, DATA: Union[dict, list]) -> Union[bool, list]:
 35    '''Add a `"name resolution"` or multiple `"name resolution"` objects to Kepware. This allows you to 
 36    create a name resolution or multiple name resolutions all in one function, if desired.
 37
 38    :param server: instance of the `server` class
 39    :param device_path: path to EGD device. Standard Kepware address decimal 
 40    notation string such as `"channel1.device1"`
 41    :param DATA: Dict or List of Dicts of name resolutions
 42    expected by Kepware Configuration API
 43
 44    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 45    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 46    name resolutions added that failed.
 47
 48    :raises KepHTTPError: If urllib provides an HTTPError
 49    :raises KepURLError: If urllib provides an URLError
 50    '''
 51
 52    r = server._config_add(server.url + _create_url(device_path), DATA)
 53    if r.code == 201: 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 del_name_resolution(server: server, device_path: str, name: str) -> bool:
 64    '''Delete a `"name resolution"` object in Kepware.
 65    
 66    :param server: instance of the `server` class
 67    :param device_path: path to EGD device. Standard Kepware address decimal 
 68    notation string such as `"channel1.device1"`
 69    :param name: name of name resolution to delete
 70    
 71    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 72
 73    :raises KepHTTPError: If urllib provides an HTTPError
 74    :raises KepURLError: If urllib provides an URLError
 75    '''
 76
 77    r = server._config_del(server.url + _create_url(device_path, name))
 78    if r.code == 200: return True 
 79    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 80
 81def modify_name_resolution(server: server, device_path: str, DATA: dict, *, name: str = None, force: bool = False) -> bool:
 82    '''Modify a `"name resolution"` object and it's properties in Kepware. If a `"name"` is not provided as an input,
 83    you need to identify the name resolution in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 84    assume that is the name resolution that is to be modified.
 85
 86    :param server: instance of the `server` class
 87    :param device_path: path to EGD device. Standard Kepware address decimal 
 88    notation string such as `"channel1.device1"`
 89    :param DATA: Dict of name resolution properties to be modified
 90    :param name: *(optional)* name of name resolution to modify. Only needed if not existing in `"DATA"`
 91    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 92    
 93    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 94
 95    :raises KepHTTPError: If urllib provides an HTTPError
 96    :raises KepURLError: If urllib provides an URLError
 97    '''
 98    
 99    name_data = server._force_update_check(force, DATA)
100    if name == None:
101        try:
102            r = server._config_update(server.url + _create_url(device_path, name_data['common.ALLTYPES_NAME']), name_data)
103            if r.code == 200: return True 
104            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
105        except KeyError as err:
106            err_msg = f'Error: No name resolution identified in DATA | Key Error: {type(DATA)}'
107            raise KepError(err_msg) 
108    else:
109        r = server._config_update(server.url + _create_url(device_path, name), name_data)
110        if r.code == 200: return True 
111        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
112
113def get_name_resolution(server: server, device_path: str, name: str = None, *, options: dict = None) -> Union[dict, list]:
114    '''Returns the properties of the `"name resolution"` object or a list of all name resolutions.
115    
116    :param server: instance of the `server` class
117    :param device_path: path to EGD device. Standard Kepware address decimal 
118    notation string such as `"channel1.device1"`
119    :param DATA: Dict of name resolution properties to be modified
120    :param name: *(optional)* name of name resolution to retrieve. If not defined, will get all name resolutions
121    :param options: *(optional)* Dict of parameters to filter, sort or pagenate when getting a list of profiles. Options are `filter`, 
122        `sortOrder`, `sortProperty`, `pageNumber`, and `pageSize`. Only used when `"name"` is not defined.
123    
124    :return: Dict of the name resolution properties or List of Dicts for all name resolutions and their properties 
125    
126    :raises KepHTTPError: If urllib provides an HTTPError
127    :raises KepURLError: If urllib provides an URLError
128    '''
129
130    if name == None:
131        r = server._config_get(f'{server.url}{_create_url(device_path)}', params= options)
132    else:
133        r = server._config_get(f'{server.url}{_create_url(device_path, name)}')
134    return r.payload