Basic Settings Loading

Typed Settings exposes two functions for loading settings: load() and load_settings(). This page describes the difference between these two.

Simple API: load()

The load() function provides a simplified API for the common case. It uses the following configuration:

• First load from TOML files (see FileLoader).

• Then load from environment variables (see EnvLoader).

• Derives settings for these loaders from your appname (but some settings can be overridden, see below).

• Don’t use any post processors.

• Use the default converter returned by default_converter().

What you can configure:

• Change the config file section (default: {appname}).

• Change the name for the environment variable that lists paths for settings files or disable this feature (default: {APPNAME}_SETTINGS).

• Change the prefix for environment varialbes for options (default: {APPNAME}_).

One use case for it is loading settings from a pyproject.toml:

example.py

import typed_settings as ts

@ts.settings
class Settings:
    option_one: str
    option_two: int

settings = ts.load(
    cls=Settings,
    appname="example",
    config_files=[ts.find("pyproject.toml")],
    config_file_section="tool.example",
)
print(settings)

pyproject.toml

[project]
# ...

[tool.example]
option_one = "value"

$ EXAMPLE_OPTION_TWO=2 python example.py
Settings(option_one='value', option_two=2)

Full API: load_settings()

The function load_settings() lets you configure everything in detail.

Here is the same example from above but without shortcuts for loader configuration:

example.py

import attrs
import typed_settings as ts
import typed_settings.converters
import typed_settings.loaders

@ts.settings
class Settings:
    option_one: str
    option_two: int

settings = ts.load_settings(
    cls=Settings,
    loaders=[
      typed_settings.loaders.FileLoader(
          files=[ts.find("pyproject.toml")],
          formats={"*.toml": typed_settings.loaders.TomlFormat("tool.example")},
      ),
      typed_settings.loaders.EnvLoader(prefix="EXAMPLE_"),
    ],
    processors=[],
    converter=typed_settings.converters.default_converter(),
)
print(settings)

pyproject.toml

[project]
# ...

[tool.example]
option_one = "value"

$ EXAMPLE_OPTION_TWO=2 python example.py
Settings(option_one='value', option_two=2)

Note

load(cls, **kwargs) is basically the same as load_settings(cls, default_loaders(**kwargs), default_converter()).

---

The following pages will demonstrate it’s usage for various use cases.