perun.util
==========

.. py:module:: perun.util

.. autoapi-nested-parse::

   Util module.



Attributes
----------

.. autoapisummary::

   perun.util.log


Classes
-------

.. autoapisummary::

   perun.util.Singleton


Functions
---------

.. autoapisummary::

   perun.util.getRunId
   perun.util.increaseIdCounter
   perun.util.filter_sensors
   perun.util.matchesOneOf


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

.. py:data:: log

.. py:class:: Singleton

   Bases: :py:obj:`type`


   Metaclass for creating singleton classes.

   Singleton classes are classes that can only have one instance. This metaclass
   ensures that only one instance of a class is created and provides a way to
   access that instance.

   Attributes
   ----------
   _instances : dict
       A dictionary that stores the instances of the singleton classes. The keys
       are the singleton classes and the values are the corresponding instances.
   __allow_reinitialization : bool
       A flag that indicates whether the singleton class allows reinitialization.
       If set to True, the `__call__` method will reinitialize the instance if the
       class has already been instantiated.

   Methods
   -------
   __call__(*args, **kwargs)
       Overrides the default behavior of calling the class. It ensures that only one
       instance of the class is created and returns that instance.

   Examples
   --------
   >>> class MyClass(metaclass=Singleton):
   ...     pass
   >>> my_instance = MyClass()  # Returns the instance of MyClass


   .. py:attribute:: _instances
      :type:  Dict


   .. py:attribute:: __allow_reinitialization
      :type:  bool
      :value: False



   .. py:method:: __call__(*args, **kwargs)

      Call method for the singleton class.

      This method is called when the singleton class is invoked as a function.
      It ensures that only one instance of the class is created and returned.

      Parameters
      ----------
      cls : class object
          The class object.
      *args : tuple
          Variable length argument list.
      **kwargs : dict
          Arbitrary keyword arguments.

      Returns
      -------
      instance : object
          The instance of the singleton class.

      Examples
      --------
      >>> instance = MyClass()
      >>> instance()
      <MyClass object at 0x7f9a8a3d6a90>



.. py:function:: getRunId(starttime: datetime.datetime) -> str

   Return run id based on the configuration object or the current datetime.

   Parameters
   ----------
   starttime : datetime
       The datetime object representing the start time of the run.

   Returns
   -------
   str
       The run id.

   Notes
   -----
   If the configuration object has a valid run id specified, it will be returned.
   If the run id is set to "SLURM" and the environment variable "SLURM_JOB_ID" is present,
   the value of "SLURM_JOB_ID" will be returned.
   Otherwise, the ISO formatted string representation of the start time will be returned.


.. py:function:: increaseIdCounter(existing: List[str], newId: str) -> str

   Increase id counter based on number of existing entries with the same id.

   Parameters
   ----------
   existing : List[str]
       List of existing ids.
   newId : str
       New id to compare againts.

   Returns
   -------
   str
       newId with an added counter if any matches were found.


.. py:function:: filter_sensors(sensors: Dict[str, Tuple], include_sensors: Optional[List[str]] = None, exclude_sensors: Optional[List[str]] = None, include_backends: Optional[List[str]] = None, exclude_backends: Optional[List[str]] = None) -> Dict[str, Tuple]

   Filter sensors based on include and exclude lists.

   Parameters
   ----------
   sensors : Dict[str, Tuple]
       Dictionary of sensors.
   include_sensors : Optional[List[str]], optional
       List of sensors to include, by default None
   exclude_sensors : Optional[List[str]], optional
       List of sensors to exclude, by default None
   include_backends : Optional[List[str]], optional
       List of backends to include, by default None
   exclude_backends : Optional[List[str]], optional
       List of backends to exclude, by default None

   Returns
   -------
   Dict[str, Tuple]
       Filtered dictionary of sensors.


.. py:function:: matchesOneOf(patterns: List[str], string: str) -> bool

   Check if a string matches any of the given patterns.

   Parameters
   ----------
   patterns : List[str]
       List of patterns to match against.
   string : str
       String to check.

   Returns
   -------
   bool
       True if the string matches any of the patterns, False otherwise.