Skip to main content

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

Project description

Build Status Documentation Status

Configcrunch is a Python library for reading YAML-based configuration files that aims to be simple while also providing some very powerful features.

Configcrunch is compatible with Python 3.6 and up.

Install it via pip: pip install configcrunch


  • 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 sub-documents of any type.
  • Documents can contain Jinja2 based variables 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 default 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!


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

# doc1.yml - Type: one
    name: Document
    number: 1
        # Sub-document of type "two"
        $ref: /doc2
        two_field: "{{ parent().method() }}"
# <lookup path>/doc2.yml - Type: two
    name: Doc 2
    number: 2
    two_field: This is overridden
from schema import Schema, Optional

from configcrunch import YamlConfigDocument, DocReference, load_subdocument, variable_helper

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

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

    def resolve_and_merge_references(self, lookup_paths):
        if "sub" in self:
            self["sub"] = load_subdocument(self["sub"], self, Two, lookup_paths)
        return self

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

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

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

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))
  name: Document
  number: 1
    name: Doc 2
    number: 2
    two_field: I will return something


Inside the configcrunch.tests package are acceptance tests. Unit tests are WIP.

To run the tests, see


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for configcrunch, version 0.1.2
Filename, size File type Python version Upload date Hashes
Filename, size configcrunch-0.1.2-py3-none-any.whl (23.0 kB) File type Wheel Python version py3 Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page