TM1py 2.2.1__py3-none-any.whl

TM1py/Exceptions/Exceptions.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+
+# TM1py Exceptions are defined here
+from typing import List, Mapping
+
+
+class TM1pyTimeout(Exception):
+    """Exception for timeout during a REST request."""
+
+    def __init__(self, method: str, url: str, timeout: float):
+        """
+        :param method: HTTP method used
+        :param url: URL of the request
+        :param timeout: Timeout in seconds
+        """
+        self.method = method
+        self.url = url
+        self.timeout = timeout
+
+    def __str__(self):
+        return f"Timeout after {self.timeout} seconds for '{self.method}' request with url :'{self.url}'"
+
+
+class TM1pyVersionException(Exception):
+    """Exception for usage of a feature requiring a higher TM1 server version."""
+
+    def __init__(self, function: str, required_version, feature: str = None):
+        """
+        :param function: Name of the function
+        :param required_version: Required TM1 server version
+        :param feature: Optional feature name
+        """
+        self.function = function
+        self.required_version = required_version
+        self.feature = feature
+
+    def __str__(self):
+        require_string = f"requires TM1 server version >= '{self.required_version}'"
+        if self.feature:
+            return f"'{self.feature}' feature of function '{self.function}' {require_string}"
+        else:
+            return f"Function '{self.function}' {require_string}"
+
+
+class TM1pyVersionDeprecationException(Exception):
+    """Exception for usage of a deprecated feature."""
+
+    def __init__(self, function: str, deprecated_in_version):
+        """
+        :param function: Name of the function
+        :param deprecated_in_version: Version in which the function was deprecated
+        """
+        self.function = function
+        self.deprecated_in_version = deprecated_in_version
+
+    def __str__(self):
+        return f"Function '{self.function}' has been deprecated in TM1 server version >= '{self.deprecated_in_version}'"
+
+
+class TM1pyPermissionException(Exception):
+    """Exception for missing permissions."""
+
+    def __init__(self, function: str, required_permission: str):
+        """
+        :param function: Name of the function
+        :param required_permission: Name of the required permission (e.g., 'admin', 'DataAdmin', 'SecurityAdmin', 'OperationsAdmin')
+        """
+        self.function = function
+        self.required_permission = required_permission
+
+    def __str__(self):
+        return f"Function '{self.function}' requires {self.required_permission} permissions"
+
+
+class TM1pyNotAdminException(TM1pyPermissionException):
+    """Exception for missing admin permissions."""
+
+    def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
+        super().__init__(function, "admin")
+
+
+class TM1pyNotDataAdminException(TM1pyPermissionException):
+    """Exception for missing DataAdmin permissions."""
+
+    def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
+        super().__init__(function, "DataAdmin")
+
+
+class TM1pyNotSecurityAdminException(TM1pyPermissionException):
+    """Exception for missing SecurityAdmin permissions."""
+
+    def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
+        super().__init__(function, "SecurityAdmin")
+
+
+class TM1pyNotOpsAdminException(TM1pyPermissionException):
+    """Exception for missing OperationsAdmin permissions."""
+
+    def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
+        super().__init__(function, "OperationsAdmin")
+
+
+class TM1pyException(Exception):
+    """The default exception for TM1py."""
+
+    def __init__(self, message):
+        """
+        :param message: Exception message
+        """
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+
+class TM1pyRestException(TM1pyException):
+    """Exception for failing REST operations."""
+
+    def __init__(self, response: str, status_code: int, reason: str, headers: Mapping):
+        """
+        :param response: Response text
+        :param status_code: HTTP status code
+        :param reason: Reason phrase
+        :param headers: HTTP headers
+        """
+        super(TM1pyRestException, self).__init__(response)
+        self._status_code = status_code
+        self._reason = reason
+        self._headers = headers
+
+    @property
+    def status_code(self):
+        """HTTP status code."""
+        return self._status_code
+
+    @property
+    def reason(self):
+        """Reason phrase."""
+        return self._reason
+
+    @property
+    def response(self):
+        """Response text."""
+        return self.message
+
+    @property
+    def headers(self):
+        """HTTP headers."""
+        return self._headers
+
+    def __str__(self):
+        return "Text: '{}' - Status Code: {} - Reason: '{}' - Headers: {}".format(
+            self.message, self._status_code, self._reason, self._headers
+        )
+
+
+class TM1pyWriteFailureException(TM1pyException):
+    """Exception for complete failure of write operations."""
+
+    def __init__(self, statuses: List[str], error_log_files: List[str]):
+        """
+        :param statuses: List of failed statuses
+        :param error_log_files: List of error log file paths
+        """
+        self.statuses = statuses
+        self.error_log_files = error_log_files
+
+        message = f"All {len(self.statuses)} write operations failed. Details: {self.error_log_files}"
+        super(TM1pyWriteFailureException, self).__init__(message)
+
+
+class TM1pyWritePartialFailureException(TM1pyException):
+    """Exception for partial failure of write operations."""
+
+    def __init__(self, statuses: List[str], error_log_files: List[str], attempts: int):
+        """
+        :param statuses: List of failed statuses
+        :param error_log_files: List of error log file paths
+        :param attempts: Total number of attempts
+        """
+        self.statuses = statuses
+        self.error_log_files = error_log_files
+        self.attempts = attempts
+
+        message = (
+            f"{len(self.statuses)} out of {self.attempts} write operations failed partially. "
+            f"Details: {self.error_log_files}"
+        )
+        super(TM1pyWritePartialFailureException, self).__init__(message)

