psyplus 1.0.0__tar.gz → 1.1.0__tar.gz

{psyplus-1.0.0 → psyplus-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: psyplus
-Version: 1.0.0
+Version: 1.1.0
 Summary: Generate, read and document pydantic-settings config files in YAML
 Keywords: DZD,pydantic,pydantic-settings,yaml,config
 Author-Email: Tim Bleimehl <bleimehl@helmholtz-munich.de>
@@ -148,18 +148,18 @@ The command above creates `config.yaml` with a comment block above every key:
 
 ```yaml
 # ## log_level ###
-# Type:         Enum
+# Type:         Enum or null
 # Required:     False
 # Default:      "INFO"
 # Allowed vals: ['INFO', 'DEBUG']
-# Env-var:      'APP_LOG_LEVEL'
+# Env-var:      'APP_LOG_LEVEL' (can not set null, use null in the YAML file)
 log_level: INFO
 
 # ## app_name ###
-# Type:        str
+# Type:        str or null
 # Required:    False
 # Default:     "THE APP"
-# Env-var:     'APP_APP_NAME'
+# Env-var:     'APP_APP_NAME' (can not set null, use null in the YAML file)
 # Description: The display name of the app
 # Example No. 1:
 #  >app_name: THAT APP
@@ -168,9 +168,9 @@ log_level: INFO
 app_name: THE APP
 
 # ## storage_dir ###
-# Type:        str
+# Type:        str or null
 # Required:    False
-# Env-var:     'APP_STORAGE_DIR'
+# Env-var:     'APP_STORAGE_DIR' (can not set null, use null in the YAML file)
 # Description: A directory to store files for the app.
 storage_dir: /home/user/.config/myapp
 
@@ -197,19 +197,19 @@ database_server:
 
   # ## host ###
   # YAML-path:   database_server.host
-  # Type:        str
+  # Type:        str or null
   # Required:    False
   # Default:     "localhost"
-  # Env-var:     'APP_DATABASE_SERVER__HOST'
+  # Env-var:     'APP_DATABASE_SERVER__HOST' (can not set null, use null in the YAML file)
   # Description: The hostname the database will be available at
   host: localhost
 
   # ## port ###
   # YAML-path:   database_server.port
-  # Type:        int
+  # Type:        int or null
   # Required:    False
   # Default:     5678
-  # Env-var:     'APP_DATABASE_SERVER__PORT'
+  # Env-var:     'APP_DATABASE_SERVER__PORT' (can not set null, use null in the YAML file)
   # Description: The port to connect to the database
   port: 5678
 
@@ -394,18 +394,61 @@ For nested models the env var path is built as:
 # e.g. MYAPP_DATABASE__HOST  (prefix="MYAPP_", delimiter="__")
 ```
 
+What pydantic-settings can set through env vars, and what the generated files show:
+
+| Field | Env var example | Behaviour |
+|---|---|---|
+| Field of a nested model, any depth | `MYAPP_DATABASE__SERVER__HOST=db` | Sets only this value. The other values from the YAML file stay. |
+| Whole nested model | `MYAPP_DATABASE='{"name": "x"}'` | JSON, merged into the values from the YAML file. |
+| List (`List[str]`, `List[SubModel]`) | `MYAPP_HOSTS='["a", "b"]'` | JSON, replaces the whole list. A single list element (`MYAPP_HOSTS__0`) can not be set, so list elements show no env var. |
+| Dict value (`Dict[str, ...]`) | `MYAPP_LABELS__team=core` | `<dict-key>` stands for the key. Env var names are case-insensitive by default, so the key arrives in lower case. |
+
+Only the root model's `env_prefix` and `env_nested_delimiter` count. A nested `BaseSettings`
+sub-model's own `env_prefix` is not used for its fields. Without `env_nested_delimiter`, nested
+fields have no env var of their own and can only be set through the JSON value of the top-level
+field. With `case_sensitive=True`, the env var names keep the case of the field names.
+A sub-model that defaults to null has no fields in the YAML file, so its comment lists the env
+vars of its fields under `Env-vars of the sub-fields:`.
+
+#### Nullable fields
+
+A nullable field (`Optional[int]`, `int | None`) shows its type as `int or null`. By default,
+pydantic-settings can not set such a field to null through an env var: an `int` or `bool` field
+fails validation, a `str` field gets the literal text `null`, and a list, dict or model field
+silently keeps its default. Only the YAML file can set null then. Set `env_parse_none_str` to name
+the env var value that means null:
+
+```python
+class MyConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MYAPP_", env_parse_none_str="null")
+
+    max_age_days: Optional[int] = 30
+    # → Type:    int or null
+    # → Env-var: 'MYAPP_MAX_AGE_DAYS' ('null' sets null)
+```
+
+For a nullable field whose default is not null, the `Env-var:` hint says which case applies:
+`('null' sets null)` with `env_parse_none_str`, or `(can not set null, use null in the YAML file)`
+without it. A field that defaults to null gets no hint, since leaving the env var unset already
+gives null.
+
 ---
 
 ## Environment variable overrides
 
 `load()` creates a thin dynamic subclass that adds the YAML file as a pydantic-settings source while keeping the normal env var source with higher priority. The effective source priority (highest → lowest) is:
 
-1. **Environment variables** (respects `env_prefix` / `env_nested_delimiter`)
-2. **YAML file** values
-3. **Model defaults**
+1. **Init arguments** (values passed to the settings class directly)
+2. **Environment variables** (respects `env_prefix` / `env_nested_delimiter`)
+3. **`.env` file** (if the model sets `env_file`)
+4. **Secrets directory** (if the model sets `secrets_dir`)
+5. **YAML file** values
+6. **Model defaults**
 
 No changes to your settings class are required.
 
+A missing YAML file is not an error: `load()` then returns the model defaults plus whatever the env vars, the `.env` file and the secrets directory set.
+
 ---
 
 ## Development
@@ -434,7 +477,7 @@ To visually inspect the generated YAML and Markdown for all built-in test models
 pdm run smoke
 ```
 
-This writes four files per model (YAML config template + Markdown reference) to `smoke_output/` and prints a preview of each to the terminal. The output is committed to the repository and linked from the [Example gallery](#example-gallery) section — re-run the script and commit the results whenever the generator logic changes.
+This writes two files per model (YAML config template + Markdown reference) to `smoke_output/` and prints a preview of each to the terminal. The output is committed to the repository and linked from the [Example gallery](#example-gallery) section. Re-run the script and commit the results whenever the generator logic changes.
 
 ```
 smoke_output/

{psyplus-1.0.0 → psyplus-1.1.0}/README.md

@@ -125,18 +125,18 @@ The command above creates `config.yaml` with a comment block above every key:
 
 ```yaml
 # ## log_level ###
-# Type:         Enum
+# Type:         Enum or null
 # Required:     False
 # Default:      "INFO"
 # Allowed vals: ['INFO', 'DEBUG']
-# Env-var:      'APP_LOG_LEVEL'
+# Env-var:      'APP_LOG_LEVEL' (can not set null, use null in the YAML file)
 log_level: INFO
 
 # ## app_name ###
-# Type:        str
+# Type:        str or null
 # Required:    False
 # Default:     "THE APP"
-# Env-var:     'APP_APP_NAME'
+# Env-var:     'APP_APP_NAME' (can not set null, use null in the YAML file)
 # Description: The display name of the app
 # Example No. 1:
 #  >app_name: THAT APP
@@ -145,9 +145,9 @@ log_level: INFO
 app_name: THE APP
 
 # ## storage_dir ###
-# Type:        str
+# Type:        str or null
 # Required:    False
-# Env-var:     'APP_STORAGE_DIR'
+# Env-var:     'APP_STORAGE_DIR' (can not set null, use null in the YAML file)
 # Description: A directory to store files for the app.
 storage_dir: /home/user/.config/myapp
 
@@ -174,19 +174,19 @@ database_server:
 
   # ## host ###
   # YAML-path:   database_server.host
-  # Type:        str
+  # Type:        str or null
   # Required:    False
   # Default:     "localhost"
-  # Env-var:     'APP_DATABASE_SERVER__HOST'
+  # Env-var:     'APP_DATABASE_SERVER__HOST' (can not set null, use null in the YAML file)
   # Description: The hostname the database will be available at
   host: localhost
 
   # ## port ###
   # YAML-path:   database_server.port
-  # Type:        int
+  # Type:        int or null
   # Required:    False
   # Default:     5678
-  # Env-var:     'APP_DATABASE_SERVER__PORT'
+  # Env-var:     'APP_DATABASE_SERVER__PORT' (can not set null, use null in the YAML file)
   # Description: The port to connect to the database
   port: 5678
 
@@ -371,18 +371,61 @@ For nested models the env var path is built as:
 # e.g. MYAPP_DATABASE__HOST  (prefix="MYAPP_", delimiter="__")
 ```
 
+What pydantic-settings can set through env vars, and what the generated files show:
+
+| Field | Env var example | Behaviour |
+|---|---|---|
+| Field of a nested model, any depth | `MYAPP_DATABASE__SERVER__HOST=db` | Sets only this value. The other values from the YAML file stay. |
+| Whole nested model | `MYAPP_DATABASE='{"name": "x"}'` | JSON, merged into the values from the YAML file. |
+| List (`List[str]`, `List[SubModel]`) | `MYAPP_HOSTS='["a", "b"]'` | JSON, replaces the whole list. A single list element (`MYAPP_HOSTS__0`) can not be set, so list elements show no env var. |
+| Dict value (`Dict[str, ...]`) | `MYAPP_LABELS__team=core` | `<dict-key>` stands for the key. Env var names are case-insensitive by default, so the key arrives in lower case. |
+
+Only the root model's `env_prefix` and `env_nested_delimiter` count. A nested `BaseSettings`
+sub-model's own `env_prefix` is not used for its fields. Without `env_nested_delimiter`, nested
+fields have no env var of their own and can only be set through the JSON value of the top-level
+field. With `case_sensitive=True`, the env var names keep the case of the field names.
+A sub-model that defaults to null has no fields in the YAML file, so its comment lists the env
+vars of its fields under `Env-vars of the sub-fields:`.
+
+#### Nullable fields
+
+A nullable field (`Optional[int]`, `int | None`) shows its type as `int or null`. By default,
+pydantic-settings can not set such a field to null through an env var: an `int` or `bool` field
+fails validation, a `str` field gets the literal text `null`, and a list, dict or model field
+silently keeps its default. Only the YAML file can set null then. Set `env_parse_none_str` to name
+the env var value that means null:
+
+```python
+class MyConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MYAPP_", env_parse_none_str="null")
+
+    max_age_days: Optional[int] = 30
+    # → Type:    int or null
+    # → Env-var: 'MYAPP_MAX_AGE_DAYS' ('null' sets null)
+```
+
+For a nullable field whose default is not null, the `Env-var:` hint says which case applies:
+`('null' sets null)` with `env_parse_none_str`, or `(can not set null, use null in the YAML file)`
+without it. A field that defaults to null gets no hint, since leaving the env var unset already
+gives null.
+
 ---
 
 ## Environment variable overrides
 
 `load()` creates a thin dynamic subclass that adds the YAML file as a pydantic-settings source while keeping the normal env var source with higher priority. The effective source priority (highest → lowest) is:
 
-1. **Environment variables** (respects `env_prefix` / `env_nested_delimiter`)
-2. **YAML file** values
-3. **Model defaults**
+1. **Init arguments** (values passed to the settings class directly)
+2. **Environment variables** (respects `env_prefix` / `env_nested_delimiter`)
+3. **`.env` file** (if the model sets `env_file`)
+4. **Secrets directory** (if the model sets `secrets_dir`)
+5. **YAML file** values
+6. **Model defaults**
 
 No changes to your settings class are required.
 
+A missing YAML file is not an error: `load()` then returns the model defaults plus whatever the env vars, the `.env` file and the secrets directory set.
+
 ---
 
 ## Development
@@ -411,7 +454,7 @@ To visually inspect the generated YAML and Markdown for all built-in test models
 pdm run smoke
 ```
 
-This writes four files per model (YAML config template + Markdown reference) to `smoke_output/` and prints a preview of each to the terminal. The output is committed to the repository and linked from the [Example gallery](#example-gallery) section — re-run the script and commit the results whenever the generator logic changes.
+This writes two files per model (YAML config template + Markdown reference) to `smoke_output/` and prints a preview of each to the terminal. The output is committed to the repository and linked from the [Example gallery](#example-gallery) section. Re-run the script and commit the results whenever the generator logic changes.
 
 ```
 smoke_output/

psyplus-1.1.0/psyplus/field_info.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import fields as pydantic_fields
+from pydantic_core import PydanticUndefined
+from pydantic_settings import BaseSettings
+
+from psyplus.utils import (
+    clean_annotation,
+    get_literal_list,
+    get_str_dict_as_table,
+    has_literal,
+    is_nullable,
+    python_annotation_to_readable,
+    readable_constraints,
+    to_json_text,
+    to_yaml_text,
+)
+
+log = logging.getLogger(__name__)
+
+ENV_VAR_LISTINDEX_PLACEHOLDER = "<list-index>"
+ENV_VAR_DICTKEY_PLACEHOLDER = "<dict-key>"
+# Stands for "any element" in a path, e.g. ``servers[*].host`` in the Markdown doc.
+ANY_ITEM = "*"
+
+_warned_no_delimiter: set[type] = set()
+
+
+@dataclass
+class ListIndex:
+    index: int | str
+
+    def __str__(self) -> str:
+        return f"[{self.index}]"
+
+
+@dataclass
+class DictKey:
+    key: Any
+
+    def __str__(self) -> str:
+        if self.key == ANY_ITEM:
+            return "[*]"
+        return f"['{self.key}']"
+
+
+def path_to_str(path: list[str | ListIndex | DictKey]) -> str:
+    """``["servers", ListIndex(0), "host"]`` -> ``servers[0].host``."""
+    out = ""
+    for segment in path:
+        if isinstance(segment, str):
+            out += f".{segment}" if out else segment
+        else:
+            out += str(segment)
+    return out
+
+
+@dataclass
+class FieldInfoContainer:
+    """Wraps metadata for a single settings field and generates YAML comments / markdown."""
+
+    path: list[str | ListIndex | DictKey]
+    field_name: str
+    root_settings_class: type[BaseSettings]
+    field_info: pydantic_fields.FieldInfo | None = None
+    # annotation is used for dict/list items where field_info is not available
+    annotation: Any = None
+
+    def get_annotation(self) -> Any:
+        if self.field_info is not None and self.field_info.annotation is not None:
+            return self.field_info.annotation
+        return self.annotation
+
+    def get_env_var(self) -> str | None:
+        """The env var that sets this field, or None when pydantic-settings offers none.
+
+        pydantic-settings can not set a single list element: ``APP_ITEMS__0`` is read
+        as the dict ``{"0": ...}`` and fails list validation, so list elements only
+        change through the JSON value of the whole list. Without
+        ``env_nested_delimiter`` only top-level fields have an env var.
+        """
+        config = self.root_settings_class.model_config
+        delimiter = config.get("env_nested_delimiter") or ""
+        case_sensitive = bool(config.get("case_sensitive", False))
+        prefix = config.get("env_prefix") or ""
+        if not case_sensitive:
+            prefix = prefix.upper()
+
+        if any(isinstance(segment, ListIndex) for segment in self.path):
+            return None
+
+        if len(self.path) > 1 and not delimiter:
+            if (
+                not os.getenv("PSYPLUS_SUPPRESS_ENV_WARNING")
+                and self.root_settings_class not in _warned_no_delimiter
+            ):
+                _warned_no_delimiter.add(self.root_settings_class)
+                log.warning(
+                    f"`{self.root_settings_class.__name__}` has nested fields but no "
+                    "`env_nested_delimiter`, so they can only be set through the JSON value "
+                    "of their top-level env var. "
+                    "Set env var PSYPLUS_SUPPRESS_ENV_WARNING=true to silence this warning. "
+                    "See https://docs.pydantic.dev/latest/concepts/pydantic_settings/#parsing-environment-variable-values"
+                )
+            return None
+
+        parts: list[str] = []
+        for segment in self.path:
+            if isinstance(segment, str):
+                parts.append(segment if case_sensitive else segment.upper())
+            else:
+                parts.append(ENV_VAR_DICTKEY_PLACEHOLDER)
+        return prefix + delimiter.join(parts)
+
+    def get_path_str(self) -> str:
+        return path_to_str(self.path)
+
+    def get_type_string(self) -> str | None:
+        type_str = python_annotation_to_readable(self.get_annotation())
+        if type_str and is_nullable(self.get_annotation()):
+            type_str += " or null"
+        return type_str
+
+    def needs_env_var_null_note(self) -> bool:
+        """True for a nullable field whose default is not null.
+
+        Only there does a user have a reason to set null through the env var, and
+        pydantic-settings can not do that unless the model sets
+        ``env_parse_none_str``: without it an int or bool field fails validation,
+        a str field gets the literal text, and a list, dict or model field silently
+        keeps its default.
+        """
+        if self.field_info is None or self.field_info.default is None:
+            return False
+        return is_nullable(self.get_annotation())
+
+    def get_env_parse_none_str(self) -> str | None:
+        """The env var value that means null (``env_parse_none_str``), if the model sets one."""
+        return self.root_settings_class.model_config.get("env_parse_none_str")
+
+    def get_enum_vals(self) -> list[Any] | None:
+        if has_literal(self.get_annotation()):
+            return get_literal_list(self.get_annotation())
+        return None
+
+    def get_sub_field_env_vars(self) -> list[tuple[str, str]]:
+        """``(path, env var)`` for the fields of this field's sub-model, recursively.
+
+        Only direct sub-models are followed (``Optional[Model]`` included); fields
+        without an env var of their own (list elements, no ``env_nested_delimiter``)
+        are left out.
+        """
+        out: list[tuple[str, str]] = []
+
+        def walk(container: FieldInfoContainer, seen: tuple[type, ...]) -> None:
+            cls = clean_annotation(container.get_annotation())
+            if not (isinstance(cls, type) and issubclass(cls, BaseModel)) or cls in seen:
+                return
+            for key, fi in cls.model_fields.items():
+                child = FieldInfoContainer(
+                    path=container.path + [key],
+                    field_name=key,
+                    field_info=fi,
+                    root_settings_class=self.root_settings_class,
+                )
+                env_var = child.get_env_var()
+                if env_var:
+                    out.append((child.get_path_str(), env_var))
+                walk(child, seen + (cls,))
+
+        walk(self, ())
+        return out
+
+    def build_comment_lines(
+        self,
+        overwrite_required: bool | None = None,
+        list_sub_field_env_vars: bool = False,
+    ) -> list[str]:
+        """Build the list of lines that form the YAML comment block above a key.
+
+        ``list_sub_field_env_vars`` adds the env vars of the sub-model's fields. The
+        YAML generator sets it when the sub-model is null, because its fields (and
+        their comments) are then not written to the file.
+        """
+        fi = self.field_info or pydantic_fields.FieldInfo()
+        key = self.field_name
+        path = self.get_path_str()
+
+        header = f"## {key}"
+        if fi.title:
+            header += f" - {fi.title}"
+        header += " ###"
+
+        data: dict[str, str] = {}
+
+        if key != path:
+            data["YAML-path:"] = path
+
+        type_str = self.get_type_string()
+        if type_str:
+            data["Type:"] = type_str
+
+        is_required = fi.is_required() if overwrite_required is None else overwrite_required
+        data["Required:"] = str(is_required)
+
+        if fi.default is not PydanticUndefined:
+            if fi.default is None:
+                data["Default:"] = "null"
+            else:
+                data["Default:"] = to_json_text(fi.default)
+
+        enum_vals = self.get_enum_vals()
+        if enum_vals is not None:
+            data["Allowed vals:"] = str(enum_vals)
+
+        constraints = readable_constraints(fi.metadata)
+        if constraints:
+            data["Constraints:"] = constraints
+
+        env_var = self.get_env_var()
+        if env_var:
+            data["Env-var:"] = f"'{env_var}'"
+            if self.needs_env_var_null_note():
+                none_str = self.get_env_parse_none_str()
+                if none_str is not None:
+                    data["Env-var:"] += f" ('{none_str}' sets null)"
+                else:
+                    data["Env-var:"] += " (can not set null, use null in the YAML file)"
+
+        if fi.description:
+            data["Description:"] = fi.description
+
+        table = get_str_dict_as_table(data)
+        lines = [header]
+        if table:
+            lines.extend(table.split("\n"))
+
+        if list_sub_field_env_vars:
+            sub_env_vars = self.get_sub_field_env_vars()
+            if sub_env_vars:
+                lines.append("Env-vars of the sub-fields:")
+                lines.extend(f"  {sub_path}: '{env}'" for sub_path, env in sub_env_vars)
+
+        if fi.examples:
+            lines.extend(self._example_lines(key))
+
+        return lines
+
+    def _example_lines(self, key: str) -> list[str]:
+        if not self.field_info or not self.field_info.examples:
+            return []
+        examples = self.field_info.examples
+        lines: list[str] = []
+        for i, example in enumerate(examples):
+            label = f"Example No. {i + 1}:" if len(examples) > 1 else "Example:"
+            lines.append(label)
+            try:
+                as_yaml = to_yaml_text({key: example})
+                for line in as_yaml.rstrip("\n").split("\n"):
+                    lines.append(f" >{line}")
+            except Exception:
+                lines.append(f" >{repr(example)}")
+        return lines

{psyplus-1.0.0 → psyplus-1.1.0}/psyplus/main.py

@@ -1,17 +1,13 @@
 from __future__ import annotations
 
-import logging
 from pathlib import Path
 from typing import Literal, Type, Union
 
-import yaml
-from pydantic_settings import BaseSettings
+from pydantic_settings import BaseSettings, YamlConfigSettingsSource
 
 from psyplus.markdown_generator import MarkdownDocGenerator
 from psyplus.yaml_generator import YamlFileGenerator
 
-log = logging.getLogger(__name__)
-
 
 class YamlSettingsPlus:
     """Central helper for generating and reading pydantic-settings YAML configs.
@@ -47,6 +43,10 @@ class YamlSettingsPlus:
         """
         if self.config_file is None:
             raise ValueError("file_path must be set to generate a config file.")
+        if on_exists not in ("skip", "overwrite", "error"):
+            raise ValueError(
+                f"on_exists must be 'skip', 'overwrite' or 'error', not {on_exists!r}."
+            )
 
         self.config_file.parent.mkdir(parents=True, exist_ok=True)
 
@@ -60,11 +60,11 @@ class YamlSettingsPlus:
                 )
             # on_exists == "overwrite" → fall through
 
