jeliebig / configcrunch

Configuration parser based on YAML-Files with support for variables, overlaying and hierarchies

Configcrunch

Configcrunch is a Python library written in Rust for reading YAML-based configuration files. It aims to be simple and fast while also providing some very powerful features.

Configcrunch is compatible with Python 3.6 and up.

Install it via pip: pip install configcrunch

Features:

• Read configuration files from YAML files.
• Define various types of configuration files, that can be validated via a schema.
• Types of configuration files are defined as separate Python classes.
• Documents can be configured to contain nested documents of any type.
• Documents can contain Minijinja templates that can reference any other field inside the same or parent document.
• The classes that represent your document types can contain methods that can be used inside the configuration files.
• Documents can reference documents from other files. Configcrunch will merge them together. You decide where referenced documents are looked up.
• Configuration objects can also be created without YAML files, by using ordinary Python dicts.
• All features are optional.

Used by:

• Riptide
• (Your project here! Open an issue.)

By default Configcrunch uses schema to validate schemas. But you can also use your own validation logic!

Example

This is an example that uses most of the features described above, using two document types.

# doc1.yml - Type: one
one:
    name: Document
    number: 1
    sub:
        # Sub-document of type "two"
        $ref: /doc2
        two_field: "{{ parent().method() }}"

# <lookup path>/doc2.yml - Type: two
two:
    name: Doc 2
    number: 2
    two_field: This is overridden

# classes.py
from schema import Schema, Optional

from configcrunch import YamlConfigDocument, DocReference, variable_helper


class One(YamlConfigDocument):
    @classmethod
    def header(cls) -> str:
        return "one"

    @classmethod
    def schema(cls) -> Schema:
        return Schema(
            {
                Optional('$ref'): str,  # reference to other One documents
                'name': str,
                'number': int,
                Optional('sub'): DocReference(Two)
            }
        )

    @classmethod
    def subdocuments(cls):
        return [
            ("sub", Two)
        ]

    @variable_helper
    def method(self):
        return "I will return something"


class Two(YamlConfigDocument):
    @classmethod
    def header(cls) -> str:
        return "two"

    @classmethod
    def schema(cls) -> Schema:
        return Schema(
            {
                Optional('$ref'): str,  # reference to other Two documents
                'name': str,
                'number': int,
                'two_field': str
            }
        )

    @classmethod
    def subdocuments(cls):
        return []

The document "one.yml" can then be read via Python:

>>> import yaml
>>> from classes import One
>>> doc = One.from_yaml('./doc1.yml')
>>> doc.resolve_and_merge_references(['<lookup path>'])
>>> doc.process_vars()
>>> print(yaml.dump(doc.to_dict(), default_flow_style=False))
one:
  name: Document
  number: 1
  sub:
    name: Doc 2
    number: 2
    two_field: I will return something

Tests

Inside the configcrunch.tests package are tests.

To run the tests, see run_tests.sh.

Documentation

The complete documentation can be found at Read the Docs (or in the docs directory).