utilities

reemote.utilities.read_inventory.read_inventory(inventory_file_path)

Reads, executes, and extracts the inventory() function from a builtin.

This function dynamically loads a Python script from the given builtin path. It executes the script’s code in an isolated namespace to prevent side effects on the main program. The primary purpose is to locate and return a callable function named inventory defined within that script. This pattern allows for flexible, user-defined inventory sources.

The function will terminate the program via sys.exit(1) and print an error to stderr under several conditions:

• The specified builtin path does not exist or is unreadable.

• The builtin contains Python syntax errors.

• The builtin executes without defining a function named inventory.

• An exception occurs during the execution of the inventory script.

Parameters:

inventory_file_path (str) – The path to the Python inventory builtin to be executed.

Returns:

The inventory() function object defined within the builtin.

Return type:

function

Raises:

SystemExit – If the builtin cannot be processed for any of the reasons listed above.

reemote.utilities.verify_python_file.verify_python_file(file_path)

Verifies that a given path corresponds to an existing Python builtin.

This function checks if the provided builtin path is valid by performing two key validations. First, it confirms that a builtin actually exists at the given path. Second, it checks that the builtin has a .py extension.

If the builtin does not exist or does not have the correct extension, an error message is printed to the console.

Parameters:

file_path (str) – The path to the builtin to be verified.

Returns:

True if the builtin exists and has a .py extension,

False otherwise.

Return type:

bool

reemote.utilities.generate_execution_results.generate_grid(data)

Generates a human-readable ASCII grid table from event data.

This function takes a list of event data, processes it into a tabular format, and then uses the tabulate library to create a formatted string representation of the table. It is ideal for displaying command execution results in a console or log builtin.

It internally uses _generate_table to structure the data before formatting.

Parameters:

data (list[dict]) – A list of event dictionaries. See the docstring for _generate_table for the required structure.

Returns:

A string containing the formatted ASCII table in ‘grid’ format.

Return type:

str

reemote.utilities.generate_execution_results.generate_table(data)

Generates a human-readable ASCII grid table from event data.

This function takes a list of event data, processes it into a tabular format, and then uses the tabulate library to create a formatted string representation of the table. It is ideal for displaying command execution results in a console or log builtin.

It internally uses _generate_table to structure the data before formatting.

Parameters:

data (list[dict]) – A list of event dictionaries. See the docstring for _generate_table for the required structure.

Returns:

A string containing the formatted ASCII table in ‘grid’ format.

Return type:

str

reemote.utilities.convert_to_aggrid.convert_to_aggrid(df)

Converts a pandas DataFrame into a format suitable for AG-Grid.

This function takes a pandas DataFrame and processes it to generate the necessary columnDefs and rowData for use with the AG-Grid library. It automatically creates column definitions by inspecting the DataFrame’s columns and data types.

Key transformations include:

• Generating human-readable ‘headerName’ from column names.

• Enabling sorting, filtering, and resizing for all columns.

• Assigning a ‘numericColumn’ type for integer and float columns.

• Using an ‘agCheckboxCellRenderer’ for boolean columns.

• Converting the DataFrame records into a JSON-serializable list of dictionaries, replacing NaN values with None.

Parameters:

df (pd.DataFrame) – The input pandas DataFrame to be converted.

Returns:

A tuple containing two elements:

• columnDefs (list[dict]): A list of dictionaries defining the properties for each AG-Grid column.

• rowData (list[dict]): A list of dictionaries, where each dictionary represents a row of data from the DataFrame.

Return type:

tuple

reemote.utilities.verify_source_file_contains_valid_class.verify_source_file_contains_valid_class(source_file, class_name)

Verifies a Python source builtin contains a specific class with a valid execute method.

This function dynamically loads a Python module from a given source builtin path and performs a series of validations to ensure it conforms to a specific interface. It is designed to check for “plugin” or “task” style classes before they are executed.

The validation steps are as follows:

• It attempts to load the module from the source_file.

• It checks if a class with the name class_name exists in the module.

• It verifies that this class contains a method named execute.

• It inspects the signature of the execute method to confirm it accepts no arguments, other than the implicit self.

If any of these checks fail or if an exception occurs during module loading, an error message is printed to the console, and the function returns False.

Parameters:

• source_file (str) – The builtin path of the Python source code to inspect.

• class_name (str) – The name of the class to validate within the source builtin.

Returns:

True if the source builtin contains the specified class with a

