logs-py 4.0.7__py3-none-any.whl

LOGS/Auxiliary/Constants.py

@@ -0,0 +1,99 @@
+import os
+from typing import TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    from LOGS.Entities.Attachment import Attachment
+    from LOGS.Entities.Bridge import Bridge
+    from LOGS.Entities.CustomField import CustomField
+    from LOGS.Entities.CustomType import CustomType
+    from LOGS.Entities.DataFormat import DataFormat
+    from LOGS.Entities.DataFormatInstrument import DataFormatInstrument
+    from LOGS.Entities.Dataset import Dataset
+    from LOGS.Entities.DatasetTemplate import DatasetTemplate
+    from LOGS.Entities.DataSource import DataSource
+    from LOGS.Entities.FileEntry import FileEntry
+    from LOGS.Entities.InventoryItem import InventoryItem
+    from LOGS.Entities.LabNotebook import LabNotebook
+    from LOGS.Entities.LabNotebookEntry import LabNotebookEntry
+    from LOGS.Entities.LabNotebookExperiment import LabNotebookExperiment
+    from LOGS.Entities.LabNotebookTemplate import LabNotebookTemplate
+    from LOGS.Entities.Method import Method
+    from LOGS.Entities.Origin import Origin
+    from LOGS.Entities.Person import Person
+    from LOGS.Entities.Project import Project
+    from LOGS.Entities.Role import Role
+    from LOGS.Entities.Sample import Sample
+    from LOGS.Entities.Vendor import Vendor
+
+
+class Constants:
+    _control_character = {
+        "0": ("\u0000", "null"),
+        "1": ("\u0001", "start of heading"),
+        "2": ("\u0002", "start of text"),
+        "3": ("\u0003", "end of text"),
+        "4": ("\u0004", "end of transmission"),
+        "5": ("\u0005", "enquiry"),
+        "6": ("\u0006", "acknowledge"),
+        "7": ("\u0007", "bell"),
+        "8": ("\u0008", "backspace"),
+        "9": ("\u0009", "horizontal tabulation"),
+        "a": ("\u000a", "line feed"),
+        "b": ("\u000b", "vertical tabulation"),
+        "c": ("\u000c", "form feed"),
+        "d": ("\u000d", "carriage return"),
+        "e": ("\u000e", "shift out"),
+        "f": ("\u000f", "shift in"),
+        "10": ("\u0010", "data link escape"),
+        "11": ("\u0011", "device control one"),
+        "12": ("\u0012", "device control two"),
+        "13": ("\u0013", "device control three"),
+        "14": ("\u0014", "device control four"),
+        "15": ("\u0015", "negative acknowledge"),
+        "16": ("\u0016", "synchronous idle"),
+        "17": ("\u0017", "end of transmission block"),
+        "18": ("\u0018", "cancel"),
+        "19": ("\u0019", "end of medium"),
+        "1a": ("\u001a", "substitute"),
+        "1b": ("\u001b", "escape"),
+        "1c": ("\u001c", "file separator"),
+        "1d": ("\u001d", "group separator"),
+        "1e": ("\u001e", "record separator"),
+        "1f": ("\u001f", "unit separator"),
+    }
+
+    byteUnits = ["", "K", "M", "G", "T", "P", "E", "Z"]
+
+    exceptionIndentation = " " * 2
+
+    # Typing aliases constants
+    ID_TYPE = Union[int, str]
+
+    FILE_TYPE = Union[str, os.DirEntry, "FileEntry"]
+
+    TYPED_ENTITIES = Union[
+        "Sample", "Dataset", "InventoryItem", "DatasetTemplate", "Person", "Project"
+    ]
+
+    ENTITIES = Union[
+        "Bridge",
+        "CustomField",
+        "CustomType",
+        "Dataset",
+        "DataSource",
+        "InventoryItem",
+        "LabNotebook",
+        "LabNotebookEntry",
+        "LabNotebookExperiment",
+        "LabNotebookTemplate",
+        "Origin",
+        "Person",
+        "Project",
+        "Sample",
+        "DataFormat",
+        "Role",
+        "Vendor",
+        "DataFormatInstrument",
+        "Method",
+        "Attachment",
+    ]

