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

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

.. autoapi-nested-parse::

   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')

   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"

   The log level is determined in the following priority:
       - OASIS_PYTOOLS_LOG_LEVEL environment variable
       - wrapped function kwargs `logging_level`

   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

   :param exec_name: The name of the script or function being executed. This will be used as part of the log file name.
   :type exec_name: str
   :param log_dir: The path to the directory where log files will be stored. Defaults to './log'.
   :type log_dir: str, optional
   :param log_level: The logging level to use. Can be an integer or a string. See docstring for order of priority of log level set. If no log levels set, then defaults to WARNING.
   :type log_level: int or str, optional

   :returns: The decorated function.
   :rtype: function

   .. rubric:: 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.

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

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