API Reference - Command Processor Module¤

Core Interfaces¤

ICommandProcessor¤

Abstract base class defining the command processing contract.

Methods¤

process_commands(commands, target_format="generic")¤

Process a command structure into a target format.

Parameters: - commands (Dict[str, Any]): Dictionary containing command structure - target_format (str, optional): Target format identifier. Defaults to "generic"

Returns: - Dict[str, Any]: Dictionary with processed commands

Raises: - PantherException: If command structure is invalid

Example:

processor = CommandProcessor()
commands = {
    "pre_run_cmds": ["echo setup"],
    "run_cmd": {"command_args": "python script.py"},
    "post_run_cmds": ["echo cleanup"]
}
result = processor.process_commands(commands)

process_command_list(commands, detect_properties=True)¤

Process a list of commands into structured format.

Parameters: - commands (List[Any]): List of commands (strings, ShellCommand objects, etc.) - detect_properties (bool, optional): Whether to detect properties like multiline, function definitions. Defaults to True

Returns: - List[Dict[str, Any]]: List of processed command dictionaries

detect_command_properties(command)¤

Detect properties of a command string.

Parameters: - command (str): Command string to analyze

Returns: - Dict[str, bool]: Dictionary of detected properties including: - is_multiline: Whether command spans multiple lines - is_function_definition: Whether command defines a function - is_control_structure: Whether command is a control structure

IEnvironmentCommandAdapter¤

Abstract interface for environment-specific command adaptations.

Methods¤

adapt_commands(commands)¤

Adapt commands for a specific environment.

Parameters: - commands (Dict[str, Any]): Processed commands

Returns: - Dict[str, Any]: Environment-adapted commands

Core Classes¤

CommandProcessor¤

Main implementation of ICommandProcessor with validation and transformation logic.

Inherits: ICommandProcessor, ErrorHandlerMixin

Constructor¤

CommandProcessor()

Creates a new command processor instance with feature logger.

Methods¤

All methods from ICommandProcessor plus:

_validate_command_structure(commands)¤

Validate command structure before processing (internal method).

Parameters: - commands (Dict[str, Any]): Dictionary containing command structure

Raises: - PantherException: If command structure is invalid

Pre-conditions: - Commands must be a dictionary - Command types must be strings - run_cmd must be a dictionary if present

Post-conditions: - Command structure is validated as correct - No side effects if validation passes

ShellCommand¤

Primary command representation with rich metadata.

Constructor¤

ShellCommand(command, metadata=None)

Parameters: - command (str): The shell command string - metadata (CommandMetadata, optional): Command metadata

Class Methods¤

from_string(command_str, is_critical=True)¤

Create ShellCommand from string with automatic property detection.

Parameters: - command_str (str): Command string to parse - is_critical (bool, optional): Whether command failure is critical. Defaults to True

Returns: - ShellCommand: New ShellCommand instance

Example:

cmd = ShellCommand.from_string("echo 'hello world'")
print(cmd.command)  # "echo 'hello world'"
print(cmd.metadata.is_critical)  # True

from_dict(command_dict)¤

Create ShellCommand from dictionary representation.

Parameters: - command_dict (Dict[str, Any]): Dictionary with command and metadata

Returns: - ShellCommand: New ShellCommand instance

Instance Methods¤

to_dict()¤

Convert ShellCommand to dictionary representation.

Returns: - Dict[str, Any]: Dictionary representation including command and metadata

escape_command()¤

Escape shell command for safe execution.

Returns: - str: Escaped command string

Post-conditions: - Command is safe for shell execution - Special characters are properly escaped

CommandMetadata¤

Metadata container for shell commands.

Attributes¤

Core Metadata: - is_critical (bool): Whether command failure is critical. Defaults to True - timeout (Optional[int]): Command timeout in seconds - retry_count (int): Number of retries on failure. Defaults to 0 - environment (Dict[str, str]): Environment variables - working_directory (Optional[str]): Working directory for execution - description (Optional[str]): Human-readable description - tags (List[str]): Command tags for categorization

Detection Metadata: - is_multiline (bool): Whether command spans multiple lines - is_function_definition (bool): Whether command defines a function - is_function_call (bool): Whether command calls a function - has_control_operators (bool): Whether command uses control operators - control_operators (List[str]): List of detected control operators - is_variable_assignment (bool): Whether command assigns variables - is_shell_builtin (bool): Whether command uses shell builtins

Builder Classes¤

CommandBuilder¤

Base builder for command construction using fluent interface.