Skip to content

Commit 6f82400

Browse files
rlabbeptcrlabbeptc
committed
Docstring, Type hinting and optional arg update
1 parent 6d46c1c commit 6f82400

24 files changed

Lines changed: 1060 additions & 1595 deletions

‎kepconfig/admin/__init__.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,8 @@
44
# license information.
55
# --------------------------------------------------------------------------
66

7-
# __path__ = __import__("pkgutil").extend_path(__path__, __name__)
7+
r"""`admin` module provides functionality to manage Kepware Administration based
8+
properties available through the Kepware Configuration API
9+
"""
10+
811
from . import users, user_groups,ua_server, lls

‎kepconfig/admin/lls.py‎

Lines changed: 34 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
from .. import connection
1111
from typing import Union
1212
from ..error import KepHTTPError, KepError
13-
import inspect
13+
1414

1515

1616
LLS_ROOT = '/admin'
@@ -28,15 +28,13 @@ class lls_config:
2828
'''A class to represent a admin properties for the Local License Server connection from an instance of Kepware.
2929
This object is used to easily manage the LLS parameters for a Kepware instance.
3030
31-
Properties:
32-
33-
"server_name" - Host name or IP address of the LLS server
34-
"server_port" - HTTP/non-SSL port to target for the LLS server
35-
"check_period" - Period that Kepware checks licensing status
36-
"server_port_SSL" - HTTPS/SSL port to target for the LLS server
37-
"allow_insecure_comms" - When True, use HTTP/non-SSL connection to LLS
38-
"allow_self_signed_certs" - Allow for self signed certificates to be used during HTTPS/SSL connections to the LLS
39-
"instance_alias_name" - Alias name for LLS to use as reference to this Kepware instance
31+
:param server_name: Host name or IP address of the LLS server
32+
:param server_port: HTTP/non-SSL port to target for the LLS server
33+
:param check_period: Period that Kepware checks licensing status
34+
:param server_port_SSL: HTTPS/SSL port to target for the LLS server
35+
:param allow_insecure_comms: When True, use HTTP/non-SSL connection to LLS
36+
:param allow_self_signed_certs: Allow for self signed certificates to be used during HTTPS/SSL connections to the LLS
37+
:param instance_alias_name: Alias name for LLS to use as reference to this Kepware instance
4038
'''
4139

4240
def __init__(self, config = {}):
@@ -63,35 +61,29 @@ def __str__(self) -> str:
6361
return "{}".format(self._get_dict())
6462

6563
def get_lls_config(server: connection.server) -> lls_config:
66-
'''Returns the properties of the Local License server properties. Returned object is lls_config class object.
64+
'''Returns the properties of the Local License server connection properties. Returned object is `lls_config` class object.
6765
68-
INPUTS:
69-
"server" - instance of the "server" class
66+
:param server: instance of the `server` class
7067
71-
RETURNS:
72-
lls_config - class object with lls configuration
68+
:return: `lls_config` class object with lls connection configuration
7369
74-
EXCEPTIONS:
75-
KepHTTPError - If urllib provides an HTTPError
76-
KepURLError - If urllib provides an URLError
70+
:raises KepHTTPError: If urllib provides an HTTPError
71+
:raises KepURLError: If urllib provides an URLError
7772
'''
7873

7974
r = server._config_get(server.url + LLS_ROOT)
8075
return lls_config(r.payload)
8176

8277
def update_lls_config(server: connection.server, config: lls_config) -> bool:
83-
'''Updates the Local License Server admin properties for Kepware.
78+
'''Updates the Local License Server connection properties for Kepware.
8479
85-
INPUTS:
86-
"server" - instance of the "server" class
87-
"config" - lls_config class object
80+
:param server: instance of the `server` class
81+
:param config: `lls_config` class object with lls connection configuration
8882
89-
RETURNS:
90-
True - If a "HTTP 200 - OK" is received from Kepware
83+
:return: True - If a "HTTP 200 - OK" is received from Kepware server
9184
92-
EXCEPTIONS:
93-
KepHTTPError - If urllib provides an HTTPError
94-
KepURLError - If urllib provides an URLError
85+
:raises KepHTTPError: If urllib provides an HTTPError
86+
:raises KepURLError: If urllib provides an URLError
9587
'''
9688

9789
DATA = config._get_dict()
@@ -102,15 +94,12 @@ def update_lls_config(server: connection.server, config: lls_config) -> bool:
10294
def enable_lls(server: connection.server) -> bool:
10395
'''Enables the Local License Server connection for Kepware.
10496
105-
INPUTS:
106-
"server" - instance of the "server" class
97+
:param server: instance of the `server` class
10798
108-
RETURNS:
109-
True - If a "HTTP 200 - OK" is received from Kepware
99+
:return: True - If a "HTTP 200 - OK" is received from Kepware server
110100
111-
EXCEPTIONS:
112-
KepHTTPError - If urllib provides an HTTPError
113-
KepURLError - If urllib provides an URLError
101+
:raises KepHTTPError: If urllib provides an HTTPError
102+
:raises KepURLError: If urllib provides an URLError
114103
'''
115104

