Merge branch 'ent-11756-plugintools-python' of https://brutus.artica.es:8081/artica/pandorafms into ent-11756-plugintools-python

pandora_server/extras/pandoraPlugintools/agents.py

@@ -107,7 +107,10 @@ class Agent:
             config: dict = {}
         ):
         '''
-        TODO: Add commnets
+        Update the configuration settings with new values.
+
+        Args:
+            config (dict): A dictionary containing configuration keys and their new values.
         '''
         for key, value in config.items():
             if key in self.config:
@@ -117,7 +120,10 @@ class Agent:
             self
         ) -> dict:
         '''
-        TODO: Add commnets
+        Retrieve the current configuration settings.
+
+        Returns:
+            dict: A dictionary containing the current configuration settings.
         '''
         return self.config
 
@@ -126,7 +132,10 @@ class Agent:
             module: dict = {}
         ):
         '''
-        TODO: Add commnets
+        Add a new module to the list of modules.
+
+        Args:
+            module (dict): A dictionary containing module information.
         '''
         from .general import generate_md5
         from .modules import init_module
@@ -140,7 +149,10 @@ class Agent:
             module_name: str = ""
         ):
         '''
-        TODO: Add commnets
+        Delete a module based on its name.
+
+        Args:
+            module_name (str): The name of the module to be deleted.
         '''
         from .general import generate_md5
 
@@ -160,7 +172,11 @@ class Agent:
             module: dict = {}
         ):
         '''
-        TODO: Add commnets
+        Update a module based on its name.
+
+        Args:
+            module_name (str): The name of the module to be updated.
+            module (dict): A dictionary containing updated module information.
         '''
         module_def = self.get_module(module_name)
         
@@ -178,7 +194,13 @@ class Agent:
             module_name: str = ""
         ) -> dict:
         '''
-        TODO: Add commnets
+        Retrieve module information based on its name.
+
+        Args:
+            module_name (str): The name of the module to retrieve.
+
+        Returns:
+            dict: A dictionary containing module information if found, otherwise an empty dictionary.
         '''
         from .general import generate_md5
 
@@ -197,7 +219,10 @@ class Agent:
             self
         ) -> dict:
         '''
-        TODO: Add commnets
+        Retrieve the definitions of all added modules.
+
+        Returns:
+            dict: A dictionary containing the definitions of all added modules.
         '''
         return self.modules_def
 
@@ -206,18 +231,24 @@ class Agent:
             log_module: dict = {}
         ):
         '''
-        TODO: Add commnets
+        Add a new log module to the list of log modules.
+
+        Args:
+            log_module (dict): A dictionary containing log module information.
         '''
         from .modules import init_log_module
 
-        if "source" in module and type(module["source"]) == str and len(module["source"].strip()) > 0:
+        if "source" in log_module and type(log_module["source"]) == str and len(log_module["source"].strip()) > 0:
             self.log_modules_def.append(init_log_module(log_module))
 
     def get_log_modules_def(
             self
         ) -> dict:
         '''
-        TODO: Add commnets
+        Retrieve the definitions of all added log modules.
+
+        Returns:
+            dict: A dictionary containing the definitions of all added log modules.
         '''
         return self.log_modules_def
 
@@ -226,7 +257,13 @@ class Agent:
             print_flag: bool = False
         ) -> str:
         '''
-        TODO: Add commnets
+        Generate and optionally print the XML representation of the agent.
+
+        Args:
+            print_flag (bool): A flag indicating whether to print the XML representation.
+
+        Returns:
+            str: The XML representation of the agent.
         '''
         return print_agent(self.get_config(), self.get_modules_def(), self.get_log_modules_def(), print_flag)
 
@@ -269,10 +306,13 @@ def init_agent(
         default_values: dict = {}
     ) -> dict:
     """
-    Initializes an agent template with default values.
+    Initialize an agent template with default values.
+
+    Args:
+        default_values (dict): A dictionary containing custom default values for the agent template.
 
     Returns:
-        dict: Dictionary representing the agent template with default values.
+        dict: A dictionary representing the agent template with default and custom values.
     """
     from .general import now
 
@@ -307,9 +347,16 @@ def print_agent(
         print_flag: bool = False
     ) -> str:
     """
-    Prints agent XML. Requires agent conf (dict) and modules (list) as arguments.
+    Print the XML representation of an agent.
-    - Use print_flag to show modules' XML in STDOUT.
+
-    - Returns xml (str).
+    Args:
+        agent (dict): A dictionary containing agent configuration.
+        modules (list): A list of dictionaries representing modules.
+        log_modules (list): A list of dictionaries representing log modules.
+        print_flag (bool): A flag indicating whether to print the XML representation.
+
+    Returns:
+        str: The XML representation of the agent.
     """
     from .output import print_stdout
     from .modules import print_module,print_log_module

