Pydantic Settings
Bases: ValueError
Base exception for settings-related errors.
Bases: TomlConfigSettingsSource
A source class that loads variables from a pyproject.toml file.
Bases: InitSettingsSource, ConfigFileSourceMixin
A source class that loads variables from a JSON file
Annotation to prevent decoding of a field value.
Bases: PydanticBaseEnvSettingsSource
Source class for loading settings values from secret files.
@classmethod
def find_case_path(
cls,
dir_path: Path,
file_name: str,
case_sensitive: bool,
) -> Path | None
Find a file within path’s directory matching filename, optionally ignoring case.
Path | None — Whether file path or None if file does not exist in directory.
Directory path.
file_name : str
File name.
case_sensitive : bool
Whether to search for file name case sensitively.
def get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]
Gets the value for field from secret file and a flag to determine whether value is complex.
tuple[Any, str, bool] — A tuple that contains the value (None if the file does not exist), key, and
a flag to determine whether value is complex.
The field.
field_name : str
The field name.
Annotation to force decoding of a field value.
Bases: EnvSettingsSource
Source class for loading settings values from env files.
Bases: InitSettingsSource, ConfigFileSourceMixin
A source class that loads variables from a yaml file
Bases: PydanticBaseEnvSettingsSource
Source class for loading settings values from environment variables.
def get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]
Gets the value for field from environment variables and a flag to determine whether value is complex.
tuple[Any, str, bool] — A tuple that contains the value (None if not found), key, and
a flag to determine whether value is complex.
The field.
field_name : str
The field name.
def prepare_field_value(
field_name: str,
field: FieldInfo,
value: Any,
value_is_complex: bool,
) -> Any
Prepare value for the field.
- Extract value for nested field.
- Deserialize value to python object for complex field.
Any — A tuple contains prepared value for the field.
The field.
field_name : str
The field name.
ValuesError— When There is an error in deserializing value for complex field.
def next_field(
field: FieldInfo | Any | None,
key: str,
case_sensitive: bool | None = None,
) -> FieldInfo | None
Find the field in a sub model by key(env name)
By having the following models:
class SubSubModel(BaseSettings):
dvals: Dict
class SubModel(BaseSettings):
vals: list[str]
sub_sub_model: SubSubModel
class Cfg(BaseSettings):
sub_model: SubModel
FieldInfo | None — Field if it finds the next field otherwise None.
The field.
key : str
The key (env name).
Whether to search for key case sensitively.
def explode_env_vars(
field_name: str,
field: FieldInfo,
env_vars: Mapping[str, str | None],
) -> dict[str, Any]
Process env_vars and extract the values of keys containing env_nested_delimiter into nested dictionaries.
This is applied to a single field, hence filtering by env_var prefix.
dict[str, Any] — A dictionary contains extracted values from nested env values.
field_name : str
The field name.
The field.
Environment variables.
Bases: InitSettingsSource, ConfigFileSourceMixin
A source class that loads variables from a TOML file
Bases: ConfigDict
Specifies the section in a YAML file from which to load the settings. Supports dot-notation for nested paths (e.g., ‘config.app.settings’). If provided, the settings will be loaded from the specified section. This is useful when the YAML file contains multiple configuration sections and you only want to load a specific subset into your settings model.
Number of levels up from the current working directory to attempt to find a pyproject.toml file.
This is only used when a pyproject.toml file is not found in the current working directory.
Type: int
Header of the TOML table within a pyproject.toml file to use when filling variables.
This is supplied as a tuple[str, ...] instead of a str to accommodate for headers
containing a ..
For example, toml_table_header = ("tool", "my.tool", "foo") can be used to fill variable
values from a table with header [tool."my.tool".foo].
To use the root table, exclude this config setting or provide an empty tuple.
Bases: ABC
Abstract base class for settings sources, every settings source classes should inherit from it.
The current state of the settings, populated by the previous settings sources.
The state of all previous settings sources.
Type: dict[str, dict[str, Any]]
@abstractmethod
def get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]
Gets the value, the key for model creation, and a flag to determine whether value is complex.
This is an abstract method that should be overridden in every settings source classes.
tuple[Any, str, bool] — A tuple that contains the value, key and a flag to determine whether value is complex.
The field.
field_name : str
The field name.
def field_is_complex(field: FieldInfo) -> bool
Checks whether a field is complex, in which case it will attempt to be parsed as JSON.
bool — Whether the field is complex.
The field.
def prepare_field_value(
field_name: str,
field: FieldInfo,
value: Any,
value_is_complex: bool,
) -> Any
Prepares the value of a field.
Any — The prepared value.
field_name : str
The field name.
The field.
value : Any
The value of the field that has to be prepared.
value_is_complex : bool
A flag to determine whether value is complex.
def decode_complex_value(field_name: str, field: FieldInfo, value: Any) -> Any
Decode the value for a complex field
Any — The decoded value for further preparation
field_name : str
The field name.
The field.
value : Any
The value of the field that has to be prepared.
Bases: BaseModel
Base class for settings, allowing values to be overridden by environment variables.
This is useful in production for secrets you do not wish to save in code, it plays nicely with docker(-compose), Heroku and any 12 factor app design.
All the below attributes can be set via model_config.
Whether environment and CLI variable names should be read with case-sensitivity.
Defaults to None.
Whether to allow partial updates on nested model default object fields.
Defaults to False.
Prefix for all environment variables. Defaults to None.
_env_prefix_target : EnvPrefixTarget | None Default: None
Targets to which _env_prefix is applied. Default: variable.
_env_file : DotenvType | None Default: ENV_FILE_SENTINEL
The env file(s) to load settings values from. Defaults to Path(''), which
means that the value from model_config['env_file'] should be used. You can also pass
None to indicate that environment variables should not be loaded from an env file.
The env file encoding, e.g. 'latin-1'. Defaults to None.
Ignore environment variables where the value is an empty string. Default to False.
The nested env values delimiter. Defaults to None.
The nested env values maximum nesting. Defaults to None, which means no limit.
The env string value that should be parsed (e.g. “null”, “void”, “None”, etc.)
into None type(None). Defaults to None type(None), which means no parsing should occur.
Parse enum field names to values. Defaults to None., which means no parsing should occur.
The CLI program name to display in help text. Defaults to None if _cli_parse_args is None.
Otherwise, defaults to sys.argv[0].
The list of CLI arguments to parse. Defaults to None.
If set to True, defaults to sys.argv[1:].
Override the default CLI settings source with a user defined instance. Defaults to None.
The CLI string value that should be parsed (e.g. “null”, “void”, “None”, etc.) into
None type(None). Defaults to _env_parse_none_str value if set. Otherwise, defaults to “null” if
_cli_avoid_json is False, and “None” if _cli_avoid_json is True.
Hide None values in CLI help text. Defaults to False.
Avoid complex JSON objects in CLI help text. Defaults to False.
Enforce required fields at the CLI. Defaults to False.
Use class docstrings in CLI group help text instead of field descriptions.
Defaults to False.
Determines whether or not the internal parser exits with error info when an error occurs.
Defaults to True.
The root parser command line arguments prefix. Defaults to "".
The flag prefix character to use for CLI optional arguments. Defaults to ’-’.
Controls how bool fields are exposed as CLI flags.
- False (default): no implicit flags are generated; booleans must be set explicitly (e.g. —flag=true).
- True / ‘dual’: optional boolean fields generate both positive and negative forms (—flag and —no-flag).
- ‘toggle’: required boolean fields remain in ‘dual’ mode, while optional boolean fields generate a single flag aligned with the default value (if default=False, expose —flag; if default=True, expose —no-flag).
Whether to ignore unknown CLI args and parse only known ones. Defaults to False.
CLI args use kebab case. Defaults to False.
Mapping of target field name to alias names. Defaults to None.
_secrets_dir : PathType | None Default: None
The secret files directory or a sequence of directories. Defaults to None.
Pre-initialized sources and init kwargs to use for building instantiation values.
Defaults to None.
@classmethod
def settings_customise_sources(
cls,
settings_cls: type[BaseSettings],
init_settings: PydanticBaseSettingsSource,
env_settings: PydanticBaseSettingsSource,
dotenv_settings: PydanticBaseSettingsSource,
file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]
Define the sources and their order for loading the settings values.
tuple[PydanticBaseSettingsSource, …] — A tuple containing the sources and their order for loading the settings values.
settings_cls : type[BaseSettings]
The Settings class.
The InitSettingsSource instance.
The EnvSettingsSource instance.
The DotEnvSettingsSource instance.
The SecretsSettingsSource instance.
Bases: EnvSettingsSource
def get_field_value(field: FieldInfo, field_name: str) -> tuple[Any, str, bool]
Override get_field_value to get the secret value from GCP Secret Manager. Look for a SecretVersion metadata field to specify a particular SecretVersion.
Any — A tuple of (value, key, value_is_complex), where key is the identifier used
str — to populate the model (either the field name or an alias, depending on
bool — configuration).
The field to get the value for
field_name : str
The declared name of the field
Bases: EnvSettingsSource, Generic[T]
Source class for loading settings values from CLI.
The CLI program name to display in help text. Defaults to None if cli_parse_args is None.
Otherwise, defaults to sys.argv[0].
The list of CLI arguments to parse. Defaults to None.
If set to True, defaults to sys.argv[1:].
The CLI string value that should be parsed (e.g. “null”, “void”, “None”, etc.) into None
type(None). Defaults to “null” if cli_avoid_json is False, and “None” if cli_avoid_json is True.
Hide None values in CLI help text. Defaults to False.
Avoid complex JSON objects in CLI help text. Defaults to False.
Enforce required fields at the CLI. Defaults to False.
Use class docstrings in CLI group help text instead of field descriptions.
Defaults to False.
Determines whether or not the internal parser exits with error info when an error occurs.
Defaults to True.
Prefix for command line arguments added under the root parser. Defaults to "".
The flag prefix character to use for CLI optional arguments. Defaults to ’-’.
Controls how bool fields are exposed as CLI flags.
- False (default): no implicit flags are generated; booleans must be set explicitly (e.g. —flag=true).
- True / ‘dual’: optional boolean fields generate both positive and negative forms (—flag and —no-flag).
- ‘toggle’: required boolean fields remain in ‘dual’ mode, while optional boolean fields generate a single flag aligned with the default value (if default=False, expose —flag; if default=True, expose —no-flag).
Whether to ignore unknown CLI args and parse only known ones. Defaults to False.
CLI args use kebab case. Defaults to False.
Mapping of target field name to alias names. Defaults to None.
Whether CLI “—arg” names should be read with case-sensitivity. Defaults to True.
Note: Case-insensitive matching is only supported on the internal root parser and does not apply to CLI
subcommands.
root_parser : Any Default: None
The root parser object.
The root parser parse args method. Defaults to argparse.ArgumentParser.parse_args.
The root parser add argument method. Defaults to argparse.ArgumentParser.add_argument.
The root parser add argument group method.
Defaults to argparse.ArgumentParser.add_argument_group.
The root parser add new parser (sub-command) method.
Defaults to argparse._SubParsersAction.add_parser.
The root parser add subparsers (sub-commands) method.
Defaults to argparse.ArgumentParser.add_subparsers.
The root parser format help method. Defaults to argparse.ArgumentParser.format_help.
formatter_class : Any Default: RawDescriptionHelpFormatter
A class for customizing the root parser help text. Defaults to argparse.RawDescriptionHelpFormatter.
The connected root parser instance.
Type: T
Bases: PydanticBaseSettingsSource
Source class for loading values provided during settings class initialization.
A utility class for running Pydantic BaseSettings, BaseModel, or pydantic.dataclasses.dataclass as
CLI applications.
@staticmethod
def run(
model_cls: type[T],
cli_args: list[str] | Namespace | SimpleNamespace | dict[str, Any] | None = None,
cli_settings_source: CliSettingsSource[Any] | None = None,
cli_exit_on_error: bool | None = None,
cli_cmd_method_name: str = 'cli_cmd',
model_init_data: Any = {},
) -> T
Runs a Pydantic BaseSettings, BaseModel, or pydantic.dataclasses.dataclass as a CLI application.
Running a model as a CLI application requires the cli_cmd method to be defined in the model class.
T — The ran instance of model.
model_cls : type[T]
The model class to run as a CLI application.
The list of CLI arguments to parse. If cli_settings_source is specified, this may
also be a namespace or dictionary of pre-parsed CLI arguments. Defaults to sys.argv[1:].
Override the default CLI settings source with a user defined instance.
Defaults to None.
Determines whether this function exits on error. If model is subclass of
BaseSettings, defaults to BaseSettings cli_exit_on_error value. Otherwise, defaults to
True.
cli_cmd_method_name : str Default: 'cli_cmd'
The CLI command method name to run. Defaults to “cli_cmd”.
model_init_data : Any Default: \{\}
The model init data.
SettingsError— If model_cls is not subclass ofBaseModelorpydantic.dataclasses.dataclass.SettingsError— If model_cls does not have acli_cmdentrypoint defined.
@staticmethod
def run_subcommand(
model: PydanticModel,
cli_exit_on_error: bool | None = None,
cli_cmd_method_name: str = 'cli_cmd',
) -> PydanticModel
Runs the model subcommand. Running a model subcommand requires the cli_cmd method to be defined in
the nested model subcommand class.
PydanticModel — The ran subcommand model.
The model to run the subcommand from.
Determines whether this function exits with error if no subcommand is found.
Defaults to model_config cli_exit_on_error value if set. Otherwise, defaults to True.
cli_cmd_method_name : str Default: 'cli_cmd'
The CLI command method name to run. Defaults to “cli_cmd”.
SystemExit— When no subcommand is found and cli_exit_on_error=True(the default).SettingsError— When no subcommand is found and cli_exit_on_error=False.
@staticmethod
def serialize(
model: PydanticModel,
list_style: Literal['json', 'argparse', 'lazy'] = 'json',
dict_style: Literal['json', 'env'] = 'json',
positionals_first: bool = False,
) -> list[str]
Serializes the CLI arguments for a Pydantic data model.
list[str] — The serialized CLI arguments for the data model.
The data model to serialize.
list_style : Literal[‘json’, ‘argparse’, ‘lazy’] Default: 'json'
Controls how list-valued fields are serialized on the command line.
- ‘json’ (default):
Lists are encoded as a single JSON array.
Example:
--tags '["a","b","c"]' - ‘argparse’:
Each list element becomes its own repeated flag, following
typical
argparseconventions. Example:--tags a --tags b --tags c - ‘lazy’:
Lists are emitted as a single comma-separated string without JSON
quoting or escaping.
Example:
--tags a,b,c
dict_style : Literal[‘json’, ‘env’] Default: 'json'
Controls how dictionary-valued fields are serialized.
- ‘json’ (default):
The entire dictionary is emitted as a single JSON object.
Example:
--config '\{"host": "localhost", "port": 5432\}' - ‘env’:
The dictionary is flattened into multiple CLI flags using
environment-variable-style assignement.
Example:
--config host=localhost --config port=5432
positionals_first : bool Default: False
Controls whether positional arguments should be serialized
first compared to optional arguments. Defaults to False.
@staticmethod
def format_help(
model: PydanticModel | type[T],
cli_settings_source: CliSettingsSource[Any] | None = None,
strip_ansi_color: bool = False,
) -> str
Return a string containing a help message for a Pydantic model.
str — The help message string for the model.
model : PydanticModel | type[T]
The model or model class.
Override the default CLI settings source with a user defined instance.
Defaults to None.
strip_ansi_color : bool Default: False
Strips ANSI color codes from the help message when set to True.
@staticmethod
def print_help(
model: PydanticModel | type[T],
cli_settings_source: CliSettingsSource[Any] | None = None,
file: TextIO | None = None,
strip_ansi_color: bool = False,
) -> None
Print a help message for a Pydantic model.
model : PydanticModel | type[T]
The model or model class.
Override the default CLI settings source with a user defined instance.
Defaults to None.
A text stream to which the help message is written. If None, the output is sent to sys.stdout.
strip_ansi_color : bool Default: False
Strips ANSI color codes from the help message when set to True.
def get_subcommand(
model: PydanticModel,
is_required: bool = True,
cli_exit_on_error: bool | None = None,
_suppress_errors: list[SettingsError | SystemExit] | None = None,
) -> PydanticModel | None
Get the subcommand from a model.
PydanticModel | None — The subcommand model if found, otherwise None.
The model to get the subcommand from.
is_required : bool Default: True
Determines whether a model must have subcommand set and raises error if not
found. Defaults to True.
Determines whether this function exits with error if no subcommand is found.
Defaults to model_config cli_exit_on_error value if set. Otherwise, defaults to True.
SystemExit— When no subcommand is found and is_required=Trueand cli_exit_on_error=True(the default).SettingsError— When no subcommand is found and is_required=Trueand cli_exit_on_error=False.