-        self.config_file.write_text(self.render_yaml())
+        self.config_file.write_text(self.render_yaml(), encoding="utf-8")
 
     def generate_markdown_doc(self, output_path: Union[str, Path]) -> None:
         """Write a Markdown reference document for the settings model to *output_path*."""
-        Path(output_path).write_text(self.render_markdown())
+        Path(output_path).write_text(self.render_markdown(), encoding="utf-8")
 
     # ------------------------------------------------------------------
     # Render to string (no file I/O)
@@ -91,8 +91,10 @@ class YamlSettingsPlus:
         ``env_nested_delimiter``) take priority over YAML file values,
         following standard pydantic-settings source precedence.
 
-        Tip: if you want this behaviour without psyplus, configure
-        ``yaml_file`` directly in your model's ``model_config``::
+        Tip: to get similar behaviour without psyplus, set ``yaml_file`` in
+        your model's ``model_config`` and add a ``YamlConfigSettingsSource``
+        in ``settings_customise_sources``. Setting ``yaml_file`` alone is not
+        enough, pydantic-settings does not read it by default::
 
             class MyConfig(BaseSettings):
                 model_config = SettingsConfigDict(
@@ -101,43 +103,46 @@ class YamlSettingsPlus:
                     env_nested_delimiter="__",
                 )
 