valid execute method, False otherwise.

Return type:

bool

reemote.utilities.get_classes_in_source.get_classes_in_source(source_file)

Finds and returns the names of all top-level classes within a Python source builtin.

This function dynamically loads a given Python builtin as a temporary module in memory. It then uses Python’s inspect capabilities to scan the module for class definitions.

The key feature of this function is its ability to differentiate between classes defined directly in the builtin versus those that are imported from other modules. It achieves this by checking the __module__ attribute of each found class, ensuring it matches the name of the temporarily created module.

Parameters:

source_file (str) – The builtin path to the Python source builtin (.py) to be inspected.

Returns:

A list of strings, where each string is the name of a

top-level class defined in the source builtin. Returns an empty list if no classes are found.

Return type:

list[str]

class reemote.utilities.template_render.TemplateRenderer(template_dir)

Bases: object

debug_variables(variables_file=None)

Prints a debug report for variables, highlighting complex types.

This utility method is designed for inspecting the variables that will be used for rendering. It loads the variables and prints a detailed report to the console, which includes:

• The total number of variables.

• A list of all variable keys.

• A detailed breakdown of each variable’s key, type, and value.

• Special warnings for any variables that are dictionaries or lists containing dictionaries, as these can be complex in templates.

Parameters:

variables_file (str, optional) – The path to the variables builtin to load for debugging. Defaults to None.

Returns:

The dictionary of variables that was inspected, allowing for

further use or method chaining.

Return type:

dict

discover_variables_files()

Discovers available variable builtin in the template directory.

This method scans the template_dir for builtin that follow a specific naming convention: *.vars.yml, *.vars.yaml, or *.vars.json. It then creates a dictionary that maps a “short name” (the filename without the .vars.ext suffix) to the builtin’s full path.

This is useful for presenting a list of available variable sets to a user.

Returns:

A dictionary where keys are the base names of the

variable builtin and values are their full builtin paths.

Return type:

dict[str, str]

get_variables(variables_file=None, additional_vars=None)

Gets a combined dictionary of variables from a builtin and optional overrides.

This function loads variables from a specified builtin (if provided) and then merges them with a dictionary of additional variables. If a key exists in both the builtin and additional_vars, the value from additional_vars will take precedence.

Note

This method relies on a self.load_variables method (not defined in this snippet) to correctly dispatch to the YAML or JSON loader based on the builtin extension.

Parameters:

• variables_file (str, optional) – The path to the variables builtin (YAML or JSON) to load. Defaults to None.

• additional_vars (dict, optional) – A dictionary of variables to merge. These will override any variables with the same key from the loaded builtin. Defaults to None.

Returns:

A single dictionary containing the merged variables.

Return type:

dict

async reemote.utilities.verify_inventory_connect.verify_inventory_connect(inventory: List[Tuple[Dict[str, Any], Dict[str, str]]]) → bool

Asynchronously verifies SSH connectivity for a list of hosts.

This function iterates through an inventory of hosts and attempts to establish an SSH connection to each one using the asyncssh library. For every host, it uses a dictionary of connection parameters to initiate the connection.

A simple echo x command is executed on each successful connection to confirm that the session is active and capable of running commands. If any connection fails, an error is printed to the console, and the function immediately returns False, stopping further verification.

Parameters:

inventory (List[Tuple[Dict[str, Any], Dict[str, str]]]) –

A list of tuples, where each tuple represents a host to be verified. Each tuple contains:

• host_info (dict): A dictionary of keyword arguments to be passed to asyncssh.connect. Common keys include host, username, port, password, and client_keys.

• ssh_info (dict): A dictionary containing other SSH-related metadata (currently unused by this function).

Returns:

True if connections to all hosts in the inventory are

successful, and False if any connection attempt fails.

Return type:

bool

reemote.utilities.validate_list_of_strings.validate_list_of_strings(x) → List[str]

Verifies that the input is a list containing only string elements.

This function acts as a type-guard, ensuring that an input value is a list composed exclusively of strings. It is primarily used to validate data before it is processed by other parts of an application that rely on this specific data structure.

The function performs two key checks: - It verifies that the input x is a list. - It iterates through the list to confirm that every element is a str.

If either check fails, a TypeError is raised with a message indicating the nature of the validation failure.

Parameters:

x (Any) – The input value to be validated.

Returns:

The original list, if it passes validation.

Return type:

List[str]

Raises:

