perun.util¶
Util module.
Attributes¶
Exceptions¶
Raised when an optional dependency required for a feature is not installed. |
Classes¶
Metaclass for creating singleton classes. |
Functions¶
|
Import an optional dependency, raising a friendly error if it is missing. |
|
Return run id based on the configuration object or the current datetime. |
|
Increase id counter based on number of existing entries with the same id. |
|
Filter sensors based on include and exclude lists. |
|
Check if a string matches any of the given patterns. |
Module Contents¶
- exception perun.util.MissingDependencyError(module: str, extra: str | None = None, feature: str | None = None)[source]¶
Bases:
ImportErrorRaised 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 plainImportError/ModuleNotFoundErrorinto aMissingDependencyErrorcarrying 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:
typeMetaclass 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
- 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