pyxecm 1.5__py3-none-any.whl → 2.0.0__py3-none-any.whl

pyxecm/otpd.py

@@ -1,43 +1,22 @@
-"""
-OTPD Module to implement functions to read / write PowerDocs objects
-
-Class: OTPD
-Methods:
-
-__init__ : class initializer
-config : returns config data set
-credentials: Get credentials (username and password)
-set_credentials: Set new credentials
-hostname: Get the configured PowerDocs hostname
-set_hostname: Set the hostname of PowerDocs
-base_url : Get PowerDocs base URL
-rest_url : Get PowerDocs REST base URL
-
-parse_request_response: Converts the text property of a request
-                        response object to a Python dict in a safe way
-
-authenticate : Authenticates at PowerDocs and retrieve OTCS Ticket.
-
-import_database: imports the PowerDocs database from a zip file
-apply_setting: apply a setting to a PowerDocs tenant
-
-"""
+"""OTPD Module to implement functions to read / write PowerDocs objects."""
 
 __author__ = "Dr. Marc Diefenbruch"
-__copyright__ = "Copyright 2024, OpenText"
+__copyright__ = "Copyright (C) 2024-2025, OpenText"
 __credits__ = ["Kai-Philip Gatzweiler"]
 __maintainer__ = "Dr. Marc Diefenbruch"
 __email__ = "mdiefenb@opentext.com"
 
 import json
 import logging
+import os
+
 import requests
 from requests.auth import HTTPBasicAuth
 from requests_toolbelt.multipart.encoder import MultipartEncoder
 
-logger = logging.getLogger("pyxecm.otpd")
+default_logger = logging.getLogger("pyxecm.otpd")
 
