idmtools 0.0.0.dev0__py3-none-any.whl → 0.0.3__py3-none-any.whl

idmtools/core/interfaces/ientity.py

@@ -0,0 +1,331 @@
+"""
+IEntity definition. IEntity is the base of most of our Remote server entitiies like Experiment, Simulation, WorkItems, and Suites.
+
+Copyright 2021, Bill & Melinda Gates Foundation. All rights reserved.
+"""
+from abc import ABCMeta
+from dataclasses import dataclass, field
+from logging import getLogger
+from os import PathLike
+from pathlib import Path
+from typing import NoReturn, List, Any, Dict, Union, TYPE_CHECKING
+from idmtools.core import EntityStatus, ItemType, NoPlatformException
+from idmtools.core.interfaces.iitem import IItem
+from idmtools.core.id_file import read_id_file, write_id_file
+from idmtools.services.platforms import PlatformPersistService
+
+if TYPE_CHECKING:  # pragma: no cover
+    from idmtools.entities.iplatform import IPlatform
+
+logger = getLogger(__name__)
+
+
+@dataclass
+class IEntity(IItem, metaclass=ABCMeta):
+    """
+    Interface for all entities in the system.
+    """
+    #: ID of the platform
+    platform_id: str = field(default=None, compare=False, metadata={"md": True})
+    #: Platform
+    _platform: 'IPlatform' = field(default=None, compare=False, metadata={"pickle_ignore": False})  # noqa E821
+    #: Parent id
+    parent_id: str = field(default=None, metadata={"md": True})
+    #: Parent object
+    _parent: 'IEntity' = field(default=None, compare=False, metadata={"pickle_ignore": False})
+    #: Status of item
+    status: EntityStatus = field(default=None, compare=False, metadata={"pickle_ignore": False})
+    #: Tags for item
+    tags: Dict[str, Any] = field(default_factory=lambda: {}, metadata={"md": True})
+    #: Item Type(Experiment, Suite, Asset, etc)
+    item_type: ItemType = field(default=None, compare=False)
+    #: Platform Representation of Entity
+    _platform_object: Any = field(default=None, compare=False, metadata={"pickle_ignore": True})
+
+    def update_tags(self, tags: dict = None) -> NoReturn:
+        """
+        Shortcut to update the tags with the given dictionary.
+
+        Args:
+            tags: New tags
+        """
+        self.tags.update(tags)
+
+    def post_creation(self, platform: 'IPlatform') -> None:
+        """
+        Post creation hook for object.
+
+        Returns:
+            None
+        """
+        self.status = EntityStatus.CREATED
+        super().post_creation(platform)
+
+    @classmethod
+    def from_id_file(cls, filename: Union[PathLike, str], platform: 'IPlatform' = None,
+                     **kwargs) -> 'IEntity':  # noqa E821:
+        """
+        Load from a file that container the id.
+
+        Args:
+            filename: Filename to load
+            platform: Platform object to load id from. This can be loaded from file if saved there.
+            **kwargs: Platform extra arguments
+
+        Returns:
+            Entity loaded from id file
+
+        Raises:
+            EnvironmentError if item type is None.
+        """
+        item_id, item_type_in_file, platform_block, extra_args = read_id_file(filename)
+
+        if platform is None:
+            if platform_block:
+                from idmtools.core.platform_factory import Platform
+                platform = Platform(platform_block, **kwargs)
+            else:
+                platform = cls.get_current_platform_or_error()
+        if cls.item_type is None:
+            raise EnvironmentError(
+                "ItemType is None. This is most likely a badly derived IEntity that doesn't run set the default item type on the class")
+
+        return platform.get_item(item_id, cls.item_type, **kwargs)
+
+    @classmethod
+    def from_id(cls, item_id: str, platform: 'IPlatform' = None, **kwargs) -> 'IEntity':  # noqa E821
+        """
+        Load an item from an id.
+
+        Args:
+            item_id: Id of item
+            platform: Platform. If not supplied, we check the current context
+            **kwargs: Optional platform args
+
+        Returns:
+            IEntity of object
+        """
+        if platform is None:
+            platform = cls.get_current_platform_or_error()
+        if cls.item_type is None:
+            raise EnvironmentError(
+                "ItemType is None. This is most likely a badly derived IEntity that doesn't run set the default item type on the class")
+        return platform.get_item(item_id, cls.item_type, **kwargs)
+
+    @property
+    def parent(self):
+        """
+        Return parent object for item.
+
+        Returns:
+            Parent entity if set
+        """
+        if not self._parent:
+            if not self.parent_id:
+                return None
+            if not self.platform:
+                raise NoPlatformException("The object has no platform set...")
+            self._parent = self.platform.get_parent(self.uid, self.item_type)
+
+        return self._parent
+
+    @parent.setter
+    def parent(self, parent: 'IEntity'):  # noqa E821
+        """
+        Sets the parent object for item.
+
+        Args:
+            parent: Parent object
+
+        Returns:
+            None
+        """
+        if parent:
+            self._parent = parent
+            self.parent_id = parent.uid
+        else:
+            self.parent_id = self._parent = None
+
+    @property
+    def platform(self) -> 'IPlatform':  # noqa E821
+        """
+        Get objects platform object.
+
+        Returns:
+            Platform
+        """
+        if not self._platform and self.platform_id:
+            self._platform = PlatformPersistService.retrieve(self.platform_id)
+        return self._platform
+
+    @platform.setter
+    def platform(self, platform: 'IPlatform'):  # noqa E821
+        """
+        Sets object platform.
+
+        Args:
+            platform: Platform to set
+
+        Returns:
+            None
+        """
+        if platform:
+            self.platform_id = platform.uid
+            self._platform = platform
+        else:
+            self._platform = self.platform_id = None
+
+    def get_platform_object(self, force: bool = False, platform: 'IPlatform' = None, **kwargs):
+        """
+        Get the platform representation of an object.
+
+        Args:
+            force: Force reload of platform object
+            platform: Allow passing platform object to fetch
+            **kwargs: Optional args used for specific platform behaviour
+
+        Returns:
+            Platform Object
+        """
+        if platform:
+            self.platform = platform
+        if not self.platform:
+            raise NoPlatformException("The object has no platform set...")
+        if self._platform_object is None or force:
+            self._platform_object = self.platform.get_item(self.uid, self.item_type, raw=True, force=force, **kwargs)
+        return self._platform_object
+
+    @property
+    def done(self):
+        """
+        Returns if a item is done.
+
+        For an item to be done, it should be in either failed or succeeded state.
+
+        Returns:
+            True if status is succeeded or failed
+        """
+        return self.status in (EntityStatus.SUCCEEDED, EntityStatus.FAILED)
+
+    @property
+    def succeeded(self):
+        """
+        Returns if an item has succeeded.
+
+        Returns:
+            True if status is SUCCEEDED
+        """
+        return self.status == EntityStatus.SUCCEEDED
+
+    @property
+    def failed(self):
+        """
+        Returns is a item has failed.
+
+        Returns:
+            True if status is failed
+        """
+        return self.status == EntityStatus.FAILED
+
+    def __hash__(self):
+        """
+        Returns hash for object. For entities, the hash is the id.
+
+        Returns:
+            Hash id
+        """
+        return id(self.uid)
+
+    def _check_for_platform_from_context(self, platform) -> 'IPlatform':
+        """
+        Try to determine platform of current object from self or current platform.
+
+        Args:
+            platform: Passed in platform object
+
+        Raises:
+            NoPlatformException: when no platform is on current context
+        Returns:
+            Platform object
+        """
+        if self.platform is None:
+            # check context for current platform
+            if platform is None:
+                platform = self.get_current_platform_or_error()
+            self.platform = platform
+        return self.platform
+
+    @staticmethod
+    def get_current_platform_or_error():
+        """
+        Try to fetch the current platform from context. If no platform is set, error.
+
+        Returns:
+            Platform if set
+
+        Raises:
+            NoPlatformException if no platform is set on the current context
+        """
+        from idmtools.core.context import get_current_platform
+        p = get_current_platform()
+        if p is None:
+            raise NoPlatformException("No Platform defined on object, in current context, or passed to run")
+        return p
+
+    def to_id_file(self, filename: Union[str, PathLike], save_platform: bool = False, platform_args: Dict = None):
+        """
+        Write a id file.
+
+        Args:
+            filename: Filename to create
+            save_platform: Save platform to the file as well
+            platform_args: Platform Args
+
+        Returns:
+            None
+        """
+        write_id_file(filename, self, save_platform, platform_args)
+
+    def get_directory(self) -> Path:
+        """
+        Retrieve the directory path associated with the current item.
+
+        This method returns the local platform-specific directory for the item,
+        such as a simulation, experiment, or suite. It is only supported for
+        non-COMPS platforms and for items of type SIMULATION, EXPERIMENT, or SUITE.
+
+        Raises:
+            RuntimeError: If the current platform is COMPSPlatform, or if the item
+                          type is not one of SIMULATION, EXPERIMENT, or SUITE.
+            AttributeError: If the item does not have an associated platform object.
+
+        Returns:
+            pathlib.Path: The path to the item's working directory on the current platform.
+        """
+        platform = self.get_current_platform_or_error()
+        if not hasattr(platform, 'job_directory'):
+            raise RuntimeError(f'Not support get_directory for {platform.__class__.__name__}')
+        if self.item_type not in (ItemType.SIMULATION, ItemType.EXPERIMENT, ItemType.SUITE):
+            raise RuntimeError('Only support Suite/Experiment/Simulation for get_directory() for now.')
+        return platform.get_directory(self)
+
+    @property
+    def directory(self) -> Path:
+        """
+        The get directory for the current item. This is a convenience alias for get_directory.
+        Returns:
+            pathlib.Path: The path to the item's working directory on the current platform.
+        """
+        return self.get_directory()
+
+    def get_tags(self) -> Dict[str, Any]:
+        """
+        Get the tags associated with the entity (alias for the `tags` property).
+
+        Returns:
+            Dict[str, Any]: The dictionary of tags.
+        """
+        return self.tags
+
+
+IEntityList = List[IEntity]

