plesty.lib.utils.config
=======================

.. py:module:: plesty.lib.utils.config

.. autoapi-nested-parse::

   Reading the YAML configuration a Plesty module ships and a run supplies.

   Every Plesty module carries a ``config.yaml`` beside its package
   ``__init__`` — the constants and running defaults the scaffold creates — and
   every experiment additionally reads a run configuration from a file the
   operator points at. Both were being loaded by a hand-written ``load_config``
   copied into each module, which is why this lives here instead.

   The split the platform assumes:

   * **Environment** (:class:`~plesty.lib.utils.settings.EnvSettings`) — device
     addresses and credentials; never in a tracked file.
   * **Packaged module config** (:func:`module_config`) — constants of the module
     itself: which sub-devices a rig has, how long an operation may physically
     take. Ships in the wheel, changes with the code.
   * **Run config** (:func:`load_yaml`) — measurement tuning the operator varies
     per run, frozen into the run's plan.

   .. code-block:: python

       from plesty.lib.utils.config import load_yaml, module_config

       budgets = module_config("plesty.qd_fss", "constants", "hwp")
       tuning = load_yaml("config/default.yaml", default={})



Attributes
----------

.. autoapisummary::

   plesty.lib.utils.config.DEFAULT_CONFIG_FILE
   plesty.lib.utils.config._REQUIRED


Functions
---------

.. autoapisummary::

   plesty.lib.utils.config.load_yaml
   plesty.lib.utils.config.module_config_path
   plesty.lib.utils.config.module_config


Module Contents
---------------

.. py:data:: DEFAULT_CONFIG_FILE
   :value: 'config.yaml'


.. py:data:: _REQUIRED

.. py:function:: load_yaml(path: str | pathlib.Path, default: Any = _REQUIRED) -> Any

   Parse a YAML file.

   :param path: The file to read.
   :param default: Returned when the file does not exist. Without it a missing
                   file raises — a run configured from a path that is not there is a
                   mistake worth naming, not an empty configuration to proceed with.

   :returns: The parsed document, or *default* when the file is absent.

   :raises FileNotFoundError: If the file is missing and no *default* was given.
   :raises ValueError: If the file is not valid YAML.


.. py:function:: module_config_path(module: str | types.ModuleType, filename: str = DEFAULT_CONFIG_FILE) -> pathlib.Path

   Return the path of the configuration file packaged with *module*.

   :param module: The module, or its importable name (``"plesty.qd_fss"``).
   :param filename: Configuration file name beside the module's ``__init__``.

   :returns: The path, whether or not the file exists.

   :raises ModuleNotFoundError: If *module* names something that cannot be imported.
   :raises ValueError: If the module has no location on disk.


.. py:function:: module_config(module: str | types.ModuleType, *keys: str, filename: str = DEFAULT_CONFIG_FILE) -> Any

   Return the configuration a module ships, or one section of it.

   :param module: The module, or its importable name (``"plesty.qd_fss"``).
   :param \*keys: Path into the document, e.g. ``"constants", "hwp"``. Without
                  keys the whole document is returned.
   :param filename: Configuration file name beside the module's ``__init__``.

   :returns: The document, or the addressed section.

   :raises FileNotFoundError: If the module ships no such configuration file — an
       absent packaged config is a broken install, not a default.
   :raises KeyError: If a key is missing, naming the full path so the
       error says which constant the module forgot to declare.
   :raises ValueError: If the file is not valid YAML.