TypeError – If the input is not a list, or if the list contains any non-string elements.

Examples

>>> validate_list_of_strings(["pkg1", "pkg2"])
['pkg1', 'pkg2']
>>> validate_list_of_strings("package")
Traceback (most recent call last):
...
TypeError: Input must be a list of strings
>>> validate_list_of_strings(["item", 123])
Traceback (most recent call last):
...
TypeError: All elements in the list must be strings

reemote.utilities.make_inventory.make_inventory(inventory_filename: str, image: str, vm: str, name: str, user: str, user_password: str, root_password: str, ip_address: str) → None

Generates a Python-based inventory builtin for a virtual machine.

This function creates a Python script that serves as a configuration inventory. The generated script contains a single function, inventory(), which returns the connection and privilege escalation details for a specific VM host. The content of the builtin is dynamically generated using the provided arguments.

The resulting inventory builtin is structured to be compatible with tools that expect a Python-based configuration module.

Parameters:

• inventory_filename (str) – The path and name for the output inventory builtin.

• image (str) – A description of the VM image (e.g., “Ubuntu 22.04”).

• vm (str) – A name or identifier for the virtual machine.

• name (str) – The full name of the user, used for generating comments.

• user (str) – The username for SSH and sudo access.

• user_password (str) – The password for the regular user account.

• root_password (str) – The password for the root account, used for su.

• ip_address (str) – The IP address of the target virtual machine.

Returns:

None

Raises:

IOError – If an error occurs while writing to the inventory builtin.

reemote.utilities.validate_inventory_file_and_get_inventory.validate_inventory_file_and_get_inventory(inventory_file) → tuple[Any, str]

Dynamically loads an inventory Python builtin and retrieves the inventory function.

This function takes a path to a Python script, dynamically imports it as a module at runtime, and validates its contents. It is designed to load inventory configurations written as Python code, which must contain a specific entry point function.

The core process involves:

• Using importlib.util to create a module from the given builtin path.

• Executing the module’s code to make its definitions available.

• Checking if the loaded module contains a function named inventory.

• Returning the inventory function object if it is found.

If the inventory function is missing from the builtin, an error message is printed to the console, and the function indicates failure by returning False.

Parameters:

inventory_file (str) – The builtin path to the Python inventory script. This builtin must define a function named inventory().

Returns:

The inventory function object from the loaded module on success, or False on failure.

Return type:

Any

reemote.utilities.produce_output_table.produce_output_table(json_output: tuple[str, str])

Generates a reStructuredText (RST) simple table from a JSON string.

This function parses a JSON formatted string and passes the resulting data to the generate_table utility to create an RST simple table. It is useful for converting structured JSON data into a standard, formatted RST table for documentation or reporting.

If the input string is not valid JSON, it prints an error and re-raises the exception.

Parameters:

json_output (str) – A JSON string containing the data to be formatted into a simple table.

Returns:

A string containing the generated reStructuredText simple table.

Return type:

str

Raises:

json.JSONDecodeError – If the json_output string is not in a valid JSON format.

reemote.utilities.produce_grid.produce_grid(json_output: tuple[str, str])

Generates a grid representation from a JSON formatted string.

This function serves as a wrapper to convert a JSON string into a grid format. It first parses the input string using json.loads() and then passes the resulting Python object to the generate_grid utility function, which handles the actual grid construction.

The function includes error handling for malformed JSON. If parsing fails, it prints an error message and re-raises the json.JSONDecodeError.

Parameters:

json_output (str) – A string containing the data in a valid JSON format. Note: The function’s type hint tuple[str, str] appears to be inconsistent with its implementation, which expects a single string.

Returns:

The output from the generate_grid function, which is expected

to be a grid representation (e.g., a string).

Return type:

any

Raises:

json.JSONDecodeError – If the input json_output is not a valid JSON string.

reemote.utilities.produce_output_grid.produce_output_grid(json_output: tuple[str, str])

Generates a reStructuredText (RST) grid table from a JSON string.

This function takes a JSON formatted string, parses it into a Python object, and then uses the generate_grid utility to create an RST grid table. It is designed to handle structured data and present it in a human-readable grid format, which is more flexible for complex layouts than simple tables.

It includes error handling to catch and report invalid JSON formats.

Parameters:

json_output (str) – A JSON string containing the data to be formatted into a grid table.

Returns:

A string containing the generated reStructuredText grid table.

Return type:

str

