mypkgs.utils
============

.. py:module:: mypkgs.utils

.. autoapi-nested-parse::

   Utility functions for configuration and environment management.

   These functions are strictly decoupled from the project's folder structure
   to ensure maximum reusability and testability.



Functions
---------

.. autoapisummary::

   mypkgs.utils.load_json_config
   mypkgs.utils.prepare_output_dir


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

.. py:function:: load_json_config(config_path)

   Reads and parses a JSON configuration file.

   The specified file is accessed in read mode, and its contents are
   decoded from JSON format into a Python dictionary. It is required
   that the root element of the targeted JSON file constitutes a valid
   JSON object (key-value pairs).

   :param config_path: The file path to the targeted JSON configuration file.
   :type config_path: pathlib.Path or str

   :returns: A dictionary containing the parsed configuration parameters.
   :rtype: dict[str, Any]

   :raises FileNotFoundError: If the specified configuration file is not found at the given path.
   :raises json.JSONDecodeError: If the file contains invalid JSON syntax and cannot be parsed.
   :raises IsADirectoryError: If the provided path resolves to a directory.

   .. rubric:: Examples

   >>> config = load_json_config("./configs/model_params.json")
   >>> type(config)
   <class 'dict'>


.. py:function:: prepare_output_dir(output_path)

   Validates and prepares the designated output directory.

   This function ensures that the specified output path exists. If the
   directory does not exist, it safely creates it along with any necessar
   parent directories.

   :param output_path: The target directory path where output files will be saved.
   :type output_path: pathlib.Path or str

   :returns: The absolute path of the prepared output directory as a string.
   :rtype: str

   :raises PermissionError: If the program lacks the necessary permissions to create the directory.
   :raises OSError: If the path is invalid or creation fails for system-level reasons.

   .. rubric:: Examples

   >>> prepared_path = prepare_output_dir("./results/experiment_1")
   >>> print(prepared_path)
   '/absolute/path/to/results/experiment_1'