Metadata-Version: 2.1
Name: configcrunch
Version: 1.1.0
Summary: Configuration parser based on YAML-Files with support for variables, overlaying and hierarchies
Author-email: Marco Köpcke <hello@capypara.de>
License: MIT License
        
        Copyright (c) 2020 Marco Köpcke
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/theCapypara/configcrunch
Project-URL: Documentation, https://configcrunch.readthedocs.io
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Rust
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: schema>=0.7

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

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

.. |build| image:: https://img.shields.io/github/actions/workflow/status/theCapypara/configcrunch/build.yml 
    :target: https://github.com/theCapypara/configcrunch/actions
    :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 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.7 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 <https://github.com/mitsuhiko/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 <https://github.com/theCapypara/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, 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 <https://configcrunch.readthedocs.io/en/latest/>`_ (or in the docs directory).
