Metadata-Version: 2.1
Name: configcrunch
Version: 0.3.7
Summary: Configuration parser based on YAML-Files with support for variables, overlaying and hierarchies
Home-page: https://github.com/Parakoopa/configcrunch/
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: schema (>=0.7)
Requires-Dist: pyyaml (>=5.1)
Requires-Dist: jinja2 (>=2.10.1)

Configcrunch
============

|build| |docs| |pypi-version| |pypi-downloads| |pypi-license| |pypi-pyversions|

.. |build| image:: https://jenkins.riptide.parakoopa.de/buildStatus/icon?job=configcrunch%2Fmaster
    :target: https://jenkins.riptide.parakoopa.de/blue/organizations/jenkins/configcrunch/activity
    :alt: Build Status

.. |docs| image:: https://readthedocs.org/projects/configcrunch/badge/?version=latest
    :target: https://configcrunch.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. |pypi-version| image:: https://img.shields.io/pypi/v/configcrunch
    :target: https://pypi.org/project/configcrunch/
    :alt: Version

.. |pypi-downloads| image:: https://img.shields.io/pypi/dm/configcrunch
    :target: https://pypi.org/project/configcrunch/
    :alt: Downloads

.. |pypi-license| image:: https://img.shields.io/pypi/l/configcrunch
    :alt: License (MIT)

.. |pypi-pyversions| image:: https://img.shields.io/pypi/pyversions/configcrunch
    :alt: Supported Python versions

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``

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 sub-documents of any type.
- Documents can contain `Jinja2 <http://jinja.pocoo.org/docs/2.10/>`_ 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 <https://github.com/Parakoopa/riptide-lib>`_
- (Your project here! Open an issue.)

By default Configcrunch uses `schema <https://pypi.org/project/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.

.. code-block:: yaml

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


.. code-block:: yaml

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


.. code-block:: python

    # classes.py
    from schema import Schema, Optional

    from configcrunch import YamlConfigDocument, DocReference, load_subdocument, variable_helper, REMOVE


    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)
                }
            )

        def _load_subdocuments(self, lookup_paths):
            if "sub" in self and "sub" != REMOVE:
                self["sub"] = load_subdocument(self["sub"], self, Two, lookup_paths)
            return self

        @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
                }
            )


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 acceptance tests. Unit tests are WIP.

To run the tests, see ``run_tests.sh``.

Documentation
-------------

The complete documentation can be found at `Read the Docs <https://configcrunch.readthedocs.io/en/latest/>`_ (or in the docs directory).

