diff --git a/pandora_server/extras/pandoraPlugintools/encryption.py b/pandora_server/extras/pandoraPlugintools/encryption.py index 4b6408c120..89d1959adb 100644 --- a/pandora_server/extras/pandoraPlugintools/encryption.py +++ b/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) diff --git a/pandora_server/extras/pandoraPlugintools/general.py b/pandora_server/extras/pandoraPlugintools/general.py index 8c85cd4bc7..49c131fe5e 100644 --- a/pandora_server/extras/pandoraPlugintools/general.py +++ b/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 diff --git a/pandora_server/extras/pandoraPlugintools/http.py b/pandora_server/extras/pandoraPlugintools/http.py index 1ababef7f5..30d7722598 100644 --- a/pandora_server/extras/pandoraPlugintools/http.py +++ b/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 diff --git a/pandora_server/extras/pandoraPlugintools/modules.py b/pandora_server/extras/pandoraPlugintools/modules.py index 091c6d136c..623f379482 100644 --- a/pandora_server/extras/pandoraPlugintools/modules.py +++ b/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 = "" diff --git a/pandora_server/extras/pandoraPlugintools/output.py b/pandora_server/extras/pandoraPlugintools/output.py index 1488d548f6..f9064c2abf 100644 --- a/pandora_server/extras/pandoraPlugintools/output.py +++ b/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 diff --git a/pandora_server/extras/pandoraPlugintools/threads.py b/pandora_server/extras/pandoraPlugintools/threads.py index 2b83879b85..f38c479eab 100644 --- a/pandora_server/extras/pandoraPlugintools/threads.py +++ b/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 diff --git a/pandora_server/extras/pandoraPlugintools/transfer.py b/pandora_server/extras/pandoraPlugintools/transfer.py index 66d177f55e..e299307b11 100644 --- a/pandora_server/extras/pandoraPlugintools/transfer.py +++ b/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