loaders ¶

Custom settings sources for loading configuration from multiple file formats.

This module provides custom settings sources for pydantic-settings to load configuration from TOML, YAML, and JSON files with proper priority handling.

All loaders share common logic for field resolution and dictionary flattening, with only the file parsing implementation differing per format.

Classes:

TomlConfigSource –

Load configuration from a TOML file.
YamlConfigSource –

Load configuration from a YAML file.
JsonConfigSource –

Load configuration from a JSON file.

Classes¶

FileConfigSource ¶

Python

FileConfigSource(settings_cls: type, config_file: Path)

Bases: PydanticBaseSettingsSource, ABC

Abstract base class for file-based configuration sources.

Provides common functionality for loading configuration from files with different formats (TOML, YAML, JSON). Subclasses only need to implement the file parsing logic.

Initialize file config source.

Parameters:

settings_cls (type) –

The settings class to load config for
config_file (Path) –

Path to configuration file

Subclassed by:

loaders Classes

Methods:

get_field_value –

Get field value from configuration data.
__call__ –

Return all loaded config data.

Functions¶

_get_format_name ¶

Python

_get_format_name() -> str

Get friendly format name for error messages.

Returns:

str –

Format name (e.g., "TOML", "YAML", "JSON")

_parse_file `abstractmethod` ¶

Python

_parse_file(file_path: Path) -> dict[str, Any]

Parse configuration file and return data as dict.

Parameters:

file_path (Path) –

Path to the configuration file

Returns:

dict[str, Any] –

Parsed configuration data

Raises:

Exception –

If file parsing fails

get_field_value ¶

Python

get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]

Get field value from configuration data.

Handles nested fields using double underscore delimiter.

Parameters:

field (FieldInfo) –

The field info
field_name (str) –

The field name (may contain __ for nested access)

Returns:

tuple[Any, str, bool] –

Tuple of (value, field_name, value_is_complex)

call ¶

Python

__call__() -> dict[str, Any]

Return all loaded config data.

Returns:

dict[str, Any] –

Flattened configuration data

_flatten_nested_dict `staticmethod` ¶

Python

_flatten_nested_dict(d: dict[str, Any], parent_key: str = '') -> dict[str, Any]

Flatten nested dict with double underscore delimiter.

Converts nested dictionaries into flat dictionaries with keys joined by double underscores and uppercased, which matches pydantic-settings convention for case-insensitive field matching.

Parameters:

d (dict[str, Any]) –

Dictionary to flatten
parent_key (str, default: '' ) –

Parent key prefix, by default ""

Returns:

dict[str, Any] –

Flattened dictionary with uppercase keys

Examples:

Python Console Session

>>> _flatten_nested_dict({"a": {"b": 1}})
{'A__B': 1}
>>> _flatten_nested_dict({"value_from_toml": "test"})
{'VALUE_FROM_TOML': 'test'}

TomlConfigSource ¶

Python

TomlConfigSource(settings_cls: type, config_file: Path = Path('config.toml'))

Bases: FileConfigSource

Load configuration from a TOML file.

Initialize TOML config source.

Parameters:

settings_cls (type) –

The settings class to load config for
config_file (Path, default: Path('config.toml') ) –

Path to TOML config file, by default Path("config.toml")

Methods:

get_field_value –

Get field value from configuration data.
__call__ –

Return all loaded config data.

Functions¶

_get_format_name ¶

Python

_get_format_name() -> str

Get friendly format name for error messages.

Returns:

str –

Format name (e.g., "TOML", "YAML", "JSON")

get_field_value ¶

Python

get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]

Get field value from configuration data.

Handles nested fields using double underscore delimiter.

Parameters:

field (FieldInfo) –

The field info
field_name (str) –

The field name (may contain __ for nested access)

Returns:

tuple[Any, str, bool] –

Tuple of (value, field_name, value_is_complex)

call ¶

Python

__call__() -> dict[str, Any]

Return all loaded config data.

Returns:

dict[str, Any] –

Flattened configuration data

_flatten_nested_dict `staticmethod` ¶

Python

_flatten_nested_dict(d: dict[str, Any], parent_key: str = '') -> dict[str, Any]

Flatten nested dict with double underscore delimiter.

Converts nested dictionaries into flat dictionaries with keys joined by double underscores and uppercased, which matches pydantic-settings convention for case-insensitive field matching.

Parameters:

d (dict[str, Any]) –

Dictionary to flatten
parent_key (str, default: '' ) –

Parent key prefix, by default ""

Returns:

dict[str, Any] –

Flattened dictionary with uppercase keys

Examples:

Python Console Session

>>> _flatten_nested_dict({"a": {"b": 1}})
{'A__B': 1}
>>> _flatten_nested_dict({"value_from_toml": "test"})
{'VALUE_FROM_TOML': 'test'}

_parse_file ¶

Python

_parse_file(file_path: Path) -> dict[str, Any]

Parse TOML file.

Parameters:

file_path (Path) –

Path to TOML file

Returns:

dict[str, Any] –

Parsed TOML data

YamlConfigSource ¶

Python

YamlConfigSource(settings_cls: type, config_file: Path = Path('config.yaml'))

Bases: FileConfigSource

Load configuration from a YAML file.

