configuraptor 1.15.0

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("example_from_readme.toml")  # or .json, .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 or empty. 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.

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

License

configuraptor is distributed under the terms of the MIT license.

Changelog

See CHANGELOG.md