-requestHeaders = {
+request_headers = {
     "accept": "application/json;charset=utf-8",
     "Connection": "keep-alive",
     "Content-Type": "application/json",
@@ -45,7 +24,9 @@ requestHeaders = {
 
 
 class OTPD:
-    """Used to automate stettings in OpenText Extended ECM PowerDocs."""
+    """Class OTPD is used to automate stettings in OpenText Extended ECM PowerDocs."""
+
+    logger: logging.Logger = default_logger
 
     _config = None
     _jsessionid = None
@@ -57,17 +38,31 @@ class OTPD:
         port: int,
         username: str,
         password: str,
-    ):
-        """Initialize the OTPD object
+        logger: logging.Logger = default_logger,
+    ) -> None:
+        """Initialize the OTPD object.
 
         Args:
-            protocol (str): Either http or https.
-            hostname (str): The hostname of the PowerDocs Server Manager to communicate with.
-            port (int): The port number used to talk to the PowerDocs Server Manager.
-            username (str): The admin user name of PowerDocs Server Manager.
-            password (str): The admin password of PowerDocs Server Manager.
+            protocol (str):
+                Either http or https.
+            hostname (str):
+                The hostname of the PowerDocs Server Manager to communicate with.
+            port (int):
+                The port number used to talk to the PowerDocs Server Manager.
+            username (str):
+                The admin user name of PowerDocs Server Manager.
+            password (str):
+                The admin password of PowerDocs Server Manager.
+            logger (logging.logger):
+                The logger object to use. Defaults to "default_logger".
+
         """
 
+        if logger != default_logger:
+            self.logger = logger.getChild("otpd")
+            for logfilter in logger.filters:
+                self.logger.addFilter(logfilter)
+
         otpd_config = {}
 
         if hostname:
@@ -110,82 +105,121 @@ class OTPD:
 
         self._config = otpd_config
 
+    # end method definition
+
     def config(self) -> dict:
-        """Returns the configuration dictionary
+        """Return the configuration dictionary.
 
         Returns:
             dict: Configuration dictionary
+
         """
+
         return self._config
 
+    # end method definition
+
     def credentials(self) -> dict:
-        """Get credentials (username + password)
+        """Get credentials (username + password).
 
         Returns:
             dict: dictionary with username and password
+
         """
         return {
             "username": self.config()["username"],
             "password": self.config()["password"],
         }
 
-    def set_credentials(self, username: str = "admin", password: str = ""):
+    # end method definition
+
+    def set_credentials(self, username: str = "admin", password: str = "") -> None:
         """Set the credentials for PowerDocs for the based on user name and password.
 
         Args:
-            username (str, optional): Username. Defaults to "admin".
-            password (str, optional): Password of the user. Defaults to "".
+            username (str, optional):
+                The username. Defaults to "admin".
+            password (str, optional):
+                The password of the user. Defaults to "".
+
         """
+
         self.config()["username"] = username
         self.config()["password"] = password
 
+    # end method definition
+
     def hostname(self) -> str:
-        """Returns the hostname of PowerDocs (e.g. "otpd")
+        """Return the hostname of PowerDocs (e.g. "otpd").
 
         Returns:
             string: hostname
+
         """
+
         return self.config()["hostname"]
 
-    def set_hostname(self, hostname: str):
-        """Sets the hostname of PowerDocs
+    # end method definition
+
+    def set_hostname(self, hostname: str) -> None:
+        """Set the hostname of PowerDocs.
 
         Args:
-            hostname (str): new hostname
+            hostname (str):
+                The new hostname.
+
         """
+
         self.config()["hostname"] = hostname
 
-    def base_url(self):
-        """Returns the base URL of PowerDocs
+    # end method definition
+
+    def base_url(self) -> str:
+        """Return the base URL of PowerDocs.
 
         Returns:
-            string: base URL
+            string:
+                The base URL.
+
         """
+
         return self.config()["baseUrl"]
 
-    def rest_url(self):
-        """Returns the REST URL of PowerDocs
+    # end method definition
+
+    def rest_url(self) -> str:
+        """Return the REST URL of PowerDocs.
 
         Returns:
-            string: REST URL
+            string:
+                The REST URL.
+
         """
+
         return self.config()["restUrl"]
 
+    # end method definition
+
     def parse_request_response(
         self,
         response_object: object,
         additional_error_message: str = "",
         show_error: bool = True,
     ) -> dict | None:
-        """Converts the request response to a Python dict in a safe way
-           that also handles exceptions.
+        """Convert the request response to a dict in a safe way that handles exceptions.
 
         Args:
-            response_object (object): this is reponse object delivered by the request call
-            additional_error_message (str): print a custom error message
-            show_error (bool): if True log an error, if False log a warning
+            response_object (object):
+                Reponse object delivered by the request call.
+            additional_error_message (str, optional):
+                If provided, print a custom error message.
+            show_error (bool, optional):
+                If True, log an error, if False log a warning.
+
         Returns:
-            dict: a python dict object or None in case of an error
+            dict | None:
+                A python dict object or None in case of an error.
+
         """
 
         if not response_object:
@@ -196,16 +230,17 @@ class OTPD:
         except json.JSONDecodeError as exception:
             if additional_error_message:
                 message = "Cannot decode response as JSon. {}; error -> {}".format(
-                    additional_error_message, exception
+                    additional_error_message,
+                    exception,
                 )
             else:
                 message = "Cannot decode response as JSon; error -> {}".format(
-                    exception
+                    exception,
                 )
             if show_error:
-                logger.error(message)
+                self.logger.error(message)
             else:
-                logger.warning(message)
+                self.logger.warning(message)
             return None
         else:
             return dict_object
@@ -216,14 +251,18 @@ class OTPD:
     # It cannot handle the Request - ServerManager returns an
     # error stating that JavaScript is not enabled...
     def authenticate(self, revalidate: bool = False) -> dict:
-        """Authenticates at PowerDocs and retrieve session ID.
+        """Authenticate at PowerDocs and retrieve session ID.
 
         Args:
-            revalidate (bool): determinse if a re-athentication is enforced
-                               (e.g. if session has timed out with 401 error)
+            revalidate (bool):
+                Determine, if a re-athentication is enforced
+                (e.g. if session has timed out with 401 error).
+
         Returns:
-            dict: Cookie information of None in case of an error.
-                  Also stores cookie information in self._cookie
+            dict:
+                Cookie information of None in case of an error.
+                Also stores cookie information in self._cookie
+
         """
 
         # Already authenticated and session still valid?
@@ -243,108 +282,172 @@ class OTPD:
 
         request_url = self.config()["settingsUrl"]
 
-        ##Fetching session id will be three step process
+        # Fetching session id will be three step process:
         # Step1: intiate a dummy request to tomcat
-        # Step2: fetch session id from the response, and hit j_security_check with proper authentication
-        # Step3: get session id from the response, add to self. It can be used for other transactions
+        # Step2: fetch session id from the response,
+        #        and hit j_security_check with proper authentication
+        # Step3: get session id from the response, add to self.
+        #        It can be used for other transactions
         session = requests.Session()
-        logger.debug("Initiating dummy rest call to Tomcat to get initial session id")
+        self.logger.debug(
+            "Initiating dummy rest call to Tomcat to get initial session ID.",
+        )
         response = session.put(request_url, json=payload)
-        logger.info(response.text)
+        self.logger.info(response.text)
         if response.ok:
-            logger.debug("Url to authenticate Tomcat for Session id -> %s", auth_url)
+            self.logger.debug(
+                "Url to authenticate Tomcat for Session id -> %s",
+                auth_url,
+            )
             session_response = session.post(auth_url)
             if session_response.ok:
-                logger.debug(
-                    "Response for -> %s is -> %s", auth_url, str(session_response)
+                self.logger.debug(
+                    "Response for -> %s is -> %s",
+                    auth_url,
+                    str(session_response),
                 )
                 session_dict = session.cookies.get_dict()
-                logger.debug(
+                self.logger.debug(
                     "Session id to perform Rest API calls to Tomcat -> %s",
                     session_dict["JSESSIONID"],
                 )
-                # store session ID an write it into the global requestHeaders variable:
+                # store session ID an write it into the global request_headers variable:
                 self._jsessionid = session_dict["JSESSIONID"]
-                requestHeaders["Cookie"] = "JSESSIONID=" + self._jsessionid
+                request_headers["Cookie"] = "JSESSIONID=" + self._jsessionid
                 return session_response
             else:
-                logger.error(
-                    "Fetching session id from -> %s failed with j_security_check. Response -> %s",
+                self.logger.error(
+                    "Fetching session id from -> %s failed! Response -> %s",
                     auth_url,
                     session_response.text,
                 )
                 return None
         else:
-            logger.error(
-                "Fetching session id from -> %s failed. Response -> %s",
+            self.logger.error(
+                "Fetching session id from -> %s failed! Response -> %s",
                 request_url,
                 response.text,
             )
-            return None
+        return None
 
     # end method definition
 
-    def import_database(self, filename: str):
-        """Import PowerDocs database backup from a zip file"""
+    def import_database(self, file_path: str) -> dict | None:
+        """Import PowerDocs database backup from a zip file.
 
-        file = filename.split("/")[-1]
-        file_tup = (file, open(filename, "rb"), "application/zip")
-
-        # fields attribute is set according to the other party's interface description
-        m = MultipartEncoder(fields={"name": file, "zipfile": file_tup})
+        Args:
+            file_path (str):
+                The path to the database file to import.
 
-        request_url = self.config()["otpdImportDatabaseUrl"]
+        Returns:
+            dict | None:
+                The request response or None in case of an error.
 
-        logger.info(
-            "Importing PowerDocs database backup -> %s, into PowerDocs ServerManager on -> %s",
-            filename,
-            request_url,
-        )
-        response = requests.post(
-            request_url, data=m, headers={"content-type": m.content_type}, timeout=60
-        )
+        """
 
-        if response.ok:
-            return response
-        else:
-            logger.error(
-                "Failed to import PowerDocs database backup -> %s into -> %s; error -> %s",
-                filename,
-                request_url,
-                response.text,
+        if not file_path or not os.path.isfile(file_path):
+            self.logger.error(
+                "Cannot import PowerDocs database from non-existent file -> %s",
+                file_path,
             )
             return None
 
+        try:
+            # Extract the filename
+            file_name = os.path.basename(file_path)
+
+            # Open the file safely
+            with open(file_path, "rb") as file:
+                file_tuple = (file_name, file, "application/zip")
+
+                # Prepare the multipart encoder
+                multipart = MultipartEncoder(
+                    fields={"name": file_name, "zipfile": file_tuple},
+                )
+
+                # Retrieve the request URL
+                request_url = self.config().get("otpdImportDatabaseUrl")
+
+                if not request_url:
+                    self.logger.error("Import database URL is not configured.")
+                    return None
+
+                self.logger.info(
+                    "Importing PowerDocs database backup from -> %s; calling -> %s",
+                    file_path,
+                    request_url,
+                )
+
+                # Send the request
+                response = requests.post(
+                    url=request_url,
+                    data=multipart,
+                    headers={"content-type": multipart.content_type},
+                    timeout=60,
+                )
+
+                # Handle the response
+                if response.ok:
+                    self.logger.info("Database backup imported successfully.")
+                    return response.json()
+                else:
+                    self.logger.error(
+                        "Failed to import PowerDocs database backup from -> %s into -> %s; error -> %s",
+                        file_path,
+                        request_url,
+                        response.text,
+                    )
+                    return None
+
+        except FileNotFoundError:
+            self.logger.error("File -> '%s' not found!", file_path)
+        except requests.RequestException:
+            self.logger.error("HTTP request to -> '%s' failed", request_url)
+        except Exception:
+            self.logger.error("An unexpected error occurred!")
+
+        return None
+
     # end method definition
 
     def apply_setting(
-        self, setting_name: str, setting_value: str, tenant_name: str = ""
+        self,
+        setting_name: str,
+        setting_value: str,
+        tenant_name: str = "",
     ) -> dict | None:
-        """Appy a setting to the PowerDocs Server Manager
+        """Apply a setting to the PowerDocs Server Manager.
 
         Args:
-            setting_name (str): name of the setting
-            setting_value (str): new value of the setting
-            tenant_name (str): name of the PowerDocs tenant - this is optional as some settings are not tenant-specific!
-        Return:
-            dict: Request response or None if the REST call fails.
+            setting_name (str):
+                The name of the setting.
+            setting_value (str):
+                The new value of the setting.
+            tenant_name (str):
+                The name of the PowerDocs tenant.
+                The tenant name is optional as some settings are not tenant-specific!
+
+        Returns:
+            dict | None:
+                Request response or None if the REST call fails.
+
         """
 
-        settingsPutBody = {
+        settings_put_body = {
             "settingname": setting_name,
             "settingvalue": setting_value,
         }
 
         if tenant_name:
-            settingsPutBody["tenantName"] = tenant_name
+            settings_put_body["tenantName"] = tenant_name
 
         request_url = self.config()["settingsUrl"]
 
-        logger.debug(
-            "Update PowerDocs setting -> %s with value -> %s (tenant -> %s); calling -> %s",
+        self.logger.debug(
+            "Update PowerDocs setting -> '%s' with value -> '%s'%s; calling -> %s",
             setting_name,
             setting_value,
-            tenant_name,
+            " (tenant -> '%s')" if tenant_name else "",
             request_url,
         )
 
@@ -352,27 +455,28 @@ class OTPD:
         while True:
             response = requests.put(
                 url=request_url,
-                json=settingsPutBody,
-                headers=requestHeaders,
+                json=settings_put_body,
+                headers=request_headers,
                 auth=HTTPBasicAuth(
-                    self.config()["username"], self.config()["password"]
+                    self.config()["username"],
+                    self.config()["password"],
                 ),
-                verify=False,  # for localhost deployments this will fail otherwise
+                verify=False,  # for localhost deployments this will fail otherwis e# noqa: S501
                 timeout=None,
             )
             if response.ok:
                 return self.parse_request_response(response)
             # Check if Session has expired - then re-authenticate and try once more
-            elif response.status_code == 401 and retries == 0:
-                logger.debug("Session has expired - try to re-authenticate...")
-                self.authenticate(True)
+            if response.status_code == 401 and retries == 0:
+                self.logger.debug("Session has expired - try to re-authenticate...")
+                self.authenticate(revalidate=True)
                 retries += 1
             else:
-                logger.error(
-                    "Failed to update PowerDocs setting -> %s with value -> %s (tenant -> %s); error -> %s",
+                self.logger.error(
+                    "Failed to update PowerDocs setting -> '%s' with value -> '%s'%s; error -> %s",
                     setting_name,
                     setting_value,
-                    tenant_name,
+                    " (tenant -> '%s')" if tenant_name else "",
                     response.text,
                 )
                 return None