CLI Config
==========

|

.. image:: _static/logo_extend.png
  :align: center
  :width: 1000
  :alt: CLI config logo

|

*CLI Config*: Lightweight library that provides routines to merge nested configs
and set parameters from command line. It is also provide processing functions
that can change the whole configuration before and after each config merge, config
saving and config loading. It also contains many routines to manipulate the config as
flatten or nested dicts.

|PyPI version| |PythonVersion| |License|

|Ruff_logo| |Black_logo|

|Ruff| |Flake8| |Pydocstyle| |MyPy| |PyLint|

|Tests| |Coverage| |Documentation Status|

Make default config file(s) in your project (configs are merged from left to right):

.. code:: python

   # main.py
   from cliconfig import make_config

   config = make_config('default1.yaml', 'default2.yaml')
   config_dict = config.dict  # native python dict

Then launch your script with additional config(s) file(s) and parameters by command line.
The additional configs are merge on the default ones then the parameters are set.

.. code:: bash

   python main.py --config first.yaml,second.yaml --param1=1 --subconfig.param2='foo'

**By default, these additional configs cannot add new parameters to the default config
(for security and retro-compatibility reasons).**

With processing
---------------

The library provide powerfull tools to modify the configuration called "processings".
One of the possibility they add is to merge multiple configurations,
copy a parameter on another, enforce type and more. To do so, simply adding the
corresponding tags to your parameter names (on config files or CLI parameters).

For instance with these config files:

.. code:: yaml

    ---  # main.yaml
    path_1@merge_add: sub1.yaml
    path_2@merge_add: sub2.yaml
    config3.select@select: "config3.param1"

    --- # sub1.yaml
    config1:
      param@copy@type:int: config2.param
      param2@type:None|int: 1

    --- # sub2.yaml
    config2.param@type:int: 2
    config3:
      param1: 0
      param2: 1

Here `main.yaml` will be interpreted like:

.. code:: yaml

    path_1: sub1.yaml
    path_2: sub2.yaml
    config1:
      param: 2  # the value of config2.param
      param2: 1
    config2:
      param: 2
    config3:
      select: "config3.param1"
      param1: 0
      # param2 is deleted because it is not in the selection

Then, all the parameters in `config1` and `config2` have enforced types
(`config2.param` can also be None) and changing `config2.param` will also update
`config1.param` accordingly (which is protected by direct update).

See *Quickstart* section for more details and *Processing* section for advanced usage.

.. |PyPI version| image:: https://img.shields.io/github/v/tag/valentingol/cliconfig?label=Pypi&logo=pypi&logoColor=yellow
   :target: https://pypi.org/project/cliconfig/
.. |PythonVersion| image:: https://img.shields.io/badge/Python-3.7%20%7E%203.11-informational
.. |License| image:: https://img.shields.io/github/license/valentingol/cliconfig?color=999
   :target: https://stringfixer.com/fr/MIT_license
.. |Ruff_logo| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
   :target: https://github.com/charliermarsh/ruff
.. |Black_logo| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
.. |Ruff| image:: https://github.com/valentingol/cliconfig/actions/workflows/ruff.yaml/badge.svg
   :target: https://github.com/valentingol/cliconfig/actions/workflows/ruff.yaml
.. |Flake8| image:: https://github.com/valentingol/cliconfig/actions/workflows/flake.yaml/badge.svg
   :target: https://github.com/valentingol/cliconfig/actions/workflows/flake.yaml
.. |Pydocstyle| image:: https://github.com/valentingol/cliconfig/actions/workflows/pydocstyle.yaml/badge.svg
   :target: https://github.com/valentingol/cliconfig/actions/workflows/pydocstyle.yaml
.. |MyPy| image:: https://github.com/valentingol/cliconfig/actions/workflows/mypy.yaml/badge.svg
   :target: https://github.com/valentingol/cliconfig/actions/workflows/mypy.yaml
.. |PyLint| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/valentingol/ab12676c87f0eaa715bef0f8ad31a604/raw/cliconfig_pylint.json
   :target: https://github.com/valentingol/cliconfig/actions/workflows/pylint.yaml
.. |Tests| image:: https://github.com/valentingol/cliconfig/actions/workflows/tests.yaml/badge.svg
   :target: https://github.com/valentingol/cliconfig/actions/workflows/tests.yaml
.. |Coverage| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/valentingol/098e9c7c53be88779ee52ef2f2bc8803/raw/cliconfig_tests.json
   :target: https://github.com/valentingol/cliconfig/actions/workflows/tests.yaml
.. |Documentation Status| image:: https://readthedocs.org/projects/cliconfig/badge/?version=latest
   :target: https://cliconfig.readthedocs.io/en/latest/?badge=latest

.. toctree::
   :maxdepth: 4
   :caption: Contents:

   installation
   quickstart
   edge_cases
   processing
   cliconfig_api
   contribute
   license
