docs: Add docstrings

Author: onefloid

TM1py/Exceptions/Exceptions.py

@@ -3,9 +3,15 @@
 # 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
@@ -15,7 +21,14 @@ def __str__(self):
 
 
 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
@@ -29,7 +42,13 @@ def __str__(self):
 
 
 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
 
@@ -38,70 +57,103 @@ def __str__(self):
 
 
 class TM1pyNotAdminException(Exception):
+    """Exception for missing admin permissions."""
+
     def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
         self.function = function
 
     def __str__(self):
         return f"Function '{self.function}' requires admin permissions"
 
 
 class TM1pyNotDataAdminException(Exception):
+    """Exception for missing DataAdmin permissions."""
+
     def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
         self.function = function
 
     def __str__(self):
         return f"Function '{self.function}' requires DataAdmin permissions"
 
 
 class TM1pyNotSecurityAdminException(Exception):
+    """Exception for missing SecurityAdmin permissions."""
+
     def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
         self.function = function
 
     def __str__(self):
         return f"Function '{self.function}' requires SecurityAdmin permissions"
 
 
 class TM1pyNotOpsAdminException(Exception):
+    """Exception for missing OperationsAdmin permissions."""
+
     def __init__(self, function: str):
+        """
+        :param function: Name of the function
+        """
         self.function = function
 
     def __str__(self):
         return f"Function '{self.function}' requires OperationsAdmin permissions"
 
 
 class TM1pyException(Exception):
-    """The default exception for TM1py"""
+    """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"""
+    """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):
@@ -111,8 +163,13 @@ def __str__(self):
 
 
 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
 
@@ -121,8 +178,14 @@ def __init__(self, statuses: List[str], error_log_files: List[str]):
 
 
 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
@@ -131,4 +194,4 @@ def __init__(self, statuses: List[str], error_log_files: List[str], attempts: in
             f"{len(self.statuses)} out of {self.attempts} write operations failed partially. "
             f"Details: {self.error_log_files}"
         )
-        super(TM1pyWritePartialFailureException, self).__init__(message)
+        super(TM1pyWritePartialFailureException, self).__init__(message)

TM1py/Objects/Annotation.py

@@ -29,6 +29,20 @@ def __init__(
         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
@@ -45,7 +59,7 @@ def from_json(cls, annotation_as_json: str) -> "Annotation":
         """Alternative constructor
 
         :param annotation_as_json: String, JSON
-        :return: instance of TM1py.Process
+        :return: instance of Annotation
         """
         annotation_as_dict = json.loads(annotation_as_json)
         annotation_id = annotation_as_dict["ID"]
@@ -73,66 +87,123 @@ def from_json(cls, annotation_as_json: str) -> "Annotation":
 
     @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
+        """
+        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
-        :return:
+        :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 represenation for the Annotation entity.
+        """
+        Construct the ODATA conform JSON representation for the Annotation entity.
 
-        :return: string, the valid JSON
+        :return: Dictionary, the valid JSON.
         """
         dimensional_context = [{"Name": element} for element in self._dimensional_context]
         body = collections.OrderedDict()
@@ -151,6 +222,12 @@ def _construct_body(self) -> Dict:
         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"] = [
@@ -167,4 +244,4 @@ def construct_body_for_post(self, cube_dimensions) -> Dict:
         body["commentType"] = "ANNOTATION"
         body["commentLocation"] = ",".join(self.dimensional_context)
 
-        return body
+        return body

TM1py/Services/ApplicationService.py

@@ -34,7 +34,12 @@ def __init__(self, tm1_rest: RestService):
         self._rest = tm1_rest
 
     def get_all_public_root_names(self, **kwargs):
+        """
+        Retrieve all public root application names.
 
+        :param kwargs: Additional arguments for the REST request.
+        :return: List of public root application names.
+        """
         url = "/Contents('Applications')/Contents"
         response = self._rest.GET(url, **kwargs)
         applications = list(application["Name"] for application in response.json()["value"])