idmtools/core/interfaces/iitem.py

@@ -0,0 +1,206 @@
+"""
+IItem is the base of all items that have ids such as AssetCollections, Experiments, etc.
+
+Copyright 2025, Bill Foundation. All rights reserved.
+"""
+from dataclasses import dataclass, field, fields
+from inspect import signature
+from logging import getLogger, DEBUG
+from typing import List, Callable, TYPE_CHECKING, Any, Dict
+from uuid import uuid4
+
+from idmtools.utils.hashing import ignore_fields_in_dataclass_on_pickle
+
+if TYPE_CHECKING:  # pragma: no cover
+    from idmtools.entities.iplatform import IPlatform
+
+logger = getLogger(__name__)
+
+PRE_POST_CREATION_HOOK = Callable[['IItem', 'IPlatform'], None]
+
+
+@dataclass(repr=False)
+class IItem:
+    """
+    IItem represents items that have identifiable ids.
+
+    In addition, IItem facilities pre and post creation hooks through the __pre_creation_hooks, __post_creation_hooks, add_pre_creation_hook, add_post_creation_hook
+
+    """
+    _uid: str = field(default=None, metadata={"md": True})
+    __pre_creation_hooks: List[PRE_POST_CREATION_HOOK] = field(default_factory=list, metadata={"md": True})
+    __post_creation_hooks: List[PRE_POST_CREATION_HOOK] = field(default_factory=list, metadata={"md": True})
+
+    @property
+    def uid(self):
+        """
+        UID Of the object.
+        Returns:
+            ID
+        """
+        if self._uid is None:
+            self._uid = str(uuid4())
+        return self._uid
+
+    @uid.setter
+    def uid(self, uid):
+        """
+        Set the uid on the objects.
+
+        Args:
+            uid: Uid to set
+
+        Returns:
+            None
+        """
+        self._uid = uid
+
+    @property
+    def id(self):
+        """
+        Alias for uid.
+
+        Returns:
+            UID of object
+
+        Notes:
+            What is relation to uid?
+        """
+        if self.uid:
+            return str(self.uid)
+        else:
+            return self.uid
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        """
+        Identify the metadata from the fields.
+
+        Returns:
+            Metadata dict
+        """
+        attrs = set(vars(self).keys())
+        obj_dict = {k: getattr(self, k) for k in attrs.intersection(self.metadata_fields)}
+        return obj_dict
+
+    @property
+    def pickle_ignore_fields(self):
+        """
+        Get list of fields that will be ignored when pickling.
+
+        Returns:
+            Set of fields that are ignored when pickling the item
+        """
+        return set(f.name for f in fields(self) if "pickle_ignore" in f.metadata and f.metadata["pickle_ignore"])
+
+    @property
+    def metadata_fields(self):
+        """
+        Get list of fields that have metadata.
+
+        Returns:
+            Set of fields that have metadata
+        """
+        return set(f.name for f in fields(self) if "md" in f.metadata and f.metadata["md"])
+
+    def display(self) -> str:
+        """
+        Display as string representation.
+
+        Returns:
+            String of item
+        """
+        return self.__repr__()
+
+    # region Events methods
+    def pre_creation(self, platform: 'IPlatform') -> None:
+        """
+        Called before the actual creation of the entity.
+
+        Args:
+            platform: Platform item is being created on
+
+        Returns:
+            None
+        """
+        for hook in self.__pre_creation_hooks:
+            if logger.isEnabledFor(DEBUG):
+                logger.debug(f'Calling pre-create hook named {hook.__name__ if hasattr(hook, "__name__") else str(hook)}')
+            hook(self, platform)
+
+    def post_creation(self, platform: 'IPlatform') -> None:
+        """
+        Called after the actual creation of the entity.
+
+        Args:
+            platform: Platform item was created on
+
+        Returns:
+            None
+        """
+        for hook in self.__post_creation_hooks:
+            if logger.isEnabledFor(DEBUG):
+                logger.debug(f'Calling post-create hook named {hook.__name__ if hasattr(hook, "__name__") else str(hook)}')
+            hook(self, platform)
+
+    def add_pre_creation_hook(self, hook: PRE_POST_CREATION_HOOK):
+        """
+        Adds a hook function to be called before an item is created.
+
+        Args:
+            hook: Hook function. This should have two arguments, the item and the platform
+
+        Returns:
+            None
+        """
+        if len(signature(hook).parameters) != 2:
+            raise ValueError("Pre creation hooks should have 2 arguments. The first argument will be the item, the second the platform")
+        self.__pre_creation_hooks.append(hook)
+
+    def add_post_creation_hook(self, hook: PRE_POST_CREATION_HOOK):
+        """
+        Adds a hook function to be called after an item is created.
+
+        Args:
+            hook: Hook function. This should have two arguments, the item and the platform
+
+        Returns:
+            None
+        """
+        if len(signature(hook).parameters) != 2:
+            raise ValueError("Post creation hooks should have 2 arguments. The first argument will be the item, the second the platform")
+        self.__post_creation_hooks.append(hook)
+
+    def post_setstate(self):
+        """
+        Function called after restoring the state if additional initialization is required.
+        """
+        pass
+
+    def pre_getstate(self):
+        """
+        Function called before picking and return default values for "pickle-ignore" fields.
+        """
+        pass
+
+    # endregion
+
+    # region State management
+    def __getstate__(self):
+        """
+        Ignore the fields in pickle_ignore_fields during pickling.
+        """
+        return ignore_fields_in_dataclass_on_pickle(self)
+
+    def __setstate__(self, state):
+        """
+        Add ignored fields back since they don't exist in the pickle.
+        """
+        self.__dict__.update(state)
+
+        # Restore the pickle fields with values requested
+        self.post_setstate()
+    # endregion
+
+
+IItemList = List[IItem]