116105
r = server._config_update(server.url + LLS_ROOT, {LICENSING_SERVER_ENABLE: True})
@@ -120,38 +109,30 @@ def enable_lls(server: connection.server) -> bool:
120109
def disable_lls(server: connection.server) -> bool:
121110
'''Disables the Local License Server connection for Kepware.
122111
123-
INPUTS:
124-
"server" - instance of the "server" class
112+
:param server: instance of the `server` class
125113
126-
RETURNS:
127-
True - If a "HTTP 200 - OK" is received from Kepware
114+
:return: True - If a "HTTP 200 - OK" is received from Kepware server
128115
129-
EXCEPTIONS:
130-
KepHTTPError - If urllib provides an HTTPError
131-
KepURLError - If urllib provides an URLError
116+
:raises KepHTTPError: If urllib provides an HTTPError
117+
:raises KepURLError: If urllib provides an URLError
132118
'''
133119

134120
r = server._config_update(server.url + LLS_ROOT, {LICENSING_SERVER_ENABLE: False})
135121
if r.code == 200: return True
136122
else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
137123

138124
def force_license_check(server: connection.server, job_ttl: int = None):
139-
'''Executes a ForceLicenseCheck call to the Kepware instance. This triggers the server to verify the
125+
'''Executes a ForceLicenseCheck service call to the Kepware instance. This triggers the server to verify the
140126
license state of the license received from the Local License Server.
141127
142-
INPUTS:
143-
"server" - instance of the "server" class
144-
145-
"job_ttl" (optional) - Determines the number of seconds a job instance will exist following completion.
128+
:param server: instance of the `server` class
129+
:param job_ttl: *(optional)* Determines the number of seconds a job instance will exist following completion.
146130
147-
RETURNS:
148-
KepServiceResponse instance with job information
131+
:return: `KepServiceResponse` instance with job information
149132
150-
EXCEPTIONS (If not HTTP 200 or 429 returned):
151-
152-
KepHTTPError - If urllib provides an HTTPError
153-
KepURLError - If urllib provides an URLError
154-
'''
133+
:raises KepHTTPError: If urllib provides an HTTPError (If not HTTP code 202 [Accepted] or 429 [Too Busy] returned)
134+
:raises KepURLError: If urllib provides an URLError
135+
'''
155136

156137
url = f'{server.url}{FORCE_CHECK_URL}'
157138
job = server._kep_service_execute(url, None, job_ttl)

‎kepconfig/admin/ua_server.py‎

Lines changed: 39 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -26,25 +26,19 @@ def _create_url(endpoint = None):
2626
else:
2727
return '{}/{}'.format(UA_ROOT,endpoint)
2828

29-
def add_endpoint(server, DATA) -> Union[bool, list]:
30-
'''Add an "endpoint" or multiple "endpoint" objects to Kepware UA Server by passing a
29+
def add_endpoint(server: server, DATA: dict | list) -> Union[bool, list]:
30+
'''Add an `"endpoint"` or multiple `"endpoint"` objects to Kepware UA Server by passing a
3131
list of endpoints to be added all at once.
3232
33-
INPUTS:
34-
"server" - instance of the "server" class
33+
:param server: instance of the `server` class
34+
:param DATA: Dict or List of Dicts of the UA Endpoints to add
3535
36-
"DATA" - properly JSON object (dict) of the endpoint
37-
expected by Kepware Configuration API
38-
39-
RETURNS:
40-
True - If a "HTTP 201 - Created" is received from Kepware
41-
42-
List - If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all
36+
:return: True - If a "HTTP 201 - Created" is received from Kepware server
37+
:return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all
4338
endpoints added that failed.
4439
45-
EXCEPTIONS:
46-
KepHTTPError - If urllib provides an HTTPError
47-
KepURLError - If urllib provides an URLError
40+
:raises KepHTTPError: If urllib provides an HTTPError
41+
:raises KepURLError: If urllib provides an URLError
4842
'''
4943

5044
r = server._config_add(server.url + _create_url(), DATA)
@@ -57,47 +51,37 @@ def add_endpoint(server, DATA) -> Union[bool, list]:
5751
return errors
5852
else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
5953

60-
def del_endpoint(server, endpoint) -> bool:
61-
'''Delete a "endpoint" object in Kepware UA Server
54+
def del_endpoint(server: server, endpoint: str) -> bool:
55+
'''Delete an `"endpoint"` object in Kepware UA Server
6256
63-
INPUTS:
64-
"server" - instance of the "server" class
65-
66-
"endpoint" - name of endpoint
57+
:param server: instance of the `server` class
58+
:param endpoint: name of endpoint to delete
6759
68-
RETURNS:
69-
True - If a "HTTP 200 - OK" is received from Kepware
60+
:return: True - If a "HTTP 200 - OK" is received from Kepware server
7061
71-
EXCEPTIONS:
72-
KepHTTPError - If urllib provides an HTTPError
73-
KepURLError - If urllib provides an URLError
62+
:raises KepHTTPError: If urllib provides an HTTPError
63+
:raises KepURLError: If urllib provides an URLError
7464
'''
7565

