settingsclass 0.1.5__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.5 → settingsclass-0.2.0}/PKG-INFO +85 -40
  2. {settingsclass-0.1.5 → settingsclass-0.2.0}/README.md +84 -39
  3. {settingsclass-0.1.5 → settingsclass-0.2.0}/README_JA.md +123 -65
  4. {settingsclass-0.1.5 → settingsclass-0.2.0}/demo.py +2 -1
  5. {settingsclass-0.1.5 → settingsclass-0.2.0}/demo_ja.py +2 -1
  6. {settingsclass-0.1.5 → settingsclass-0.2.0}/pyproject.toml +8 -2
  7. settingsclass-0.2.0/requirements-dev.txt +4 -0
  8. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass/__init__.py +2 -0
  9. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass/loc/settings.csv +1 -1
  10. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass/settingsclass.py +175 -51
  11. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass.egg-info/PKG-INFO +85 -40
  12. {settingsclass-0.1.5 → 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.2.0/tests/reports/coverage-badge.svg +1 -0
  15. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/test_localization.py +13 -14
  16. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/test_settings.py +81 -29
  17. settingsclass-0.2.0/tests/test_settings_types.py +120 -0
  18. settingsclass-0.1.5/requirements-dev.txt +0 -5
  19. settingsclass-0.1.5/tests/reports/coverage-badge.svg +0 -1
  20. {settingsclass-0.1.5 → settingsclass-0.2.0}/.github/workflows/python-publish.yml +0 -0
  21. {settingsclass-0.1.5 → settingsclass-0.2.0}/.github/workflows/tests.yml +0 -0
  22. {settingsclass-0.1.5 → settingsclass-0.2.0}/.gitignore +0 -0
  23. {settingsclass-0.1.5 → settingsclass-0.2.0}/LICENSE +0 -0
  24. {settingsclass-0.1.5 → settingsclass-0.2.0}/requirements.txt +0 -0
  25. {settingsclass-0.1.5 → settingsclass-0.2.0}/setup.cfg +0 -0
  26. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass/localizer.py +0 -0
  27. settingsclass-0.1.5/tests/__init__.py → settingsclass-0.2.0/src/settingsclass/py.typed +0 -0
  28. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass.egg-info/dependency_links.txt +0 -0
  29. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass.egg-info/requires.txt +0 -0
  30. {settingsclass-0.1.5 → settingsclass-0.2.0}/src/settingsclass.egg-info/top_level.txt +0 -0
  31. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/loc/test_strings_correct.csv +0 -0
  32. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/loc/test_strings_duplicate_key.csv +0 -0
  33. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_few.csv +0 -0
  34. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_many.csv +0 -0
  35. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/loc/test_strings_error_nostr.csv +0 -0
  36. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/loc/test_strings_half_specified.csv +0 -0
  37. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/loc/test_strings_warning.csv +0 -0
  38. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config.ini/config.ini +0 -0
  39. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_bad_type.ini +0 -0
  40. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_confusing_types.ini +0 -0
  41. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_duplicate_param.ini +0 -0
  42. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_duplicate_section.ini +0 -0
  43. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_extra_parts.ini +0 -0
  44. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_generated_good.ini +0 -0
  45. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_generated_good_half_enc.ini +0 -0
  46. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_good_case_var.ini +0 -0
  47. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_missing_section.ini +0 -0
  48. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/input/settingsclass/config_modified.ini +0 -0
  49. {settingsclass-0.1.5 → settingsclass-0.2.0}/tests/test_localization_fail_cases.py +2 -2
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: settingsclass
3
- Version: 0.1.5
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
@@ -15,7 +15,7 @@ Requires-Dist: pycryptodome>=3.20.0
15
15
  Dynamic: license-file
16
16
 
17
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)
18
- [![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)
19
19
 
20
20
 
21
21
  # settingsclass
@@ -35,17 +35,18 @@ In this example only key concepts are presented and assumes you like tinkering m
35
35
  **If you are unfamiliar with dataclass or configparser, or would like a more detailed explanation skip to example 2**
36
36
 
37
37
  ```
38
- from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
38
+ from settingsclass import settingsclass, SettingsTypeHints, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
39
39
 
40
40
  @settingsclass
41
- class WebConfig:
41
+ class WebConfig(SettingsTypeHints):
42
42
  class console:
43
43
  language: str = "en"
44
44
  machine_id: RandomString[4] = ""
45
45
  backdoor_password: Encrypted[RandomString[14, 20]] = ""
46
46
  debug_pin: Encrypted[RandomInt[1000, 9999]] = 0
47
- maxiumum_message_per_second: int = 5
47
+ maximum_message_per_second: int = 5
48
48
  colored_output: Hidden[bool] = True
49
+ """Disable if the console prints the color code characters such as `^[[31mError!^[[0m`"""
49
50
 
50
51
  class agent:
51
52
  api_key: Encrypted[str] = ""
@@ -54,16 +55,16 @@ class WebConfig:
54
55
  # Save to or read from "config.ini". Custom path can also be passed
55
56
  config = WebConfig()
56
57
 
57
- # Hinting a type as RandomInt, RandomFloat and RandomString will generate
58
- # 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
59
60
  # The default value after [=] is ignored
60
61
  m_id = config.console.machine_id
61
- 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
62
63
 
63
64
  # Instance variables type hinted with Encrypted[type] return objects of their
64
65
  # encapsulated types, but are encrypted when saving to disk
65
66
  dbp = config.console.debug_pin
66
- 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'>"
67
68
 
68
69
  # The config.ini file will have the value encrypted similar to:
69
70
  # debug_pin = ?ENC22e6de0f80d81f54fbae752d27cd5663e693758554d3520466e7c90423fd3997
@@ -73,9 +74,10 @@ print(f'{dbp} w/ {type(dbp)}) # prints a 4 digit int e.g. "4521 w/ <class 'int'>
73
74
 
74
75
 
75
76
  # Hidden[type] variable also generate values of their encapsulated types,
76
- # 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
77
79
  co = config.console.colored_output
78
- print(f'{co} w/ {type(co)}) # prints "True w/ <class 'bool'>"
80
+ print(f'{co} w/ {type(co)}') # prints "True w/ <class 'bool'>"
79
81
 
80
82
  # ---
81
83
  # Modified instances can be saved to an arbitrary path
@@ -106,10 +108,10 @@ The appropriate choice during definition seems to be <code>class Settings</code>
106
108
 
107
109
 
108
110
  ```
109
- from settingsclass import settingsclass, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
111
+ from settingsclass import settingsclass, SettingsTypeHints, RandomString, RandomInt, RandomFloat, Hidden, Encrypted
110
112
 
111
113
  @settingsclass
112
- class WebConfig:
114
+ class WebConfig(SettingsTypeHints):
113
115
  class console:
114
116
  # We would like to support multiple languages.
115
117
  # This uses language codes, as such it will be stored as a string
@@ -187,7 +189,7 @@ api_key =
187
189
  seed = 8881.079
188
190
  ```
189
191
 
190
- 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.
191
193
 
192
194
  ```
193
195
  [console]
@@ -217,7 +219,7 @@ api_key = ?ENCd60d7fad60db92ace78261377c629ebad7926916bcae90a4a8aea5a2c296e4f8c7
217
219
  seed = 8881.079
218
220
  ```
219
221
 
220
- 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.
221
223
 
222
224
  ```
223
225
  print(f"Complete class:\n{config}")
@@ -261,7 +263,7 @@ This should print a float value followed by the confirmed float type.
261
263
 
262
264
  `Value 8881.079 with type <class 'float'>`
263
265
 
264
- *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]`*
265
267
 
266
268
  ### Manual saving
267
269
 
@@ -269,7 +271,7 @@ Continuing the scenario, let's say that we have a webpage where the admin can ch
269
271
  We would like to save to disk as to use the same value after the program restarts.
270
272
  We can do this using the `settingsclass` member function `save_to_file`.
271
273
 
272
- 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:
273
275
  ```
274
276
  config.console.machine_id = "TIG1"
275
277
  ```
@@ -289,7 +291,7 @@ As the above code demonstrates `save_to_file` can be called without a parameter,
289
291
 
290
292
  Let's check the changed values between the two files:
291
293
  ```
292
- 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
293
295
 
294
296
  # re-read from disk
295
297
  config = WebConfig()
@@ -306,7 +308,7 @@ print(f"Backup = {config_bk.console.machine_id}")
306
308
 
307
309
  ## Type checking
308
310
 
309
- 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.
310
312
  ```
311
313
  config.agent.seed = "abcd"
312
314
  config.save_to_file()
@@ -330,7 +332,7 @@ This will output e.g. `11392.713`
330
332
 
331
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.
332
334
 
333
- 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.
334
336
 
335
337
  ```
336
338
  config.console.language = 3
@@ -346,15 +348,15 @@ config = WebConfig()
346
348
  lang = config.console.language
347
349
  m_id = config.console.machine_id
348
350
  print(f"Lang = {lang} of type {type(lang)}")
349
- print(f"Password = {m_id} of type {type(lang)}")
351
+ print(f"Machine ID = {m_id} of type {type(m_id)}")
350
352
  ```
351
353
 
352
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
353
355
  ```
354
- 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
355
- 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
356
358
  Lang = 3 of type <class 'str'>
357
- Password = False of type <class 'str'>
359
+ Machine ID = False of type <class 'str'>
358
360
  ```
359
361
 
360
362
  ## Advanced settings
@@ -447,7 +449,7 @@ Python 3.11+
447
449
 
448
450
  Settings provided to the decorator will be shared across class instances. Settings provided at object instantiation take precedence.
449
451
 
450
- `@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)`
451
453
 
452
454
  ### Use cases:
453
455
  1. No arguments
@@ -459,40 +461,83 @@ class Settings:
459
461
  ```
460
462
  ---
461
463
  2. Specific arguments
462
- 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`**
463
- 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.
464
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.
465
467
  ```
466
- @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')
467
469
  class Settings:
468
470
  [...]
471
+
472
+ conf = Settings("webconfig.ini")
469
473
  ```
470
474
  ---
471
- 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.
472
477
  ```
473
- @settingsclass(None)
478
+ @settingsclass
474
479
  class Settings:
475
480
  [...]
481
+
482
+ conf = Settings(None)
476
483
  ```
477
484
 
478
485
  The file can also be saved later manually using
479
486
  ```
480
- conf = Settings(None)
481
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`:
482
494
 
483
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.
484
508
 
485
509
  ## Constructor
486
510
 
487
- 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
+ ```
488
533
 
489
534
 
490
535
  ## Variable types
491
536
 
492
537
  ### Random String
493
- `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]`
494
539
 
495
- 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`
496
541
  **The default value specified by user is ignored.**
497
542
 
498
543
  ### RandomInt[min_value, max_value, /, random_function] / RandomFloat[~]
@@ -509,9 +554,9 @@ The parameter specified will not be written to the file when specified, but will
509
554
  ### Encrypted[type]
510
555
  Encryption is based on AES128 (256 is slower with no practical benefits).
511
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.
512
- This can be overwritten by specifying the `encryption_key` per object or `common_encryption_key` at the class definition level.
513
- This can be either a string or a function handle that will be called as is.
514
- 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.
515
560
  An example of a full specification would be:
516
561
 
517
562
  ```
@@ -530,11 +575,11 @@ Supports any type that can be cast to string
530
575
 
531
576
  ### Saving to an ini file
532
577
  `save_to_file(self, path=None)`
533
- 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
534
579
 
535
580
  ### Loading from an ini file
536
- `update_from(self, config: configparser.ConfigParser, secrets_only: False) -> list[str]`
581
+ `update_from(self, config: configparser.ConfigParser, encrypted_only: bool = False) -> list[str]`
537
582
 
538
- 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.
539
584
 
540
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