-            config = MyConfig()  # reads YAML + env vars automatically
+                @classmethod
+                def settings_customise_sources(
+                    cls, settings_cls, init_settings, env_settings,
+                    dotenv_settings, file_secret_settings,
+                ):
+                    return (
+                        init_settings, env_settings, dotenv_settings,
+                        file_secret_settings,
+                        YamlConfigSettingsSource(settings_cls),
+                    )
         """
         if self.config_file is None:
             raise ValueError("file_path must be set to load a config file.")
 
         yaml_path = self.config_file
         base_cls = self.model
-
-        try:
-            try:
-                from pydantic_settings import YamlSettingsSource as _YamlSource
-            except ImportError:
-                from pydantic_settings import YamlConfigSettingsSource as _YamlSource  # type: ignore[assignment]
-
-            class _ModelWithYaml(base_cls):  # type: ignore[valid-type,misc]
-                @classmethod
-                def settings_customise_sources(
-                    cls,
-                    settings_cls: Type[BaseSettings],
+        # The generated file is written as UTF-8, so read it as UTF-8 unless the
+        # model asks for another encoding.
+        encoding = base_cls.model_config.get("yaml_file_encoding") or "utf-8"
+
+        class _ModelWithYaml(base_cls):  # type: ignore[valid-type,misc]
+            @classmethod
+            def settings_customise_sources(
+                cls,
+                settings_cls: Type[BaseSettings],
+                init_settings,
+                env_settings,
+                dotenv_settings,
+                file_secret_settings,
+            ):
+                # The YAML file is the lowest file based source: env vars, the
+                # .env file and the secrets directory all override it.
+                return (
                     init_settings,
                     env_settings,
                     dotenv_settings,
                     file_secret_settings,
-                ):
-                    return (
-                        init_settings,
-                        env_settings,
-                        _YamlSource(settings_cls, yaml_file=yaml_path),
-                    )
-
-            return _ModelWithYaml()
+                    YamlConfigSettingsSource(
+                        settings_cls, yaml_file=yaml_path, yaml_file_encoding=encoding
+                    ),
+                )
 
-        except ImportError:
-            log.warning(
-                "pydantic-settings >= 2.3 is required for automatic env-var overlay "
-                "in load(). Falling back to YAML-only loading."
-            )
-            with open(yaml_path) as fh:
-                data = yaml.safe_load(fh) or {}
-            return self.model.model_validate(data)
+        return _ModelWithYaml()