TM1py/Exceptions/__init__.py

@@ -0,0 +1,10 @@
+# ruff: noqa: F401
+from TM1py.Exceptions.Exceptions import (
+    TM1pyException,
+    TM1pyNotAdminException,
+    TM1pyRestException,
+    TM1pyTimeout,
+    TM1pyVersionException,
+    TM1pyWriteFailureException,
+    TM1pyWritePartialFailureException,
+)

TM1py/Objects/Annotation.py

@@ -0,0 +1,247 @@
+# -*- coding: utf-8 -*-
+
+import collections
+import json
+from typing import Dict, Iterable, List
+
+from TM1py.Objects.TM1Object import TM1Object
+from TM1py.Utils import format_url
+
+
+class Annotation(TM1Object):
+    """Abtraction of TM1 Annotation
+
+    :Notes:
+        - Class complete, functional and tested.
+        - doesn't cover Attachments though
+    """
+
+    def __init__(
+        self,
+        comment_value: str,
+        object_name: str,
+        dimensional_context: Iterable[str],
+        comment_type: str = "ANNOTATION",
+        annotation_id: str = None,
+        text: str = "",
+        creator: str = None,
+        created: str = None,
+        last_updated_by: str = None,
+        last_updated: str = None,
+    ):
+        """
+        Initialize an Annotation object.
+
+        :param comment_value: The value of the annotation comment.
+        :param object_name: Name of the TM1 object the annotation is attached to.
+        :param dimensional_context: Iterable of dimension elements providing context.
+        :param comment_type: Type of the comment (default "ANNOTATION").
+        :param annotation_id: Unique ID of the annotation.
+        :param text: Text of the annotation.
+        :param creator: Creator of the annotation.
+        :param created: Creation timestamp.
+        :param last_updated_by: Last user who updated the annotation.
+        :param last_updated: Last update timestamp.
+        """
+        self._id = annotation_id
+        self._text = text
+        self._creator = creator
+        self._created = created
+        self._last_updated_by = last_updated_by
+        self._last_updated = last_updated
+        self._dimensional_context = list(dimensional_context)
+        self._comment_type = comment_type
+        self._comment_value = comment_value
+        self._object_name = object_name
+
+    @classmethod
+    def from_json(cls, annotation_as_json: str) -> "Annotation":
+        """Alternative constructor
+
+        :param annotation_as_json: String, JSON
+        :return: instance of Annotation
+        """
+        annotation_as_dict = json.loads(annotation_as_json)
+        annotation_id = annotation_as_dict["ID"]
+        text = annotation_as_dict["Text"]
+        creator = annotation_as_dict["Creator"]
+        created = annotation_as_dict["Created"]
+        last_updated_by = annotation_as_dict["LastUpdatedBy"]
+        last_updated = annotation_as_dict["LastUpdated"]
+        dimensional_context = [item["Name"] for item in annotation_as_dict["DimensionalContext"]]
+        comment_type = annotation_as_dict["commentType"]
+        comment_value = annotation_as_dict["commentValue"]
+        object_name = annotation_as_dict["objectName"]
+        return cls(
+            comment_value=comment_value,
+            object_name=object_name,
+            dimensional_context=dimensional_context,
+            comment_type=comment_type,
+            annotation_id=annotation_id,
+            text=text,
+            creator=creator,
+            created=created,
+            last_updated_by=last_updated_by,
+            last_updated=last_updated,
+        )
+
+    @property
+    def body(self) -> str:
+        """
+        Get the annotation body as a JSON string.
+
+        :return: JSON string representation of the annotation.
+        """
+        return json.dumps(self._construct_body())
+
+    @property
+    def body_as_dict(self) -> Dict:
+        """
+        Get the annotation body as a dictionary.
+
+        :return: Dictionary representation of the annotation.
+        """
+        return self._construct_body()
+
+    @property
+    def comment_value(self) -> str:
+        """
+        Get the comment value.
+
+        :return: The comment value string.
+        """
+        return self._comment_value
+
+    @property
+    def text(self) -> str:
+        """
+        Get the annotation text.
+
+        :return: The annotation text.
+        """
+        return self._text
+
+    @property
+    def dimensional_context(self) -> List[str]:
+        """
+        Get the dimensional context.
+
+        :return: List of dimension elements providing context.
+        """
+        return self._dimensional_context
+
+    @property
+    def created(self) -> str:
+        """
+        Get the creation timestamp.
+
+        :return: Creation timestamp as string.
+        """
+        return self._created
+
+    @property
+    def object_name(self) -> str:
+        """
+        Get the object name.
+
+        :return: Name of the TM1 object.
+        """
+        return self._object_name
+
+    @property
+    def last_updated(self) -> str:
+        """
+        Get the last updated timestamp.
+
+        :return: Last update timestamp as string.
+        """
+        return self._last_updated
+
+    @property
+    def last_updated_by(self) -> str:
+        """
+        Get the last user who updated the annotation.
+
+        :return: Username of last updater.
+        """
+        return self._last_updated_by
+
+    @comment_value.setter
+    def comment_value(self, value: str):
+        """
+        Set the comment value.
+
+        :param value: New comment value.
+        """
+        self._comment_value = value
+
+    @property
+    def id(self) -> str:
+        """
+        Get the annotation ID.
+
+        :return: Annotation ID string.
+        """
+        return self._id
+
+    def move(self, dimension_order: Iterable[str], dimension: str, target_element: str, source_element: str = None):
+        """
+        Move annotation on given dimension from source_element to target_element.
+
+        :param dimension_order: List, order of the dimensions in the cube.
+        :param dimension: Dimension name.
+        :param target_element: Target element name.
+        :param source_element: Source element name (optional).
+        :return: None
+        """
+        for i, dimension_name in enumerate(dimension_order):
+            if dimension_name.lower() == dimension.lower():
+                if not source_element or self._dimensional_context[i] == source_element:
+                    self._dimensional_context[i] = target_element
+
+    def _construct_body(self) -> Dict:
+        """
+        Construct the ODATA conform JSON representation for the Annotation entity.
+
+        :return: Dictionary, the valid JSON.
+        """
+        dimensional_context = [{"Name": element} for element in self._dimensional_context]
+        body = collections.OrderedDict()
+        body["ID"] = self._id
+        body["Text"] = self._text
+        body["Creator"] = self._creator
+        body["Created"] = self._created
+        body["LastUpdatedBy"] = self._last_updated_by
+        body["LastUpdated"] = self._last_updated
+        body["DimensionalContext"] = dimensional_context
+        comment_locations = ",".join(self._dimensional_context)
+        body["commentLocation"] = comment_locations[1:]
+        body["commentType"] = self._comment_type
+        body["commentValue"] = self._comment_value
+        body["objectName"] = self._object_name
+        return body
+
+    def construct_body_for_post(self, cube_dimensions) -> Dict:
+        """
+        Construct the body for POST requests to create an annotation.
+
+        :param cube_dimensions: List of cube dimension names.
+        :return: Dictionary for POST request body.
+        """
+        body = collections.OrderedDict()
+        body["Text"] = self.text
+        body["ApplicationContext"] = [
+            {"Facet@odata.bind": "ApplicationContextFacets('}Cubes')", "Value": self.object_name}
+        ]
+        body["DimensionalContext@odata.bind"] = []
+
+        for dimension, element in zip(cube_dimensions, self.dimensional_context):
+            coordinates = format_url("Dimensions('{}')/Hierarchies('{}')/Members('{}')", dimension, dimension, element)
+            body["DimensionalContext@odata.bind"].append(coordinates)
+
+        body["objectName"] = self.object_name
+        body["commentValue"] = self.comment_value
+        body["commentType"] = "ANNOTATION"
+        body["commentLocation"] = ",".join(self.dimensional_context)
+
+        return body

