settingsclass 0.1.4__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- settingsclass/__init__.py +21 -0
- settingsclass/loc/settings.csv +36 -0
- settingsclass/localizer.py +216 -0
- settingsclass/settingsclass.py +1012 -0
- settingsclass-0.1.4.dist-info/LICENSE +21 -0
- settingsclass-0.1.4.dist-info/METADATA +539 -0
- settingsclass-0.1.4.dist-info/RECORD +9 -0
- settingsclass-0.1.4.dist-info/WHEEL +5 -0
- settingsclass-0.1.4.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 id-ai-labo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,539 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: settingsclass
|
|
3
|
+
Version: 0.1.4
|
|
4
|
+
Summary: A class decorator for easily storing setting values, with automatic sync to disk
|
|
5
|
+
Author: Robert Kajnak
|
|
6
|
+
License: MIT Licence
|
|
7
|
+
Project-URL: Homepage, https://github.com/id-ai-labo/settingsclass
|
|
8
|
+
Keywords: settings,config,configuration,ini,configparser,dataclass
|
|
9
|
+
Classifier: Programming Language :: Python
|
|
10
|
+
Requires-Python: >=3.11
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Requires-Dist: loguru
|
|
14
|
+
Requires-Dist: pycryptodome >=3.20.0
|
|
15
|
+
|
|
16
|
+
[](https://github.com/id-ai-labo/settingsclass/actions/workflows/tests.yml)
|
|
17
|
+
[](./tests/reports/www/index.html)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
# settingsclass
|
|
21
|
+
|
|
22
|
+
[日本語の説明](README_JA.md)
|
|
23
|
+
|
|
24
|
+
An easy-to-use but feature-rich solution to storing settings in python.
|
|
25
|
+
|
|
26
|
+
This library provides a decorator to mark your own custom classes, where variables become setting values. If you have used [dataclass](https://docs.python.org/3/library/dataclasses.html) before, this library should feel familiar. It also includes synchronization with an external ini file and support for runtime-generated values, e.g. random strings for synchronizing settings with an ini file using a [configparser](https://docs.python.org/3/library/configparser.html) backend.
|
|
27
|
+
|
|
28
|
+
Developed by [ID AI Factory Co., Ltd.](https://www.ai-factory.co.jp)
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
# Quick-start example (1/2)
|
|
33
|
+
In this example only key concepts are presented and assumes you like tinkering more than explanations.
|
|
34
|
+
**If you are unfamiliar with dataclass or configparser, or would like a more detailed explanation skip to example 2**
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
38
|
+
|
|
39
|
+
@settingsclass
|
|
40
|
+
class WebConfig:
|
|
41
|
+
class console:
|
|
42
|
+
language: str = "en"
|
|
43
|
+
machine_id: RandomString[4] = ""
|
|
44
|
+
backdoor_password: Encrypted[RandomString[14, 20]] = ""
|
|
45
|
+
debug_pin: Encrypted[RandomInt[1000, 9999]] = 0
|
|
46
|
+
maxiumum_message_per_second: int = 5
|
|
47
|
+
colored_output: Hidden[bool] = True
|
|
48
|
+
|
|
49
|
+
class agent:
|
|
50
|
+
api_key: Encrypted[str] = ""
|
|
51
|
+
seed: RandomFloat[0, 12345] = 0
|
|
52
|
+
|
|
53
|
+
# Save to or read from "config.ini". Custom path can also be passed
|
|
54
|
+
config = WebConfig()
|
|
55
|
+
|
|
56
|
+
# Hinting a type as RandomInt, RandomFloat and RandomString will generate
|
|
57
|
+
# will cause the class instantiation to generate a primitive within specified limits
|
|
58
|
+
# The default value after [=] is ignored
|
|
59
|
+
m_id = config.console.machine_id
|
|
60
|
+
print(f'{m_id} w/ {type(m_id)}) # prints a four character <string> e.g. 4G_b
|
|
61
|
+
|
|
62
|
+
# Instance variables type hinted with Encrypted[type] return objects of their
|
|
63
|
+
# encapsulated types, but are encrypted when saving to disk
|
|
64
|
+
dbp = config.console.debug_pin
|
|
65
|
+
print(f'{dbp} w/ {type(dbp)}) # prints a 4 digit int e.g. "4521 w/ <class 'int'>"
|
|
66
|
+
|
|
67
|
+
# The config.ini file will have the value encrypted similar to:
|
|
68
|
+
# debug_pin = ?ENC22e6de0f80d81f54fbae752d27cd5663e693758554d3520466e7c90423fd3997
|
|
69
|
+
|
|
70
|
+
# A new custom value can also be specified in the ini file, it is encrypted the
|
|
71
|
+
# next time config = WebConfig() is called
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
# Hidden[type] variable also generate values of their encapsulated types,
|
|
75
|
+
# and are not saved/read from the config file, unless already present
|
|
76
|
+
co = config.console.colored_output
|
|
77
|
+
print(f'{co} w/ {type(co)}) # prints "True w/ <class 'bool'>"
|
|
78
|
+
|
|
79
|
+
# ---
|
|
80
|
+
# Modified instances can be saved to an arbitrary path
|
|
81
|
+
# The default value is the path it was read from
|
|
82
|
+
# Variable types are not enforced when modifying the class instance,
|
|
83
|
+
# only when reading from disk. It is python after all
|
|
84
|
+
config.agent.seed = "foo"
|
|
85
|
+
config.save_to_file("config2.ini")
|
|
86
|
+
|
|
87
|
+
config2 = WebConfig("config2.ini") # prints a type mismatch warning for agent/seed
|
|
88
|
+
print(config2.agent.seed) # prints a random number e.g. "4281.154" with type Float
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
# Detailed Use-Case Example (2/2)
|
|
93
|
+
|
|
94
|
+
Let's say you are developing a chat application with login that will be deployed on a server and wish to have some settings that can be set depending on the environment. Saving and reading to a configuration file that non-python experts can also understand is most likely ideal.
|
|
95
|
+
|
|
96
|
+
### Class definition
|
|
97
|
+
To improve readability, we will define two sections: one for console-related settings and one to set the chat agent.
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
*The code for the explanation below can also be found [here](demo.py)*
|
|
101
|
+
<details>
|
|
102
|
+
<summary><i>A note on naming convention</i></summary>
|
|
103
|
+
The appropriate choice during definition seems to be <code>class Settings</code>/<code>class Section</code> (with a capital), however in during usage it will be called under the same name. Hence, it is an object during most of its usage, therefore the suggested usage is <code>class Settings</code>/<code>class section</code> (internal lowercase). I did consider changing the case of the name during runtime, but I decided that that would be more confusing, especially when using <code>ClassNamesOfMultipleWords</code> -> <code>class_names_of_multiple_words</code>
|
|
104
|
+
</details>
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
109
|
+
|
|
110
|
+
@settingsclass
|
|
111
|
+
class WebConfig:
|
|
112
|
+
class console:
|
|
113
|
+
# We would like to support multiple languages.
|
|
114
|
+
# This uses language codes, as such it will be stored as a string
|
|
115
|
+
# By default it should be english
|
|
116
|
+
language: str = "en"
|
|
117
|
+
# => A string value with the default value of "en" will be initialized
|
|
118
|
+
|
|
119
|
+
# We also want our machine in the cloud to be easily identifiable in the common log db
|
|
120
|
+
# Therefore, we add a short string that is set when deploying the machine
|
|
121
|
+
# In case it is forgotten, it will be set to a 4 character string
|
|
122
|
+
machine_id: RandomString[4] = ""
|
|
123
|
+
# => A random string with a fixed length of 4 characters
|
|
124
|
+
|
|
125
|
+
# We would like to enable admin access for system-critical information
|
|
126
|
+
# This should be a long password (14~20 characters)
|
|
127
|
+
# The generator uses python's secrets library to ensure that it is cryptographically safe
|
|
128
|
+
backdoor_password: Encrypted[RandomString[14, 20]] = ""
|
|
129
|
+
# => Generates a 14 to 20 character encrypted string
|
|
130
|
+
# If the user wants to prepare a custom password to be used per-machine,
|
|
131
|
+
# they can edit the config file with the desired value. When the code is run
|
|
132
|
+
# for the first time after modification, the value is encrypted, and the original file
|
|
133
|
+
# is overwritten
|
|
134
|
+
|
|
135
|
+
# For low-security areas, a quick access 4 digit pin will suffice
|
|
136
|
+
debug_pin: Encrypted[RandomInt[1000, 9999]] = 0
|
|
137
|
+
# => Generates a 4 digit integer
|
|
138
|
+
|
|
139
|
+
# Having too many messages printed to console can cause slow down execution,
|
|
140
|
+
# therefore a limit is set, that may be modified later based on the environment
|
|
141
|
+
maximum_message_per_second: int = 5
|
|
142
|
+
# => an integer with a default value of 5
|
|
143
|
+
|
|
144
|
+
# Depending on the environment, having colored console output may result in
|
|
145
|
+
# seeing the ANSI escape codes to be shown as character codes instead of modifying
|
|
146
|
+
# the displayed text, so an option to turn it off may be useful.
|
|
147
|
+
# This is rarely the case however, so having this option always visible may hinder readability
|
|
148
|
+
colored_output: Hidden[bool] = True
|
|
149
|
+
# => The object instance will have a boolean instance of True, but it is not
|
|
150
|
+
# saved to disk. It is only read from or written to disk,
|
|
151
|
+
# if the config file already contained the section and variable
|
|
152
|
+
|
|
153
|
+
class agent:
|
|
154
|
+
# The API key should be encrypted, but there is no possible default value,
|
|
155
|
+
# so it is set to emptystring
|
|
156
|
+
api_key: Encrypted[str] = ""
|
|
157
|
+
# => only an emptystring is saved at first, but when the ini file is modified,
|
|
158
|
+
# it will be overwritten with the encrypted value
|
|
159
|
+
|
|
160
|
+
# The seed to be used for some random elements should be settable for reproducibility,
|
|
161
|
+
# but otherwise any value is acceptable. It does not need to be regenerated on program restart
|
|
162
|
+
seed: RandomFloat[0, 12345] = 0
|
|
163
|
+
# => Generates a random float between 0 and 12345
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
## Disk I/O and variable types
|
|
168
|
+
Next, we want to match it with a .ini file, so that we can set custom values later.
|
|
169
|
+
The config file name is not relevant in this instance, so we will leave it at the default value (config.ini).
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
config = WebConfig()
|
|
173
|
+
```
|
|
174
|
+
Done! If we check the contents of the generated file, it will be similar to this:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
[console]
|
|
178
|
+
language = en
|
|
179
|
+
machine_id = b8_Q
|
|
180
|
+
backdoor_password = ?ENC5d51bb10d835ff680ce50c99dc512678cb6cb3525d18129a56c7b417c6847339790dbe0cd264ca201a7b82a0dbb4c130
|
|
181
|
+
debug_pin = ?ENC7cac31ac5bb2a5a6078d770b17a5a6728766adafa43409a2917b0c09903fcce5
|
|
182
|
+
maximum_message_per_second = 5
|
|
183
|
+
|
|
184
|
+
[agent]
|
|
185
|
+
api_key =
|
|
186
|
+
seed = 8881.079
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
We would like the to have a more easily readable `machine_id`, and the `api_key` is empty at the moment, so we modify the two values in the config.ini file.
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
[console]
|
|
193
|
+
language = en
|
|
194
|
+
machine_id = GIT0
|
|
195
|
+
backdoor_password = ?ENC5d51bb10d835ff680ce50c99dc512678cb6cb3525d18129a56c7b417c6847339790dbe0cd264ca201a7b82a0dbb4c130
|
|
196
|
+
debug_pin = ?ENC7cac31ac5bb2a5a6078d770b17a5a6728766adafa43409a2917b0c09903fcce5
|
|
197
|
+
maximum_message_per_second = 5
|
|
198
|
+
|
|
199
|
+
[agent]
|
|
200
|
+
api_key = super_secret_api_key_556
|
|
201
|
+
seed = 8881.079
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
If we re-run `config = WebConfig()`, we can observe that our api_key has been encrypted. The already encrypted values have not changed.
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
[console]
|
|
208
|
+
language = en
|
|
209
|
+
machine_id = GIT0
|
|
210
|
+
backdoor_password = ?ENC5d51bb10d835ff680ce50c99dc512678cb6cb3525d18129a56c7b417c6847339790dbe0cd264ca201a7b82a0dbb4c130
|
|
211
|
+
debug_pin = ?ENC7cac31ac5bb2a5a6078d770b17a5a6728766adafa43409a2917b0c09903fcce5
|
|
212
|
+
maximum_message_per_second = 5
|
|
213
|
+
|
|
214
|
+
[agent]
|
|
215
|
+
api_key = ?ENCd60d7fad60db92ace78261377c629ebad7926916bcae90a4a8aea5a2c296e4f8c7119229d88546374b0ce857fb8e332e
|
|
216
|
+
seed = 8881.079
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
We can also print the whole class, or a one of the sections. The data will be decrypted in plain text form, therefore care needs to be taken data during logging. If we would only like to see the contents of a section we can use
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
print(f"Complete class:\n{config}")
|
|
223
|
+
print("----+++----")
|
|
224
|
+
print(f"A section only:\n{config.agent}")
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
which will result in
|
|
228
|
+
```
|
|
229
|
+
Complete class:
|
|
230
|
+
SettingsClass [WebConfig]:
|
|
231
|
+
console:
|
|
232
|
+
language: <str> = en
|
|
233
|
+
machine_id: <RandomString[4]> = YM5W
|
|
234
|
+
backdoor_password: <Encrypted[RandomString[14,20]]> = Qt15Jk0jprCwqFQQs2ob
|
|
235
|
+
debug_pin: <Encrypted[RandomInt[1000,9999]]> = 1516
|
|
236
|
+
maximum_message_per_second: <int> = 5
|
|
237
|
+
colored_output: <Hidden[bool]> = True
|
|
238
|
+
agent:
|
|
239
|
+
api_key: <Encrypted[str]> =
|
|
240
|
+
seed: <RandomFloat[0,12345]> = 8796.928
|
|
241
|
+
|
|
242
|
+
----+++----
|
|
243
|
+
A section only:
|
|
244
|
+
WebConfig section: [agent]
|
|
245
|
+
api_key: <Encrypted[str]> =
|
|
246
|
+
seed: <RandomFloat[0,12345]> = 8796.928
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
The variable type is guaranteed for both simple types and randomized values and can be treated like any other variable.
|
|
250
|
+
We can check that by executing the following code.
|
|
251
|
+
|
|
252
|
+
```
|
|
253
|
+
def print_val_and_type(x: int): # Placeholder for user function
|
|
254
|
+
print(f"Value {x} with type {type(x)}")
|
|
255
|
+
|
|
256
|
+
print_val_and_type(config.agent.seed)
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
This should print a float value followed by the confirmed float type.
|
|
260
|
+
|
|
261
|
+
`Value 8881.079 with type <class 'float'>`
|
|
262
|
+
|
|
263
|
+
*The precision of the floats can be set by using the precision parameter `RandomFloat[0, 2, precision=5]`*
|
|
264
|
+
|
|
265
|
+
### Manual saving
|
|
266
|
+
|
|
267
|
+
Continuing the scenario, let's say that we have a webpage where the admin can change the machine id.
|
|
268
|
+
We would like to save to disk as to use the same value after the program restarts.
|
|
269
|
+
We can do this using the `settingsclass` member function `save_to_file`.
|
|
270
|
+
|
|
271
|
+
For this example, the admin has changed the value to TIG1. The relevant code would have the same affect as below:
|
|
272
|
+
```
|
|
273
|
+
config.console.machine_id = "TIG1"
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Executing the code above only modifies the object in memory, it is not automatically synced with the ini file. The save function needs to be called manually.
|
|
277
|
+
|
|
278
|
+
```
|
|
279
|
+
# Make a backup file before overwriting
|
|
280
|
+
config.save_to_file("config_bk.ini")
|
|
281
|
+
|
|
282
|
+
# Overwrite the original file
|
|
283
|
+
config.save_to_file()
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Both the ini file and the python object should reflect our change.
|
|
287
|
+
As the above code demonstrates `save_to_file` can be called without a parameter, in which case the original file will be overwritten.
|
|
288
|
+
|
|
289
|
+
Let's check the changed values between the two files:
|
|
290
|
+
```
|
|
291
|
+
old_value = config.console.machine_id # int, therefore copy etc. is not needed
|
|
292
|
+
|
|
293
|
+
# re-read from disk
|
|
294
|
+
config = WebConfig()
|
|
295
|
+
verify_value = config.console.machine_id
|
|
296
|
+
|
|
297
|
+
# read the backup value
|
|
298
|
+
config_bk = WebConfig("config_bk.ini")
|
|
299
|
+
|
|
300
|
+
# print the 3 values
|
|
301
|
+
print(f"Memory = {old_value}")
|
|
302
|
+
print(f"Re-read = {config.console.machine_id}")
|
|
303
|
+
print(f"Backup = {config_bk.console.machine_id}")
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
## Type checking
|
|
307
|
+
|
|
308
|
+
In the previous section we have set a string value to a variable that has been type hinted as string. Let's see a scenario, where the type is accidentally mistaken and a string value is set to a variable that has been type hinted as int.
|
|
309
|
+
```
|
|
310
|
+
config.agent.seed = "abcd"
|
|
311
|
+
config.save_to_file()
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Since this is python, type checks are not performed on variable assignments. They are, however, checked when reading the values from disk. To verify this, we will read the file contents once again from disk.
|
|
315
|
+
```
|
|
316
|
+
config = WebConfig()
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
A warning message should pop up with about not being able to cast the type along the following lines.
|
|
320
|
+
```
|
|
321
|
+
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:_set_members:753 - Could not convert <abcd> to type <class 'float'> for parameter <seed> in section <agent>
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
If we check the value that is actually set, we can see that it is a newly generated random value.
|
|
325
|
+
```
|
|
326
|
+
print(config.agent.seed)
|
|
327
|
+
```
|
|
328
|
+
This will output e.g. `11392.713`
|
|
329
|
+
|
|
330
|
+
The opposite case, type hinting a variable as a string, but meaning to use an int is also a possibility. Since in this case, it is possible that it is intentional, a warning is shown, but the value itself is not changed.
|
|
331
|
+
|
|
332
|
+
To simulate this, we set the following to values. We actually wanted to define language as an index in the list of available languages and have the machine id shown or hidden. An other possibility is the one modifying the config.ini file has mistaken what the values represent. The result is the same in both cases and we can see what happens by running the following code. The same would happen if we modified the values in the ini file.
|
|
333
|
+
|
|
334
|
+
```
|
|
335
|
+
config.console.language = 3
|
|
336
|
+
config.console.machine_id = False
|
|
337
|
+
|
|
338
|
+
config.save_to_file()
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
To trigger the warning, we read the file from disk.
|
|
342
|
+
```
|
|
343
|
+
config = WebConfig()
|
|
344
|
+
|
|
345
|
+
lang = config.console.language
|
|
346
|
+
m_id = config.console.machine_id
|
|
347
|
+
print(f"Lang = {lang} of type {type(lang)}")
|
|
348
|
+
print(f"Password = {m_id} of type {type(lang)}")
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
The output of the code will be two warnings about potential type mismatches, but ultimately the type and value of the variables will be unaffected
|
|
352
|
+
```
|
|
353
|
+
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:576 - The parameter <console> in section <language> with value 3 of the settings file is a string but looks like a int
|
|
354
|
+
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:560 - The parameter <console> in section <machine_id> with value False of the settings file is a string but looks like a bool
|
|
355
|
+
Lang = 3 of type <class 'str'>
|
|
356
|
+
Password = False of type <class 'str'>
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
## Advanced settings
|
|
360
|
+
In specific use cases, you may want to use some of the more advanced settings such as using a custom encryption algorithm or setting the precision of RandomFloat's. Please see section [Full Feature list](#full-feature-list)
|
|
361
|
+
|
|
362
|
+
# Why not an existing solution?
|
|
363
|
+
|
|
364
|
+
The most common recommendations for storing settings file are the following, but each have their disadvantages
|
|
365
|
+
1. Using [configparser](https://docs.python.org/3/library/configparser.html)
|
|
366
|
+
- Basic concept
|
|
367
|
+
- Stores values inside an ini file on disk
|
|
368
|
+
- Uses a two-tier dictionary-like object in memory
|
|
369
|
+
- Advantages:
|
|
370
|
+
- Simple and readable even for non-programmers
|
|
371
|
+
- Can be read from the common ini format
|
|
372
|
+
- Easy to save modified version
|
|
373
|
+
- Disadvantages:
|
|
374
|
+
- Lacks type hinting and type checking
|
|
375
|
+
- Missing values must be try-except'ed
|
|
376
|
+
- No support for optional/advanced settings
|
|
377
|
+
- No support for encryption
|
|
378
|
+
- No auto-completion hints from IDE
|
|
379
|
+
2. Using a .py file
|
|
380
|
+
- Basic Concept
|
|
381
|
+
- Write normal python code that only stores data
|
|
382
|
+
- Advantages
|
|
383
|
+
- Types are easily visible
|
|
384
|
+
- Can include additional calculation or processing
|
|
385
|
+
- Easy to import
|
|
386
|
+
- Disadvantages
|
|
387
|
+
- Requires python knowledge, cannot be easily given to non-programmers
|
|
388
|
+
- Can include arbitrary code, making it extremely unsafe
|
|
389
|
+
- Variants with different values need to be saved manually
|
|
390
|
+
- Difficult to have default and custom values separately
|
|
391
|
+
- Keeping secret keys hidden can be challenging
|
|
392
|
+
|
|
393
|
+
3. Environmental variables
|
|
394
|
+
- Basic Concept:
|
|
395
|
+
- Default values defined inside code, custom values read from the environment
|
|
396
|
+
- Advantages:
|
|
397
|
+
- Easy to set values when working inside containers
|
|
398
|
+
- Disadvantages:
|
|
399
|
+
- Setting values is difficult for non-developers
|
|
400
|
+
- Lacks type hinting and type checking
|
|
401
|
+
- No auto-completion hints from IDE
|
|
402
|
+
- Difficult to debug
|
|
403
|
+
- Variable names may conflict with other programs
|
|
404
|
+
|
|
405
|
+
## This library
|
|
406
|
+
- Basic Concept:
|
|
407
|
+
- The settings template defined inside python code, with a non-developer friendly ini file for custom values
|
|
408
|
+
- Advantages:
|
|
409
|
+
- Easy-to-understand standard ini file for non-developers and developers alike
|
|
410
|
+
- Support for environmental variables with user-defined prefix (also type cast automatically)
|
|
411
|
+
- Types can be hinted and types are enforced when loading (ini) files
|
|
412
|
+
- Support for randomly generated string, int and float at runtime
|
|
413
|
+
- Support hidden/advanced settings
|
|
414
|
+
- Support for automatic encryption of user added or default values
|
|
415
|
+
- Auto-completion support due to dataclass backbone
|
|
416
|
+
- Warnings on type mismatches
|
|
417
|
+
- e.g. bool in var definition, but "5" in code
|
|
418
|
+
- **reverse also true, e.g. str hint in code but "False" in config**
|
|
419
|
+
- Easy to save new variant after modification
|
|
420
|
+
- Safe against arbitrary content (warning message is displayed and the default value is used instead)
|
|
421
|
+
- Basically no need for boilerplate code
|
|
422
|
+
- Disadvantages:
|
|
423
|
+
- No support for single level config (e.g. config.color must be converted to config.general.color or config.ui.color etc.)
|
|
424
|
+
- No support for file change watching out-of-the-box
|
|
425
|
+
- Only supports .ini (JSON support planned)
|
|
426
|
+
|
|
427
|
+
|
|
428
|
+
# Installation
|
|
429
|
+
|
|
430
|
+
`pip install settingsclass`
|
|
431
|
+
|
|
432
|
+
If you wish to build from source, use
|
|
433
|
+
|
|
434
|
+
`python -m build`
|
|
435
|
+
|
|
436
|
+
## Requirements
|
|
437
|
+
|
|
438
|
+
Python 3.11+
|
|
439
|
+
- loguru
|
|
440
|
+
- pycryptodome
|
|
441
|
+
|
|
442
|
+
# Full Feature list
|
|
443
|
+
|
|
444
|
+
|
|
445
|
+
## Decorator
|
|
446
|
+
|
|
447
|
+
Settings provided to the decorator will be shared across class instances. Settings provided at object instantiation take precedence.
|
|
448
|
+
|
|
449
|
+
`@settingsclass(env_prefix: str = "", common_encryption_key: type[str | Callable[[Any], str] | None] = None, salt: bytes = None)`
|
|
450
|
+
|
|
451
|
+
### Use cases:
|
|
452
|
+
1. No arguments
|
|
453
|
+
The contents of the class are saved under "config.ini" in the current directory. Encryption keys are saved in the library's local folder.
|
|
454
|
+
```
|
|
455
|
+
@settingsclass
|
|
456
|
+
class Settings:
|
|
457
|
+
[...]
|
|
458
|
+
```
|
|
459
|
+
---
|
|
460
|
+
2. Specific arguments
|
|
461
|
+
Without specifying a parameter all instantiations will look at the same webconfig.ini file. **If a folder `my_folder` is specified, the class will look for `my_folder/config.ini`**
|
|
462
|
+
Specifying an encryption key will mean that all subsequent instantiations of the class will use that key unless otherwise specified.
|
|
463
|
+
Since the `_salt` parameter is specified, copying the file over to an other machine and using "my_encryption_key" will result in a correctly read settings file.
|
|
464
|
+
```
|
|
465
|
+
@settingsclass(file_path = "webconfig.ini", common_encryption_key = "my_encryption_key", _salt=b'\x87\x14~\x88\xf8\xfd\xb3&\xe2\xd4\xd9|@\xfb\x80\x9e')
|
|
466
|
+
class Settings:
|
|
467
|
+
[...]
|
|
468
|
+
```
|
|
469
|
+
---
|
|
470
|
+
3. In-memory only settings/user custom file type
|
|
471
|
+
```
|
|
472
|
+
@settingsclass(None)
|
|
473
|
+
class Settings:
|
|
474
|
+
[...]
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
The file can also be saved later manually using
|
|
478
|
+
```
|
|
479
|
+
conf = Settings(None)
|
|
480
|
+
conf.save_to_file("now_im_ready.ini")
|
|
481
|
+
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
## Constructor
|
|
485
|
+
|
|
486
|
+
All arguments of the decorator can also be overridden by the constructor. To avoid accidental setting in regards to encryption, the decorator uses `common_encryption_key` while the constructor uses encryption_key. Other parameters have identical names.
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
## Variable types
|
|
490
|
+
|
|
491
|
+
### Random String
|
|
492
|
+
`RandomString[max_length, min_length=-1, /, random_function: Callable = secrets.token_urlsafe]`
|
|
493
|
+
|
|
494
|
+
Generates a random string between the specified lengths. If `max` is not specified, the string will have a fixed length equal to the specified min length. Optionally a the `random_function` can also be specified which will be called as `random_function(max_length)[:true_length]`. The types can also be called directly to test them e.g. `RandomString(5)` will return e.g. `Ku_nR`. Uses `secrets.token_urlsafe`
|
|
495
|
+
**The default value specified by user is ignored.**
|
|
496
|
+
|
|
497
|
+
### RandomInt[min_value, max_value, /, random_function] / RandomFloat[~]
|
|
498
|
+
`RandomInt[min_value: int, max_value: int, random_function: Callable = random.randint]`
|
|
499
|
+
`RandomFloat[min_value: float, max_value: float, precision: int = 3, random_function: Callable = random.random]`
|
|
500
|
+
|
|
501
|
+
Generates a number between the two limits. Optionally a function can be specified, that should accept the two limits as parameters. For floats, the precision can also be specified.
|
|
502
|
+
**The default value specified by user is ignored**
|
|
503
|
+
|
|
504
|
+
### Hidden[type]
|
|
505
|
+
|
|
506
|
+
The parameter specified will not be written to the file when specified, but will be read both from environmental variables and the specified files when available.
|
|
507
|
+
|
|
508
|
+
### Encrypted[type]
|
|
509
|
+
Encryption is based on AES128 (256 is slower with no practical benefits).
|
|
510
|
+
By default both the key and salt are randomly generated and saved inside the library directory. The IV is included within the encrypted string's field.
|
|
511
|
+
This can be overwritten by specifying the `encryption_key` per object or `common_encryption_key` at the class definition level.
|
|
512
|
+
This can be either a string or a function handle that will be called as is.
|
|
513
|
+
Salt is generated and saved per environment, ensuring that a config file cannot be copy-pasted from one environment to an other, providing an other layer of protection over the encryption key. For environments where the directory is not user-writeable the salt can be also be specified in binary string form. Per class specification is not supported, as it is not the intended use-case.
|
|
514
|
+
An example of a full specification would be:
|
|
515
|
+
|
|
516
|
+
```
|
|
517
|
+
@settingsclass(encryption_key="123X456", _salt=b"\x86\xce'?\xbc\x1eA\xd3&\x84\x82\xb4\xa3\x99\x10P")
|
|
518
|
+
class Settings:
|
|
519
|
+
class program:
|
|
520
|
+
password: Encrypted[str] = "will be encrypted on save"
|
|
521
|
+
|
|
522
|
+
s = Settings(encryption_key="abcdefgh") # this takes precedence over the encryption_key defined in the decorator
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
Supports any type that can be cast to string
|
|
526
|
+
|
|
527
|
+
## Useful functions
|
|
528
|
+
|
|
529
|
+
|
|
530
|
+
### Saving to an ini file
|
|
531
|
+
`save_to_file(self, path=None)`
|
|
532
|
+
Saves to contents (including encryption) to the specified path. If the path is left as None, the file path used to load the file is used
|
|
533
|
+
|
|
534
|
+
### Loading from an ini file
|
|
535
|
+
`update_from(self, config: configparser.ConfigParser, secrets_only: False) -> list[str]`
|
|
536
|
+
|
|
537
|
+
configparser handle should be prepared by the user, including case sensitivity settings etc. Returns a list of fields that should have been encrypted but were not. For automatic encryption please use the constructor
|
|
538
|
+
|
|
539
|
+
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
settingsclass/__init__.py,sha256=n7NLoS66xTE_50TYjdguiiQ_WpP5V3eDI4UCrZB9l00,353
|
|
2
|
+
settingsclass/localizer.py,sha256=rixz3cuSY6d11oD1bKzgWVBbQeaTfsRHkI5xFSh5914,8373
|
|
3
|
+
settingsclass/settingsclass.py,sha256=V2dDdbv8WndPdQcWT4DGIkbZcBh9mfYFa60LRVX_TeE,36367
|
|
4
|
+
settingsclass/loc/settings.csv,sha256=8spf3_xxZxuvRHkcJsP_00RnjLJXsmFfpiCk-STw33Y,5794
|
|
5
|
+
settingsclass-0.1.4.dist-info/LICENSE,sha256=XNbPL_5OOJ__SUZ_ZQQ5RBZBQXtCDl-E28zjp-XRcp8,1067
|
|
6
|
+
settingsclass-0.1.4.dist-info/METADATA,sha256=j-8geb6LD16XiHY4sk-t28fNhxceZdufWiUpcwxtLvI,23730
|
|
7
|
+
settingsclass-0.1.4.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
|
|
8
|
+
settingsclass-0.1.4.dist-info/top_level.txt,sha256=bOWf24J8ejEd_F1BQHorqHidw8OGGt5K3B3cMhquKT4,14
|
|
9
|
+
settingsclass-0.1.4.dist-info/RECORD,,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
settingsclass
|