pandora_server/extras/pandoraPlugintools/discovery.py

@@ -19,7 +19,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)
@@ -92,7 +96,7 @@ def add_disco_summary_value(
     if key in _SUMMARY:
         _SUMMARY[key] += value
     else:
-        set_summary_value(key, value)
+        set_disco_summary_value(key, value)
 
 ####
 # Set fixed value to info
@@ -133,7 +137,10 @@ def set_disco_monitoring_data(
         data: list = []
     ):
     """
-    TODO: Add comments
+    Set the monitoring data for disk usage.
+
+    Args:
+        data (list): A list containing disk monitoring data.
     """
     global _MONITORING_DATA
 
@@ -146,7 +153,10 @@ def add_disco_monitoring_data(
         data: dict = {}
     ):
     """
-    TODO: Add comments
+    Add disk monitoring data to the global monitoring dataset.
+
+    Args:
+        data (dict): A dictionary containing disk monitoring data.
     """
     global _MONITORING_DATA
 

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_AES(
         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_AES(
         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()
 
@@ -403,8 +424,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
+    Get the current time in the specified format or as a Unix timestamp.
-    to get epoch time (utimestamp)
+
+    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
 
@@ -428,10 +455,14 @@ def translate_macros(
         data: str = ""
     ) -> str:
     """
-    Expects a macro dictionary key:value (macro_name:macro_value) 
+    Replace macros in the input string with their corresponding values.
-    and a string to replace macro.
 
-    It will replace the macro_name for the macro_value in any string.
+    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) 
@@ -449,14 +480,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
+        file (str): The path to the configuration file. Defaults to "/etc/pandora/pandora_server.conf".
-    - separator (str, optional): Separator for option and value. Defaults to " ".
+        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
 
@@ -492,16 +524,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
+        file (str): The path to the CSV configuration file.
-    - separator (str, optional): Separator for option and value. Defaults to ";".
+        separator (str, optional): The separator between values in the CSV. Defaults to ";".
-    - coun_parameters (int): min number of parameters each line shold have. Default None
+        count_parameters (int, optional): The minimum number of parameters each line should have. Defaults to 0.
-    - print_errors (bool): print errors on lines
+        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

@@ -14,7 +14,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)
@@ -30,13 +34,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.
+        session (object, optional): The request Session() object. Defaults to None.
-    - authtype (str): 'ntlm', 'basic' or 'digest'.
+        authtype (str, optional): The authentication type. Supported values: 'ntlm', 'basic', or 'digest'. Defaults to 'basic'.
-    - user (str): auth user.
+        user (str, optional): The authentication user. Defaults to an empty string.
-    - passw (str): auth password.
+        passw (str, optional): The authentication password. Defaults to an empty string.
     """
     if session is not None:
         if authtype == 'ntlm':
@@ -60,17 +64,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
+        url (str): The URL to call.
-    - authtype (str): ntlm', 'basic', 'digest'. Optional.
+        authtype (str, optional): The authentication type. Supported values: 'ntlm', 'basic', 'digest'. Defaults to 'basic'.
-    - user (str): auth user. Optional.
+        user (str, optional): The authentication user. Defaults to an empty string.
-    - passw (str): auth password. Optional.
+        passw (str, optional): The authentication password. Defaults to an empty string.
-    - timeout (int): session timeout seconds. Optional.
+        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.
+    Args:
-    - Use print_flag to show modules' XML in STDOUT.
+        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
 
@@ -261,6 +272,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.
     """
@@ -288,7 +302,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.
+    Set a value for a key in the internal shared dictionary.
-    Used by all parallel processes.
+    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.
+    Add a value to a key in the internal shared dictionary.
-    Used by all parallel processes.
+    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.
+    Get the value of a key in the internal shared dictionary.
-    Used by all parallel processes.
+    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)
@@ -80,14 +84,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
     
-    Returns True for OK and False for errors.
+    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:
+        bool: True for success, False for errors.
     """
     from .output import print_stderr
 
@@ -177,11 +183,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.
+        xml (str): XML string to be written in the file.
-    - agent_name (str): agent name for the xml and file name.
+        agent_name (str): Agent name for the XML and file name.
-    - data_dir (str): folder in which the file will be created.
+        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