configuraptor 1.23.5

Load toml/yaml/json config files into classes for a typed config (type hinting etc.)

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