oasislmf.pytools.utils
======================

.. py:module:: oasislmf.pytools.utils

.. autoapi-nested-parse::

   This file contains general-purpose utilities.



Functions
---------

.. autoapisummary::

   oasislmf.pytools.utils.logging_set_handlers
   oasislmf.pytools.utils.logging_reset_handlers
   oasislmf.pytools.utils.redirect_logging
   oasislmf.pytools.utils.assert_allclose


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

.. py:function:: logging_set_handlers(logger_name, handler, log_level)

.. py:function:: logging_reset_handlers(logger_name)

.. py:function:: redirect_logging(exec_name, log_dir='./log', log_level=logging.WARNING)

   Decorator that redirects logging output to a file.

   Apply to the main run function of a python exec from the pytools directory.
   Only errors will be send to STDERR, all other logging is stored in a file named:
      "<log_dir>/<exec_name>_<PID>.log"

   Each log file is timestamped with start / finish times
       ❯ cat log/fmpy_112820.log
       2023-03-01 13:48:31,286 - oasislmf - INFO - starting process
       2023-03-01 13:48:36,476 - oasislmf - INFO - finishing process

   Args:
       exec_name (str): The name of the script or function being executed. This will be used as part of the log file name.
       log_dir (str, optional): The path to the directory where log files will be stored. Defaults to './log'.
       log_level (int or str, optional): The logging level to use. Can be an integer or a string. Defaults to logging.INFO.

   Returns:
       function: The decorated function.

   Example:
       @redirect_logging(exec_name='my_script', log_dir='./logs', log_level=logging.DEBUG)
       def my_run_function():
           # code here



.. py:function:: assert_allclose(x, y, rtol=1e-10, atol=1e-08, x_name='x', y_name='y')

   Drop in replacement for `numpy.testing.assert_allclose` that also shows
   the nonmatching elements in a nice human-readable format.

   Args:
       x (np.array or scalar): first input to compare.
       y (np.array or scalar): second input to compare.
       rtol (float, optional): relative tolreance. Defaults to 1e-10.
       atol (float, optional): absolute tolerance. Defaults to 1e-8.
       x_name (str, optional): header to print for x if x and y do not match. Defaults to "x".
       y_name (str, optional): header to print for y if x and y do not match. Defaults to "y".

   Raises:
       AssertionError: if x and y shapes do not match.
       AssertionError: if x and y data do not match.