perun.util

Util module.

Attributes

log

Exceptions

MissingDependencyError

Raised when an optional dependency required for a feature is not installed.

Classes

Singleton

Metaclass for creating singleton classes.

Functions

optional_import(module[, extra, feature]) → types.ModuleType

Import an optional dependency, raising a friendly error if it is missing.

getRunId(starttime[, run_id]) → str

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

increaseIdCounter(existing, newId) → str

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

filter_sensors(sensors[, include_sensors, ...]) → dict[str, tuple]

Filter sensors based on include and exclude lists.

matchesOneOf(patterns, string) → bool

Check if a string matches any of the given patterns.

Module Contents

perun.util.log[source]
exception perun.util.MissingDependencyError(module: str, extra: str | None = None, feature: str | None = None)[source]

Bases: ImportError

Raised when an optional dependency required for a feature is not installed.

The error message includes an actionable hint telling the user which perun “extra” to install (e.g. pip install perun[nvidia]) so that missing optional dependencies never result in a bare, hard-to-interpret traceback.

Parameters:
  • module (str)

  • extra (str | None)

  • feature (str | None)

module

The name of the module that failed to import.

Type:

str

extra

The name of the perun optional-dependency extra that provides the module.

Type:

str | None

module
extra = None
perun.util.optional_import(module: str, extra: str | None = None, feature: str | None = None) → types.ModuleType[source]

Import an optional dependency, raising a friendly error if it is missing.

This is a thin wrapper around importlib.import_module() that converts a plain ImportError/ModuleNotFoundError into a MissingDependencyError carrying an actionable, user-facing hint about how to install the missing package.

Parameters:
  • module (str) – Name of the module to import.

  • extra (str | None, optional) – Name of the perun optional-dependency extra that ships module.

  • feature (str | None, optional) – Human readable name of the feature that requires the dependency.

Returns:

The imported module.

Return type:

ModuleType

Raises:

MissingDependencyError – If the module cannot be imported.

class perun.util.Singleton[source]

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

_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

__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

__call__(*args, \*\*kwargs)[source]

Overrides the default behavior of calling the class. It ensures that only one instance of the class is created and returns that instance.

Parameters:
  • args (Any)

  • kwargs (Any)

Return type:

Any

Examples

>>> class MyClass(metaclass=Singleton):
...     pass
>>> my_instance = MyClass()  # Returns the instance of MyClass
getInstance() → Any[source]

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

Returns:

Existing instance of the class.

Return type:

ClassInstance

Raises:

ValueError – If no instance has been created before.

perun.util.getRunId(starttime: datetime.datetime, run_id: str | None = None) → str[source]

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.

  • run_id (str, optional) – A string with the id given by the user in the configuration or the command line.

Returns:

The run id.

Return type:

str

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.

perun.util.increaseIdCounter(existing: list[str], newId: str) → str[source]

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:

newId with an added counter if any matches were found.

Return type:

str

perun.util.filter_sensors(sensors: dict[str, tuple], include_sensors: list[str] | None = None, exclude_sensors: list[str] | None = None, include_backends: list[str] | None = None, exclude_backends: list[str] | None = None) → dict[str, tuple][source]

Filter sensors based on include and exclude lists.

Parameters:
  • sensors (dict[str, tuple]) – Dictionary of sensors.

  • include_sensors (list[str] | None, optional) – List of sensors to include, by default None

  • exclude_sensors (list[str] | None, optional) – List of sensors to exclude, by default None

  • include_backends (list[str] | None, optional) – List of backends to include, by default None

  • exclude_backends (list[str] | None, optional) – List of backends to exclude, by default None

Returns:

Filtered dictionary of sensors.

Return type:

dict[str, tuple]

perun.util.matchesOneOf(patterns: list[str], string: str) → bool[source]

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:

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

Return type:

bool