Configuraptor

Load config files into Python classes for a typed config (for type hinting etc.). Supported file types are toml/yaml/json, and .env/.ini to a lesser degree (see Supported Config File Types).

Table of Contents

Installation
Usage
Supported Config File Types
License
Changelog

Installation

pip install configuraptor

Usage

Configuraptor can be used to load your config files into structured Python classes.

# examples/example_from_readme.toml
[config]
name = "Hello World!"

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

Could be loaded into Python classes using the following code:

# examples/example_from_readme.py
from configuraptor import load_into, TypedConfig


######################
# with basic classes #
######################

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


class Config:
    name: str
    reference: SomeRegularClass


if __name__ == '__main__':
    my_config = load_into(Config, "example_from_readme.toml")  # or .json, .yaml, ...

    print(my_config.name)
    # Hello World!
    print(my_config.reference.numbers)
    # [41, 43]


########################
# alternative notation #
########################

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


class OtherConfig(TypedConfig):
    name: str
    reference: SomeRegularClass


if __name__ == '__main__':
    my_config = OtherConfig.load("https://api.my-server.dev/v1/config.json?secret=token")  # or .toml, .yaml, ...

    print(my_config.name)
    # Hello World!
    print(my_config.reference.numbers)
    # [41, 43]

    # TypedConfig has an extra benefit of allowing .update:
    my_config.update(numbers=[68, 70])

The second argument of .load_into and the first argument of .load (which is "example_from_readme.toml" in the examples above), can be either a string or a Path to a file, a raw dictionary with data, a URL or empty. You can also use a list of these options to combine data sources. If it is left empty, the pyproject.toml will be used. You can supply a key='tool.mytool.myconf' to specify which section of the file should be read. For HTTP authentication, currently you can use http basic auth (https://user:pass@host or query parameters (like ?token=...)). Other authentication methods are not currently supported.

More examples can be found in examples.

Supported Config File Types

.toml: supports the most types (strings, numbers, booleans, datetime, lists/arrays, dicts/tables);
.json: supports roughly the same types as toml (except datetime);
.yaml: supports roughly the same types as toml, backwards compatible with JSON;
.env: only supports strings. You can use convert_types=True to try to convert to your annotated types;
.ini: only supports strings. You can use convert_types=True to try to convert to your annotated types;

For other file types, a custom Loader can be written. See examples/readme.md#Custom File Types

Binary Config

You can also parse a struct-packed bytestring into a config class. For this, you have to use BinaryConfig with BinaryFields. Annotations are not supported in this case, because the order of properties is important for this type of config.

from configuraptor import BinaryConfig, BinaryField


class MyBinaryConfig(BinaryConfig):
    # annotations not supported! (because mixing annotation and __dict__ lookup messes with the order,
    # which is important for struct.(un)pack
    number = BinaryField(int)
    string = BinaryField(str, length=5)
    decimal = BinaryField(float)
    double = BinaryField(float, format="d")
    other_string = BinaryField(str, format="10s")
    boolean = BinaryField(bool)


MyBinaryConfig.load(
    b'*\x00\x00\x00Hello\x00\x00\x00fff@\xab\xaa\xaa\xaa\xaa\xaa\n@Hi\x00\x00\x00\x00\x00\x00\x00\x00\x01')

License

configuraptor is distributed under the terms of the MIT license.

Changelog

See CHANGELOG.md

Metadata

Release files for configuraptor 2.5.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for configuraptor 2.5.4
File	Size	Uploaded
configuraptor-2.5.4.tar.gz	666.5 kB	May 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for configuraptor 2.5.4
File	Interpreter	ABI	Platform	Reset
configuraptor-2.5.4-py3-none-any.whl 34.7 kB May 14, 2026	Python 3	none	any	Details

Total release size: 701.2 kB

Release files / configuraptor-2.5.4.tar.gz

Download URL	configuraptor-2.5.4.tar.gz
Size	666.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`62a5a7ae22bf70c3d256776a1f1edd7ba086d1b39aa41c04ee9932a18769e3d7`
BLAKE2b-256 checksum How to use checksums	`1981cc5a63229c8b61193aab03153de5f91289958c31cd3b4a50873c6efb827b`
Upload date	May 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.4 {"installer":{"name":"uv","version":"0.11.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / configuraptor-2.5.4-py3-none-any.whl

Download URL	configuraptor-2.5.4-py3-none-any.whl
Size	34.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ebe5d3a280f76c8776ad3fde839486fcd9b6d293d4198c6fe60d5a18176c540d`
BLAKE2b-256 checksum How to use checksums	`db442957fa13db89a93587f7b6daf47be7de4737cafa24753aaabf621eca0274`
Upload date	May 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.4 {"installer":{"name":"uv","version":"0.11.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`