LOGS/Auxiliary/CustomEntityClassGenerator.py

@@ -0,0 +1,254 @@
+import base64
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Generic,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+)
+
+from LOGS.Auxiliary.CheckClassName import CheckClassName
+from LOGS.Auxiliary.Constants import Constants
+from LOGS.Auxiliary.Exceptions import TypedEntityNotConnectedException
+from LOGS.Auxiliary.Tools import Tools
+from LOGS.Entities.CustomFieldModels import CustomTypeEntityTypeMapper
+from LOGS.Entity import Entity
+from LOGS.Interfaces.ITypedEntity import ITypedEntity
+
+if TYPE_CHECKING:
+    from LOGS.Entities.CustomType import CustomType
+    from LOGS.LOGSConnection import LOGSConnection
+
+
+_T = TypeVar("_T", bound=Constants.TYPED_ENTITIES)
+
+
+class CustomEntityClassGenerator(Generic[_T]):
+
+    _customTypeCache: Dict[str, "CustomType"] = {}
+    _classCache: Dict[str, Type[_T]] = {}
+
+    @classmethod
+    def generate(
+        cls,
+        customType: Optional["CustomType"],
+        connection: "LOGSConnection",
+        fieldName: Optional[str] = None,
+        limitToEntityType: Optional[Type[_T]] = None,
+    ) -> Type[_T]:
+        if customType is None:
+            if not limitToEntityType:
+                raise ValueError(
+                    "When 'customType' is None, 'limitToEntityType' must be provided."
+                )
+
+            if not isinstance(limitToEntityType, type) or not issubclass(
+                limitToEntityType, Entity
+            ):
+                raise ValueError("'limitToEntityType' must be an entity class.")
+
+            return limitToEntityType
+        else:
+            if not customType or not customType.id:
+                raise ValueError(f"Custom type is missing for field '{fieldName}'.")
+
+            cacheId = cls._getCacheKey(customType.id, connection)
+            if cacheId in cls._classCache:
+                return cls._classCache[cacheId]
+
+            if not customType.entityType:
+                raise ValueError(
+                    f"Custom type '{customType.name}' (ID: {customType.id}) has no entity type defined."
+                )
+
+            entityType = CustomTypeEntityTypeMapper.getClass(customType.entityType)
+
+            if limitToEntityType and limitToEntityType != entityType:
+                raise Exception(
+                    f"The custom type '{customType.name}' is not valid for entity type '{limitToEntityType.__name__}'. (Expected entity type '{entityType.__name__}')"
+                )
+
+            name = (
+                entityType.__name__
+                + "_"
+                + (
+                    CheckClassName.sanitizeClassName(customType.name)
+                    if customType.name
+                    else f"CustomType_ID{customType.id}"
+                )
+            )
+
+            doc = f"This class represents a LOGS {entityType.__name__} of custom type '{customType.name}' (TypeID: {customType.id})"
+
+            module = ".".join(
+                entityType.__module__.split(".")[:-1]
+                + [f"Custom{Tools.wordToPlural(entityType.__name__)}"],
+            )
+
+        def __init__(
+            self,
+            ref=None,
+            id: Optional[int] = None,
+            connection: Optional["LOGSConnection"] = connection,
+            *args,
+            **kwargs,
+        ):
+            cast(Any, type(self).__bases__[0]).__init__(
+                self,
+                ref=ref,
+                id=id,
+                connection=connection,
+                *args,
+                **kwargs,
+            )
+
+        typeDict = {
+            "__init__": __init__,
+            "__module__": module,
+            "__doc__": doc,
+            "_customType": customType,
+            "_baseType": entityType,
+        }
+
+        newClass = cast(
+            Type[_T],
+            type(
+                name,
+                (entityType,),
+                typeDict,
+            ),
+        )
+
+        return newClass
+
+    @classmethod
+    def _getCacheKey(
+        cls,
+        customTypeOrId: int,
+        connection: "LOGSConnection",
+    ) -> str:
+        url = connection.getEndpointUrl(
+            ["custom_type_entities"] + [str(customTypeOrId)],
+        )
+        return base64.b64encode(url.encode()).decode()
+
+    @classmethod
+    def fetchCustomType(
+        cls, customTypeOrId: Union["CustomType", int], connection: "LOGSConnection"
+    ):
+        from LOGS.Entities.CustomType import CustomType
+
+        if isinstance(customTypeOrId, CustomType):
+            return customTypeOrId
+
+        if isinstance(customTypeOrId, int):
+            cacheId = cls._getCacheKey(customTypeOrId, connection)
+            if cacheId in cls._customTypeCache:
+                return cls._customTypeCache[cacheId]
+
+            customType = CustomType(id=customTypeOrId, connection=connection)
+            customType.fetch()
+
+            cls._customTypeCache[cacheId] = customType
+            return customType
+
+        raise ValueError(
+            f"Parameter '{customTypeOrId}' must be either a {CustomType.__name__} instance or an integer ID."
+        )
+
+    @classmethod
+    def convert(
+        cls,
+        value: Any,
+        customTypeOrId: Union["CustomType", int],
+        connection: "LOGSConnection",
+        fieldName: Optional[str] = None,
+        limitToEntityType: Optional[Type[_T]] = None,
+    ) -> _T:
+
+        if isinstance(value, Entity):
+            return cast(_T, value)
+
+        customType = cls.fetchCustomType(customTypeOrId, connection)
+
+        c = cls.generate(customType, connection, fieldName, limitToEntityType)
+        try:
+            return c(value)
+        except Exception as e:
+            raise ValueError(
+                f"Field '{fieldName}' cannot be converted to '{c.__name__}': {str(e)}"
+            ) from e
+
+    @classmethod
+    def convertToUntyped(cls, entity: _T, fieldName: Optional[str] = None) -> _T:
+        if not isinstance(entity, ITypedEntity) or not entity._baseType:
+            return entity
+
+        if not entity._connection:
+            raise TypedEntityNotConnectedException(entity)
+
+        customType = entity.customType
+        customValues = entity.customValues
+
+        entity._customType = None
+        entity._customValues = None
+
+        c = cls.generate(
+            None,
+            connection=entity._connection,
+            fieldName=fieldName,
+            limitToEntityType=cast(_T, entity._baseType),
+        )(entity, connection=entity._getConnection())
+
+        entity._customType = customType
+        entity._customValues = customValues
+
+        c._untypedCustomType = customType.toDict() if customType else None
+        c._untypedValues = cast(Any, customValues.toDict()) if customValues else None
+        return c
+
+    @classmethod
+    def convertFromUntyped(
+        cls,
+        entity: _T,
+        fieldName: Optional[str] = None,
+        limitToEntityType: Optional[Type[_T]] = None,
+    ) -> _T:
+        if not isinstance(entity, ITypedEntity) or not entity._untypedCustomType:
+            return entity
+
+        if (
+            not isinstance(entity._untypedCustomType, dict)
+            or "id" not in entity._untypedCustomType
+        ):
+            raise Exception(f"Custom type of {entity.identifier} is invalid.")
+
+        if not entity._connection:
+            raise TypedEntityNotConnectedException(entity)
+
+        customTypeId = entity._untypedCustomType["id"]
+        entity._untypedCustomType = None
+        values = entity._untypedValues
+        entity._untypedValues = None
+
+        customType = cls.fetchCustomType(customTypeId, entity._connection)
+
+        c = cls.generate(
+            customType,
+            connection=entity._connection,
+            fieldName=fieldName,
+            limitToEntityType=limitToEntityType,
+        )
+
+        try:
+            e = c(entity, connection=entity._getConnection())
+        except Exception as e:
+            raise ValueError(
+                f"Field '{fieldName}' cannot be converted to '{c.__name__}': {str(e)}"
+            ) from e
+        e.customValues = values
+        return e

