kepconfig.admin.users

  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
  7r"""`users` exposes an API to allow modifications (add, delete, modify) to 
  8users within the Kepware Administration User Management through the Kepware Configuration API
  9"""
 10from typing import Union
 11from ..error import KepError, KepHTTPError
 12from ..connection import server
 13from ..utils import _url_parse_object
 14
 15
 16USERS_ROOT = '/admin/server_users'
 17ENABLE_PROPERTY = 'libadminsettings.USERMANAGER_USER_ENABLED'
 18
 19def _create_url(user = None):
 20    '''Creates url object for the "server_users" branch of Kepware's project tree. Used 
 21    to build a part of Kepware Configuration API URL structure
 22
 23    Returns the user specific url when a value is passed as the user name.
 24    '''
 25    
 26    if user == None:
 27        return USERS_ROOT
 28    else:
 29        return '{}/{}'.format(USERS_ROOT, _url_parse_object(user))
 30
 31def add_user(server: server, DATA: Union[dict, list]) -> Union[bool, list]:
 32    '''Add a `"user"` or multiple `"user"` objects to Kepware User Manager by passing a 
 33    list of users to be added all at once.
 34
 35    :param server: instance of the `server` class
 36    :param DATA: Dict or List of Dicts of the users to add
 37
 38    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 39    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 40    endpoints added that failed.
 41
 42    :raises KepHTTPError: If urllib provides an HTTPError
 43    :raises KepURLError: If urllib provides an URLError
 44    '''
 45
 46    r = server._config_add(server.url + _create_url(), DATA)
 47    if r.code == 201: return True 
 48    elif r.code == 207:
 49        errors = [] 
 50        for item in r.payload:
 51            if item['code'] != 201:
 52                errors.append(item)
 53        return errors
 54    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 55
 56def del_user(server: server, user: str) -> bool:
 57    '''Delete a `"user"` object in Kepware User Manager
 58    
 59    :param server: instance of the `server` class
 60    :param user: name of user to delete
 61    
 62    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 63
 64    :raises KepHTTPError: If urllib provides an HTTPError
 65    :raises KepURLError: If urllib provides an URLError
 66    '''
 67
 68    r = server._config_del(server.url + _create_url(user))
 69    if r.code == 200: return True 
 70    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 71
 72def modify_user(server: server , DATA: dict, *, user: str = None) -> bool:
 73    '''Modify a `"user object"` and it's properties in Kepware User Manager. If a `"user"` is not provided as an input,
 74    you need to identify the user in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 75    assume that is the user that is to be modified.
 76
 77    :param server: instance of the `server` class
 78    :param DATA: Dict of the user properties to be modified.
 79    :param user: *(optional)* name of user to modify. Only needed if not existing in `"DATA"`
 80    
 81    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 82
 83    :raises KepHTTPError: If urllib provides an HTTPError
 84    :raises KepURLError: If urllib provides an URLError
 85    '''
 86
 87    if user == None:
 88        try:
 89            r = server._config_update(server.url + _create_url(DATA['common.ALLTYPES_NAME']), DATA)
 90            if r.code == 200: return True 
 91            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 92        except KeyError as err:
 93            err_msg = 'Error: No User identified in DATA | Key Error: {}'.format(err)
 94            raise KepError(err_msg)
 95    else:
 96        r = server._config_update(server.url + _create_url(user), DATA)
 97        if r.code == 200: return True 
 98        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 99
100def get_user(server: server, user: str) -> dict:
101    '''Returns the properties of the `"user"` object.
102    
103    :param server: instance of the `server` class
104    :param user: name of user to retrieve
105    
106    :return: Dict of properties for the user requested
107
108    :raises KepHTTPError: If urllib provides an HTTPError
109    :raises KepURLError: If urllib provides an URLError
110    '''
111
112    r = server._config_get(server.url + _create_url(user))
113    return r.payload
114
115def get_all_users(server: server, *, options: dict = None) -> list:
116    '''Returns list of all `"user"` objects and their properties.
117    
118    :param server: instance of the `server` class
119    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of users. Options are 'filter', 
120    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize.
121
122    :return: List of properties for all users
123
124    :raises KepHTTPError: If urllib provides an HTTPError
125    :raises KepURLError: If urllib provides an URLError
126    '''
127
128    r = server._config_get(f'{server.url}{_create_url()}', params= options)
129    return r.payload
130
131def enable_user(server: server, user: str) -> bool:
132    '''Enable the `"user"`.
133    
134    :param server: instance of the `server` class
135    :param user: name of user
136
137    :return: True - If a "HTTP 200 - OK" is received from Kepware server
138
139    :raises KepHTTPError: If urllib provides an HTTPError
140    :raises KepURLError: If urllib provides an URLError
141    '''
142    DATA = {ENABLE_PROPERTY: True}
143    return modify_user(server, DATA, user= user)
144
145def disable_user(server: server, user: str) -> bool:
146    '''Disable the `"user"`.
147    
148    :param server: instance of the `server` class
149    :param user: name of user
150
151    :return: True - If a "HTTP 200 - OK" is received from Kepware server
152
153    :raises KepHTTPError: If urllib provides an HTTPError
154    :raises KepURLError: If urllib provides an URLError
155    '''
156    DATA = {ENABLE_PROPERTY: False}
157    return modify_user(server, DATA, user= user)