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.
@@ -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
+ [![Python Tests](https://github.com/id-ai-labo/settingsclass/actions/workflows/tests.yml/badge.svg)](https://github.com/id-ai-labo/settingsclass/actions/workflows/tests.yml)
17
+ [![Tests Status](./tests/reports/coverage-badge.svg?dummy=8484744)](./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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (72.1.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ settingsclass