aa-toolkit-settings 0.1.0a1__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.
- aa_toolkit_settings-0.1.0a1/LICENSE +21 -0
- aa_toolkit_settings-0.1.0a1/PKG-INFO +215 -0
- aa_toolkit_settings-0.1.0a1/README.md +204 -0
- aa_toolkit_settings-0.1.0a1/pyproject.toml +19 -0
- aa_toolkit_settings-0.1.0a1/pyproject.toml.orig +19 -0
- aa_toolkit_settings-0.1.0a1/src/aa_settings/__init__.py +17 -0
- aa_toolkit_settings-0.1.0a1/src/aa_settings/_errors.py +233 -0
- aa_toolkit_settings-0.1.0a1/src/aa_settings/_secrets.py +76 -0
- aa_toolkit_settings-0.1.0a1/src/aa_settings/_settings.py +78 -0
- aa_toolkit_settings-0.1.0a1/src/aa_settings/_store.py +248 -0
- aa_toolkit_settings-0.1.0a1/src/aa_settings/py.typed +0 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aaron Aco
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: aa-toolkit-settings
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Settings for apps, on top of pydantic-settings.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Dist: keyring>=25.7.0
|
|
8
|
+
Requires-Dist: pydantic-settings>=2.16.2
|
|
9
|
+
Requires-Python: >=3.14
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
|
|
12
|
+
# aa-toolkit-settings
|
|
13
|
+
|
|
14
|
+
Settings and Secrets for apps, on top of [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/).
|
|
15
|
+
|
|
16
|
+
An app describes its Settings as a typed class and loads them from values passed in code, environment variables, a `.env` file, the Secret store and defaults, in that order. A `Secret` prints and saves as `[REDACTED]` and reveals its real value only when code asks for it.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
Install it from the toolkit's GitHub repo, pinned to a version tag:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
uv add "aa-toolkit-settings @ git+https://github.com/aaronaco/aa-toolkit@settings-v0.1.0#subdirectory=packages/aa-toolkit-settings"
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Use
|
|
27
|
+
|
|
28
|
+
Subclass `BaseSettings`, list your Settings with their types, and call `Settings()`:
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
import os
|
|
32
|
+
|
|
33
|
+
from aa_settings import BaseSettings
|
|
34
|
+
|
|
35
|
+
os.environ["DATABASE_URL"] = "postgres://db.internal/app"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class Settings(BaseSettings):
|
|
39
|
+
database_url: str
|
|
40
|
+
port: int = 8080
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
settings = Settings()
|
|
44
|
+
print(settings.database_url, settings.port)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
That prints:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
postgres://db.internal/app 8080
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Values are checked and converted to their field types when `Settings()` runs. Anything missing or wrong raises `SettingsError` (a `ValueError`) listing every problem at once, with no input values in its message or `.problems`:
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
import os
|
|
57
|
+
|
|
58
|
+
from aa_settings import BaseSettings, SettingsError
|
|
59
|
+
|
|
60
|
+
os.environ.pop("DATABASE_URL", None)
|
|
61
|
+
os.environ["PORT"] = "not-a-port"
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class Settings(BaseSettings):
|
|
65
|
+
database_url: str
|
|
66
|
+
port: int
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
try:
|
|
70
|
+
Settings()
|
|
71
|
+
except SettingsError as err:
|
|
72
|
+
print(err)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
That prints:
|
|
76
|
+
|
|
77
|
+
```text
|
|
78
|
+
database_url: missing. Set DATABASE_URL in the environment or in .env
|
|
79
|
+
port: Input should be a valid integer, unable to parse string as an integer
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
A field path shows only names written in your Settings classes, so a dict key from the input shows as `[key]`, as in `tokens.[key]`. The one exception to "no input values" is your own validators: their messages are kept as written (see [What this library can't do](#what-this-library-cant-do)).
|
|
83
|
+
|
|
84
|
+
## Where values come from
|
|
85
|
+
|
|
86
|
+
Each Setting is taken from the first place that has it:
|
|
87
|
+
|
|
88
|
+
1. Values passed in code (`Settings(port=9000)`)
|
|
89
|
+
2. Environment variables (matching the field name in any case, with no prefix by default)
|
|
90
|
+
3. `.env` in the current folder (read as UTF-8; a missing `.env` or unknown keys in `.env` are ignored)
|
|
91
|
+
4. The Secret store (for `Secret` fields when `app_name` is set in `model_config`)
|
|
92
|
+
5. `secrets_dir` (off unless set in `model_config`)
|
|
93
|
+
6. The default on the class
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
from contextlib import chdir
|
|
97
|
+
import os
|
|
98
|
+
from pathlib import Path
|
|
99
|
+
from tempfile import TemporaryDirectory
|
|
100
|
+
|
|
101
|
+
from aa_settings import BaseSettings
|
|
102
|
+
|
|
103
|
+
os.environ["FROM_ENV"] = "env"
|
|
104
|
+
|
|
105
|
+
with TemporaryDirectory() as folder, chdir(folder):
|
|
106
|
+
Path(".env").write_text("FROM_ENV=dotenv\nFROM_DOTENV=dotenv\n", encoding="utf-8")
|
|
107
|
+
|
|
108
|
+
class Settings(BaseSettings):
|
|
109
|
+
from_code: str = "default"
|
|
110
|
+
from_env: str = "default"
|
|
111
|
+
from_dotenv: str = "default"
|
|
112
|
+
from_default: str = "default"
|
|
113
|
+
|
|
114
|
+
settings = Settings(from_code="code")
|
|
115
|
+
print(settings.from_code, settings.from_env, settings.from_dotenv, settings.from_default)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
That prints:
|
|
119
|
+
|
|
120
|
+
```text
|
|
121
|
+
code env dotenv default
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Override any default through `model_config = SettingsConfigDict(...)`, or change the source order by overriding `settings_customise_sources`.
|
|
125
|
+
|
|
126
|
+
## Secrets
|
|
127
|
+
|
|
128
|
+
Type a sensitive Setting as `Secret[T]`. It validates the inner type `T`, prints as `[REDACTED]`, uses `Secret('[REDACTED]')` for `repr()`, and serializes to `"[REDACTED]"` in JSON. Call `get_secret_value()` only where you need the real value:
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
import os
|
|
132
|
+
|
|
133
|
+
from aa_settings import BaseSettings, Secret
|
|
134
|
+
|
|
135
|
+
os.environ["API_KEY"] = "sk-live-abc123"
|
|
136
|
+
os.environ["PIN"] = "4242"
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
class Settings(BaseSettings):
|
|
140
|
+
api_key: Secret[str]
|
|
141
|
+
pin: Secret[int]
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
settings = Settings()
|
|
145
|
+
print(settings)
|
|
146
|
+
print(settings.api_key)
|
|
147
|
+
print(settings.model_dump_json())
|
|
148
|
+
print(settings.pin.get_secret_value())
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
That prints:
|
|
152
|
+
|
|
153
|
+
```text
|
|
154
|
+
api_key=Secret('[REDACTED]') pin=Secret('[REDACTED]')
|
|
155
|
+
[REDACTED]
|
|
156
|
+
{"api_key":"[REDACTED]","pin":"[REDACTED]"}
|
|
157
|
+
4242
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Credential Manager
|
|
161
|
+
|
|
162
|
+
On Windows, the Secret store is Credential Manager. Save a `Secret` there once so no `.env` file in your project has to hold it:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
aa secret set api_key
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Name your app once in `model_config = SettingsConfigDict(app_name="my-app")`. Only fields typed as `Secret[...]` (including `Secret[...] | None`) are read from the Secret store, and only when `app_name` is set. That `app_name` must match the name `aa secret set` uses: `[project].name` from `pyproject.toml` in the current folder, or the name passed to `--app`.
|
|
169
|
+
|
|
170
|
+
Each `Secret` is stored under your `app_name` and the Python field name as written in the class (not an alias or environment variable name). On a machine with no Secret store (such as a Linux CI runner), the Settings library treats the store as empty and loads Settings from environment variables, `.env` and defaults.
|
|
171
|
+
|
|
172
|
+
You can inspect or remove saved entries in **Control Panel** -> **Credential Manager** -> **Windows Credentials** (under `<app_name>` or `<field>@<app_name>`).
|
|
173
|
+
|
|
174
|
+
## Logging Settings with the log and redaction libraries
|
|
175
|
+
|
|
176
|
+
The Settings library never imports [`aa-toolkit-log`](../aa-toolkit-log/README.md) or [`aa-toolkit-redact`](../aa-toolkit-redact/README.md). An app connects them when it starts and passes `secret_values(settings)` to `known_values()` so Secrets stay hidden even if a real value from `get_secret_value()` ends up in another message, and passwords inside plain text Settings such as `database_url` are redacted too:
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
import os
|
|
180
|
+
|
|
181
|
+
from aa_log import configure_logging, get_logger
|
|
182
|
+
from aa_redact import Redactor, known_values
|
|
183
|
+
from aa_settings import BaseSettings, Secret, secret_values
|
|
184
|
+
|
|
185
|
+
os.environ["DATABASE_URL"] = "postgres://app:hunter2@db.internal/app"
|
|
186
|
+
os.environ["API_KEY"] = "rawtokenwithoutprefix12345"
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
class Settings(BaseSettings):
|
|
190
|
+
database_url: str
|
|
191
|
+
api_key: Secret[str]
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
settings = Settings()
|
|
195
|
+
configure_logging(redact=Redactor(detectors=[known_values("SECRET", secret_values(settings))]))
|
|
196
|
+
log = get_logger(__name__)
|
|
197
|
+
log.info("started", extra={"settings": settings})
|
|
198
|
+
log.error("upstream rejected %s", settings.api_key.get_secret_value())
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
When stderr isn't a terminal, that writes:
|
|
202
|
+
|
|
203
|
+
```json
|
|
204
|
+
{"time": "2026-11-15T15:35:30.501+08:00", "level": "info", "logger": "__main__", "message": "started", "settings": "database_url='postgres://app:[URL_PASSWORD]@db.internal/app' api_key=[REDACTED]"}
|
|
205
|
+
{"time": "2026-11-15T15:35:30.503+08:00", "level": "error", "logger": "__main__", "message": "upstream rejected [SECRET]"}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## What this library can't do
|
|
209
|
+
|
|
210
|
+
- **Store values larger than 2560 bytes in Credential Manager.** Windows Credential Manager holds at most 2560 bytes per Secret (1280 ordinary characters or 640 emoji in UTF-16). A short Ed25519 private key file fits; an RSA private key file does not.
|
|
211
|
+
- **Isolate saved Secrets from other programs you run.** Any program running as the same Windows user can read saved Secrets from Credential Manager.
|
|
212
|
+
- **Guarantee Secret stores off Windows.** Only Windows is tested; elsewhere `keyring` picks macOS Keychain or the Linux Secret Service, untested.
|
|
213
|
+
- **Keep values hidden after `get_secret_value()`.** Once code calls `get_secret_value()`, it holds the plain value and must keep it out of logs, errors and files itself.
|
|
214
|
+
- **Hide passwords inside plain text Settings on its own.** A password inside a `str` Setting such as `postgres://app:hunter2@db.internal/app` is hidden only when the [redaction library](../aa-toolkit-redact/README.md) is attached.
|
|
215
|
+
- **Hide input values echoed inside custom validator exceptions.** A `@field_validator` or `@model_validator` keeps its raised exception message, so validator code must not include raw values in that text.
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# aa-toolkit-settings
|
|
2
|
+
|
|
3
|
+
Settings and Secrets for apps, on top of [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/).
|
|
4
|
+
|
|
5
|
+
An app describes its Settings as a typed class and loads them from values passed in code, environment variables, a `.env` file, the Secret store and defaults, in that order. A `Secret` prints and saves as `[REDACTED]` and reveals its real value only when code asks for it.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Install it from the toolkit's GitHub repo, pinned to a version tag:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv add "aa-toolkit-settings @ git+https://github.com/aaronaco/aa-toolkit@settings-v0.1.0#subdirectory=packages/aa-toolkit-settings"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Use
|
|
16
|
+
|
|
17
|
+
Subclass `BaseSettings`, list your Settings with their types, and call `Settings()`:
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
import os
|
|
21
|
+
|
|
22
|
+
from aa_settings import BaseSettings
|
|
23
|
+
|
|
24
|
+
os.environ["DATABASE_URL"] = "postgres://db.internal/app"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Settings(BaseSettings):
|
|
28
|
+
database_url: str
|
|
29
|
+
port: int = 8080
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
settings = Settings()
|
|
33
|
+
print(settings.database_url, settings.port)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
That prints:
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
postgres://db.internal/app 8080
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Values are checked and converted to their field types when `Settings()` runs. Anything missing or wrong raises `SettingsError` (a `ValueError`) listing every problem at once, with no input values in its message or `.problems`:
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import os
|
|
46
|
+
|
|
47
|
+
from aa_settings import BaseSettings, SettingsError
|
|
48
|
+
|
|
49
|
+
os.environ.pop("DATABASE_URL", None)
|
|
50
|
+
os.environ["PORT"] = "not-a-port"
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class Settings(BaseSettings):
|
|
54
|
+
database_url: str
|
|
55
|
+
port: int
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
try:
|
|
59
|
+
Settings()
|
|
60
|
+
except SettingsError as err:
|
|
61
|
+
print(err)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
That prints:
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
database_url: missing. Set DATABASE_URL in the environment or in .env
|
|
68
|
+
port: Input should be a valid integer, unable to parse string as an integer
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
A field path shows only names written in your Settings classes, so a dict key from the input shows as `[key]`, as in `tokens.[key]`. The one exception to "no input values" is your own validators: their messages are kept as written (see [What this library can't do](#what-this-library-cant-do)).
|
|
72
|
+
|
|
73
|
+
## Where values come from
|
|
74
|
+
|
|
75
|
+
Each Setting is taken from the first place that has it:
|
|
76
|
+
|
|
77
|
+
1. Values passed in code (`Settings(port=9000)`)
|
|
78
|
+
2. Environment variables (matching the field name in any case, with no prefix by default)
|
|
79
|
+
3. `.env` in the current folder (read as UTF-8; a missing `.env` or unknown keys in `.env` are ignored)
|
|
80
|
+
4. The Secret store (for `Secret` fields when `app_name` is set in `model_config`)
|
|
81
|
+
5. `secrets_dir` (off unless set in `model_config`)
|
|
82
|
+
6. The default on the class
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
from contextlib import chdir
|
|
86
|
+
import os
|
|
87
|
+
from pathlib import Path
|
|
88
|
+
from tempfile import TemporaryDirectory
|
|
89
|
+
|
|
90
|
+
from aa_settings import BaseSettings
|
|
91
|
+
|
|
92
|
+
os.environ["FROM_ENV"] = "env"
|
|
93
|
+
|
|
94
|
+
with TemporaryDirectory() as folder, chdir(folder):
|
|
95
|
+
Path(".env").write_text("FROM_ENV=dotenv\nFROM_DOTENV=dotenv\n", encoding="utf-8")
|
|
96
|
+
|
|
97
|
+
class Settings(BaseSettings):
|
|
98
|
+
from_code: str = "default"
|
|
99
|
+
from_env: str = "default"
|
|
100
|
+
from_dotenv: str = "default"
|
|
101
|
+
from_default: str = "default"
|
|
102
|
+
|
|
103
|
+
settings = Settings(from_code="code")
|
|
104
|
+
print(settings.from_code, settings.from_env, settings.from_dotenv, settings.from_default)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
That prints:
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
code env dotenv default
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Override any default through `model_config = SettingsConfigDict(...)`, or change the source order by overriding `settings_customise_sources`.
|
|
114
|
+
|
|
115
|
+
## Secrets
|
|
116
|
+
|
|
117
|
+
Type a sensitive Setting as `Secret[T]`. It validates the inner type `T`, prints as `[REDACTED]`, uses `Secret('[REDACTED]')` for `repr()`, and serializes to `"[REDACTED]"` in JSON. Call `get_secret_value()` only where you need the real value:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
import os
|
|
121
|
+
|
|
122
|
+
from aa_settings import BaseSettings, Secret
|
|
123
|
+
|
|
124
|
+
os.environ["API_KEY"] = "sk-live-abc123"
|
|
125
|
+
os.environ["PIN"] = "4242"
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
class Settings(BaseSettings):
|
|
129
|
+
api_key: Secret[str]
|
|
130
|
+
pin: Secret[int]
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
settings = Settings()
|
|
134
|
+
print(settings)
|
|
135
|
+
print(settings.api_key)
|
|
136
|
+
print(settings.model_dump_json())
|
|
137
|
+
print(settings.pin.get_secret_value())
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
That prints:
|
|
141
|
+
|
|
142
|
+
```text
|
|
143
|
+
api_key=Secret('[REDACTED]') pin=Secret('[REDACTED]')
|
|
144
|
+
[REDACTED]
|
|
145
|
+
{"api_key":"[REDACTED]","pin":"[REDACTED]"}
|
|
146
|
+
4242
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## Credential Manager
|
|
150
|
+
|
|
151
|
+
On Windows, the Secret store is Credential Manager. Save a `Secret` there once so no `.env` file in your project has to hold it:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
aa secret set api_key
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Name your app once in `model_config = SettingsConfigDict(app_name="my-app")`. Only fields typed as `Secret[...]` (including `Secret[...] | None`) are read from the Secret store, and only when `app_name` is set. That `app_name` must match the name `aa secret set` uses: `[project].name` from `pyproject.toml` in the current folder, or the name passed to `--app`.
|
|
158
|
+
|
|
159
|
+
Each `Secret` is stored under your `app_name` and the Python field name as written in the class (not an alias or environment variable name). On a machine with no Secret store (such as a Linux CI runner), the Settings library treats the store as empty and loads Settings from environment variables, `.env` and defaults.
|
|
160
|
+
|
|
161
|
+
You can inspect or remove saved entries in **Control Panel** -> **Credential Manager** -> **Windows Credentials** (under `<app_name>` or `<field>@<app_name>`).
|
|
162
|
+
|
|
163
|
+
## Logging Settings with the log and redaction libraries
|
|
164
|
+
|
|
165
|
+
The Settings library never imports [`aa-toolkit-log`](../aa-toolkit-log/README.md) or [`aa-toolkit-redact`](../aa-toolkit-redact/README.md). An app connects them when it starts and passes `secret_values(settings)` to `known_values()` so Secrets stay hidden even if a real value from `get_secret_value()` ends up in another message, and passwords inside plain text Settings such as `database_url` are redacted too:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
import os
|
|
169
|
+
|
|
170
|
+
from aa_log import configure_logging, get_logger
|
|
171
|
+
from aa_redact import Redactor, known_values
|
|
172
|
+
from aa_settings import BaseSettings, Secret, secret_values
|
|
173
|
+
|
|
174
|
+
os.environ["DATABASE_URL"] = "postgres://app:hunter2@db.internal/app"
|
|
175
|
+
os.environ["API_KEY"] = "rawtokenwithoutprefix12345"
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
class Settings(BaseSettings):
|
|
179
|
+
database_url: str
|
|
180
|
+
api_key: Secret[str]
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
settings = Settings()
|
|
184
|
+
configure_logging(redact=Redactor(detectors=[known_values("SECRET", secret_values(settings))]))
|
|
185
|
+
log = get_logger(__name__)
|
|
186
|
+
log.info("started", extra={"settings": settings})
|
|
187
|
+
log.error("upstream rejected %s", settings.api_key.get_secret_value())
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
When stderr isn't a terminal, that writes:
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{"time": "2026-11-15T15:35:30.501+08:00", "level": "info", "logger": "__main__", "message": "started", "settings": "database_url='postgres://app:[URL_PASSWORD]@db.internal/app' api_key=[REDACTED]"}
|
|
194
|
+
{"time": "2026-11-15T15:35:30.503+08:00", "level": "error", "logger": "__main__", "message": "upstream rejected [SECRET]"}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## What this library can't do
|
|
198
|
+
|
|
199
|
+
- **Store values larger than 2560 bytes in Credential Manager.** Windows Credential Manager holds at most 2560 bytes per Secret (1280 ordinary characters or 640 emoji in UTF-16). A short Ed25519 private key file fits; an RSA private key file does not.
|
|
200
|
+
- **Isolate saved Secrets from other programs you run.** Any program running as the same Windows user can read saved Secrets from Credential Manager.
|
|
201
|
+
- **Guarantee Secret stores off Windows.** Only Windows is tested; elsewhere `keyring` picks macOS Keychain or the Linux Secret Service, untested.
|
|
202
|
+
- **Keep values hidden after `get_secret_value()`.** Once code calls `get_secret_value()`, it holds the plain value and must keep it out of logs, errors and files itself.
|
|
203
|
+
- **Hide passwords inside plain text Settings on its own.** A password inside a `str` Setting such as `postgres://app:hunter2@db.internal/app` is hidden only when the [redaction library](../aa-toolkit-redact/README.md) is attached.
|
|
204
|
+
- **Hide input values echoed inside custom validator exceptions.** A `@field_validator` or `@model_validator` keeps its raised exception message, so validator code must not include raw values in that text.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "aa-toolkit-settings"
|
|
3
|
+
version = "0.1.0a1"
|
|
4
|
+
description = "Settings for apps, on top of pydantic-settings."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.14"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
dependencies = [
|
|
10
|
+
"keyring>=25.7.0",
|
|
11
|
+
"pydantic-settings>=2.16.2",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
[build-system]
|
|
15
|
+
requires = ["uv_build>=0.13.7,<0.14"]
|
|
16
|
+
build-backend = "uv_build"
|
|
17
|
+
|
|
18
|
+
[tool.uv.build-backend]
|
|
19
|
+
module-name = "aa_settings"
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "aa-toolkit-settings"
|
|
3
|
+
version = "0.1.0a1"
|
|
4
|
+
description = "Settings for apps, on top of pydantic-settings."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.14"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
dependencies = [
|
|
10
|
+
"keyring>=25.7.0",
|
|
11
|
+
"pydantic-settings>=2.16.2",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
[build-system]
|
|
15
|
+
requires = ["uv_build>=0.13.7,<0.14"]
|
|
16
|
+
build-backend = "uv_build"
|
|
17
|
+
|
|
18
|
+
[tool.uv.build-backend]
|
|
19
|
+
module-name = "aa_settings"
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""Settings for apps, on top of pydantic-settings."""
|
|
2
|
+
|
|
3
|
+
from aa_settings._errors import SettingsError
|
|
4
|
+
from aa_settings._secrets import Secret, secret_values
|
|
5
|
+
from aa_settings._settings import BaseSettings, SettingsConfigDict
|
|
6
|
+
from aa_settings._store import SecretStoreError, delete_secret, save_secret
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"BaseSettings",
|
|
10
|
+
"Secret",
|
|
11
|
+
"SecretStoreError",
|
|
12
|
+
"SettingsConfigDict",
|
|
13
|
+
"SettingsError",
|
|
14
|
+
"delete_secret",
|
|
15
|
+
"save_secret",
|
|
16
|
+
"secret_values",
|
|
17
|
+
]
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
"""Settings validation errors without raw input values."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Mapping, Sequence
|
|
6
|
+
from dataclasses import fields as dataclass_fields
|
|
7
|
+
from dataclasses import is_dataclass
|
|
8
|
+
from types import UnionType
|
|
9
|
+
from typing import TYPE_CHECKING, Annotated, Literal, TypedDict, Union, get_args, get_origin
|
|
10
|
+
|
|
11
|
+
from pydantic import AliasChoices, AliasPath, BaseModel
|
|
12
|
+
|
|
13
|
+
from aa_settings._secrets import is_secret_annotation
|
|
14
|
+
|
|
15
|
+
if TYPE_CHECKING:
|
|
16
|
+
from pydantic import ValidationError
|
|
17
|
+
from pydantic.fields import FieldInfo
|
|
18
|
+
from pydantic_settings.exceptions import SettingsError as PydanticSettingsError
|
|
19
|
+
|
|
20
|
+
from aa_settings._settings import SettingsConfigDict
|
|
21
|
+
|
|
22
|
+
KEY_PLACEHOLDER = "[key]"
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class SettingsProblem(TypedDict):
|
|
26
|
+
"""One validation problem on a Settings field, with no raw input value."""
|
|
27
|
+
|
|
28
|
+
field: str
|
|
29
|
+
type: str
|
|
30
|
+
message: str
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class SettingsError(ValueError):
|
|
34
|
+
"""Raised when Settings fail to load or validate, with no input values."""
|
|
35
|
+
|
|
36
|
+
def __init__(self, message: str, problems: Sequence[SettingsProblem] = ()) -> None:
|
|
37
|
+
super().__init__(message)
|
|
38
|
+
self.problems: list[SettingsProblem] = [
|
|
39
|
+
{"field": p["field"], "type": p["type"], "message": p["message"]} for p in problems
|
|
40
|
+
]
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _alias_names(alias: object) -> set[str]:
|
|
44
|
+
if isinstance(alias, str):
|
|
45
|
+
return {alias}
|
|
46
|
+
if isinstance(alias, AliasPath):
|
|
47
|
+
return {part for part in alias.path if isinstance(part, str)}
|
|
48
|
+
if isinstance(alias, AliasChoices):
|
|
49
|
+
return {name for choice in alias.choices for name in _alias_names(choice)}
|
|
50
|
+
return set()
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _own_fields(annotation: object) -> list[tuple[set[str], object]]:
|
|
54
|
+
"""The names and type of each field when `annotation` is a model or dataclass."""
|
|
55
|
+
if isinstance(annotation, type) and issubclass(annotation, BaseModel):
|
|
56
|
+
return [
|
|
57
|
+
(
|
|
58
|
+
{name} | _alias_names(field.alias) | _alias_names(field.validation_alias),
|
|
59
|
+
field.annotation,
|
|
60
|
+
)
|
|
61
|
+
for name, field in annotation.model_fields.items()
|
|
62
|
+
]
|
|
63
|
+
if isinstance(annotation, type) and is_dataclass(annotation):
|
|
64
|
+
return [({field.name}, field.type) for field in dataclass_fields(annotation)]
|
|
65
|
+
return []
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _declared_names(settings_cls: type[BaseModel]) -> set[str]:
|
|
69
|
+
"""Every name written in the Settings types: fields, aliases and Literal values.
|
|
70
|
+
|
|
71
|
+
These come from code, so they are safe to show. Anything else in an error
|
|
72
|
+
location, such as a dict key, came from the input.
|
|
73
|
+
"""
|
|
74
|
+
names: set[str] = set()
|
|
75
|
+
seen: set[int] = set()
|
|
76
|
+
pending: list[object] = [settings_cls]
|
|
77
|
+
while pending:
|
|
78
|
+
annotation = pending.pop()
|
|
79
|
+
if id(annotation) in seen:
|
|
80
|
+
continue
|
|
81
|
+
seen.add(id(annotation))
|
|
82
|
+
for field_names, field_type in _own_fields(annotation):
|
|
83
|
+
names |= field_names
|
|
84
|
+
pending.append(field_type)
|
|
85
|
+
if get_origin(annotation) is Literal:
|
|
86
|
+
names |= {arg for arg in get_args(annotation) if isinstance(arg, str)}
|
|
87
|
+
pending.extend(get_args(annotation))
|
|
88
|
+
return names
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _safe_location(loc: tuple[int | str, ...], declared: set[str]) -> str:
|
|
92
|
+
parts: list[str] = []
|
|
93
|
+
for part in loc:
|
|
94
|
+
text = str(part) if isinstance(part, int) or part in declared else KEY_PLACEHOLDER
|
|
95
|
+
if not (text == KEY_PLACEHOLDER and parts and parts[-1] == KEY_PLACEHOLDER):
|
|
96
|
+
parts.append(text)
|
|
97
|
+
return ".".join(parts)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _single_model(annotation: object) -> type[BaseModel] | None:
|
|
101
|
+
"""The model class behind `Model`, `Model | None` or `Annotated[Model, ...]`, if any."""
|
|
102
|
+
origin = get_origin(annotation)
|
|
103
|
+
if origin is Annotated:
|
|
104
|
+
return _single_model(get_args(annotation)[0])
|
|
105
|
+
if origin is Union or origin is UnionType:
|
|
106
|
+
branches = [arg for arg in get_args(annotation) if arg is not type(None)]
|
|
107
|
+
return _single_model(branches[0]) if len(branches) == 1 else None
|
|
108
|
+
if isinstance(annotation, type) and issubclass(annotation, BaseModel):
|
|
109
|
+
return annotation
|
|
110
|
+
return None
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _alias(field: FieldInfo) -> object:
|
|
114
|
+
return field.validation_alias if field.validation_alias is not None else field.alias
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _find_field(model: type[BaseModel] | None, part: int | str) -> tuple[str, FieldInfo] | None:
|
|
118
|
+
fields = model.model_fields.items() if model is not None else ()
|
|
119
|
+
return next(((name, field) for name, field in fields if part in (name, _alias(field))), None)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _env_name_part(name: str, field: FieldInfo, by_alias: bool) -> tuple[str, bool] | None:
|
|
123
|
+
"""The name pydantic-settings reads for one field, and whether it's an alias."""
|
|
124
|
+
alias = _alias(field)
|
|
125
|
+
if not by_alias or alias is None:
|
|
126
|
+
return name, False
|
|
127
|
+
return (alias, True) if isinstance(alias, str) else None
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _env_var_name(
|
|
131
|
+
loc: tuple[int | str, ...],
|
|
132
|
+
settings_cls: type[BaseModel],
|
|
133
|
+
config: SettingsConfigDict,
|
|
134
|
+
) -> str | None:
|
|
135
|
+
"""The environment variable that sets the missing field, or None when unsure."""
|
|
136
|
+
delimiter = config.get("env_nested_delimiter")
|
|
137
|
+
if len(loc) > 1 and not delimiter:
|
|
138
|
+
return None
|
|
139
|
+
parts: list[tuple[str, bool]] = []
|
|
140
|
+
model: type[BaseModel] | None = settings_cls
|
|
141
|
+
for loc_part in loc:
|
|
142
|
+
found = _find_field(model, loc_part)
|
|
143
|
+
part = _env_name_part(*found, config.get("validate_by_alias", True)) if found else None
|
|
144
|
+
if found is None or part is None:
|
|
145
|
+
return None
|
|
146
|
+
parts.append(part)
|
|
147
|
+
model = _single_model(found[1].annotation)
|
|
148
|
+
target = config.get("env_prefix_target", "variable")
|
|
149
|
+
prefixed = target == "all" or target == ("alias" if parts[0][1] else "variable")
|
|
150
|
+
prefix = config.get("env_prefix", "") if prefixed else ""
|
|
151
|
+
full_name = prefix + (delimiter or "").join(name for name, _ in parts)
|
|
152
|
+
return full_name if config.get("case_sensitive", False) else full_name.upper()
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _matches_secret_alias(loc: tuple[int | str, ...], alias: object) -> bool:
|
|
156
|
+
if isinstance(alias, str):
|
|
157
|
+
return loc == (alias,)
|
|
158
|
+
if isinstance(alias, AliasPath):
|
|
159
|
+
return tuple(alias.path) == loc
|
|
160
|
+
if isinstance(alias, AliasChoices):
|
|
161
|
+
return any(_matches_secret_alias(loc, choice) for choice in alias.choices)
|
|
162
|
+
return False
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def _secret_store_field_name(
|
|
166
|
+
loc: tuple[int | str, ...],
|
|
167
|
+
settings_cls: type[BaseModel],
|
|
168
|
+
config: SettingsConfigDict,
|
|
169
|
+
) -> str | None:
|
|
170
|
+
"""The Python field name when `loc` is a top-level Secret on a class with `app_name`."""
|
|
171
|
+
if not config.get("app_name") or not loc:
|
|
172
|
+
return None
|
|
173
|
+
for name, field in settings_cls.model_fields.items():
|
|
174
|
+
if not is_secret_annotation(field.annotation):
|
|
175
|
+
continue
|
|
176
|
+
if loc == (name,) or _matches_secret_alias(loc, _alias(field)):
|
|
177
|
+
return name
|
|
178
|
+
return None
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def _safe_message(
|
|
182
|
+
err: Mapping[str, object],
|
|
183
|
+
settings_cls: type[BaseModel],
|
|
184
|
+
config: SettingsConfigDict,
|
|
185
|
+
) -> str:
|
|
186
|
+
if err["type"] == "missing":
|
|
187
|
+
loc = err["loc"]
|
|
188
|
+
env_name = _env_var_name(loc, settings_cls, config) if isinstance(loc, tuple) else None
|
|
189
|
+
secret_name = (
|
|
190
|
+
_secret_store_field_name(loc, settings_cls, config) if isinstance(loc, tuple) else None
|
|
191
|
+
)
|
|
192
|
+
if env_name and secret_name:
|
|
193
|
+
return (
|
|
194
|
+
f"missing. Set {env_name} in the environment or in .env, "
|
|
195
|
+
f"or run aa secret set {secret_name}"
|
|
196
|
+
)
|
|
197
|
+
if env_name:
|
|
198
|
+
return f"missing. Set {env_name} in the environment or in .env"
|
|
199
|
+
if secret_name:
|
|
200
|
+
return f"missing. Run aa secret set {secret_name}"
|
|
201
|
+
return "missing"
|
|
202
|
+
if err["type"] == "union_tag_invalid":
|
|
203
|
+
# pydantic's message repeats the tag from the input.
|
|
204
|
+
ctx = err.get("ctx")
|
|
205
|
+
expected = ctx.get("expected_tags") if isinstance(ctx, Mapping) else None
|
|
206
|
+
return f"Input tag does not match any of the expected tags: {expected}"
|
|
207
|
+
return str(err["msg"])
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def build_settings_error_from_validation(
|
|
211
|
+
exc: ValidationError,
|
|
212
|
+
settings_cls: type[BaseModel],
|
|
213
|
+
config: SettingsConfigDict,
|
|
214
|
+
) -> SettingsError:
|
|
215
|
+
"""Convert a pydantic ValidationError into a SettingsError with no input values."""
|
|
216
|
+
declared = _declared_names(settings_cls)
|
|
217
|
+
problems: list[SettingsProblem] = [
|
|
218
|
+
{
|
|
219
|
+
"field": _safe_location(err["loc"], declared),
|
|
220
|
+
"type": err["type"],
|
|
221
|
+
"message": _safe_message(err, settings_cls, config),
|
|
222
|
+
}
|
|
223
|
+
for err in exc.errors(include_url=False, include_input=False)
|
|
224
|
+
]
|
|
225
|
+
lines = [f"{p['field']}: {p['message']}" if p["field"] else p["message"] for p in problems]
|
|
226
|
+
return SettingsError("\n".join(lines), problems)
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def build_settings_error_from_source(exc: PydanticSettingsError) -> SettingsError:
|
|
230
|
+
"""Convert a pydantic-settings source parsing error into a SettingsError."""
|
|
231
|
+
message = str(exc)
|
|
232
|
+
problem: SettingsProblem = {"field": "", "type": "settings_error", "message": message}
|
|
233
|
+
return SettingsError(message, [problem])
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
"""Secret field type that always displays as [REDACTED]."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Iterable, Mapping
|
|
6
|
+
from dataclasses import fields as dataclass_fields
|
|
7
|
+
from dataclasses import is_dataclass
|
|
8
|
+
from types import UnionType
|
|
9
|
+
from typing import TYPE_CHECKING, Annotated, Union, get_args, get_origin
|
|
10
|
+
|
|
11
|
+
from pydantic import BaseModel, SecretBytes, SecretStr
|
|
12
|
+
from pydantic import Secret as PydanticSecret
|
|
13
|
+
|
|
14
|
+
if TYPE_CHECKING:
|
|
15
|
+
from aa_settings._settings import BaseSettings
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class Secret[T](PydanticSecret[T]):
|
|
19
|
+
"""A Secret value whose display text is always `[REDACTED]`."""
|
|
20
|
+
|
|
21
|
+
def _display(self) -> str:
|
|
22
|
+
return "[REDACTED]"
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def is_secret_annotation(annotation: object) -> bool:
|
|
26
|
+
"""Whether `annotation` is `Secret[...]` (or `Secret[...] | None`)."""
|
|
27
|
+
origin = get_origin(annotation)
|
|
28
|
+
if origin is Annotated:
|
|
29
|
+
return is_secret_annotation(get_args(annotation)[0])
|
|
30
|
+
if origin is Union or origin is UnionType:
|
|
31
|
+
branches = [arg for arg in get_args(annotation) if arg is not type(None)]
|
|
32
|
+
return bool(branches) and all(is_secret_annotation(branch) for branch in branches)
|
|
33
|
+
target = origin if origin is not None else annotation
|
|
34
|
+
return isinstance(target, type) and issubclass(target, Secret)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _extract_secret_text(secret: PydanticSecret[object] | SecretStr | SecretBytes) -> str:
|
|
38
|
+
raw = secret.get_secret_value()
|
|
39
|
+
if raw is None:
|
|
40
|
+
return ""
|
|
41
|
+
return raw.decode("utf-8", errors="replace") if isinstance(raw, bytes) else str(raw)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _iter_children(value: object) -> Iterable[object]:
|
|
45
|
+
if isinstance(value, BaseModel):
|
|
46
|
+
return (getattr(value, name) for name in type(value).model_fields)
|
|
47
|
+
if is_dataclass(value) and not isinstance(value, type):
|
|
48
|
+
return (getattr(value, field.name) for field in dataclass_fields(value))
|
|
49
|
+
if isinstance(value, Mapping):
|
|
50
|
+
return value.values()
|
|
51
|
+
if isinstance(value, (list, tuple, set, frozenset)):
|
|
52
|
+
return value
|
|
53
|
+
return ()
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _collect_secrets(value: object, values: list[str], seen: set[int]) -> None:
|
|
57
|
+
if isinstance(value, (PydanticSecret, SecretStr, SecretBytes)):
|
|
58
|
+
text = _extract_secret_text(value)
|
|
59
|
+
if text:
|
|
60
|
+
values.append(text)
|
|
61
|
+
return
|
|
62
|
+
|
|
63
|
+
obj_id = id(value)
|
|
64
|
+
if obj_id in seen:
|
|
65
|
+
return
|
|
66
|
+
seen.add(obj_id)
|
|
67
|
+
|
|
68
|
+
for item in _iter_children(value):
|
|
69
|
+
_collect_secrets(item, values, seen)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def secret_values(settings: BaseSettings) -> list[str]:
|
|
73
|
+
"""Return the real value of every populated Secret field on `settings` as text."""
|
|
74
|
+
values: list[str] = []
|
|
75
|
+
_collect_secrets(settings, values, set())
|
|
76
|
+
return values
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""Settings base class and SettingsConfigDict."""
|
|
2
|
+
|
|
3
|
+
from typing import Any, ClassVar, cast
|
|
4
|
+
|
|
5
|
+
from pydantic import ValidationError
|
|
6
|
+
from pydantic_settings import BaseSettings as PydanticBaseSettings
|
|
7
|
+
from pydantic_settings import PydanticBaseSettingsSource
|
|
8
|
+
from pydantic_settings import SettingsConfigDict as PydanticSettingsConfigDict
|
|
9
|
+
from pydantic_settings.exceptions import SettingsError as PydanticSettingsError
|
|
10
|
+
|
|
11
|
+
from aa_settings._errors import (
|
|
12
|
+
SettingsError,
|
|
13
|
+
build_settings_error_from_source,
|
|
14
|
+
build_settings_error_from_validation,
|
|
15
|
+
)
|
|
16
|
+
from aa_settings._store import SecretStoreSettingsSource
|
|
17
|
+
|
|
18
|
+
# Options an app can also pass when creating Settings, as `Settings(_env_prefix="APP_")`.
|
|
19
|
+
_RUNTIME_OPTIONS = ("env_prefix", "env_prefix_target", "case_sensitive", "env_nested_delimiter")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class SettingsConfigDict(PydanticSettingsConfigDict, total=False):
|
|
23
|
+
"""Settings options for `BaseSettings` subclasses."""
|
|
24
|
+
|
|
25
|
+
app_name: str | None
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class BaseSettings(PydanticBaseSettings):
|
|
29
|
+
"""Base class for app Settings loaded from code, environment, `.env`, and defaults."""
|
|
30
|
+
|
|
31
|
+
# Mirrors pydantic_settings.BaseSettings narrowing BaseModel.model_config.
|
|
32
|
+
model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict( # ty: ignore[invalid-mutable-override]
|
|
33
|
+
env_file=".env",
|
|
34
|
+
env_file_encoding="utf-8",
|
|
35
|
+
extra="ignore",
|
|
36
|
+
hide_input_in_errors=True,
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
@classmethod
|
|
40
|
+
def settings_customise_sources(
|
|
41
|
+
cls,
|
|
42
|
+
settings_cls: type[PydanticBaseSettings],
|
|
43
|
+
init_settings: PydanticBaseSettingsSource,
|
|
44
|
+
env_settings: PydanticBaseSettingsSource,
|
|
45
|
+
dotenv_settings: PydanticBaseSettingsSource,
|
|
46
|
+
file_secret_settings: PydanticBaseSettingsSource,
|
|
47
|
+
) -> tuple[PydanticBaseSettingsSource, ...]:
|
|
48
|
+
return (
|
|
49
|
+
init_settings,
|
|
50
|
+
env_settings,
|
|
51
|
+
dotenv_settings,
|
|
52
|
+
SecretStoreSettingsSource(settings_cls),
|
|
53
|
+
file_secret_settings,
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
def __init__(
|
|
57
|
+
self,
|
|
58
|
+
**values: Any, # noqa: ANN401 # mirrors pydantic_settings.BaseSettings.__init__
|
|
59
|
+
) -> None:
|
|
60
|
+
error: SettingsError | None = None
|
|
61
|
+
try:
|
|
62
|
+
super().__init__(**values)
|
|
63
|
+
except ValidationError as exc:
|
|
64
|
+
overrides = {
|
|
65
|
+
key: values[f"_{key}"]
|
|
66
|
+
for key in _RUNTIME_OPTIONS
|
|
67
|
+
if values.get(f"_{key}") is not None
|
|
68
|
+
}
|
|
69
|
+
config = cast("SettingsConfigDict", {**type(self).model_config, **overrides})
|
|
70
|
+
error = build_settings_error_from_validation(exc, type(self), config)
|
|
71
|
+
except PydanticSettingsError as exc:
|
|
72
|
+
error = build_settings_error_from_source(exc)
|
|
73
|
+
except SettingsError as exc:
|
|
74
|
+
error = exc
|
|
75
|
+
# Raised here, outside the except blocks, so pydantic's error is neither
|
|
76
|
+
# the cause nor the context and its input values stay out of tracebacks.
|
|
77
|
+
if error is not None:
|
|
78
|
+
raise error
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
"""Secret store source and helpers backed by keyring."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Iterator, Mapping
|
|
6
|
+
from typing import TYPE_CHECKING, Any
|
|
7
|
+
|
|
8
|
+
import keyring
|
|
9
|
+
from keyring.backends import null as null_keyring
|
|
10
|
+
from keyring.errors import NoKeyringError, PasswordDeleteError
|
|
11
|
+
from pydantic import AliasChoices, AliasPath
|
|
12
|
+
from pydantic_settings import PydanticBaseSettingsSource
|
|
13
|
+
|
|
14
|
+
from aa_settings._errors import SettingsError, SettingsProblem
|
|
15
|
+
from aa_settings._secrets import is_secret_annotation
|
|
16
|
+
|
|
17
|
+
if TYPE_CHECKING:
|
|
18
|
+
from pydantic.fields import FieldInfo
|
|
19
|
+
from pydantic_settings import BaseSettings as PydanticBaseSettings
|
|
20
|
+
|
|
21
|
+
MAX_SECRET_BYTES = 2560
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class SecretStoreError(Exception):
|
|
25
|
+
"""Raised when the OS Secret store is unavailable or fails, with no Secret value."""
|
|
26
|
+
|
|
27
|
+
def __init__(self, message: str, *, no_store: bool = False) -> None:
|
|
28
|
+
super().__init__(message)
|
|
29
|
+
self.no_store = no_store
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
type _Path = tuple[str | int, ...]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _alias_path(alias: object) -> _Path | None:
|
|
36
|
+
if isinstance(alias, str):
|
|
37
|
+
return (alias,)
|
|
38
|
+
if isinstance(alias, AliasPath) and alias.path and isinstance(alias.path[0], str):
|
|
39
|
+
return tuple(alias.path)
|
|
40
|
+
return None
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _validate_by_name(config: Mapping[str, Any]) -> bool:
|
|
44
|
+
"""Resolve `validate_by_name` the way pydantic does, including `populate_by_name`."""
|
|
45
|
+
for key in ("validate_by_name", "populate_by_name"):
|
|
46
|
+
value = config.get(key)
|
|
47
|
+
if value is not None:
|
|
48
|
+
return bool(value)
|
|
49
|
+
return config.get("validate_by_alias") is False
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _accepted_paths(field: FieldInfo, field_name: str, config: Mapping[str, Any]) -> list[_Path]:
|
|
53
|
+
"""Every key path pydantic accepts for `field`, in the order it tries them."""
|
|
54
|
+
paths: list[_Path] = []
|
|
55
|
+
alias = field.validation_alias
|
|
56
|
+
if alias is not None and config.get("validate_by_alias") is not False:
|
|
57
|
+
choices = alias.choices if isinstance(alias, AliasChoices) else [alias]
|
|
58
|
+
paths = [path for path in map(_alias_path, choices) if path is not None]
|
|
59
|
+
if not paths or _validate_by_name(config):
|
|
60
|
+
paths.append((field_name,))
|
|
61
|
+
return paths
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _validation_path(field: FieldInfo, field_name: str, config: Mapping[str, Any]) -> _Path:
|
|
65
|
+
"""The key path pydantic expects when populating `field`."""
|
|
66
|
+
return _accepted_paths(field, field_name, config)[0]
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _has_path(data: object, path: _Path) -> bool:
|
|
70
|
+
for part in path:
|
|
71
|
+
if isinstance(part, str) and isinstance(data, dict) and part in data:
|
|
72
|
+
data = data[part]
|
|
73
|
+
elif (
|
|
74
|
+
isinstance(part, int)
|
|
75
|
+
and isinstance(data, (list, tuple))
|
|
76
|
+
and -len(data) <= part < len(data)
|
|
77
|
+
):
|
|
78
|
+
data = data[part]
|
|
79
|
+
else:
|
|
80
|
+
return False
|
|
81
|
+
return True
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _nest(path: _Path, value: str) -> object:
|
|
85
|
+
"""Wrap `value` so it sits at `path` below its first key."""
|
|
86
|
+
nested: object = value
|
|
87
|
+
for part in reversed(path[1:]):
|
|
88
|
+
if isinstance(part, int):
|
|
89
|
+
items: list[object] = [None] * (part + 1 if part >= 0 else -part)
|
|
90
|
+
items[part] = nested
|
|
91
|
+
nested = items
|
|
92
|
+
else:
|
|
93
|
+
nested = {part: nested}
|
|
94
|
+
return nested
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _combine(current: object, incoming: object) -> object:
|
|
98
|
+
"""Merge two values built by `_nest`, keeping every filled key and list slot."""
|
|
99
|
+
if isinstance(current, dict) and isinstance(incoming, dict):
|
|
100
|
+
for key, value in incoming.items():
|
|
101
|
+
current[key] = _combine(current[key], value) if key in current else value
|
|
102
|
+
return current
|
|
103
|
+
if isinstance(current, list) and isinstance(incoming, list):
|
|
104
|
+
return _combine_lists(current, incoming)
|
|
105
|
+
return incoming
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _combine_lists(current: list[object], incoming: list[object]) -> list[object]:
|
|
109
|
+
current.extend([None] * (len(incoming) - len(current)))
|
|
110
|
+
for index, value in enumerate(incoming):
|
|
111
|
+
if value is not None:
|
|
112
|
+
slot = current[index]
|
|
113
|
+
current[index] = value if slot is None else _combine(slot, value)
|
|
114
|
+
return current
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _read_secret(app_name: str, field_name: str) -> tuple[str | None, SettingsProblem | None, bool]:
|
|
118
|
+
"""Read one Secret entry, returning `(value, problem, store_missing)`."""
|
|
119
|
+
try:
|
|
120
|
+
return keyring.get_password(app_name, field_name), None, False
|
|
121
|
+
except NoKeyringError:
|
|
122
|
+
return None, None, True
|
|
123
|
+
except Exception as exc:
|
|
124
|
+
message = f"could not read from Secret store ({type(exc).__name__})"
|
|
125
|
+
return None, {"field": field_name, "type": "secret_store_error", "message": message}, False
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
class SecretStoreSettingsSource(PydanticBaseSettingsSource):
|
|
129
|
+
"""Read `Secret[...]` fields from the OS Secret store when `app_name` is configured."""
|
|
130
|
+
|
|
131
|
+
def __init__(self, settings_cls: type[PydanticBaseSettings]) -> None:
|
|
132
|
+
super().__init__(settings_cls)
|
|
133
|
+
self.app_name = self.config.get("app_name")
|
|
134
|
+
|
|
135
|
+
def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
|
|
136
|
+
path = _validation_path(field, field_name, self.config)
|
|
137
|
+
if not self.app_name or not is_secret_annotation(field.annotation):
|
|
138
|
+
return None, str(path[0]), False
|
|
139
|
+
value, problem, _ = _read_secret(self.app_name, field_name)
|
|
140
|
+
if problem is not None:
|
|
141
|
+
raise SettingsError(f"{problem['field']}: {problem['message']}", [problem])
|
|
142
|
+
return (None if value is None else _nest(path, value)), str(path[0]), False
|
|
143
|
+
|
|
144
|
+
def _fields_to_read(self) -> Iterator[tuple[str, _Path]]:
|
|
145
|
+
"""Each Secret field no higher source has set, with the path pydantic reads it from."""
|
|
146
|
+
for field_name, field in self.settings_cls.model_fields.items():
|
|
147
|
+
if not is_secret_annotation(field.annotation):
|
|
148
|
+
continue
|
|
149
|
+
paths = _accepted_paths(field, field_name, self.config)
|
|
150
|
+
if not any(_has_path(self.current_state, path) for path in paths):
|
|
151
|
+
yield field_name, paths[0]
|
|
152
|
+
|
|
153
|
+
def __call__(self) -> dict[str, Any]:
|
|
154
|
+
if not self.app_name:
|
|
155
|
+
return {}
|
|
156
|
+
data: dict[str, Any] = {}
|
|
157
|
+
problems: list[SettingsProblem] = []
|
|
158
|
+
for field_name, path in self._fields_to_read():
|
|
159
|
+
value, problem, store_missing = _read_secret(self.app_name, field_name)
|
|
160
|
+
if store_missing:
|
|
161
|
+
return {}
|
|
162
|
+
if problem is not None:
|
|
163
|
+
problems.append(problem)
|
|
164
|
+
continue
|
|
165
|
+
if value is not None:
|
|
166
|
+
root, nested = str(path[0]), _nest(path, value)
|
|
167
|
+
data[root] = _combine(data[root], nested) if root in data else nested
|
|
168
|
+
if problems:
|
|
169
|
+
lines = [f"{p['field']}: {p['message']}" for p in problems]
|
|
170
|
+
raise SettingsError("\n".join(lines), problems)
|
|
171
|
+
return data
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def _require_store() -> None:
|
|
175
|
+
error: SecretStoreError | None = None
|
|
176
|
+
backend: object = None
|
|
177
|
+
try:
|
|
178
|
+
backend = keyring.get_keyring()
|
|
179
|
+
except Exception as exc:
|
|
180
|
+
error = _store_error(exc)
|
|
181
|
+
if error is not None:
|
|
182
|
+
raise error
|
|
183
|
+
if isinstance(backend, null_keyring.Keyring):
|
|
184
|
+
raise SecretStoreError("No Secret store is available on this machine", no_store=True)
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def _store_error(exc: Exception) -> SecretStoreError:
|
|
188
|
+
if isinstance(exc, NoKeyringError):
|
|
189
|
+
return SecretStoreError("No Secret store is available on this machine", no_store=True)
|
|
190
|
+
return SecretStoreError(f"Secret store failed ({type(exc).__name__})", no_store=False)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def save_secret(app_name: str, name: str, value: str) -> bool:
|
|
194
|
+
"""Save a Secret in the OS Secret store and return whether it replaced an existing entry."""
|
|
195
|
+
if not app_name:
|
|
196
|
+
raise ValueError("app_name must not be empty")
|
|
197
|
+
if not name:
|
|
198
|
+
raise ValueError("name must not be empty")
|
|
199
|
+
if not value:
|
|
200
|
+
raise ValueError(
|
|
201
|
+
f"Secret value must not be empty (0 bytes; limit is {MAX_SECRET_BYTES} UTF-16 bytes)"
|
|
202
|
+
)
|
|
203
|
+
size = len(value.encode("utf-16-le"))
|
|
204
|
+
if size > MAX_SECRET_BYTES:
|
|
205
|
+
raise ValueError(
|
|
206
|
+
f"Secret value is {size} bytes in UTF-16, over the {MAX_SECRET_BYTES} byte limit"
|
|
207
|
+
)
|
|
208
|
+
|
|
209
|
+
_require_store()
|
|
210
|
+
error: SecretStoreError | None = None
|
|
211
|
+
replaced = False
|
|
212
|
+
try:
|
|
213
|
+
replaced = keyring.get_password(app_name, name) is not None
|
|
214
|
+
keyring.set_password(app_name, name, value)
|
|
215
|
+
except Exception as exc:
|
|
216
|
+
error = _store_error(exc)
|
|
217
|
+
if error is not None:
|
|
218
|
+
raise error
|
|
219
|
+
return replaced
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def delete_secret(app_name: str, name: str) -> bool:
|
|
223
|
+
"""Remove a Secret from the OS Secret store and return whether one existed."""
|
|
224
|
+
if not app_name:
|
|
225
|
+
raise ValueError("app_name must not be empty")
|
|
226
|
+
if not name:
|
|
227
|
+
raise ValueError("name must not be empty")
|
|
228
|
+
|
|
229
|
+
_require_store()
|
|
230
|
+
error: SecretStoreError | None = None
|
|
231
|
+
existed = True
|
|
232
|
+
try:
|
|
233
|
+
keyring.delete_password(app_name, name)
|
|
234
|
+
except PasswordDeleteError:
|
|
235
|
+
existed = False
|
|
236
|
+
except Exception as exc:
|
|
237
|
+
error = _store_error(exc)
|
|
238
|
+
if not existed:
|
|
239
|
+
# Some backends raise PasswordDeleteError for failures other than a missing
|
|
240
|
+
# entry, so only report "not there" once a read confirms it.
|
|
241
|
+
try:
|
|
242
|
+
if keyring.get_password(app_name, name) is not None:
|
|
243
|
+
error = SecretStoreError("Secret store failed (PasswordDeleteError)")
|
|
244
|
+
except Exception as exc:
|
|
245
|
+
error = _store_error(exc)
|
|
246
|
+
if error is not None:
|
|
247
|
+
raise error
|
|
248
|
+
return existed
|
|
File without changes
|