added comments

pandora_server/extras/pandoraPlugintools/encryption.py

@@ -27,7 +27,11 @@ def _print_debug(
         print_errors: bool = False
     ):
     """
-    Prints any list, dict, string, float or integer as a json
+    Print the variable as a JSON-like representation for debugging purposes.
+
+    Args:
+        var (any): The variable to be printed.
+        print_errors (bool): A flag indicating whether to print errors during debugging.
     """
     from .output import print_debug
     print_debug(var, print_errors)
@@ -39,7 +43,13 @@ def _get_cipher(
         password: str = _PASSWORD
     ) -> AES:
     '''
-    Internal use only: Get AES cipher
+    Internal use only: Get AES cipher for encryption and decryption.
+
+    Args:
+        password (str): The password used to derive the encryption key.
+
+    Returns:
+        AES: An AES cipher instance for encryption and decryption.
     '''
     key = b''
     msg = password.encode('utf-8')
@@ -59,7 +69,14 @@ def encrypt(
         password: str = _PASSWORD
     ) -> str:
     '''
-    Return encrypted string
+    Encrypt a string using AES encryption.
+
+    Args:
+        str_to_encrypt (str): The string to be encrypted.
+        password (str): The password used to derive the encryption key.
+
+    Returns:
+        str: The encrypted string in base64 encoding.
     '''
     cipher = _get_cipher(password)
     
@@ -80,7 +97,14 @@ def decrypt(
         password: str = _PASSWORD
     ) -> str:
     '''
-    Return decrypted string
+    Decrypt an encrypted string using AES decryption.
+
+    Args:
+        str_to_decrypt (str): The encrypted string to be decrypted.
+        password (str): The password used to derive the encryption key.
+
+    Returns:
+        str: The decrypted string.
     '''
     cipher = _get_cipher(password)
     

pandora_server/extras/pandoraPlugintools/general.py

@@ -300,7 +300,11 @@ def _print_debug(
         print_errors: bool = False
     ):
     """
-    Prints any list, dict, string, float or integer as a json
+    Print the variable as a JSON-like representation for debugging purposes.
+
+    Args:
+        var (any): The variable to be printed.
+        print_errors (bool): A flag indicating whether to print errors during debugging.
     """
     from .output import print_debug
     print_debug(var, print_errors)
@@ -312,7 +316,13 @@ def safe_input(
         input_string: str = ""
     ) -> str:
     '''
-    Convert the input_string encoded in html entity to clear char string.
+    Convert an input string encoded in HTML entities to a clear character string.
+
+    Args:
+        input_string (str): The input string encoded in HTML entities.
+
+    Returns:
+        str: The decoded clear character string.
     '''
     if not input_string:
         return ""
@@ -326,7 +336,13 @@ def safe_output(
         input_string: str = ""
     ) -> str:
     '''
-    Convert the html entities to input_string encoded to rebuild char string.
+    Convert HTML entities back to their corresponding characters in the input string.
+
+    Args:
+        input_string (str): The input string containing HTML entities.
+
+    Returns:
+        str: The decoded clear character string.
     '''
     if not input_string:
         return ""
@@ -346,7 +362,12 @@ def set_dict_key_value(
         input_value = None
     ):
     """
-    Assign to a key in a dict a given value
+    Assign a given value to a specified key in a dictionary.
+
+    Args:
+        input_dict (dict): The dictionary to which the value will be assigned.
+        input_key (str): The key in the dictionary to which the value will be assigned.
+        input_value (any): The value to be assigned to the specified key.
     """
     key = input_key.strip()
 
@@ -385,8 +406,14 @@ def now(
         print_flag: bool = False
     ) -> str:
     """
-    Returns time in yyyy/mm/dd HH:MM:SS format by default. Use 1 as an argument
-    to get epoch time (utimestamp)
+    Get the current time in the specified format or as a Unix timestamp.
+
+    Args:
+        utimestamp (bool): Set to True to get the Unix timestamp (epoch time).
+        print_flag (bool): Set to True to print the time to standard output.
+
+    Returns:
+        str: The current time in the desired format or as a Unix timestamp.
     """
     from .output import print_stdout
 
@@ -410,10 +437,14 @@ def translate_macros(
         data: str = ""
     ) -> str:
     """
-    Expects a macro dictionary key:value (macro_name:macro_value) 
-    and a string to replace macro.
-    
-    It will replace the macro_name for the macro_value in any string.
+    Replace macros in the input string with their corresponding values.
+
+    Args:
+        macro_dic (dict): A dictionary containing macro names and their corresponding values.
+        data (str): The input string in which macros should be replaced.
+
+    Returns:
+        str: The input string with macros replaced by their values.
     """
     for macro_name, macro_value in macro_dic.items():
         data = data.replace(macro_name, macro_value) 
