Skip to main content

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.


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 — BaseModel sub-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.
  • Markdown docs — generate a Markdown reference document straight from your settings class.
  • Zero boilerplate — define your settings in a standard pydantic_settings.BaseSettings subclass; psyplus does the rest.

Installation

pip install psyplus

Requirements: Python ≥ 3.12, pydantic ≥ 2.0, pydantic-settings ≥ 2.3


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: use SettingsConfigDict (pydantic-settings v2 style) rather than the old inner class Config. Both work, but SettingsConfigDict is 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'
  # 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'
init_values: {}

Required fields without defaults are written with an empty placeholder ('', [], {}).
The Required: True comment tells the user they must fill these in before the app will validate.


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() 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_file directly in your model and call it without psyplus:

from pydantic_settings import BaseSettings, SettingsConfigDict

class MyAppConfig(BaseSettings):
    model_config = SettingsConfigDict(
        yaml_file="config.yaml",
        env_prefix="APP_",
        env_nested_delimiter="__",
    )

config = MyAppConfig()  # reads YAML + env vars automatically

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 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() → BaseSettings Load file_path, apply env var overrides, return a validated settings instance.

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)
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]) 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:

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

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

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for psyplus 1.1.0
File Size Uploaded Provenance Actions
psyplus-1.1.0.tar.gz 37.7 kB Without provenance Details for psyplus-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for psyplus 1.1.0
File Interpreter ABI Platform Actions
psyplus-1.1.0-py3-none-any.whl Python 3 none any Details for psyplus-1.1.0-py3-none-any.whl

Total release size: 58.7 kB

Release files / psyplus-1.1.0.tar.gz

Download URL psyplus-1.1.0.tar.gz
Size 37.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a651b316144ae5f63d2b22a17a6b334d7e98432085d66e577f058e471cd1fb18
BLAKE2b-256 checksum
How to use checksums
4d05cf7fcb42e022bb0110f958e59f27a884c59b9959c4bae481b143e7ca2e38
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.1.0-py3-none-any.whl

Download URL psyplus-1.1.0-py3-none-any.whl
Size 21.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
34ab1f6f45dc3340b6080ac6bd852390658368477e189f1e2a1ceed96a7888e7
BLAKE2b-256 checksum
How to use checksums
0de0d5e0d7391e91750e8d2f21216cbce2aab5d17f5210f13ffda5df624dd048
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.1.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page