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.
Files changed (49) hide show
  1. {settingsclass-0.1.4 → settingsclass-0.2.0}/PKG-INFO +87 -41
  2. {settingsclass-0.1.4 → settingsclass-0.2.0}/README.md +84 -39
  3. {settingsclass-0.1.4 → settingsclass-0.2.0}/README_JA.md +123 -65
  4. {settingsclass-0.1.4 → settingsclass-0.2.0}/demo.py +2 -1
  5. {settingsclass-0.1.4 → settingsclass-0.2.0}/demo_ja.py +2 -1
  6. {settingsclass-0.1.4 → settingsclass-0.2.0}/pyproject.toml +8 -2
  7. settingsclass-0.2.0/requirements-dev.txt +4 -0
  8. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/__init__.py +2 -0
  9. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/loc/settings.csv +8 -4
  10. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/settingsclass.py +376 -74
  11. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/PKG-INFO +87 -41
  12. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/SOURCES.txt +2 -0
  13. settingsclass-0.2.0/tests/__init__.py +0 -0
  14. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config.ini/config.ini +3 -1
  15. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_bad_type.ini +3 -1
  16. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_confusing_types.ini +1 -1
  17. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_duplicate_param.ini +1 -1
  18. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_duplicate_section.ini +2 -2
  19. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_extra_parts.ini +1 -1
  20. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_generated_good.ini +3 -1
  21. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_generated_good_half_enc.ini +1 -1
  22. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_good_case_var.ini +4 -2
  23. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_modified.ini +3 -1
  24. settingsclass-0.2.0/tests/reports/coverage-badge.svg +1 -0
  25. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/test_localization.py +13 -14
  26. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/test_settings.py +184 -58
  27. settingsclass-0.2.0/tests/test_settings_types.py +120 -0
  28. settingsclass-0.1.4/requirements-dev.txt +0 -5
  29. settingsclass-0.1.4/tests/reports/coverage-badge.svg +0 -1
  30. {settingsclass-0.1.4 → settingsclass-0.2.0}/.github/workflows/python-publish.yml +0 -0
  31. {settingsclass-0.1.4 → settingsclass-0.2.0}/.github/workflows/tests.yml +0 -0
  32. {settingsclass-0.1.4 → settingsclass-0.2.0}/.gitignore +0 -0
  33. {settingsclass-0.1.4 → settingsclass-0.2.0}/LICENSE +0 -0
  34. {settingsclass-0.1.4 → settingsclass-0.2.0}/requirements.txt +0 -0
  35. {settingsclass-0.1.4 → settingsclass-0.2.0}/setup.cfg +0 -0
  36. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass/localizer.py +0 -0
  37. settingsclass-0.1.4/tests/__init__.py → settingsclass-0.2.0/src/settingsclass/py.typed +0 -0
  38. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/dependency_links.txt +0 -0
  39. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/requires.txt +0 -0
  40. {settingsclass-0.1.4 → settingsclass-0.2.0}/src/settingsclass.egg-info/top_level.txt +0 -0
  41. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_correct.csv +0 -0
  42. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_duplicate_key.csv +0 -0
  43. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_few.csv +0 -0
  44. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_many.csv +0 -0
  45. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_nostr.csv +0 -0
  46. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_half_specified.csv +0 -0
  47. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/loc/test_strings_warning.csv +0 -0
  48. {settingsclass-0.1.4 → settingsclass-0.2.0}/tests/input/settingsclass/config_missing_section.ini +0 -0
  49. {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
1
+ Metadata-Version: 2.4
2
2
  Name: settingsclass
3
- Version: 0.1.4
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
  [![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
+ [![Tests Status](https://raw.githubusercontent.com/id-ai-labo/settingsclass/main/tests/reports/coverage-badge.svg?dummy=8484744)](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
- maxiumum_message_per_second: int = 5
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 and RandomString will generate
57
- # will cause the class instantiation to generate a primitive within specified limits
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 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.
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 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
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 by using the precision parameter `RandomFloat[0, 2, precision=5]`*
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 affect as below:
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 # int, therefore copy etc. is not needed
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 int.
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 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.
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"Password = {m_id} of type {type(lang)}")
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 <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
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
- Password = False of type <class 'str'>
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 = "", common_encryption_key: type[str | Callable[[Any], str] | None] = None, salt: bytes = None)`
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
- 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.
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(file_path = "webconfig.ini", common_encryption_key = "my_encryption_key", _salt=b'\x87\x14~\x88\xf8\xfd\xb3&\xe2\xd4\xd9|@\xfb\x80\x9e')
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(None)
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
- 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.
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[max_length, min_length=-1, /, random_function: Callable = secrets.token_urlsafe]`
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 `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`
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 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.
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 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
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, secrets_only: False) -> list[str]`
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
  [![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)
2
- [![Tests Status](./tests/reports/coverage-badge.svg?dummy=8484744)](./tests/reports/www/index.html)
2
+ [![Tests Status](https://raw.githubusercontent.com/id-ai-labo/settingsclass/main/tests/reports/coverage-badge.svg?dummy=8484744)](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
- maxiumum_message_per_second: int = 5
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 and RandomString will generate
42
- # will cause the class instantiation to generate a primitive within specified limits
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 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.
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 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
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 by using the precision parameter `RandomFloat[0, 2, precision=5]`*
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 affect as below:
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 # int, therefore copy etc. is not needed
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 int.
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 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.
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"Password = {m_id} of type {type(lang)}")
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 <console> in section <language> with value 3 of the settings file is a string but looks like a int
339
- 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
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
- Password = False of type <class 'str'>
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 = "", common_encryption_key: type[str | Callable[[Any], str] | None] = None, salt: bytes = None)`
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
- 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`**
447
- Specifying an encryption key will mean that all subsequent instantiations of the class will use that key unless otherwise specified.
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(file_path = "webconfig.ini", common_encryption_key = "my_encryption_key", _salt=b'\x87\x14~\x88\xf8\xfd\xb3&\xe2\xd4\xd9|@\xfb\x80\x9e')
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(None)
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
- 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.
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[max_length, min_length=-1, /, random_function: Callable = secrets.token_urlsafe]`
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 `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`
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 the `encryption_key` per object or `common_encryption_key` at the class definition level.
497
- This can be either a string or a function handle that will be called as is.
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 be also be specified in binary string form. Per class specification is not supported, as it is not the intended use-case.
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 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
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, secrets_only: False) -> list[str]`
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