TM1py/Objects/Application.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+import json
+import warnings
+from collections import OrderedDict, namedtuple
+from enum import Enum
+from typing import Dict, Union
+
+from TM1py.Objects.TM1Object import TM1Object
+from TM1py.Utils import format_url
+
+ApplicationType = namedtuple("ApplicationType", ["value", "suffix", "odata_type"])
+
+
+class ApplicationTypes(Enum):
+    CHORE = ApplicationType(1, ".chore", "tm1.ChoreReference")
+    CUBE = ApplicationType(2, ".cube", "tm1.CubeReference")
+    DIMENSION = ApplicationType(3, ".dimension", "tm1.DimensionReference")
+    DOCUMENT = ApplicationType(4, ".blob", "#ibm.tm1.api.v1.Document")
+    FOLDER = ApplicationType(5, "", "#ibm.tm1.api.v1.Folder")
+    LINK = ApplicationType(6, ".extr", "#ibm.tm1.api.v1.Link")
+    PROCESS = ApplicationType(7, ".process", "tm1.ProcessReference")
+    SUBSET = ApplicationType(8, ".subset", "tm1.SubsetReference")
+    VIEW = ApplicationType(9, ".view", "tm1.ViewReference")
+
+    @classmethod
+    def _missing_(cls, value: str) -> ApplicationType:
+        for member in cls:
+            if member.name.lower() == value.lower():
+                return member
+
+    @property
+    def suffix(self) -> str:
+        return self.value.suffix
+
+    @property
+    def odata_type(self) -> str:
+        return self.value.odata_type
+
+
+class Application(TM1Object):
+
+    def __init__(self, path: str, name: str, application_type: Union[ApplicationTypes, str]):
+        self.path = path
+        # remove suffix from name
+        if application_type.suffix and name.endswith(application_type.suffix):
+            self.name = name[: -len(application_type.suffix)]
+        else:
+            self.name = name
+        # raise ValueError if not a valid type
+        self.application_type = ApplicationTypes(application_type)
+
+    @property
+    def application_id(self) -> str:
+        return self.path + self.name + self.application_type.suffix
+
+    @property
+    def body_as_dict(self) -> Dict:
+        body_as_dict = OrderedDict()
+        body_as_dict["@odata.type"] = self.application_type.odata_type
+        body_as_dict["Name"] = self.name
+        return body_as_dict
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        return json.dumps(body_as_dict, ensure_ascii=False)
+
+
+class ChoreApplication(Application):
+    def __init__(self, path: str, name: str, chore_name: str):
+        super().__init__(path, name, ApplicationTypes.CHORE)
+        self.chore_name = chore_name
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        body_as_dict["Chore@odata.bind"] = format_url("Chores('{}')", self.chore_name)
+        return json.dumps(body_as_dict, ensure_ascii=False)
+
+
+class CubeApplication(Application):
+    def __init__(self, path: str, name: str, cube_name: str):
+        super().__init__(path, name, ApplicationTypes.CUBE)
+        self.cube_name = cube_name
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        body_as_dict["Cube@odata.bind"] = format_url("Cubes('{}')", self.cube_name)
+        return json.dumps(body_as_dict, ensure_ascii=False)
+
+
+class DimensionApplication(Application):
+    def __init__(self, path: str, name: str, dimension_name: str):
+        super().__init__(path, name, ApplicationTypes.DIMENSION)
+        self.dimension_name = dimension_name
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        body_as_dict["Dimension@odata.bind"] = format_url("Dimensions('{}')", self.dimension_name)
+        return json.dumps(body_as_dict, ensure_ascii=False)
+
+
+class DocumentApplication(Application):
+    def __init__(
+        self, path: str, name: str, content: bytes, file_id: str = None, file_name: str = None, last_updated: str = None
+    ):
+        super().__init__(path, name, ApplicationTypes.DOCUMENT)
+        self.content = content
+        # below fields only populated for retrieved applications
+        self.file_id = file_id
+        self.file_name = file_name
+        self.last_updated = last_updated
+
+    def to_xlsx(self, path_to_file: str):
+        warnings.warn("Function 'to_xlsx' is deprecated. Use 'to_file' instead", DeprecationWarning, stacklevel=2)
+        return self.to_file(path_to_file=path_to_file)
+
+    def to_file(self, path_to_file: str):
+        """
+
+        :param path_to_file: path to newly to create file including the extension (e.g., xlsx, xlsm)
+        :return:
+        """
+        with open(path_to_file, "wb") as file:
+            file.write(self.content)
+
+
+class FolderApplication(Application):
+    def __init__(self, path: str, name: str):
+        super().__init__(path, name, ApplicationTypes.FOLDER)
+
+
+class LinkApplication(Application):
+    def __init__(self, path: str, name: str, url: str):
+        super().__init__(path, name, ApplicationTypes.LINK)
+        self.url = url
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        body_as_dict["URL"] = self.url
+        return json.dumps(body_as_dict, ensure_ascii=False)
+
+
+class ProcessApplication(Application):
+    def __init__(self, path: str, name: str, process_name: str):
+        super().__init__(path, name, ApplicationTypes.PROCESS)
+        self.process_name = process_name
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        body_as_dict["Process@odata.bind"] = format_url("Processes('{}')", self.process_name)
+        return json.dumps(body_as_dict, ensure_ascii=False)
+
+
+class SubsetApplication(Application):
+    def __init__(self, path: str, name: str, dimension_name: str, hierarchy_name: str, subset_name: str):
+        super().__init__(path, name, ApplicationTypes.SUBSET)
+        self.dimension_name = dimension_name
+        self.hierarchy_name = hierarchy_name
+        self.subset_name = subset_name
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        body_as_dict["Subset@odata.bind"] = format_url(
+            "Dimensions('{}')/Hierarchies('{}')/Subsets('{}')",
+            self.dimension_name,
+            self.hierarchy_name,
+            self.subset_name,
+        )
+        return json.dumps(body_as_dict, ensure_ascii=False)
+
+
+class ViewApplication(Application):
+    def __init__(self, path: str, name: str, cube_name: str, view_name: str):
+        super().__init__(path, name, ApplicationTypes.VIEW)
+        self.cube_name = cube_name
+        self.view_name = view_name
+
+    @property
+    def body(self) -> str:
+        body_as_dict = self.body_as_dict
+        body_as_dict["View@odata.bind"] = format_url("Cubes('{}')/Views('{}')", self.cube_name, self.view_name)
+        return json.dumps(body_as_dict, ensure_ascii=False)