LOGS/Auxiliary/CustomFieldClassGenerator.py

@@ -0,0 +1,115 @@
+from base64 import b64encode
+from typing import TYPE_CHECKING, Any, Dict, Optional, Type, cast
+
+from LOGS.Auxiliary.CheckClassName import CheckClassName
+from LOGS.Auxiliary.Constants import Constants
+from LOGS.Auxiliary.Exceptions import EntityFetchingException
+
+if TYPE_CHECKING:
+    from LOGS.Interfaces.ICustomFieldValue import ICustomFieldValue
+    from LOGS.LOGSConnection import LOGSConnection
+
+
+class CustomFieldClassGenerator:
+
+    _classCache: Dict[str, Type["ICustomFieldValue"]] = {}
+
+    @classmethod
+    def _getCacheKey(cls, customTypeField: int, connection: "LOGSConnection") -> str:
+        url = connection.getEndpointUrl(["custom_type_fields", customTypeField])
+        return b64encode(url.encode()).decode()
+
+    @classmethod
+    def generate(
+        cls,
+        customFieldId: int,
+        connection: "LOGSConnection",
+        fieldName: Optional[str] = None,
+    ) -> Type["ICustomFieldValue"]:
+        from LOGS.Entities.CustomField import CustomField
+        from LOGS.Interfaces.ICustomFieldValue import ICustomFieldValue
+
+        cacheId = cls._getCacheKey(customFieldId, connection)
+        if cacheId in cls._classCache:
+            return cls._classCache[cacheId]
+
+        customField = CustomField(id=customFieldId, connection=connection)
+        try:
+            customField.fetch()
+        except EntityFetchingException as e:
+            raise ValueError(
+                f"Custom field with ID {customFieldId} specified in '{fieldName}' not found:"
+                + f"\n{Constants.exceptionIndentation}{str(e)}"
+            )
+
+        if cacheId in cls._classCache:
+            return cls._classCache[cacheId]
+
+        name = (
+            CheckClassName.sanitizeClassName(customField.name)
+            if customField.name
+            else f"CustomField_ID{customField.id}"
+        )
+
+        def __init__(self, ref=None):
+            cast(Any, type(self).__bases__[0]).__init__(self, ref, customField.dataType)
+
+        doc = (
+            f"This class represents the value of the LOGS custom field '{customField.name}' (ID: {customField.id})"
+            + ("\n" + customField.description if customField.description else "")
+        )
+
+        module = ".".join(
+            ICustomFieldValue.__module__.split(".")[:-1]
+            + ["GeneratedCustomFieldValues"],
+        )
+
+        newClass: Type[ICustomFieldValue] = type(
+            name,
+            (ICustomFieldValue,),
+            {
+                "__init__": __init__,
+                "_dataType": customField.dataType,
+                "__module__": module,
+                "__doc__": doc,
+                "_name": customField.name,
+                "_id": customField.id,
+                "_connection": connection,
+                "_value": (
+                    customField.defaultValues
+                    if customField.defaultValues is not None
+                    else None
+                ),
+            },
+        )
+        cls._classCache[cacheId] = newClass
+
+        return newClass
+
+    @classmethod
+    def convert(
+        cls,
+        value: Any,
+        customFieldId: int,
+        connection: "LOGSConnection",
+        fieldName: Optional[str] = None,
+    ) -> Optional["ICustomFieldValue"]:
+        from LOGS.Interfaces.ICustomFieldValue import ICustomFieldValue
+
+        if isinstance(value, ICustomFieldValue):
+            return value
+
+        if not isinstance(value, dict):
+            raise ValueError(
+                f"Field '{fieldName}' cannot be converted from value of type '{type(value).__name__}'."
+            )
+
+        c = cls.generate(
+            customFieldId=customFieldId, fieldName=fieldName, connection=connection
+        )
+        try:
+            return c(value)
+        except Exception as e:
+            raise ValueError(
+                f"Field '{fieldName}' cannot be converted to '{c.__name__}': {str(e)}"
+            ) from e