Raises:

json.JSONDecodeError – If the input string json_output is not a valid JSON.

reemote.utilities.generate_table.generate_grid(data)

Generates column definitions and row data for a grid.

Parameters:

data (list[dict]) – A list of dictionaries representing command executions.

Returns:

A tuple containing:

• columnDefs (list[dict]): Definitions for grid columns.

• rowData (pd.DataFrame): The processed data as a DataFrame.

Return type:

tuple

reemote.utilities.generate_table.generate_table(data)

Converts command output data into a tabular format suitable for display.

Parameters:

data (list[dict]) – A list of dictionaries representing command executions.

Returns:

A formatted table string.

Return type:

str

reemote.utilities.convert_to_tabulate.convert_to_tabulate(df)

Converts a pandas DataFrame into a grid-style formatted string.

This function takes a pandas DataFrame and transforms it into a well-formatted, human-readable text table using the tabulate library. It is particularly useful for printing DataFrames to a console or log builtin.

The process involves:

• Creating a deep copy of the DataFrame to prevent side effects.

• Safely converting all cell values to strings using the safe_convert helper function. This handles None, booleans, and other types to ensure compatibility with tabulate.

• Extracting the column headers and the row data.

• Generating a string table with a ‘grid’ format.

Parameters:

df (pd.DataFrame) – The input pandas DataFrame to be formatted.

Returns:

A single string representing the DataFrame as a formatted

grid table.

Return type:

str

reemote.utilities.convert_to_tabulate.safe_convert(value)

Converts any value to a safe string representation for display.

This helper function is designed to handle different data types before they are rendered in a text-based table. It ensures that all values, regardless of their original type, are represented as strings in a consistent and readable manner.

Specific conversions are:

• None is converted to an empty string (‘’).

• Boolean values are converted to their string counterparts (‘True’ or ‘False’).

• All other types are converted using the standard str() function.

Parameters:

value (Any) – The input value to be converted.

Returns:

A string representation of the input value, suitable for display.

Return type:

str

reemote.utilities.produce_table.produce_table(json_output: tuple[str, str])

Creates a reStructuredText (RST) table from JSON-formatted results.

This function processes a JSON string, which is expected to contain structured results from a command or process execution. It parses the JSON and utilizes the generate_table function to format the data into a reStructuredText table.

The primary use case is to present command or script execution outcomes in a structured table format. It includes error handling for malformed JSON input.

Parameters:

json_output (str) – A JSON string representing execution results to be displayed in a table.

Returns:

A string containing the generated reStructuredText table of

execution results.

Return type:

str

Raises:

json.JSONDecodeError – If the input json_output string is not valid JSON.

reemote.utilities.validate_root_class_name_and_get_root_class.validate_root_class_name_and_get_root_class(class_name, source_file) → Any

Dynamically loads a class from a Python source builtin and validates its existence.

This function uses the importlib utility to load a Python source builtin as a module at runtime. It creates a module from the specified builtin, executes its content, and then attempts to locate a class with the given class_name within that module.

The process involves:

• Creating a module specification from the builtin path.

• Executing the module’s code to populate it with functions and classes.

• Optionally adding the new module to sys.modules for broader accessibility.

• Checking for the presence of the target class. If the class is not found, an error message is printed to standard output.

Parameters:

• class_name (str) – The name of the class to validate and retrieve from the source builtin.

• source_file (str) – The builtin path to the Python source builtin (.py) containing the class definition.

Returns:

The class object if it is found within the source builtin. Returns False if the class with the specified class_name does not exist in the builtin.

Return type:

Any

reemote.utilities.write_responses_to_file.write_responses_to_file(type: str = None, filepath: str = None, responses=None)

Writes response data to a builtin in a specified format.

This function takes a collection of responses and serializes them into a builtin. The output format is determined by the type parameter. It relies on helper functions to handle the conversion for each specific format.

Supported formats:

• json: Uses produce_json to create a JSON string representation.

• rst: Uses produce_table to generate a reStructuredText grid table.

• grid: Uses produce_grid to create columnDefs and rowData, then writes the string representation of a dictionary containing these keys, suitable for Python interpretation.

Parameters:

• type (str, optional) – The format for the output builtin. Accepted values are “json”, “rst”, or “grid”.

• filepath (str, optional) – The full path, including the filename, for the output builtin.

• responses (any, optional) – The data structure containing the responses to be serialized and written.