@@ -431,14 +462,15 @@ def parse_configuration(
         default_values: dict = {}
     ) -> dict:
     """
-    Parse configuration. Reads configuration file and stores its data as dict.
+    Parse a configuration file and return its data as a dictionary.
 
     Args:
-    - file (str): configuration file path. Defaults to "/etc/pandora/pandora_server.conf". \n
-    - separator (str, optional): Separator for option and value. Defaults to " ".
+        file (str): The path to the configuration file. Defaults to "/etc/pandora/pandora_server.conf".
+        separator (str, optional): The separator between option and value. Defaults to " ".
+        default_values (dict, optional): A dictionary of default values. Defaults to an empty dictionary.
 
     Returns:
-    - dict: containing all keys and values from file.
+        dict: A dictionary containing all keys and values from the configuration file.
     """
     from .output import print_stderr
 
@@ -474,16 +506,16 @@ def parse_csv_file(
         print_errors: bool = False
     ) -> list:
     """
-    Parse csv configuration. Reads configuration file and stores its data in a list.
+    Parse a CSV configuration file and return its data in a list.
 
     Args:
-    - file (str): configuration csv file path. \n
-    - separator (str, optional): Separator for option and value. Defaults to ";".
-    - coun_parameters (int): min number of parameters each line shold have. Default None
-    - print_errors (bool): print errors on lines
+        file (str): The path to the CSV configuration file.
+        separator (str, optional): The separator between values in the CSV. Defaults to ";".
+        count_parameters (int, optional): The minimum number of parameters each line should have. Defaults to 0.
+        print_errors (bool, optional): Set to True to print errors for lines with insufficient parameters. Defaults to False.
 
     Returns:
-    - List: containing a list for of values for each csv line.
+        list: A list containing lists of values for each line in the CSV.
     """
     from .output import print_stderr
 

pandora_server/extras/pandoraPlugintools/http.py

@@ -12,7 +12,11 @@ def _print_debug(
         print_errors: bool = False
     ):
     """
-    Prints any list, dict, string, float or integer as a json
+    Print the provided variable as JSON, supporting various data types.
+
+    Args:
+        var (any): The variable to be printed as JSON.
+        print_errors (bool): Set to True to print errors encountered during printing.
     """
     from .output import print_debug
     print_debug(var, print_errors)
@@ -28,13 +32,13 @@ def auth_call(
         passw: str = ""
     ):
     """
-    Authentication for url request. Requires request.sessions.Session() object.
+    Perform authentication for URL requests using various authentication types.
 
     Args:
-    - session (object): request Session() object.
-    - authtype (str): 'ntlm', 'basic' or 'digest'.
-    - user (str): auth user.
-    - passw (str): auth password.
+        session (object, optional): The request Session() object. Defaults to None.
+        authtype (str, optional): The authentication type. Supported values: 'ntlm', 'basic', or 'digest'. Defaults to 'basic'.
+        user (str, optional): The authentication user. Defaults to an empty string.
+        passw (str, optional): The authentication password. Defaults to an empty string.
     """
     if session is not None:
         if authtype == 'ntlm':
@@ -57,17 +61,18 @@ def call_url(
         print_errors: bool = False
     ) -> str:
     """
-    Call URL. Uses request module to get url contents.
+    Call a URL and return its contents.
 
     Args:
-    - url (str): URL
-    - authtype (str): ntlm', 'basic', 'digest'. Optional.
-    - user (str): auth user. Optional.
-    - passw (str): auth password. Optional.
-    - timeout (int): session timeout seconds. Optional.
+        url (str): The URL to call.
+        authtype (str, optional): The authentication type. Supported values: 'ntlm', 'basic', 'digest'. Defaults to 'basic'.
+        user (str, optional): The authentication user. Defaults to an empty string.
+        passw (str, optional): The authentication password. Defaults to an empty string.
+        timeout (int, optional): The session timeout in seconds. Defaults to 1.
+        print_errors (bool, optional): Set to True to print errors encountered during the call. Defaults to False.
 
     Returns:
-    - str: call output
+        str: The output from the URL call.
     """
     from .output import print_stderr
 

pandora_server/extras/pandoraPlugintools/modules.py

