curryer.utils
=============

.. py:module:: curryer.utils

.. autoapi-nested-parse::

   Generic utilities (not specific to the SPICE library).

   @author: Brandon Stone



Attributes
----------

.. autoapisummary::

   curryer.utils.logger


Functions
---------

.. autoapisummary::

   curryer.utils.track_performance
   curryer.utils.format_performance
   curryer.utils.capture_subprocess
   curryer.utils.enable_logging


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

.. py:data:: logger

.. py:function:: track_performance(func: Callable, storage: dict = None)

   Wrapper to track the performance of functions or class methods.

   :param func: Function to track.
   :type func: callable
   :param storage: Dictionary to store the metrics in, otherwise it is assumed that func is
                   part of an instance and metrics will be added to the
                   `_performance_metrics` attribute.
   :type storage: dict, optional

   :returns: Wrapped function or class method.
   :rtype: callable


.. py:function:: format_performance(obj, indent: str = '\t', p: int = 3, ascending=None)

   Format the performance results from `track_performance`.

   :param obj: Dictionary of the performance metrics or instance with the automated
               `_performance_metrics` attribute.
   :type obj: instance or dict
   :param indent: String used for indentation. Default is tab.
   :type indent: str, optional
   :param p: Decimal precision in timing format. Default is 3, aka milliseconds.
   :type p: int, optional
   :param ascending: Order results by insert (None), ascending (True), or descending (False).
                     Default is None.
   :type ascending: None or bool, optional

   :returns: Formatted performance results.
   :rtype: str


.. py:function:: capture_subprocess(cmd, timeout=3600, capture_output=False)

   Execute commands in a subprocess.

   :param cmd: Command arguments to execute.
   :type cmd: list of str
   :param timeout: Number of seconds to wait before timing out. Default=3600 (1hr)
   :type timeout: int, optional
   :param capture_output: Option to return the stdout text. Default=False
   :type capture_output: bool, optional

   :returns: The stdout text is returned if `capture_output`=True.
   :rtype: None or str


.. py:function:: enable_logging(log_level=logging.DEBUG, log_file: bool | str | pathlib.Path = False, extra_loggers: list[str] = None)

   Enable logging to the console and optionally to a file.

   :param log_level: A logging log level.
   :type log_level: int
   :param log_file: Option to enable logging to a file. If true or a directory the filename
                    will be auto-generated. If true, the file will be saved to the current
                    working directory. Otherwise, the supplied file will be used.
   :type log_file: bool or str or Path, optional
   :param extra_loggers: Collection of additional loggers to enable at DEBUG level.
   :type extra_loggers: List[str], optional