7666
r = server._config_del(server.url + _create_url(endpoint))
7767
if r.code == 200: return True
7868
else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
7969

80-
def modify_endpoint(server, DATA, endpoint = None) -> bool:
81-
'''Modify a endpoint object and it's properties in Kepware UA Server. If a "endpoint" is not provided as an input,
82-
you need to identify the endpoint in the 'common.ALLTYPES_NAME' property field in the "DATA". It will
70+
def modify_endpoint(server: server, DATA: dict, endpoint: str = None) -> bool:
71+
'''Modify a `"endpoint"` object and it's properties in Kepware UA Server. If a `"endpoint"` is not provided as an input,
72+
you need to identify the endpoint in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will
8373
assume that is the endpoint that is to be modified.
8474
85-
INPUTS:
86-
"server" - instance of the "server" class
87-
88-
"DATA" - properly JSON object (dict) of the endpoint properties to be modified.
89-
90-
"endpoint" (optional) - name of endpoint to modify. Only needed if not existing in "DATA"
75+
:param server: instance of the `server` class
76+
:param DATA: Dict of the UA endpoint properties to be modified.
77+
:param endpoint: *(optional)* name of endpoint to modify. Only needed if not existing in `"DATA"`
9178
92-
RETURNS:
93-
True - If a "HTTP 200 - OK" is received from Kepware
79+
:return: True - If a "HTTP 200 - OK" is received from Kepware server
9480
95-
EXCEPTIONS:
96-
KepHTTPError - If urllib provides an HTTPError
97-
KepURLError - If urllib provides an URLError
81+
:raises KepHTTPError: If urllib provides an HTTPError
82+
:raises KepURLError: If urllib provides an URLError
9883
'''
99-
100-
# channel_data = server._force_update_check(force, DATA)
84+
10185
if endpoint == None:
10286
try:
10387
r = server._config_update(server.url + _create_url(DATA['common.ALLTYPES_NAME']), DATA)
@@ -106,48 +90,37 @@ def modify_endpoint(server, DATA, endpoint = None) -> bool:
10690
except KeyError as err:
10791
err_msg = 'Error: No UA Endpoint identified in DATA | Key Error: {}'.format(err)
10892
raise KepError(err_msg)
109-
110-
# except Exception as e:
111-
# return 'Error: Error with {}: {}'.format(inspect.currentframe().f_code.co_name, str(e))
11293
else:
11394
r = server._config_update(server.url + _create_url(endpoint), DATA)
11495
if r.code == 200: return True
11596
else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
11697

117-
def get_endpoint(server, endpoint) -> dict:
118-
'''Returns the properties of the endpoint object. Returned object is JSON.
98+
def get_endpoint(server: server, endpoint: str) -> dict:
99+
'''Returns the properties of the `"endpoint"` object.
119100
120-
INPUTS:
121-
"server" - instance of the "server" class
122-
123-
"endpoint" - name of endpoint
101+
:param server: instance of the `server` class
102+
:param endpoint: name of endpoint to retrieve
124103
125-
RETURNS:
126-
dict - data for the endpoint requested
104+
:return: Dict of properties for the UA endpoint requested
127105
128-
EXCEPTIONS:
129-
KepHTTPError - If urllib provides an HTTPError
130-
KepURLError - If urllib provides an URLError
106+
:raises KepHTTPError: If urllib provides an HTTPError
107+
:raises KepURLError: If urllib provides an URLError
131108
'''
132109

133110
r = server._config_get(server.url + _create_url(endpoint))
134111
return r.payload
135112

136113
def get_all_endpoints(server: server, *, options: dict = None) -> list:
137-
'''Returns list of all endpoint objects and their properties. Returned object is JSON list.
114+
'''Returns list of all `"endpoint"` objects and their properties.
138115
139-
INPUTS:
140-
server - instance of the "server" class
141-
142-
options - (optional) Dict of parameters to filter, sort or pagenate the list of UA endpoints. Options are 'filter',
143-
'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize'.
116+
:param server: instance of the `server` class
117+
:param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of UA endpoints. Options are 'filter',
118+
'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize.
144119
145-
RETURNS:
146-
list - data for all endpoints requested
120+
:return: List of properties for all UA endpoints requested
147121
148-
EXCEPTIONS:
149-
KepHTTPError - If urllib provides an HTTPError
150-
KepURLError - If urllib provides an URLError
122+
:raises KepHTTPError: If urllib provides an HTTPError
123+
:raises KepURLError: If urllib provides an URLError
151124
'''
152125

153126
r = server._config_get(f'{server.url}{_create_url()}', params= options)

0 commit comments

Comments
 (0)