@@ -7,7 +7,11 @@ def _print_debug(
         print_errors: bool = False
     ):
     """
-    Prints any list, dict, string, float or integer as a json
+    Print the provided variable as JSON format, supporting various data types.
+
+    Args:
+        var (any, optional): The variable to be printed as JSON. Defaults to an empty string.
+        print_errors (bool, optional): Set to True to print errors encountered during printing. Defaults to False.
     """
     from .output import print_debug
     print_debug(var, print_errors)
@@ -21,6 +25,9 @@ def init_module(
     """
     Initializes a module template with default values.
 
+    Args:
+        default_values (dict, optional): Dictionary containing default values to override template values. Defaults to an empty dictionary.
+
     Returns:
         dict: Dictionary representing the module template with default values.
     """
@@ -87,9 +94,13 @@ def print_module(
     ) -> str:
     """
     Returns module in XML format. Accepts only {dict}.
-    - Only works with one module at a time: otherwise iteration is needed.
-    - Module "value" field accepts str type or [list] for datalists.
-    - Use print_flag to show modules' XML in STDOUT.
+    
+    Args:
+        module (dict, optional): Dictionary containing module data. Defaults to None.
+        print_flag (bool, optional): Flag to print the module XML to STDOUT. Defaults to False.
+    
+    Returns:
+        str: Module data in XML format.
     """
     from .output import print_stdout
 
@@ -220,6 +231,9 @@ def init_log_module(
     """
     Initializes a log module template with default values.
 
+    Args:
+        default_values (dict, optional): Default values to initialize the log module with. Defaults to an empty dictionary.
+
     Returns:
         dict: Dictionary representing the log module template with default values.
     """
@@ -247,7 +261,15 @@ def print_log_module(
     - Only works with one module at a time: otherwise iteration is needed.
     - Module "value" field accepts str type.
     - Use not_print_flag to avoid printing the XML (only populates variables).
+
+    Args:
+        module (dict, optional): Dictionary representing the log module. Defaults to None.
+        print_flag (bool, optional): Flag to indicate whether to print the XML. Defaults to False.
+
+    Returns:
+        str: XML representation of the log module.
     """
+
     from .output import print_stdout
 
     module_xml = ""

pandora_server/extras/pandoraPlugintools/output.py

@@ -12,6 +12,10 @@ def _print_debug(
     ):
     """
     Prints any list, dict, string, float or integer as a json
+
+    Args:
+        var (any, optional): Variable to be printed. Defaults to "".
+        print_errors (bool, optional): Flag to indicate whether to print errors. Defaults to False.
     """
     print_debug(var, print_errors)
 
@@ -24,6 +28,9 @@ def print_stdout(
     ):
     """
     Prints message in stdout
+
+    Args:
+        message (str, optional): Message to be printed. Defaults to "".
     """
     print(message)
 
@@ -36,6 +43,9 @@ def print_stderr(
     ):
     """
     Prints message in stderr
+
+    Args:
+        message (str, optional): Message to be printed. Defaults to "".
     """
     print(message, file=sys.stderr)
 
@@ -49,6 +59,10 @@ def print_debug(
     ):
     """
     Prints any list, dict, string, float or integer as a json
+
+    Args:
+        var: Variable to be printed.
+        print_errors (bool, optional): Whether to print errors. Defaults to False.
     """
     try:
         debug_json = json.dumps(var, indent=4)
@@ -72,6 +86,16 @@ def logger(
     ) -> bool:
     '''
     Add new line to log file
+
+    Args:
+        log_file (str): Path to the log file.
+        message (str): Message to be added to the log.
+        log_level (str): Log level, if applicable. Defaults to an empty string.
+        add_date (bool): Whether to add the current date and time to the log entry. Defaults to True.
+        print_errors (bool): Whether to print errors. Defaults to False.
+
+    Returns:
+        bool: True if the log entry was successfully added, False otherwise.
     '''
     from .general import now
 

pandora_server/extras/pandoraPlugintools/threads.py

@@ -20,7 +20,11 @@ def _print_debug(
         print_errors: bool = False
     ):
     """
-    Prints any list, dict, string, float or integer as a json
+    Prints the provided variable in a JSON-like format.
+    
+    Args:
+        var: The variable (list, dict, string, float, integer) to be printed.
+        print_errors (bool): If True, prints any errors that occur during formatting.
     """
     from .output import print_debug
     print_debug(var, print_errors)
@@ -34,7 +38,12 @@ def _single_thread(
         errors: list = []
     ):
     """
-    Internal use only: Run a given function in a thread
+    Internal use only: Runs a given function in a thread.
+
+    Args:
+        q: A queue from which to get parameters for the function.
+        function (callable): The function to be executed in the thread.
+        errors (list): A list to store any errors encountered during execution.
     """
     params=q.get()
     q.task_done()
@@ -53,7 +62,16 @@ def run_threads(
         print_errors: bool = False
     ) -> bool:
     """
-    Run a given function for given items list in a given number of threads
+    Run a given function for a list of items in multiple threads.
+
+    Args:
+        max_threads (int): Maximum number of threads to use.
+        function (callable): The function to be executed in each thread.
+        items (list): List of items to process.
+        print_errors (bool): Whether to print errors encountered during execution.
+
+    Returns:
+        bool: True if all threads executed successfully, False otherwise.
     """
     from .output import print_stderr
 
@@ -122,8 +140,12 @@ def set_shared_dict_value(
         value = None
     ):
     """
-    Set a given value to a key in the internal shared dict.
-    Used by all parallel processes.
+    Set a value for a key in the internal shared dictionary.
+    This function is used by all parallel processes.
+
+    Args:
+        key (str): The key in the shared dictionary.
+        value: The value to be assigned to the key.
     """
     global _SHARED_DICT
 
@@ -140,8 +162,12 @@ def add_shared_dict_value(
         value = None
     ):
     """
-    Add a given value to a key in the internal shared dict.
-    Used by all parallel processes.
+    Add a value to a key in the internal shared dictionary.
+    This function is used by all parallel processes.
+
+    Args:
+        key (str): The key in the shared dictionary.
+        value: The value to be added to the key.
     """
     global _SHARED_DICT
 
@@ -160,8 +186,14 @@ def get_shared_dict_value(
         key: str = None
     ):
     """
-    Get the value of a key in the internal shared dict.
-    Used by all parallel processes.
+    Get the value of a key in the internal shared dictionary.
+    This function is used by all parallel processes.
+
+    Args:
+        key (str): The key in the shared dictionary.
+
+    Returns:
+        The value associated with the key, or None if the key does not exist.
     """
     global _SHARED_DICT
 
@@ -183,6 +215,15 @@ def run_processes(
     ) -> bool:
     """
     Run a given function for given items list in a given number of processes
+
+    Args:
+        max_processes (int): The maximum number of processes to run in parallel.
+        function (callable): The function to be executed for each item.
+        items (list): List of items to be processed.
+        print_errors (bool): Whether to print errors.
+
+    Returns:
+        bool: True if all processes completed successfully, False otherwise.
     """
     from .output import print_stderr
 

pandora_server/extras/pandoraPlugintools/transfer.py

@@ -30,6 +30,10 @@ def _print_debug(
     ):
     """
     Prints any list, dict, string, float or integer as a json
+
+    Args:
+        var: The variable to be printed.
+        print_errors (bool): Whether to print errors.
     """
     from .output import print_debug
     print_debug(var, print_errors)
@@ -64,14 +68,16 @@ def tentacle_xml(
     ) -> bool:
     """
     Sends file using tentacle protocol
-    - Only works with one file at time.
-    - file variable needs full file path.
-    - tentacle_opts should be a dict with tentacle options (address [password] [port]).
-    - tentacle_path allows to define a custom path for tentacle client in case is not in sys path).
-    - if debug is enabled, the data file will not be removed after being sent.
-    - if print_errors is enabled, function will print all error messages
+    
+    Args:
+        data_file (str): Path to the data file to be sent.
+        tentacle_ops (dict): Tentacle options as a dictionary (address [password] [port]).
+        tentacle_path (str): Custom path for the tentacle client executable.
+        debug (int): Debug mode flag. If enabled (1), the data file will not be removed after sending.
+        print_errors (bool): Whether to print error messages.
 
-    Returns True for OK and False for errors.
+    Returns:
+        bool: True for success, False for errors.
     """
     from .output import print_stderr
 
@@ -161,11 +167,16 @@ def write_xml(
         print_errors: bool = False
     ) -> str:
     """
-    Creates a agent .data file in the specified data_dir folder
+    Creates an agent .data file in the specified data_dir folder
+
     Args:
-    - xml (str): XML string to be written in the file.
-    - agent_name (str): agent name for the xml and file name.
-    - data_dir (str): folder in which the file will be created.
+        xml (str): XML string to be written in the file.
+        agent_name (str): Agent name for the XML and file name.
+        data_dir (str): Folder in which the file will be created.
+        print_errors (bool): Whether to print error messages.
+
+    Returns:
+        str: Path to the created .data file.
     """
     from .general import generate_md5
     from .output import print_stderr