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.

   .. attribute:: _instances

      A dictionary that stores the instances of the singleton classes. The keys
      are the singleton classes and the values are the corresponding instances.

      :type: dict

   .. attribute:: __allow_reinitialization

      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.

      :type: bool

   .. method:: __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.


   .. rubric:: Examples

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


   .. py:method:: getInstance() -> Any

      Return an instance of a singleton class if it has already been created.

      :returns: Existing instance of the class.
      :rtype: ClassInstance

      :raises ValueError: If no instance has been created before.



.. py:function:: getRunId(starttime: datetime.datetime, run_id: Optional[str] = None) -> str

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

   :param starttime: The datetime object representing the start time of the run.
   :type starttime: datetime
   :param run_id: A string with the id given by the user in the configuration or the command line.
   :type run_id: str, optional

   :returns: The run id.
   :rtype: str

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

   :param existing: List of existing ids.
   :type existing: List[str]
   :param newId: New id to compare againts.
   :type newId: str

   :returns: newId with an added counter if any matches were found.
   :rtype: str


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

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

   :returns: Filtered dictionary of sensors.
   :rtype: Dict[str, Tuple]


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

   Check if a string matches any of the given patterns.

   :param patterns: List of patterns to match against.
   :type patterns: List[str]
   :param string: String to check.
   :type string: str

   :returns: True if the string matches any of the patterns, False otherwise.
   :rtype: bool