kepconfig.connectivity.udd.profile

  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"""`profile` exposes an API to allow modifications (add, delete, modify) to 
  9profile objects for the UDD Profile Library plug-in within the Kepware Configuration API
 10"""
 11
 12from ...connection import server
 13from ...error import KepHTTPError, KepError
 14from typing import Union
 15
 16PROFILE_ROOT = '/project/_profile_library/profiles'
 17
 18def add_profile(server: server, DATA: Union[dict, list]) -> Union[bool, list]:
 19    '''Add a `"profile"` or a list of `"profile"` objects to the UDD Profile Library plug-in for Kepware. 
 20
 21    :param server: instance of the `server` class
 22    :param DATA: Dict or List of Dicts of the profiles to add to the Profile Library 
 23    through Kepware Configuration API
 24
 25    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 26    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 27    profiles added that failed.
 28
 29    :raises KepHTTPError: If urllib provides an HTTPError
 30    :raises KepURLError: If urllib provides an URLError
 31    '''
 32
 33    r = server._config_add(f'{server.url}{PROFILE_ROOT}', DATA)
 34    if r.code == 201: return True
 35    elif r.code == 207:
 36        errors = [] 
 37        for item in r.payload:
 38            if item['code'] != 201:
 39                errors.append(item)
 40        return errors
 41    else: 
 42        raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 43
 44def del_profile(server: server, profile_name: str) -> bool:
 45    '''Delete a `"profile"` object in UDD Profile Library plug-in for Kepware.
 46    
 47    :param server: instance of the `server` class
 48    :param profile_name: name of profile
 49    
 50    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 51
 52    :raises KepHTTPError: If urllib provides an HTTPError
 53    :raises KepURLError: If urllib provides an URLError
 54    '''
 55
 56    r = server._config_del(f'{server.url}{PROFILE_ROOT}/{profile_name}')
 57    if r.code == 200: return True 
 58    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 59
 60def modify_profile(server: server, DATA: dict, profile_name: str = None, force: bool = False) -> bool:
 61    '''Modify a `"profile"` object and it's properties in Kepware. If a `"profile_name"` is not provided as an input,
 62    you need to identify the profile in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 63    assume that is the profile that is to be modified.
 64
 65    :param server: instance of the `server` class
 66    :param DATA: Dict or List of Dicts of the profile properties to be modified.
 67    :param profile_name: *(optional)* name of profile to modify. Only needed if not existing in `"DATA"`
 68    :param force: *(optional)* if True, will force the configuration update to the Kepware server
 69    
 70    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 71
 72    :raises KepHTTPError: If urllib provides an HTTPError
 73    :raises KepURLError: If urllib provides an URLError
 74    '''
 75    
 76    profile_data = server._force_update_check(force, DATA)
 77    if profile_name == None:
 78        try:
 79            r = server._config_update(f"{server.url}{PROFILE_ROOT}/{profile_data['common.ALLTYPES_NAME']}", profile_data)
 80            if r.code == 200: return True 
 81            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 82        except KeyError as err:
 83            err_msg = 'Error: No profile identified in DATA | Key Error: {}'.format(err)
 84            raise KepError(err_msg)
 85    else:
 86        r = server._config_update(f'{server.url}{PROFILE_ROOT}/{profile_name}', profile_data)
 87        if r.code == 200: return True 
 88        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 89
 90def get_profile(server: server, profile_name: str = None, *, options: dict = None) -> Union[dict, list]:
 91    '''Returns the properties of the profile object or a list of all profiles and their 
 92    properties. Will return a list if `"profile_name"` is not provided.
 93    
 94    INPUTS:
 95
 96    :param server: instance of the `server` class
 97    :param profile_name: *(optional)* name of profile. If not defined, will get all profiles
 98    :param options: *(optional)* Dict of parameters to filter, sort or pagenate when getting a list of profiles. Options are `filter`, 
 99        `sortOrder`, `sortProperty`, `pageNumber`, and `pageSize`. Only used when profile_name is not defined.
100    
101    :return: Dict of the profile properties or List of Dicts for all profiles and their properties in the Profile Library
102
103    :raises KepHTTPError: If urllib provides an HTTPError
104    :raises KepURLError: If urllib provides an URLError
105    '''
106
107    if profile_name == None:
108        r = server._config_get(f'{server.url}{PROFILE_ROOT}', params= options)
109    else:
110        r = server._config_get(f'{server.url}{PROFILE_ROOT}/{profile_name}')
111    return r.payload
112
113def get_all_profiles(server: server, *, options: dict = None):
114    '''Returns list of all profile objects and their properties. Returned object is JSON list.
115    
116    :param server: instance of the `server` class
117    :param options: *(optional)* Dict of parameters to filter, sort or pagenate when getting a list of profiles. Options are `filter`, 
118        `sortOrder`, `sortProperty`, `pageNumber`, and `pageSize`. Only used when profile_name is not defined.
119    
120    :return: List of data for all profiles and their properties in the Profile Library
121
122    :raises KepHTTPError: If urllib provides an HTTPError
123    :raises KepURLError: If urllib provides an URLError
124    '''
125    return get_profile(server, options= options)