Initialize YAML config source.

Parameters:

settings_cls (type) –

The settings class to load config for
config_file (Path, default: Path('config.yaml') ) –

Path to YAML config file, by default Path("config.yaml")

Methods:

get_field_value –

Get field value from configuration data.
__call__ –

Return all loaded config data.

Functions¶

_get_format_name ¶

Python

_get_format_name() -> str

Get friendly format name for error messages.

Returns:

str –

Format name (e.g., "TOML", "YAML", "JSON")

get_field_value ¶

Python

get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]

Get field value from configuration data.

Handles nested fields using double underscore delimiter.

Parameters:

field (FieldInfo) –

The field info
field_name (str) –

The field name (may contain __ for nested access)

Returns:

tuple[Any, str, bool] –

Tuple of (value, field_name, value_is_complex)

call ¶

Python

__call__() -> dict[str, Any]

Return all loaded config data.

Returns:

dict[str, Any] –

Flattened configuration data

_flatten_nested_dict `staticmethod` ¶

Python

_flatten_nested_dict(d: dict[str, Any], parent_key: str = '') -> dict[str, Any]

Flatten nested dict with double underscore delimiter.

Converts nested dictionaries into flat dictionaries with keys joined by double underscores and uppercased, which matches pydantic-settings convention for case-insensitive field matching.

Parameters:

d (dict[str, Any]) –

Dictionary to flatten
parent_key (str, default: '' ) –

Parent key prefix, by default ""

Returns:

dict[str, Any] –

Flattened dictionary with uppercase keys

Examples:

Python Console Session

>>> _flatten_nested_dict({"a": {"b": 1}})
{'A__B': 1}
>>> _flatten_nested_dict({"value_from_toml": "test"})
{'VALUE_FROM_TOML': 'test'}

_parse_file ¶

Python

_parse_file(file_path: Path) -> dict[str, Any]

Parse YAML file.

Parameters:

file_path (Path) –

Path to YAML file

Returns:

dict[str, Any] –

Parsed YAML data

JsonConfigSource ¶

Python

JsonConfigSource(settings_cls: type, config_file: Path = Path('config.json'))

Bases: FileConfigSource

Load configuration from a JSON file.

Initialize JSON config source.

Parameters:

settings_cls (type) –

The settings class to load config for
config_file (Path, default: Path('config.json') ) –

Path to JSON config file, by default Path("config.json")

Methods:

get_field_value –

Get field value from configuration data.
__call__ –

Return all loaded config data.

Functions¶

_get_format_name ¶

Python

_get_format_name() -> str

Get friendly format name for error messages.

Returns:

str –

Format name (e.g., "TOML", "YAML", "JSON")

get_field_value ¶

Python

get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]

Get field value from configuration data.

Handles nested fields using double underscore delimiter.

Parameters:

field (FieldInfo) –

The field info
field_name (str) –

The field name (may contain __ for nested access)

Returns:

tuple[Any, str, bool] –

Tuple of (value, field_name, value_is_complex)

call ¶

Python

__call__() -> dict[str, Any]

Return all loaded config data.

Returns:

dict[str, Any] –

Flattened configuration data

_flatten_nested_dict `staticmethod` ¶

Python

_flatten_nested_dict(d: dict[str, Any], parent_key: str = '') -> dict[str, Any]

Flatten nested dict with double underscore delimiter.

Converts nested dictionaries into flat dictionaries with keys joined by double underscores and uppercased, which matches pydantic-settings convention for case-insensitive field matching.

Parameters:

d (dict[str, Any]) –

Dictionary to flatten
parent_key (str, default: '' ) –

Parent key prefix, by default ""

Returns:

dict[str, Any] –

Flattened dictionary with uppercase keys

Examples:

Python Console Session

>>> _flatten_nested_dict({"a": {"b": 1}})
{'A__B': 1}
>>> _flatten_nested_dict({"value_from_toml": "test"})
{'VALUE_FROM_TOML': 'test'}

_parse_file ¶

Python

_parse_file(file_path: Path) -> dict[str, Any]

Parse JSON file.

Parameters:

file_path (Path) –

Path to JSON file

Returns:

dict[str, Any] –

Parsed JSON data

loaders ¶

Classes¶

FileConfigSource ¶

Functions¶

_get_format_name ¶

_parse_file abstractmethod ¶

get_field_value ¶

__call__ ¶

_flatten_nested_dict staticmethod ¶

TomlConfigSource ¶

Functions¶

_get_format_name ¶

get_field_value ¶

__call__ ¶

_flatten_nested_dict staticmethod ¶

_parse_file ¶

YamlConfigSource ¶

Functions¶

_get_format_name ¶

get_field_value ¶

__call__ ¶

_flatten_nested_dict staticmethod ¶

_parse_file ¶

JsonConfigSource ¶

Functions¶

_get_format_name ¶

get_field_value ¶

__call__ ¶

_flatten_nested_dict staticmethod ¶

_parse_file ¶

_parse_file `abstractmethod` ¶

call ¶

_flatten_nested_dict `staticmethod` ¶

call ¶

_flatten_nested_dict `staticmethod` ¶

call ¶

_flatten_nested_dict `staticmethod` ¶

call ¶

_flatten_nested_dict `staticmethod` ¶