pydantic-settings-yaml-plus
A helper library that builds upon pydantic-settings to generate, read, and document YAML config files, with comment headers that explain every setting's type, default value, allowed values, environment variable override, and description.
- pydantic-settings-yaml-plus
Features
- Generate documented YAML: each field gets a comment block with its type, required flag, default value, allowed enum values, corresponding environment variable, description, and examples.
- Nested models:
BaseModelsub-models are rendered as indented YAML sections with full comment headers. - Read back with env-var override:
load()loads the YAML file and still applies environment variable overrides using pydantic-settings' standard machinery. - Single list elements from env vars:
load()also reads env vars likeAPP_SERVERS__0__HOSTthat change one element of a list from the YAML file. - Markdown docs: generate a Markdown reference document straight from your settings class.
- Zero boilerplate: define your settings in a standard
pydantic_settings.BaseSettingssubclass; psyplus does the rest.
Installation
pip install psyplus
Requirements: Python ≥ 3.11, pydantic ≥ 2.10, pydantic-settings ≥ 2.13.1, ruamel.yaml ≥ 0.17.5, PyYAML ≥ 6.0.1
Quick start
1. Define your settings model
# config.py
from typing import Annotated, Dict, List, Literal, Optional
from pathlib import Path, PurePath
from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict
class DatabaseServerSettings(BaseSettings):
model_config = SettingsConfigDict(env_nested_delimiter="__")
host: Optional[str] = Field(
default="localhost",
description="The hostname the database will be available at",
)
port: Optional[int] = Field(
default=5678,
description="The port to connect to the database",
)
database_names: List[str] = Field(
description="The names of the databases to use",
examples=[["mydb", "theotherdb"]],
)
class MyAppConfig(BaseSettings):
model_config = SettingsConfigDict(env_prefix="APP_", env_nested_delimiter="__")
log_level: Optional[Literal["INFO", "DEBUG"]] = "INFO"
app_name: Optional[str] = Field(
default="THE APP",
description="The display name of the app",
examples=["THAT APP", "THIS APP"],
)
storage_dir: Optional[str] = Field(
description="A directory to store files for the app.",
default_factory=lambda: str(Path(PurePath(Path().home(), ".config/myapp/"))),
)
admin_pw: Annotated[str, Field(description="The init password for the admin account")]
database_server: DatabaseServerSettings = Field(
description="The settings for the database server",
examples=[
DatabaseServerSettings(
host="db.company.org", port=1234, database_names=["db1", "db2"]
)
],
)
init_values: Dict[str, str]
Note on
model_config: useSettingsConfigDict(pydantic-settings v2 style) rather than the old innerclass Config. Both work, butSettingsConfigDictis preferred.
2. Generate the YAML config file
from psyplus import YamlSettingsPlus
from config import MyAppConfig
handler = YamlSettingsPlus(MyAppConfig, "config.yaml")
handler.generate_config_file() # silently skips if file exists (default)
handler.generate_config_file(on_exists="overwrite") # replace existing file
handler.generate_config_file(on_exists="error") # raise FileExistsError if file exists
Generated YAML output
The command above creates config.yaml with a comment block above every key:
# ## log_level ###
# Type: Enum or null
# Required: False
# Default: "INFO"
# Allowed vals: ['INFO', 'DEBUG']
# Env-var: 'APP_LOG_LEVEL' (can not set null, use null in the YAML file)
log_level: INFO
# ## app_name ###
# Type: str or null
# Required: False
# Default: "THE APP"
# 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
# Example No. 2:
# >app_name: THIS APP
app_name: THE APP
# ## storage_dir ###
# Type: str or null
# Required: False
# 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
# ## admin_pw ###
# Type: str
# Required: True
# Env-var: 'APP_ADMIN_PW'
# Description: The init password for the admin account
admin_pw:
# ## database_server ###
# Type: Object (DatabaseServerSettings)
# Required: True
# Env-var: 'APP_DATABASE_SERVER'
# Description: The settings for the database server
# Example:
# >database_server:
# > host: db.company.org
# > port: 1234
# > database_names:
# > - db1
# > - db2
database_server:
# ## host ###
# YAML-path: database_server.host
# Type: str or null
# Required: False
# Default: "localhost"
# 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 or null
# Required: False
# Default: 5678
# 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
# ## database_names ###
# YAML-path: database_server.database_names
# Type: List of str
# Required: True
# Env-var: 'APP_DATABASE_SERVER__DATABASE_NAMES'
# 'APP_DATABASE_SERVER__DATABASE_NAMES__<list-index>' (one element, 0 is the first; psyplus load() only)
# Description: The names of the databases to use
# Example:
# >database_names:
# >- mydb
# >- theotherdb
database_names:
# ## init_values ###
# Type: Dictionary of (str, str)
# Required: True
# Env-var: 'APP_INIT_VALUES'
# 'APP_INIT_VALUES__<dict-key>' sets one entry, its key arrives in lower case
init_values:
Required fields without a default are written with an empty value (admin_pw:, which YAML reads as null),
whatever their type. A required sub-model without a default shows its fields, so the structure is
visible, with its own required fields empty. The Required: True comment marks every value to fill in.
Until that is done, load() raises a pydantic ValidationError that names each empty required field,
so an app does not start with an unfilled config. (A required Optional[...] field is the exception:
null is a valid value for it.)
Reading the config
from psyplus import YamlSettingsPlus
from config import MyAppConfig
handler = YamlSettingsPlus(MyAppConfig, "config.yaml")
config: MyAppConfig = handler.load()
print(config.database_server.host) # → "localhost" (or whatever is in the YAML)
print(config.log_level) # → "INFO"
load() returns an instance of your model class itself (type(config) is MyAppConfig), validated once, exactly as if you had called MyAppConfig(). It compares equal to and pickles like any other MyAppConfig instance.
load() honours environment variable overrides through pydantic-settings' standard source priority: env vars beat YAML values. For example:
export APP_LOG_LEVEL=DEBUG
…will make config.log_level == "DEBUG" even if the YAML file says INFO.
Tip: if you prefer to keep psyplus out of your runtime path, configure
yaml_filedirectly in your model and add a YAML source (settingyaml_filealone is not enough, pydantic-settings does not read it by default):from pydantic_settings import BaseSettings, SettingsConfigDict, YamlConfigSettingsSource class MyAppConfig(BaseSettings): model_config = SettingsConfigDict( yaml_file="config.yaml", env_prefix="APP_", env_nested_delimiter="__", ) @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), ) config = MyAppConfig() # reads YAML + env varsSuch a model still works with
load(): psyplus then reads its ownfile_pathin place ofyaml_file(see Environment variable overrides).
Generating Markdown documentation
Write a Markdown reference document to disk:
from psyplus import YamlSettingsPlus
from config import MyAppConfig
YamlSettingsPlus(MyAppConfig).generate_markdown_doc("SETTINGS.md")
Or get the Markdown as a string (e.g. to post to a wiki API):
md = YamlSettingsPlus(MyAppConfig).render_markdown()
Both produce a document with a property table for every field: type, required flag, default, allowed values, environment variable, description, and examples.
The fields of a nested model get their own sections, headed by their full path (database.host,
servers[*].port). A field that holds one of several models (Union[Cat, Dog]) gets one section
per model, labelled option 1 of 2 and so on. Markdown has no headings below level 6, so deeper
fields stay at level 6 and the path in the heading shows where they belong.
Example gallery
The table below links the bundled test models to their pre-generated output so you can see exactly what psyplus produces before writing a single line of your own config.
| Model | Source | What it demonstrates | YAML output | Markdown output |
|---|---|---|---|---|
SimpleModel |
tests/models/simple.py | Flat settings: scalars, Optional, Literal, List, Dict, Annotated metadata, default_factory |
SimpleModel.yaml | SimpleModel.md |
NestedModel |
tests/models/nested.py | Nested BaseModel sub-field, optional sub-model, env-var path generation with env_nested_delimiter |
NestedModel.yaml | NestedModel.md |
MultiNestedModel |
tests/models/nested.py | List[BaseModel] and Dict[str, BaseModel] fields; YAML renders each item, Markdown recurses into the item schema |
MultiNestedModel.yaml | MultiNestedModel.md |
MyAppConfig |
tests/models/readme_example.py | The full README quick-start model with nested database settings and field examples | MyAppConfig.yaml | MyAppConfig.md |
These files are regenerated automatically by the smoke script (pdm run smoke) and committed to the repository, so they are always in sync with the current code.
API reference
YamlSettingsPlus(model, file_path=None)
| Parameter | Type | Description |
|---|---|---|
model |
Type[BaseSettings] |
The pydantic-settings class to work with |
file_path |
str | Path | None |
Path of the YAML config file |
Methods
| Method | Description |
|---|---|
generate_config_file(on_exists="skip") |
Write a documented YAML template to file_path. on_exists controls what happens when the file already exists: "skip" (default) does nothing, "overwrite" replaces it, "error" raises FileExistsError. |
generate_markdown_doc(output_path) |
Write a Markdown reference document to output_path. |
render_yaml() → str |
Render the documented YAML as a string without touching the filesystem. |
render_markdown() → str |
Render the Markdown reference document as a string without touching the filesystem. |
load() → model |
Load file_path, apply env var overrides (including single list elements), return a validated instance of model. |
YamlFileGenerator(settings_class, indent_size=2)
Low-level generator for the YAML string. Useful if you want to customise output without using YamlSettingsPlus.
from psyplus import YamlFileGenerator
from config import MyAppConfig
gen = YamlFileGenerator(MyAppConfig)
gen.parse()
print(gen.get_yaml())
MarkdownDocGenerator(settings_class)
Low-level generator for the Markdown string.
from psyplus import MarkdownDocGenerator
from config import MyAppConfig
doc = MarkdownDocGenerator(MyAppConfig).generate()
Defining your settings model
psyplus works with any standard pydantic_settings.BaseSettings subclass. The richer the metadata you provide on your fields, the more informative the generated YAML/Markdown will be.
Useful Field() kwargs
| Kwarg | Shown in output as |
|---|---|
description="…" |
# Description: comment row |
title="…" |
Appended to the ## field_name - Title ### header |
examples=[…] |
# Example: block with rendered YAML |
default=… |
# Default: comment row |
default_factory=lambda: … |
# Default: not shown (factory evaluated at generation time, its result is the value in the YAML file) |
default_factory=lambda data: … |
Same, the factory gets the values of the fields defined before it. If it needs a required value without a default, the field is written empty with a note to remove the key |
max_length=… / gt=… / etc. |
# Constraints: comment row |
Configuring env vars
Set env_prefix and env_nested_delimiter in model_config so that psyplus can generate correct Env-var: hints:
from pydantic_settings import BaseSettings, SettingsConfigDict
class MyConfig(BaseSettings):
model_config = SettingsConfigDict(
env_prefix="MYAPP_",
env_nested_delimiter="__",
)
database_host: str = "localhost"
# → Env-var: 'MYAPP_DATABASE_HOST'
For nested models the env var path is built as:
{env_prefix}{parent_key}{env_nested_delimiter}{child_key}
# 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], tuple, set) |
MYAPP_HOSTS='["a", "b"]' |
JSON, replaces the whole list. |
| One list element, or a field of it | MYAPP_HOSTS__1=b, MYAPP_SERVERS__0__PORT=8080 |
Only with load(), see Single list elements. <list-index> stands for the position, 0 is the first. Changes this element of the list from the YAML file, the other elements stay. |
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, and the generated files say so next to the env var of the dict field. Keys in a JSON value keep their 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. With
env_nested_max_split, only fields that many levels below the top-level field have an env var
(a list index counts as a level).
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:. For a field that holds one of several
models (Union[Cat, Dog]), this list covers the fields of every model.
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:
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.
Fields with an alias
pydantic-settings reads the YAML file and the env vars by a field's validation alias, so psyplus
uses it as the YAML key, in the YAML path and in the env var name. That covers alias=,
validation_alias= and an alias_generator such as to_camel, also with populate_by_name=True.
A serialization_alias changes nothing.
class Database(BaseModel):
host_name: str = Field("localhost", alias="hostName")
class MyConfig(BaseSettings):
model_config = SettingsConfigDict(env_prefix="MYAPP_", env_nested_delimiter="__")
log_level: str = Field("INFO", alias="logLevel")
# → YAML key: logLevel, Env-var: 'LOGLEVEL'
database: Database = Database()
# → YAML path: database.hostName, Env-var: 'MYAPP_DATABASE__HOSTNAME'
| Field | YAML key | Env var |
|---|---|---|
alias="logLevel" or validation_alias="logLevel" |
logLevel |
LOGLEVEL |
validation_alias=AliasChoices("a", "b") |
a, the first string choice |
A |
validation_alias=AliasPath("database", "host") |
host inside a database map |
none |
serialization_alias="x" only |
the field name | as without an alias |
- Prefix: pydantic-settings puts
env_prefixin front of an alias only when the model setsenv_prefix_target="alias"or"all". With the default"variable"only field names get it. What counts is the top-level field:MYAPP_DATABASE__HOSTNAMEabove gets the prefix becausedatabasehas no alias. - Case: without
case_sensitive=Trueenv var names arrive in lower case, and pydantic-settings matches them back to a camelCase key only along plain sub-model fields. Below a dict, a Union of models, or anOptionalsub-model deeper down, a key with upper case letters can not be set through its own env var, so none is shown there. The JSON value of the field above still works. populate_by_name: below a top-level field with an alias, the fields and dict entries have no env var of their own. pydantic-settings files them under the field name, which clashes with the alias key from the YAML file. The JSON value of the top-level field still works.AliasPath: a path of names is written as nested maps, which several fields may share. A path with a list index (AliasPath("servers", 0)) or one that clashes with another key is not written; its comment block says where to add it. No env var sets anAliasPathfield: pydantic-settings would read each element of the path as an env var of its own.- Alias and validation alias differ: pydantic-settings reads a top-level field from the YAML
file only under its
alias. When validation expects another name (alias="a", validation_alias="b", analias_generatornext to an explicitvalidation_alias, orvalidate_by_alias=False), no key works, so the field is left out of the YAML file. A note in the YAML file and in the Markdown doc says so. Set it through its env var instead.
Environment variable overrides
load() uses the same sources pydantic-settings uses for your model and adds the YAML file as the lowest priority source, just above the field defaults. For a model without its own settings_customise_sources the effective source priority (highest → lowest) is:
- Environment variables (respects
env_prefix/env_nested_delimiter) .envfile (if the model setsenv_file)- Secrets directory (if the model sets
secrets_dir) - YAML file values
- Model defaults
No changes to your settings class are required.
If your model defines settings_customise_sources, load() respects it: the YAML file is added after the sources it returns, and a source it leaves out stays out. A model that drops env_settings, for example, ignores env vars in load() too. If it already returns a YamlConfigSettingsSource, load() adds no second one but reads file_path through it, at the position your model chose.
Command line parsing configured in model_config (cli_parse_args, cli_settings_source) also applies to load(), with the command line beating all other sources.
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.
Single list elements
pydantic-settings itself can only replace a whole list through an env var (APP_SERVERS='[{"host": "a"}]'). load() also reads env vars that address one element by its position, in the environment and in the .env file:
export APP_SERVERS__0__HOST=db.internal # field of the first element
export APP_TAGS__1=beta # second element of a List[str]
export APP_GROUPS__admins__0=ann # list inside a dict
export APP_MATRIX__1__0=7 # list inside a list
The generated YAML comments and Markdown docs show these names with <list-index> in place of the position (APP_SERVERS__<list-index>__HOST). They work with load() only: a model instantiated directly (MyAppConfig()) reads them the way pydantic-settings does, which fails list validation.
The env var changes the list that the lower priority sources provide (usually the YAML file) instead of replacing it:
- Index below the list length: changes that element. The fields of an element model are merged into it (
APP_SERVERS__0__HOSTkeeps the element'sport), the same goes for a JSON object (APP_SERVERS__0='{"host": "x"}'). Any other value replaces the element. - Index equal to the list length: adds an element. Several new elements need consecutive indices (2, 3, 4 for a list of two). A new element that is a model needs its required fields set too.
- Index further beyond the end:
load()fails with an error that names the env var. - List not in the YAML file: the env var changes the field's default list. A field without a default (or with
null) starts as an empty list, so its indices start at 0. A default from adefault_factorythat takes the other values (lambda data: ...) can not be changed this way:load()fails with an error, put the list in the YAML file or set it as a whole. - Aliases: the list is found in the YAML file under the field name or any of its aliases, and the changed list stays under that key.
- Whole list and elements together: an index env var changes the whole list value from the same place (
APP_TAGS='["a", "b"]'plusAPP_TAGS__1=cgives["a", "c"]). A whole value that is not a JSON list there (a comma separated string for aNoDecodefield, for example) can not be changed this way,load()fails with an error. A whole list from a higher priority source replaces everything below it, as usual. - Not a list index:
-1or01where a list is expected is an error that names the env var. Other names (APP_TAGS__NAME) are left to pydantic-settings, as without psyplus. - A list or a dict (
Union[List[str], Dict[str, str]]): a number is a list index only where the value it changes is a list. Where it is a dict, the number is a dict key, as pydantic-settings reads it. - Tuples and sets work like lists. For a set, the index counts the elements in the order the YAML file lists them.
Only the env and .env sources that load() hands to your model's settings_customise_sources (env_settings, dotenv_settings) read list indices. A source your model builds itself (EnvSettingsSource(settings_cls, env_prefix=...)) works as pydantic-settings makes it, without list index support. Under load(), env_settings and dotenv_settings are subclasses of EnvSettingsSource and DotEnvSettingsSource: isinstance() checks on them work, type(...) is EnvSettingsSource does not.
Development
This project uses PDM for dependency management.
git clone https://github.com/DZD-eV-Diabetes-Research/pydantic-settings-yaml-plus
cd pydantic-settings-yaml-plus
pdm install -G test
pdm run pytest
If you prefer plain pip (no PDM):
pip install -e ".[test]"
pytest
Smoke test
To visually inspect the generated YAML and Markdown for all built-in test models, run:
pdm run smoke
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 section. Re-run the script and commit the results whenever the generator logic changes.
smoke_output/
├── SimpleModel.yaml
├── SimpleModel.md
├── NestedModel.yaml
├── NestedModel.md
├── MultiNestedModel.yaml
├── MultiNestedModel.md
├── MyAppConfig.yaml
└── MyAppConfig.md
Running tests with coverage
pdm run pytest tests/ --cov=psyplus --cov-report=term-missing
PDM cheat-sheet
| Task | Command |
|---|---|
| Install all deps incl. test extras | pdm install -G test |
| Add a runtime dependency | pdm add <package> |
| Add a test-only dependency | pdm add -G test <package> |
| Update lock file | pdm update |
| Run any command in the PDM venv | pdm run <command> |
| Show installed packages | pdm list |
Tests are in tests/ and cover utilities, field metadata, YAML generation, Markdown generation, and the full YamlSettingsPlus API. They run in CI against Python 3.12, 3.13, and 3.14.
Metadata
Release files for psyplus 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| psyplus-1.2.0.tar.gz | 80.8 kB | Without provenance | Details for psyplus-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| psyplus-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for psyplus-1.2.0-py3-none-any.whl |
Total release size: 121.9 kB
Release files / psyplus-1.2.0.tar.gz
| Download URL | psyplus-1.2.0.tar.gz |
|---|---|
| Size | 80.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
34c09ff88008a34278144531e5d3b82b3a8b42501dff8ab4703b2e58f3935e7e
|
|
BLAKE2b-256 checksum How to use checksums |
12533a11701a7b593e9464f0dc90990d6ebe321ad852c7622ab9352b7d541961
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / psyplus-1.2.0-py3-none-any.whl
| Download URL | psyplus-1.2.0-py3-none-any.whl |
|---|---|
| Size | 41.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3ac8bd1925e1dc3310bb633c2811f77c725ab9cd514bec246688c86e0f686cb3
|
|
BLAKE2b-256 checksum How to use checksums |
6553f1d73f27bc12aa0e6376802076ce2ad25a0c753a8d1a5724c05890ac223e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for psyplus 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.