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.
@@ -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