Configuraptor

Load config into typed Python classes.

Read TOML, JSON, YAML, .env and .ini files into ordinary Python classes with type annotations. Your editor and mypy know the types of your settings. If a value has the wrong type, Configuraptor raises an error when you load it and tells you which key to fix.

pip install configuraptor
Source on GitHub

config.toml

[config.reference]number = 42numbers = [41, 43]string = "42"

Try it. Pick a block, then pick a hole. Or drag it.

number: int
numbers: list[int]
string: str

The raptor says

"It goes in the square hole!" Try putting "forty-two" into number: int and see what happens.

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.toml
[config]
name = "Hello World!"

[config.reference]
number = 42
numbers = [41, 43]
string = "42"
app.py
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:

pyproject.toml
[tool.mytool]
line_length = 100
exclude = ["build"]
mytool.py
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:

config.toml
[my_config]
public_key = "some key"
private_key = "<overwrite me>"
secrets.env
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.

ExtensionParsed values
.tomlStrings, numbers, booleans, lists, tables and dates.
.json, .json5The same as TOML, minus dates.
.yamlRoughly the same as TOML. A JSON file is valid YAML too.
.envOnly strings: PORT=8080 arrives as "8080" unless you pass convert_types=True.
.iniOnly strings. Use convert_types=True to convert them to the annotated types.
bytesStruct-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:

.env
HOST=localhost
PORT=8080
DEBUG=yes
app.py
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 (MyConfig looks for my_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 PORT maps to port. Enabled automatically when you load a list of sources.
convert_types : bool
Convert strings to the annotated type, so "8080" becomes 8080 for an int. For a bool, "True", "Yes" and "1" become True, "False", "No" and "0" become False, 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.
  • TypedMapping and TypedMutableMapping make a config that also behaves like a dict.
  • BinaryConfig with fields like BinaryField(int) and BinaryField(str, length=5) reads struct-packed bytes, and asbytes packs them again.
  • @beautify gives any class a readable repr. TypedConfig has it already; opt out with class 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.toml
[server]
host = "localhost"
port = "eighty"
python
>>> 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:

ErrorExample cause
ConfigErrorCouldNotConvertDEBUG=maybe in a .env loaded with convert_types=True into debug: bool.Could not convert `maybe` from `<class 'str'>` to `<class 'bool'>`
ConfigErrorExtraKeyserver.update(color="red") on a class that has no color.
ConfigErrorImmutableCalling update on a TypedMapping, which is read-only.
IsPostponedErrorReading session.token before it was set.
FailedToLoadThe source can't be read, like a URL that is down or returns broken JSON.