Load a nested config
Define a class for each section of your config, then pass the outer class to load_into. In this example, [config.reference] becomes a SomeRegularClass instance, available as my_config.reference.
[config]
name = "Hello World!"
[config.reference]
number = 42
numbers = [41, 43]
string = "42"
from configuraptor import load_into
class SomeRegularClass:
number: int
numbers: list[int]
string: str
class Config:
name: str
reference: SomeRegularClass
my_config = load_into(Config, "config.toml")
print(my_config.name) # Hello World!
print(my_config.reference.numbers) # [41, 43]
Both classes work without inheriting from a Configuraptor base class. Their annotations tell your editor and mypy that my_config.reference.numbers is a list[int].
Configuraptor selects the [config] table automatically. It's the only top-level table here, and its name also matches the class Config. Use key= to select a different section.
Load with TypedConfig
Subclass TypedConfig and the class gets a .load() method. It accepts the same sources as load_into, including a URL:
from configuraptor import TypedConfig
class OtherConfig(TypedConfig):
name: str
reference: SomeRegularClass
my_config = OtherConfig.load("https://api.my-server.dev/v1/config.json?secret=token")
How it compares to Pydantic
Configuraptor loads configuration into ordinary annotated classes and dataclasses, including classes you already have. Inherit from TypedConfig if you want .load() and .update() methods. Pydantic is a general-purpose validation library whose BaseModel API includes serialization and JSON Schema generation.
The defaults for type conversion differ too. Configuraptor rejects "8080" for an int field unless you enable convert_types=True. Pydantic converts that string to an integer by default; you can enable its strict mode to reject it.
Loading from files, dicts and URLs
Pass a file path, a dict or a URL to load_into or TypedConfig.load:
load_into(Config, "config.toml") # a path as a string
load_into(Config, Path("config.yaml")) # or as a pathlib.Path
load_into(Config, data) # a dict you already have
load_into(Config, "https://example.com/config.json?token=...")
URLs can carry credentials as basic auth (https://user:pass@host/...) or in the query string, like above.
Your tool's section of pyproject.toml
If you omit the source, Configuraptor reads pyproject.toml. Use key to select your tool's settings:
[tool.mytool]
line_length = 100
exclude = ["build"]
class MyTool:
line_length: int
exclude: list[str]
settings = load_into(MyTool, key="tool.mytool")
Combine config sources
Pass a list to merge sources in order. Values from later sources overwrite earlier ones. This lets you keep defaults in one file and read a private key from a separate .env file:
[my_config]
public_key = "some key"
private_key = "<overwrite me>"
PRIVATE_KEY="some private key"
class MyConfig:
public_key: str
private_key: str
extra: int
data = load_into(MyConfig, ["config.toml", "secrets.env", {"extra": 3}])
data.public_key # "some key", from config.toml
data.private_key # "some private key", secrets.env came later
File formats
Configuraptor selects a parser by file extension. Some formats store numbers and booleans directly; others need type conversion when you load them.
| Extension | Parsed values |
|---|---|
.toml | Strings, numbers, booleans, lists, tables and dates. |
.json, .json5 | The same as TOML, minus dates. |
.yaml | Roughly the same as TOML. A JSON file is valid YAML too. |
.env | Only strings: PORT=8080 arrives as "8080" unless you pass convert_types=True. |
.ini | Only strings. Use convert_types=True to convert them to the annotated types. |
| bytes | Struct-packed binary data, read with BinaryConfig and BinaryField. |
Reading a .env file
For a .env file with uppercase keys, use lower_keys=True to match lowercase attributes. Add convert_types=True to convert text values to the annotated types:
HOST=localhost
PORT=8080
DEBUG=yes
class Server:
host: str
port: int
debug: bool
server = load_into(Server, ".env",
lower_keys=True, convert_types=True)
server.port # 8080, an int
server.debug # True
Register a parser for another format with the @configuraptor.loader decorator. Add a type conversion with @configuraptor.converter.
Options for load and load_into
load_into(cls, data, **kwargs) and TypedConfig.load(data, **kwargs) take the same keyword arguments.
- key : str
- The dotted path to the section to load, like
key="tool.mytool". Without it, Configuraptor uses the only top-level key if there is just one, and otherwise the class name in snake_case (MyConfiglooks formy_config).key=""loads from the top level. - init : dict
- Keyword arguments to pass to the class's
__init__method. - strict : bool = True
- Check every value against its annotation. With
strict=False, values with the wrong type are accepted unchanged:port = "123"stays the string"123". - lower_keys : bool
- Lowercase every key, so
PORTmaps toport. Enabled automatically when you load a list of sources. - convert_types : bool
- Convert strings to the annotated type, so
"8080"becomes8080for anint. For abool,"True","Yes"and"1"becomeTrue,"False","No"and"0"becomeFalse, and anything else raises an error.
Additional features
Change a loaded config
A TypedConfig instance has an update method that checks new values the same way loading does:
class Server(TypedConfig):
host: str
port: int
server = Server.load("server.toml")
server.update(port=9090) # fine
server.update(port="9090") # ConfigErrorInvalidType
server.update(color="red") # ConfigErrorExtraKey
server.update(color="red", _strict=False) # allowed
server |= {"port": 9090} does the same. Two TypedConfig instances compare equal with == when their values match, and printing one shows its fields.
Load environment variables
Server.from_env() builds a Server from os.environ: PORT=9090 becomes port = 9090. Pass load_dotenv=True to read a .env file first.
Use dataclasses
Dataclasses load like any other class. Fields with a default can be left out of the file:
@dataclass
class Two:
name: str
include: list[str] = field(default_factory=list)
@dataclass
class Simple:
name: str
two: Two
simple = load_into(Simple, {"simple": {"name": "Steve", "two": {"name": "Alex"}}})
simple.two.include # []
__post_init__ runs once, after loading.
Accept two names for one setting
When a key was renamed, or two tools spell it differently, alias lets the file use either name:
class Server:
host: str
hostname: str = alias("host")
server = load_into(Server, {"hostname": "example.org"}, key="")
server.host # "example.org"
Set a value after loading
Some values only exist after the program starts, like a token the user types in. Mark the field with postpone() to set it later. Reading it before it's set raises IsPostponedError:
class Session(TypedConfig):
url: str
token: str = postpone()
session = Session.load("session.toml")
session.update(token=input("Token: "))
Share a config across modules
Add the Singleton mixin and every MyConfig() call returns the loaded data, so modules don't have to pass the config around. Updating it in one place updates it everywhere.
Defaults for whole sections
Subclass Defaultable and a nested section that's missing from the file is built with Cls.default() instead of raising ConfigErrorMissingKey. Annotate it as SomeDefaultable | None and a missing section still gets the default, while an explicit empty value gives None.
Export a loaded config
asdict, asjson, astoml and asyaml turn a loaded config back into data, nested classes included. astoml(config) gives you a file you can load again.
Other utilities
load_into_instance(obj, data)fills only the attributes an existing object doesn't have yet.TypedMappingandTypedMutableMappingmake a config that also behaves like a dict.BinaryConfigwith fields likeBinaryField(int)andBinaryField(str, length=5)reads struct-packed bytes, andasbytespacks them again.@beautifygives any class a readablerepr.TypedConfighas it already; opt out withclass X(TypedConfig, beautify=False).
Configuration errors
If a value has the wrong type, loading stops with an error that names the key and its expected type. For example, this file has text where port requires an integer:
[server]
host = "localhost"
port = "eighty"
>>> load_into(Server, "server.toml")
ConfigErrorInvalidType: Config key 'port' had a value (`eighty`) with a type (`<class 'str'>`) that was not expected: `<class 'int'>` is the required type.
Leave port out entirely and you get this instead:
ConfigErrorMissingKey: Config key 'port' (type `int`) of class `Server` was not found in the config, but is required as a default value is not specified.
Import errors from configuraptor.errors. They all subclass ConfigError, so you can catch them together with except ConfigError, or handle a specific error below:
| Error | Example cause |
|---|---|
ConfigErrorCouldNotConvert | DEBUG=maybe in a .env loaded with convert_types=True into debug: bool.Could not convert `maybe` from `<class 'str'>` to `<class 'bool'>` |
ConfigErrorExtraKey | server.update(color="red") on a class that has no color. |
ConfigErrorImmutable | Calling update on a TypedMapping, which is read-only. |
IsPostponedError | Reading session.token before it was set. |
FailedToLoad | The source can't be read, like a URL that is down or returns broken JSON. |
The raptor says