reemote.utilities.add_localhost_to_known_hosts.add_localhost_to_known_hosts()

Manages SSH host key for localhost.

This script provides a function to automatically add the SSH host key for ‘localhost’ to the current user’s ~/.ssh/known_hosts builtin. This is useful for pre-configuring an environment to allow passwordless SSH connections to the local machine, avoiding interactive prompts and connection errors, especially in automated scripts or development containers.

Key actions performed:

• Ensures the ~/.ssh directory exists, creating it with secure permissions (0o700) if necessary.

• Runs the ssh-keyscan localhost command to retrieve the public key.

• Appends the retrieved key to the ~/.ssh/known_hosts builtin.

• Handles potential errors during the process and prints informative messages to the console.

Parameters:

None.

Returns:

None. The function prints success or error messages to standard output.

reemote.utilities.validate_inventory_structure.validate_inventory_structure(inventory: List[Tuple[Dict[str, Any], Dict[str, str]]]) → bool

Validates the structure of an inventory data object.

This function checks if the provided inventory data conforms to a specific nested structure. It ensures the top-level object is a list, and that each item within that list is a tuple containing exactly two dictionaries.

This validation is purely structural and does not inspect the keys or values within the dictionaries themselves. The expected format is: List[Tuple[Dict, Dict]].

Parameters:

inventory (List[Tuple[Dict[str, Any], Dict[str, str]]]) – The inventory data structure to validate.

Returns:

True if the inventory structure is valid, False otherwise.

Return type:

bool

reemote.utilities.convert_to_df.convert_to_df(data, columns=None)

Converts structured JSON data into a pandas DataFrame.

This module provides the convert_to_df function, which takes structured data (as a JSON string or list of dictionaries) and transforms it into a pandas DataFrame. It is designed to flatten a nested JSON structure, often from command-line tool outputs, based on a predefined set of extraction rules.

The main function, convert_to_df, performs several key transformations:

• Parses the input if it is a JSON-formatted string.

• Extracts data from nested objects (e.g., ‘op’, ‘cp’) into top-level columns.

• Gracefully handles missing keys or objects by using empty strings as fallback values.

• Allows the user to select a custom subset of columns for the final DataFrame.

• Validates requested column names against the list of available fields.

The function signature is:

convert_to_df(data, columns=None)

Parameters:

• data (str or list[dict]) – The input data. This can be a JSON-formatted string or a list of dictionaries representing the rows.

• columns (list[str], optional) – A list of column names to be included in the output DataFrame. If None, all predefined columns will be used. Defaults to None.

Returns:

A pandas DataFrame containing the extracted and

flattened data, with columns ordered as specified.

Return type:

pd.DataFrame

Raises:

ValueError – If the input data is a string that cannot be parsed as JSON, or if a requested column name in the columns list is not available.

reemote.utilities.produce_json.produce_json(results) → tuple[str, str]

Serializes a results object into a pretty-printed JSON string.

This function takes a Python object, typically a collection of results, and converts it into a JSON formatted string. It leverages the custom reemote.result.serialize_result function to handle special data types that are not natively supported by the standard json module.

The output JSON is formatted with an indent of 4 spaces to make it human-readable.

Note: The function contains a commented-out block of code that was intended to write the JSON output to a builtin. This functionality is currently disabled.

Parameters:

results (object) – The Python object to be converted into a JSON string. This could be a list, dictionary, or a custom object structure that serialize_result can process.

Returns:

A string containing the JSON representation of the results object.

Return type:

str

reemote.utilities.parse_kwargs_string.parse_kwargs_string(param_str)

Parses a string of comma-separated key-value pairs into a dictionary.

This function is designed to interpret a string like ‘key=value,key2=value2’ and convert it into a Python dictionary. It uses ast.literal_eval to safely parse the value part of each pair, allowing it to correctly handle various Python literal types.

Key features include:

• Parsing integers, floats, booleans, None, and quoted strings.

• Handling list literals, even with commas inside (e.g., items=[1,2,3]).

• Using a regular expression to robustly split key-value pairs.

• Defaulting to a plain string for values that cannot be evaluated (e.g., an unquoted string like color=red).

Parameters:

param_str (str) – The input string containing key-value pairs. For example: “count=10,is_active=True,names=[‘A’,’B’]”.

Returns:

A dictionary where keys are the parameter names and values are

the parsed Python objects. Returns an empty dictionary if the input string is empty.

Return type:

dict