.. _welcome:

``yayaml``
==========

The ``yayaml`` package provides extensions to ``ruamel.yaml`` that allow creating
some often-needed Python objects directly via YAML tags and making it easier
to represent custom objects when writing YAML files.

**Features:**

- 40+ built-in YAML tags for common operations (math, strings, paths, etc.)
- Easy creation of custom constructors and representers
- Seamless integration with ``ruamel.yaml``
- Support for environment variables, conditionals, and NumPy arrays

Quick Example
-------------

Use YAML tags to create Python objects directly:

.. code-block:: yaml

    # config.yml
    sum:        !sum        [1, 2, 3]               # 6
    formatted:  !format     ["{}+{}={}", 1, 2, 3]   # "1+2=3"
    linspace:   !linspace   [-1, 1, 5]              # np.linspace(-1, 1, 5)
    home_path:  !expanduser ~/config                # "/home/user/config"
    username:   !getenv [USER, "unknown_user"]      # $USER or fallback

Load and use in Python:

.. code-block:: python

    import yayaml as yay

    # Load YAML with built-in tags
    config = yay.load_yml("config.yml")
    print(config["sum"])  # 6

    # Or load from string
    data = yay.yaml.load("value: !sum [1, 2, 3]")

    # Write YAML files
    yay.write_yml({"key": "value"}, path="output.yml")


Related Projects
----------------

:py:mod:`yayaml` is used in the following projects to read and write YAML
files, including custom constructors and representers:

* `paramspace <https://gitlab.com/blsqr/paramspace>`_: for config-file-based
  grid search with deeply nested dicts
* `dantro <https://gitlab.com/utopia-project/dantro>`_: for loading, processing
  and visualizing high-dimensional simulation output
* `utopya <https://gitlab.com/utopia-project/utopya>`_: a versatile simulation
  framework


.. note::

    If you find any errors in this documentation or would like to contribute
    to the project, we are happy about your visit to the
    `project page <https://gitlab.com/blsqr/yayaml>`_.


.. toctree::
    :caption: User Guide
    :maxdepth: 2
    :hidden:

    tags
    custom-constructors

.. toctree::
    :hidden:

    Repository <https://gitlab.com/blsqr/yayaml>
    Changelog <https://gitlab.com/blsqr/yayaml/-/blob/main/CHANGELOG.md>

.. toctree::
    :caption: Reference
    :maxdepth: 2
    :hidden:

    API Reference <api/yayaml>
    index_pages