idmtools/core/interfaces/imetadata_operations.py

@@ -0,0 +1,89 @@
+"""
+Here we implement the Metadata operations interface.
+
+Copyright 2021, Bill & Melinda Gates Foundation. All rights reserved.
+"""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Dict, List
+from idmtools.core import ItemType
+from idmtools.core.interfaces.ientity import IEntity
+
+
+@dataclass
+class IMetadataOperations(ABC):
+    """
+    Operations to handle metadata for SlurmPlatform.
+    """
+    @abstractmethod
+    def get(self, item: IEntity) -> Dict:
+        """
+        Obtain item's metadata.
+
+        Args:
+            item: idmtools entity (Suite, Experiment and Simulation, etc.)
+        Returns:
+            a key/value dict of metadata from the given item
+        """
+        pass
+
+    @abstractmethod
+    def dump(self, item: IEntity) -> None:
+        """
+        Save item's metadata to a file.
+
+        Args:
+            item: idmtools entity (Suite, Experiment and Simulation, etc.)
+        Returns:
+            None
+        """
+        pass
+
+    @abstractmethod
+    def load(self, item: IEntity) -> Dict:
+        """
+        Obtain item's metadata file.
+
+        Args:
+            item: idmtools entity (Suite, Experiment and Simulation, etc.)
+        Returns:
+             key/value dict of item's metadata file
+        """
+        pass
+
+    @abstractmethod
+    def update(self, item: IEntity) -> None:
+        """
+        Update item's metadata file.
+
+        Args:
+            item: idmtools entity (Suite, Experiment and Simulation, etc.)
+        Returns:
+            None
+        """
+        pass
+
+    @abstractmethod
+    def clear(self, item: IEntity) -> None:
+        """
+        Clear the item's metadata file.
+
+        Args:
+            item: idmtools entity (Suite, Experiment and Simulation, etc.)
+        Returns:
+            None
+        """
+        pass
+
+    @abstractmethod
+    def filter(self, item_type: ItemType, item_filter: Dict = None) -> List:
+        """
+        Obtain all items that match the given item_filter key/value pairs passed.
+
+        Args:
+            item_type: the type of items to search for matches (simulation, experiment, suite, etc)
+            item_filter: a dict of metadata key/value pairs for exact match searching
+        Returns:
+            a list of matching items
+        """
+        pass

idmtools/core/interfaces/inamed_entity.py

@@ -0,0 +1,17 @@
+"""
+INamedEntity definition. INamedEntity Provides a class with a name like Experiments or Suites.
+
+Copyright 2021, Bill & Melinda Gates Foundation. All rights reserved.
+"""
+from abc import ABCMeta
+from dataclasses import dataclass, field
+
+from idmtools.core.interfaces.ientity import IEntity
+
+
+@dataclass
+class INamedEntity(IEntity, metaclass=ABCMeta):
+    """
+    INamedEntity extends the IEntity adding the name property.
+    """
+    name: str = field(default=None, metadata={"md": True}, compare=False)