LOGS/Auxiliary/CustomFieldValueTypeChecker.py

@@ -0,0 +1,168 @@
+from datetime import date, datetime, time, timedelta
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Union
+
+from LOGS.Auxiliary.MinimalModelGenerator import MinimalModelGenerator
+from LOGS.Auxiliary.Tools import Tools
+from LOGS.Converter.DateTimeRange import DateTimeRange
+from LOGS.Entities.CustomFieldModels import CustomFieldDataType
+
+if TYPE_CHECKING:
+    from LOGS.LOGSConnection import LOGSConnection
+
+
+class CustomFieldValueTypeChecker:
+
+    _customFieldTypeMap: Dict[CustomFieldDataType, Union[type, str, Callable]] = {
+        CustomFieldDataType.String: str,
+        CustomFieldDataType.StringArray: str,
+        CustomFieldDataType.Integer: int,
+        CustomFieldDataType.IntegerArray: int,
+        CustomFieldDataType.Float: float,
+        CustomFieldDataType.FloatArray: float,
+        CustomFieldDataType.Boolean: bool,
+        CustomFieldDataType.Date: date,
+        CustomFieldDataType.DateArray: date,
+        CustomFieldDataType.DateTime: datetime,
+        CustomFieldDataType.DateTimeArray: datetime,
+        CustomFieldDataType.Time: time,
+        CustomFieldDataType.TimeArray: time,
+        CustomFieldDataType.DateTimeRange: DateTimeRange,
+        CustomFieldDataType.TimeRange: lambda value: (
+            timedelta(seconds=value) if isinstance(value, (int, float)) else value
+        ),
+        CustomFieldDataType.Dataset: "DatasetMinimal",
+        CustomFieldDataType.DatasetArray: "DatasetMinimal",
+        CustomFieldDataType.Sample: "SampleMinimal",
+        CustomFieldDataType.SampleArray: "SampleMinimal",
+        CustomFieldDataType.Project: "ProjectMinimal",
+        CustomFieldDataType.ProjectArray: "ProjectMinimal",
+        CustomFieldDataType.Person: "PersonMinimal",
+        CustomFieldDataType.PersonArray: "PersonMinimal",
+        CustomFieldDataType.Method: "MethodMinimal",
+        CustomFieldDataType.MethodArray: "MethodMinimal",
+        CustomFieldDataType.SharedContent: "SharedContentMinimal",
+        CustomFieldDataType.SharedContentArray: "SharedContentMinimal",
+        CustomFieldDataType.LabNotebook: "LabNotebookMinimal",
+        CustomFieldDataType.LabNotebookArray: "LabNotebookMinimal",
+        CustomFieldDataType.LabNotebookExperiment: "LabNotebookExperimentMinimal",
+        CustomFieldDataType.LabNotebookExperimentArray: "LabNotebookExperimentMinimal",
+        CustomFieldDataType.LabNotebookEntry: "LabNotebookEntryMinimal",
+        CustomFieldDataType.LabNotebookEntryArray: "LabNotebookEntryMinimal",
+        CustomFieldDataType.Attachment: "AttachmentMinimal",
+        CustomFieldDataType.InventoryItem: "InventoryItemMinimal",
+        CustomFieldDataType.InventoryItemArray: "InventoryItemMinimal",
+        CustomFieldDataType.Barcode: str,
+        CustomFieldDataType.Url: str,
+        CustomFieldDataType.UrlArray: str,
+    }
+
+    _converter: Callable[[Any, str], Any]
+    _isArrayType: bool
+    _enumOptions: Any = None
+
+    @classmethod
+    def _arrayTypeCheck(cls, data_type: CustomFieldDataType) -> bool:
+        return data_type.name.endswith("Array")
+
+    @classmethod
+    def _generateConverter(
+        cls,
+        dataType: CustomFieldDataType,
+        isArrayType: bool,
+        connection: Optional["LOGSConnection"],
+    ) -> Callable[[Any, str], Any]:
+        dataClass = cls._customFieldTypeMap.get(dataType, None)
+
+        if dataClass is None:
+            raise ValueError(f"Unknown custom field type: '{dataType}'")
+
+        if isinstance(dataClass, str):
+            if isArrayType:
+                return lambda value, fieldName: MinimalModelGenerator.MinimalFromList(
+                    value, dataClass, fieldName, connection
+                )
+            else:
+                return lambda value, fieldName: MinimalModelGenerator.MinimalFromSingle(
+                    value, dataClass, fieldName, connection
+                )
+        elif isinstance(dataClass, type):
+            if isArrayType:
+                return lambda value, fieldName: Tools.checkListAndConvert(
+                    value, dataClass, fieldName, allowNone=True
+                )
+            else:
+                return lambda value, fieldName: Tools.checkAndConvert(
+                    value, dataClass, f"{fieldName} <{dataType.name}>", allowNone=True
+                )
+        elif callable(dataClass):
+            if isArrayType:
+                return lambda value, fieldName: Tools.checkListAndConvert(
+                    value, dataType.name, fieldName, dataClass, allowNone=True
+                )
+            else:
+                return lambda value, fieldName: Tools.checkAndConvert(
+                    value, dataType.name, fieldName, dataClass, allowNone=True
+                )
+        else:
+            raise ValueError(f"Cannot create converter for type '{dataType}'")
+
+    def __str__(self):
+        s = " array" if self._isArrayType else ""
+        return f"<{type(self).__name__} [{self.dataType.name}]{s}>"
+
+    def __init__(
+        self,
+        dataType: CustomFieldDataType,
+        connection: Optional["LOGSConnection"],
+        enumOptions: Any = None,
+    ):
+        Tools.checkAndConvert(
+            dataType, CustomFieldDataType, "dataType", allowNone=False
+        )
+
+        self.dataType = dataType
+        self._isArrayType = self._arrayTypeCheck(dataType)
+        self._converter = self._generateConverter(
+            dataType, self._isArrayType, connection
+        )
+        self.enumOptions = enumOptions
+
+    def checkAndConvertIgnoreEnumOptions(self, value: Any, fieldName: str = "value"):
+        if not self._isArrayType and isinstance(value, list):
+            return [
+                self._converter(v, f"{fieldName}[{i}]") for i, v in enumerate(value)
+            ]
+        return self._converter(value, fieldName)
+
+    def checkAndConvert(self, value: Any, fieldName: str = "value", allowNone=True):
+        if allowNone and value is None:
+            return None
+        result = self._converter(value, fieldName)
+        if self._isArrayType:
+            if self._enumOptions:
+                for i, v in enumerate(result):
+                    if v not in self._enumOptions:
+                        raise ValueError(
+                            f"Value of field '{fieldName}[{i}]' must be out of enumOptions. (Value '{Tools.truncString(str(v))}' is not accepted)"
+                        )
+        else:
+            if self._enumOptions and result not in self._enumOptions:
+                raise ValueError(
+                    f"Value of field '{fieldName}' must be out of enumOptions. (Value '{Tools.truncString(str(result))}' is not accepted)"
+                )
+
+        return result
+
+    @property
+    def enumOptions(self) -> Any:
+        return self._enumOptions
+
+    @enumOptions.setter
+    def enumOptions(self, value: Any):
+        if not value:
+            self._enumOptions = None
+            return
+
+        self._enumOptions = Tools.checkAndConvert(
+            value, list, "enumOptions", allowNone=False
+        )