settingsclass 0.1.4__tar.gz → 0.2.0__tar.gz
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-0.1.4 → settingsclass-0.2.0}/PKG-INFO +87 -41
- {settingsclass-0.1.4 → settingsclass-0.2.0}/README.md +84 -39
- {settingsclass-0.1.4 → settingsclass-0.2.0}/README_JA.md +123 -65
- {settingsclass-0.1.4 → settingsclass-0.2.0}/demo.py +2 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/demo_ja.py +2 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/pyproject.toml +8 -2
- settingsclass-0.2.0/requirements-dev.txt +4 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/__init__.py +2 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/loc/settings.csv +8 -4
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/settingsclass.py +376 -74
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/PKG-INFO +87 -41
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/SOURCES.txt +2 -0
- settingsclass-0.2.0/tests/__init__.py +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config.ini/config.ini +3 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_bad_type.ini +3 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_confusing_types.ini +1 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_duplicate_param.ini +1 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_duplicate_section.ini +2 -2
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_extra_parts.ini +1 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_generated_good.ini +3 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_generated_good_half_enc.ini +1 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_good_case_var.ini +4 -2
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_modified.ini +3 -1
- settingsclass-0.2.0/tests/reports/coverage-badge.svg +1 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/test_localization.py +13 -14
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/test_settings.py +184 -58
- settingsclass-0.2.0/tests/test_settings_types.py +120 -0
- settingsclass-0.1.4/requirements-dev.txt +0 -5
- settingsclass-0.1.4/tests/reports/coverage-badge.svg +0 -1
- {settingsclass-0.1.4 → settingsclass-0.2.0}/.github/workflows/python-publish.yml +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/.github/workflows/tests.yml +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/.gitignore +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/LICENSE +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/requirements.txt +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/setup.cfg +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/localizer.py +0 -0
- settingsclass-0.1.4/tests/__init__.py → settingsclass-0.2.0/src/settingsclass/py.typed +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/dependency_links.txt +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/requires.txt +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/top_level.txt +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_correct.csv +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_duplicate_key.csv +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_few.csv +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_many.csv +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_nostr.csv +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_half_specified.csv +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_warning.csv +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_missing_section.ini +0 -0
- {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/test_localization_fail_cases.py +2 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
2
|
Name: settingsclass
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.2.0
|
|
4
4
|
Summary: A class decorator for easily storing setting values, with automatic sync to disk
|
|
5
5
|
Author: Robert Kajnak
|
|
6
6
|
License: MIT Licence
|
|
@@ -12,9 +12,10 @@ Description-Content-Type: text/markdown
|
|
|
12
12
|
License-File: LICENSE
|
|
13
13
|
Requires-Dist: loguru
|
|
14
14
|
Requires-Dist: pycryptodome>=3.20.0
|
|
15
|
+
Dynamic: license-file
|
|
15
16
|
|
|
16
17
|
[](https://github.com/id-ai-labo/settingsclass/actions/workflows/tests.yml)
|
|
17
|
-
[](https://github.com/id-ai-labo/settingsclass/blob/main/tests/reports/www/index.html)
|
|
18
19
|
|
|
19
20
|
|
|
20
21
|
# settingsclass
|
|
@@ -34,17 +35,18 @@ In this example only key concepts are presented and assumes you like tinkering m
|
|
|
34
35
|
**If you are unfamiliar with dataclass or configparser, or would like a more detailed explanation skip to example 2**
|
|
35
36
|
|
|
36
37
|
```
|
|
37
|
-
from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
38
|
+
from settingsclass import settingsclass, SettingsTypeHints, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
38
39
|
|
|
39
40
|
@settingsclass
|
|
40
|
-
class WebConfig:
|
|
41
|
+
class WebConfig(SettingsTypeHints):
|
|
41
42
|
class console:
|
|
42
43
|
language: str = "en"
|
|
43
44
|
machine_id: RandomString[4] = ""
|
|
44
45
|
backdoor_password: Encrypted[RandomString[14, 20]] = ""
|
|
45
46
|
debug_pin: Encrypted[RandomInt[1000, 9999]] = 0
|
|
46
|
-
|
|
47
|
+
maximum_message_per_second: int = 5
|
|
47
48
|
colored_output: Hidden[bool] = True
|
|
49
|
+
"""Disable if the console prints the color code characters such as `^[[31mError!^[[0m`"""
|
|
48
50
|
|
|
49
51
|
class agent:
|
|
50
52
|
api_key: Encrypted[str] = ""
|
|
@@ -53,16 +55,16 @@ class WebConfig:
|
|
|
53
55
|
# Save to or read from "config.ini". Custom path can also be passed
|
|
54
56
|
config = WebConfig()
|
|
55
57
|
|
|
56
|
-
# Hinting a type as RandomInt, RandomFloat
|
|
57
|
-
#
|
|
58
|
+
# Hinting a type as RandomInt, RandomFloat or RandomString will cause
|
|
59
|
+
# the class instantiation to generate a primitive within the specified limits
|
|
58
60
|
# The default value after [=] is ignored
|
|
59
61
|
m_id = config.console.machine_id
|
|
60
|
-
print(f'{m_id} w/ {type(m_id)}) # prints a four character <string> e.g. 4G_b
|
|
62
|
+
print(f'{m_id} w/ {type(m_id)}') # prints a four character <string> e.g. 4G_b
|
|
61
63
|
|
|
62
64
|
# Instance variables type hinted with Encrypted[type] return objects of their
|
|
63
65
|
# encapsulated types, but are encrypted when saving to disk
|
|
64
66
|
dbp = config.console.debug_pin
|
|
65
|
-
print(f'{dbp} w/ {type(dbp)}) # prints a 4 digit int e.g. "4521 w/ <class 'int'>"
|
|
67
|
+
print(f'{dbp} w/ {type(dbp)}') # prints a 4 digit int e.g. "4521 w/ <class 'int'>"
|
|
66
68
|
|
|
67
69
|
# The config.ini file will have the value encrypted similar to:
|
|
68
70
|
# debug_pin = ?ENC22e6de0f80d81f54fbae752d27cd5663e693758554d3520466e7c90423fd3997
|
|
@@ -72,9 +74,10 @@ print(f'{dbp} w/ {type(dbp)}) # prints a 4 digit int e.g. "4521 w/ <class 'int'>
|
|
|
72
74
|
|
|
73
75
|
|
|
74
76
|
# Hidden[type] variable also generate values of their encapsulated types,
|
|
75
|
-
# and are not saved/read from the config file, unless already present
|
|
77
|
+
# and are not saved/read from the config file, unless already present.
|
|
78
|
+
# The string directly below it is treated as a docstring and is shown when hovered over the member
|
|
76
79
|
co = config.console.colored_output
|
|
77
|
-
print(f'{co} w/ {type(co)}) # prints "True w/ <class 'bool'>"
|
|
80
|
+
print(f'{co} w/ {type(co)}') # prints "True w/ <class 'bool'>"
|
|
78
81
|
|
|
79
82
|
# ---
|
|
80
83
|
# Modified instances can be saved to an arbitrary path
|
|
@@ -105,10 +108,10 @@ The appropriate choice during definition seems to be <code>class Settings</code>
|
|
|
105
108
|
|
|
106
109
|
|
|
107
110
|
```
|
|
108
|
-
from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
111
|
+
from settingsclass import settingsclass, SettingsTypeHints, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
109
112
|
|
|
110
113
|
@settingsclass
|
|
111
|
-
class WebConfig:
|
|
114
|
+
class WebConfig(SettingsTypeHints):
|
|
112
115
|
class console:
|
|
113
116
|
# We would like to support multiple languages.
|
|
114
117
|
# This uses language codes, as such it will be stored as a string
|
|
@@ -186,7 +189,7 @@ api_key =
|
|
|
186
189
|
seed = 8881.079
|
|
187
190
|
```
|
|
188
191
|
|
|
189
|
-
We would like
|
|
192
|
+
We would like 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
193
|
|
|
191
194
|
```
|
|
192
195
|
[console]
|
|
@@ -216,7 +219,7 @@ api_key = ?ENCd60d7fad60db92ace78261377c629ebad7926916bcae90a4a8aea5a2c296e4f8c7
|
|
|
216
219
|
seed = 8881.079
|
|
217
220
|
```
|
|
218
221
|
|
|
219
|
-
We can also print the whole class, or
|
|
222
|
+
We can also print the whole class, or one of its sections. Encrypted values are printed decrypted, in plain text, so care needs to be taken when logging them.
|
|
220
223
|
|
|
221
224
|
```
|
|
222
225
|
print(f"Complete class:\n{config}")
|
|
@@ -260,7 +263,7 @@ This should print a float value followed by the confirmed float type.
|
|
|
260
263
|
|
|
261
264
|
`Value 8881.079 with type <class 'float'>`
|
|
262
265
|
|
|
263
|
-
*The precision of the floats can be set
|
|
266
|
+
*The precision of the floats can be set with the third parameter, e.g. `RandomFloat[0, 2, 5]`*
|
|
264
267
|
|
|
265
268
|
### Manual saving
|
|
266
269
|
|
|
@@ -268,7 +271,7 @@ Continuing the scenario, let's say that we have a webpage where the admin can ch
|
|
|
268
271
|
We would like to save to disk as to use the same value after the program restarts.
|
|
269
272
|
We can do this using the `settingsclass` member function `save_to_file`.
|
|
270
273
|
|
|
271
|
-
For this example, the admin has changed the value to TIG1. The relevant code would have the same
|
|
274
|
+
For this example, the admin has changed the value to TIG1. The relevant code would have the same effect as below:
|
|
272
275
|
```
|
|
273
276
|
config.console.machine_id = "TIG1"
|
|
274
277
|
```
|
|
@@ -288,7 +291,7 @@ As the above code demonstrates `save_to_file` can be called without a parameter,
|
|
|
288
291
|
|
|
289
292
|
Let's check the changed values between the two files:
|
|
290
293
|
```
|
|
291
|
-
old_value = config.console.machine_id #
|
|
294
|
+
old_value = config.console.machine_id # str is immutable, therefore copy etc. is not needed
|
|
292
295
|
|
|
293
296
|
# re-read from disk
|
|
294
297
|
config = WebConfig()
|
|
@@ -305,7 +308,7 @@ print(f"Backup = {config_bk.console.machine_id}")
|
|
|
305
308
|
|
|
306
309
|
## Type checking
|
|
307
310
|
|
|
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
|
|
311
|
+
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 float.
|
|
309
312
|
```
|
|
310
313
|
config.agent.seed = "abcd"
|
|
311
314
|
config.save_to_file()
|
|
@@ -329,7 +332,7 @@ This will output e.g. `11392.713`
|
|
|
329
332
|
|
|
330
333
|
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
334
|
|
|
332
|
-
To simulate this, we set the following
|
|
335
|
+
To simulate this, we set the following two 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
336
|
|
|
334
337
|
```
|
|
335
338
|
config.console.language = 3
|
|
@@ -345,15 +348,15 @@ config = WebConfig()
|
|
|
345
348
|
lang = config.console.language
|
|
346
349
|
m_id = config.console.machine_id
|
|
347
350
|
print(f"Lang = {lang} of type {type(lang)}")
|
|
348
|
-
print(f"
|
|
351
|
+
print(f"Machine ID = {m_id} of type {type(m_id)}")
|
|
349
352
|
```
|
|
350
353
|
|
|
351
354
|
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
355
|
```
|
|
353
|
-
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:576 - The parameter <
|
|
354
|
-
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:560 - The parameter <
|
|
356
|
+
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:576 - The parameter <language> in section <console> with value 3 of the settings file is a string but looks like a int
|
|
357
|
+
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:560 - The parameter <machine_id> in section <console> with value False of the settings file is a string but looks like a bool
|
|
355
358
|
Lang = 3 of type <class 'str'>
|
|
356
|
-
|
|
359
|
+
Machine ID = False of type <class 'str'>
|
|
357
360
|
```
|
|
358
361
|
|
|
359
362
|
## Advanced settings
|
|
@@ -446,7 +449,7 @@ Python 3.11+
|
|
|
446
449
|
|
|
447
450
|
Settings provided to the decorator will be shared across class instances. Settings provided at object instantiation take precedence.
|
|
448
451
|
|
|
449
|
-
`@settingsclass(env_prefix: str = "",
|
|
452
|
+
`@settingsclass(env_prefix: str | None = "", encryption_key: str | tuple[Callable[[Any], bytes], Callable[[bytes], str]] | None = None, _salt: bytes | None = None)`
|
|
450
453
|
|
|
451
454
|
### Use cases:
|
|
452
455
|
1. No arguments
|
|
@@ -458,40 +461,83 @@ class Settings:
|
|
|
458
461
|
```
|
|
459
462
|
---
|
|
460
463
|
2. Specific arguments
|
|
461
|
-
|
|
462
|
-
Specifying an encryption key
|
|
464
|
+
The file path is passed to the constructor. **If a folder `my_folder` is specified, the class will look for `my_folder/config.ini`**
|
|
465
|
+
Specifying an encryption key in the decorator means that all instances of the class will use that key, unless a different one is passed to the constructor.
|
|
463
466
|
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
467
|
```
|
|
465
|
-
@settingsclass(
|
|
468
|
+
@settingsclass(encryption_key="my_encryption_key", _salt=b'\x87\x14~\x88\xf8\xfd\xb3&\xe2\xd4\xd9|@\xfb\x80\x9e')
|
|
466
469
|
class Settings:
|
|
467
470
|
[...]
|
|
471
|
+
|
|
472
|
+
conf = Settings("webconfig.ini")
|
|
468
473
|
```
|
|
469
474
|
---
|
|
470
|
-
3. In-memory only settings/user custom file type
|
|
475
|
+
3. In-memory only settings/user custom file type
|
|
476
|
+
Passing `None` as the path keeps the settings in memory only, no file is read or written.
|
|
471
477
|
```
|
|
472
|
-
@settingsclass
|
|
478
|
+
@settingsclass
|
|
473
479
|
class Settings:
|
|
474
480
|
[...]
|
|
481
|
+
|
|
482
|
+
conf = Settings(None)
|
|
475
483
|
```
|
|
476
484
|
|
|
477
485
|
The file can also be saved later manually using
|
|
478
486
|
```
|
|
479
|
-
conf = Settings(None)
|
|
480
487
|
conf.save_to_file("now_im_ready.ini")
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
## Type checker support (optional)
|
|
491
|
+
|
|
492
|
+
The decorator adds its members (e.g. `save_to_file`, `update_from` and the constructor parameters) at runtime, which static type checkers such as Pylance/Pyright or mypy cannot see. As a result, the IDE may not offer auto-completion for them, or may even report them as errors.
|
|
493
|
+
To make them visible, inherit from `SettingsTypeHints`:
|
|
481
494
|
|
|
482
495
|
```
|
|
496
|
+
from settingsclass import settingsclass, SettingsTypeHints
|
|
497
|
+
|
|
498
|
+
@settingsclass
|
|
499
|
+
class Settings(SettingsTypeHints):
|
|
500
|
+
class program:
|
|
501
|
+
lang: str = "en"
|
|
502
|
+
|
|
503
|
+
conf = Settings("config.ini", env_prefix="APP") # parameters are now hinted
|
|
504
|
+
conf.save_to_file("backup.ini") # recognized by the type checker
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
This import is completely optional: `SettingsTypeHints` only contains type declarations and has no effect at runtime; the decorated class behaves identically with or without it.
|
|
483
508
|
|
|
484
509
|
## Constructor
|
|
485
510
|
|
|
486
|
-
|
|
511
|
+
`Settings(path: str | None = "config.ini", secret_config_path: str | None = "/run/secrets/flask_settings", case_sensitive: bool = False, *, env_prefix: str | None = "", encryption_key = None)`
|
|
512
|
+
|
|
513
|
+
- `path`: the ini file to read from and write to. If it does not exist, it is generated with the default values. `None` keeps the settings in memory only
|
|
514
|
+
- `secret_config_path`: if this file exists, it is used instead of `path` (see [Docker secrets](https://docs.docker.com/engine/swarm/secrets/)). `None` disables it
|
|
515
|
+
- `case_sensitive`: if True, section and variable names are case sensitive
|
|
516
|
+
- `env_prefix` and `encryption_key` override the values set in the decorator. `_salt` can only be set in the decorator
|
|
517
|
+
|
|
518
|
+
## Environment variables
|
|
519
|
+
|
|
520
|
+
After the ini file is loaded, each value can be overridden by an environment variable named `<PREFIX>_<SECTION>_<VARIABLE>` (upper case), where the prefix is `env_prefix`. With the default `env_prefix=""` the name is only `<SECTION>_<VARIABLE>`, e.g. `CONSOLE_LANGUAGE`. Setting `env_prefix=None` disables the check.
|
|
521
|
+
Values are cast to the hinted type; lists and tuples are parsed as JSON (e.g. `["a", "b"]`). They are not written to the ini file when loading, but `save_to_file` saves the current values, including these.
|
|
522
|
+
|
|
523
|
+
```
|
|
524
|
+
@settingsclass(env_prefix="APP")
|
|
525
|
+
class Settings:
|
|
526
|
+
class console:
|
|
527
|
+
language: str = "en"
|
|
528
|
+
|
|
529
|
+
# with APP_CONSOLE_LANGUAGE=ja set in the environment
|
|
530
|
+
conf = Settings()
|
|
531
|
+
print(conf.console.language) # ja
|
|
532
|
+
```
|
|
487
533
|
|
|
488
534
|
|
|
489
535
|
## Variable types
|
|
490
536
|
|
|
491
537
|
### Random String
|
|
492
|
-
`RandomString[
|
|
538
|
+
`RandomString[min_length, max_length=-1, *, random_function: Callable = secrets.token_urlsafe]`
|
|
493
539
|
|
|
494
|
-
Generates a random string between the specified lengths. If `
|
|
540
|
+
Generates a random string between the specified lengths. If `max_length` is not specified, the string will have a fixed length of `min_length`. Optionally 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
541
|
**The default value specified by user is ignored.**
|
|
496
542
|
|
|
497
543
|
### RandomInt[min_value, max_value, /, random_function] / RandomFloat[~]
|
|
@@ -508,9 +554,9 @@ The parameter specified will not be written to the file when specified, but will
|
|
|
508
554
|
### Encrypted[type]
|
|
509
555
|
Encryption is based on AES128 (256 is slower with no practical benefits).
|
|
510
556
|
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
|
|
512
|
-
|
|
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
|
|
557
|
+
This can be overwritten by specifying `encryption_key` in the decorator (per class) or in the constructor (per object).
|
|
558
|
+
The key can be either a string, or a tuple of `(encrypt, decrypt)` functions replacing the default encryption method: `encrypt` receives the value and returns `bytes`, `decrypt` receives those `bytes` and returns a `str`.
|
|
559
|
+
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 also be specified in binary string form, using the `_salt` decorator argument. Per object specification is not supported, as it is not the intended use-case.
|
|
514
560
|
An example of a full specification would be:
|
|
515
561
|
|
|
516
562
|
```
|
|
@@ -529,11 +575,11 @@ Supports any type that can be cast to string
|
|
|
529
575
|
|
|
530
576
|
### Saving to an ini file
|
|
531
577
|
`save_to_file(self, path=None)`
|
|
532
|
-
Saves
|
|
578
|
+
Saves the 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
579
|
|
|
534
580
|
### Loading from an ini file
|
|
535
|
-
`update_from(self, config: configparser.ConfigParser,
|
|
581
|
+
`update_from(self, config: configparser.ConfigParser, encrypted_only: bool = False) -> list[str]`
|
|
536
582
|
|
|
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
|
|
583
|
+
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. `encrypted_only=True` is not implemented yet.
|
|
538
584
|
|
|
539
585
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
[](https://github.com/id-ai-labo/settingsclass/actions/workflows/tests.yml)
|
|
2
|
-
[](https://github.com/id-ai-labo/settingsclass/blob/main/tests/reports/www/index.html)
|
|
3
3
|
|
|
4
4
|
|
|
5
5
|
# settingsclass
|
|
@@ -19,17 +19,18 @@ In this example only key concepts are presented and assumes you like tinkering m
|
|
|
19
19
|
**If you are unfamiliar with dataclass or configparser, or would like a more detailed explanation skip to example 2**
|
|
20
20
|
|
|
21
21
|
```
|
|
22
|
-
from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
22
|
+
from settingsclass import settingsclass, SettingsTypeHints, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
23
23
|
|
|
24
24
|
@settingsclass
|
|
25
|
-
class WebConfig:
|
|
25
|
+
class WebConfig(SettingsTypeHints):
|
|
26
26
|
class console:
|
|
27
27
|
language: str = "en"
|
|
28
28
|
machine_id: RandomString[4] = ""
|
|
29
29
|
backdoor_password: Encrypted[RandomString[14, 20]] = ""
|
|
30
30
|
debug_pin: Encrypted[RandomInt[1000, 9999]] = 0
|
|
31
|
-
|
|
31
|
+
maximum_message_per_second: int = 5
|
|
32
32
|
colored_output: Hidden[bool] = True
|
|
33
|
+
"""Disable if the console prints the color code characters such as `^[[31mError!^[[0m`"""
|
|
33
34
|
|
|
34
35
|
class agent:
|
|
35
36
|
api_key: Encrypted[str] = ""
|
|
@@ -38,16 +39,16 @@ class WebConfig:
|
|
|
38
39
|
# Save to or read from "config.ini". Custom path can also be passed
|
|
39
40
|
config = WebConfig()
|
|
40
41
|
|
|
41
|
-
# Hinting a type as RandomInt, RandomFloat
|
|
42
|
-
#
|
|
42
|
+
# Hinting a type as RandomInt, RandomFloat or RandomString will cause
|
|
43
|
+
# the class instantiation to generate a primitive within the specified limits
|
|
43
44
|
# The default value after [=] is ignored
|
|
44
45
|
m_id = config.console.machine_id
|
|
45
|
-
print(f'{m_id} w/ {type(m_id)}) # prints a four character <string> e.g. 4G_b
|
|
46
|
+
print(f'{m_id} w/ {type(m_id)}') # prints a four character <string> e.g. 4G_b
|
|
46
47
|
|
|
47
48
|
# Instance variables type hinted with Encrypted[type] return objects of their
|
|
48
49
|
# encapsulated types, but are encrypted when saving to disk
|
|
49
50
|
dbp = config.console.debug_pin
|
|
50
|
-
print(f'{dbp} w/ {type(dbp)}) # prints a 4 digit int e.g. "4521 w/ <class 'int'>"
|
|
51
|
+
print(f'{dbp} w/ {type(dbp)}') # prints a 4 digit int e.g. "4521 w/ <class 'int'>"
|
|
51
52
|
|
|
52
53
|
# The config.ini file will have the value encrypted similar to:
|
|
53
54
|
# debug_pin = ?ENC22e6de0f80d81f54fbae752d27cd5663e693758554d3520466e7c90423fd3997
|
|
@@ -57,9 +58,10 @@ print(f'{dbp} w/ {type(dbp)}) # prints a 4 digit int e.g. "4521 w/ <class 'int'>
|
|
|
57
58
|
|
|
58
59
|
|
|
59
60
|
# Hidden[type] variable also generate values of their encapsulated types,
|
|
60
|
-
# and are not saved/read from the config file, unless already present
|
|
61
|
+
# and are not saved/read from the config file, unless already present.
|
|
62
|
+
# The string directly below it is treated as a docstring and is shown when hovered over the member
|
|
61
63
|
co = config.console.colored_output
|
|
62
|
-
print(f'{co} w/ {type(co)}) # prints "True w/ <class 'bool'>"
|
|
64
|
+
print(f'{co} w/ {type(co)}') # prints "True w/ <class 'bool'>"
|
|
63
65
|
|
|
64
66
|
# ---
|
|
65
67
|
# Modified instances can be saved to an arbitrary path
|
|
@@ -90,10 +92,10 @@ The appropriate choice during definition seems to be <code>class Settings</code>
|
|
|
90
92
|
|
|
91
93
|
|
|
92
94
|
```
|
|
93
|
-
from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
95
|
+
from settingsclass import settingsclass, SettingsTypeHints, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
|
|
94
96
|
|
|
95
97
|
@settingsclass
|
|
96
|
-
class WebConfig:
|
|
98
|
+
class WebConfig(SettingsTypeHints):
|
|
97
99
|
class console:
|
|
98
100
|
# We would like to support multiple languages.
|
|
99
101
|
# This uses language codes, as such it will be stored as a string
|
|
@@ -171,7 +173,7 @@ api_key =
|
|
|
171
173
|
seed = 8881.079
|
|
172
174
|
```
|
|
173
175
|
|
|
174
|
-
We would like
|
|
176
|
+
We would like 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.
|
|
175
177
|
|
|
176
178
|
```
|
|
177
179
|
[console]
|
|
@@ -201,7 +203,7 @@ api_key = ?ENCd60d7fad60db92ace78261377c629ebad7926916bcae90a4a8aea5a2c296e4f8c7
|
|
|
201
203
|
seed = 8881.079
|
|
202
204
|
```
|
|
203
205
|
|
|
204
|
-
We can also print the whole class, or
|
|
206
|
+
We can also print the whole class, or one of its sections. Encrypted values are printed decrypted, in plain text, so care needs to be taken when logging them.
|
|
205
207
|
|
|
206
208
|
```
|
|
207
209
|
print(f"Complete class:\n{config}")
|
|
@@ -245,7 +247,7 @@ This should print a float value followed by the confirmed float type.
|
|
|
245
247
|
|
|
246
248
|
`Value 8881.079 with type <class 'float'>`
|
|
247
249
|
|
|
248
|
-
*The precision of the floats can be set
|
|
250
|
+
*The precision of the floats can be set with the third parameter, e.g. `RandomFloat[0, 2, 5]`*
|
|
249
251
|
|
|
250
252
|
### Manual saving
|
|
251
253
|
|
|
@@ -253,7 +255,7 @@ Continuing the scenario, let's say that we have a webpage where the admin can ch
|
|
|
253
255
|
We would like to save to disk as to use the same value after the program restarts.
|
|
254
256
|
We can do this using the `settingsclass` member function `save_to_file`.
|
|
255
257
|
|
|
256
|
-
For this example, the admin has changed the value to TIG1. The relevant code would have the same
|
|
258
|
+
For this example, the admin has changed the value to TIG1. The relevant code would have the same effect as below:
|
|
257
259
|
```
|
|
258
260
|
config.console.machine_id = "TIG1"
|
|
259
261
|
```
|
|
@@ -273,7 +275,7 @@ As the above code demonstrates `save_to_file` can be called without a parameter,
|
|
|
273
275
|
|
|
274
276
|
Let's check the changed values between the two files:
|
|
275
277
|
```
|
|
276
|
-
old_value = config.console.machine_id #
|
|
278
|
+
old_value = config.console.machine_id # str is immutable, therefore copy etc. is not needed
|
|
277
279
|
|
|
278
280
|
# re-read from disk
|
|
279
281
|
config = WebConfig()
|
|
@@ -290,7 +292,7 @@ print(f"Backup = {config_bk.console.machine_id}")
|
|
|
290
292
|
|
|
291
293
|
## Type checking
|
|
292
294
|
|
|
293
|
-
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
|
|
295
|
+
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 float.
|
|
294
296
|
```
|
|
295
297
|
config.agent.seed = "abcd"
|
|
296
298
|
config.save_to_file()
|
|
@@ -314,7 +316,7 @@ This will output e.g. `11392.713`
|
|
|
314
316
|
|
|
315
317
|
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.
|
|
316
318
|
|
|
317
|
-
To simulate this, we set the following
|
|
319
|
+
To simulate this, we set the following two 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.
|
|
318
320
|
|
|
319
321
|
```
|
|
320
322
|
config.console.language = 3
|
|
@@ -330,15 +332,15 @@ config = WebConfig()
|
|
|
330
332
|
lang = config.console.language
|
|
331
333
|
m_id = config.console.machine_id
|
|
332
334
|
print(f"Lang = {lang} of type {type(lang)}")
|
|
333
|
-
print(f"
|
|
335
|
+
print(f"Machine ID = {m_id} of type {type(m_id)}")
|
|
334
336
|
```
|
|
335
337
|
|
|
336
338
|
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
|
|
337
339
|
```
|
|
338
|
-
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:576 - The parameter <
|
|
339
|
-
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:560 - The parameter <
|
|
340
|
+
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:576 - The parameter <language> in section <console> with value 3 of the settings file is a string but looks like a int
|
|
341
|
+
2024-XX-YY HH:MM:SS.MSS | WARNING | settingsclass.settingsclass:warn_confusing_types:560 - The parameter <machine_id> in section <console> with value False of the settings file is a string but looks like a bool
|
|
340
342
|
Lang = 3 of type <class 'str'>
|
|
341
|
-
|
|
343
|
+
Machine ID = False of type <class 'str'>
|
|
342
344
|
```
|
|
343
345
|
|
|
344
346
|
## Advanced settings
|
|
@@ -431,7 +433,7 @@ Python 3.11+
|
|
|
431
433
|
|
|
432
434
|
Settings provided to the decorator will be shared across class instances. Settings provided at object instantiation take precedence.
|
|
433
435
|
|
|
434
|
-
`@settingsclass(env_prefix: str = "",
|
|
436
|
+
`@settingsclass(env_prefix: str | None = "", encryption_key: str | tuple[Callable[[Any], bytes], Callable[[bytes], str]] | None = None, _salt: bytes | None = None)`
|
|
435
437
|
|
|
436
438
|
### Use cases:
|
|
437
439
|
1. No arguments
|
|
@@ -443,40 +445,83 @@ class Settings:
|
|
|
443
445
|
```
|
|
444
446
|
---
|
|
445
447
|
2. Specific arguments
|
|
446
|
-
|
|
447
|
-
Specifying an encryption key
|
|
448
|
+
The file path is passed to the constructor. **If a folder `my_folder` is specified, the class will look for `my_folder/config.ini`**
|
|
449
|
+
Specifying an encryption key in the decorator means that all instances of the class will use that key, unless a different one is passed to the constructor.
|
|
448
450
|
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.
|
|
449
451
|
```
|
|
450
|
-
@settingsclass(
|
|
452
|
+
@settingsclass(encryption_key="my_encryption_key", _salt=b'\x87\x14~\x88\xf8\xfd\xb3&\xe2\xd4\xd9|@\xfb\x80\x9e')
|
|
451
453
|
class Settings:
|
|
452
454
|
[...]
|
|
455
|
+
|
|
456
|
+
conf = Settings("webconfig.ini")
|
|
453
457
|
```
|
|
454
458
|
---
|
|
455
|
-
3. In-memory only settings/user custom file type
|
|
459
|
+
3. In-memory only settings/user custom file type
|
|
460
|
+
Passing `None` as the path keeps the settings in memory only, no file is read or written.
|
|
456
461
|
```
|
|
457
|
-
@settingsclass
|
|
462
|
+
@settingsclass
|
|
458
463
|
class Settings:
|
|
459
464
|
[...]
|
|
465
|
+
|
|
466
|
+
conf = Settings(None)
|
|
460
467
|
```
|
|
461
468
|
|
|
462
469
|
The file can also be saved later manually using
|
|
463
470
|
```
|
|
464
|
-
conf = Settings(None)
|
|
465
471
|
conf.save_to_file("now_im_ready.ini")
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
## Type checker support (optional)
|
|
475
|
+
|
|
476
|
+
The decorator adds its members (e.g. `save_to_file`, `update_from` and the constructor parameters) at runtime, which static type checkers such as Pylance/Pyright or mypy cannot see. As a result, the IDE may not offer auto-completion for them, or may even report them as errors.
|
|
477
|
+
To make them visible, inherit from `SettingsTypeHints`:
|
|
466
478
|
|
|
467
479
|
```
|
|
480
|
+
from settingsclass import settingsclass, SettingsTypeHints
|
|
481
|
+
|
|
482
|
+
@settingsclass
|
|
483
|
+
class Settings(SettingsTypeHints):
|
|
484
|
+
class program:
|
|
485
|
+
lang: str = "en"
|
|
486
|
+
|
|
487
|
+
conf = Settings("config.ini", env_prefix="APP") # parameters are now hinted
|
|
488
|
+
conf.save_to_file("backup.ini") # recognized by the type checker
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
This import is completely optional: `SettingsTypeHints` only contains type declarations and has no effect at runtime; the decorated class behaves identically with or without it.
|
|
468
492
|
|
|
469
493
|
## Constructor
|
|
470
494
|
|
|
471
|
-
|
|
495
|
+
`Settings(path: str | None = "config.ini", secret_config_path: str | None = "/run/secrets/flask_settings", case_sensitive: bool = False, *, env_prefix: str | None = "", encryption_key = None)`
|
|
496
|
+
|
|
497
|
+
- `path`: the ini file to read from and write to. If it does not exist, it is generated with the default values. `None` keeps the settings in memory only
|
|
498
|
+
- `secret_config_path`: if this file exists, it is used instead of `path` (see [Docker secrets](https://docs.docker.com/engine/swarm/secrets/)). `None` disables it
|
|
499
|
+
- `case_sensitive`: if True, section and variable names are case sensitive
|
|
500
|
+
- `env_prefix` and `encryption_key` override the values set in the decorator. `_salt` can only be set in the decorator
|
|
501
|
+
|
|
502
|
+
## Environment variables
|
|
503
|
+
|
|
504
|
+
After the ini file is loaded, each value can be overridden by an environment variable named `<PREFIX>_<SECTION>_<VARIABLE>` (upper case), where the prefix is `env_prefix`. With the default `env_prefix=""` the name is only `<SECTION>_<VARIABLE>`, e.g. `CONSOLE_LANGUAGE`. Setting `env_prefix=None` disables the check.
|
|
505
|
+
Values are cast to the hinted type; lists and tuples are parsed as JSON (e.g. `["a", "b"]`). They are not written to the ini file when loading, but `save_to_file` saves the current values, including these.
|
|
506
|
+
|
|
507
|
+
```
|
|
508
|
+
@settingsclass(env_prefix="APP")
|
|
509
|
+
class Settings:
|
|
510
|
+
class console:
|
|
511
|
+
language: str = "en"
|
|
512
|
+
|
|
513
|
+
# with APP_CONSOLE_LANGUAGE=ja set in the environment
|
|
514
|
+
conf = Settings()
|
|
515
|
+
print(conf.console.language) # ja
|
|
516
|
+
```
|
|
472
517
|
|
|
473
518
|
|
|
474
519
|
## Variable types
|
|
475
520
|
|
|
476
521
|
### Random String
|
|
477
|
-
`RandomString[
|
|
522
|
+
`RandomString[min_length, max_length=-1, *, random_function: Callable = secrets.token_urlsafe]`
|
|
478
523
|
|
|
479
|
-
Generates a random string between the specified lengths. If `
|
|
524
|
+
Generates a random string between the specified lengths. If `max_length` is not specified, the string will have a fixed length of `min_length`. Optionally 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`
|
|
480
525
|
**The default value specified by user is ignored.**
|
|
481
526
|
|
|
482
527
|
### RandomInt[min_value, max_value, /, random_function] / RandomFloat[~]
|
|
@@ -493,9 +538,9 @@ The parameter specified will not be written to the file when specified, but will
|
|
|
493
538
|
### Encrypted[type]
|
|
494
539
|
Encryption is based on AES128 (256 is slower with no practical benefits).
|
|
495
540
|
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.
|
|
496
|
-
This can be overwritten by specifying
|
|
497
|
-
|
|
498
|
-
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
|
|
541
|
+
This can be overwritten by specifying `encryption_key` in the decorator (per class) or in the constructor (per object).
|
|
542
|
+
The key can be either a string, or a tuple of `(encrypt, decrypt)` functions replacing the default encryption method: `encrypt` receives the value and returns `bytes`, `decrypt` receives those `bytes` and returns a `str`.
|
|
543
|
+
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 also be specified in binary string form, using the `_salt` decorator argument. Per object specification is not supported, as it is not the intended use-case.
|
|
499
544
|
An example of a full specification would be:
|
|
500
545
|
|
|
501
546
|
```
|
|
@@ -514,11 +559,11 @@ Supports any type that can be cast to string
|
|
|
514
559
|
|
|
515
560
|
### Saving to an ini file
|
|
516
561
|
`save_to_file(self, path=None)`
|
|
517
|
-
Saves
|
|
562
|
+
Saves the contents (including encryption) to the specified path. If the path is left as None, the file path used to load the file is used
|
|
518
563
|
|
|
519
564
|
### Loading from an ini file
|
|
520
|
-
`update_from(self, config: configparser.ConfigParser,
|
|
565
|
+
`update_from(self, config: configparser.ConfigParser, encrypted_only: bool = False) -> list[str]`
|
|
521
566
|
|
|
522
|
-
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
|
|
567
|
+
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. `encrypted_only=True` is not implemented yet.
|
|
523
568
|
|
|
524
569
|
|