📚 Shell Class Documentation

Overview

The Shell class is an abstract base class (ABC) that provides a framework for executing shell commands with consistent logging, context management, and error handling. It implements the Template Method pattern for command execution and allows different shell implementations to define their own command formatting strategies.

Class: Shell

Inheritance

• Inherits from ABC (Abstract Base Class)

Constructor Parameters

Attributes

Abstract Methods

Abstract method that must be implemented by child classes to define how the final command list should be formatted (Strategy pattern).

Parameters:

• executable (str): The executable/command to run
• args (list[str]): List of command arguments

Returns:

• list[str]: Formatted command list ready for execution

Public Methods

__enter__() -> Shell

Context manager entry method. Logs the start of a shell session.

Returns:

• Shell: The shell instance

Logging:

• Info: "Iniciando sesión de {ShellClassName}"

__exit__(exc_type, exc_val, exc_tb)

Context manager exit method. Logs session termination, including any errors that occurred.

Parameters:

• exc_type: Exception type if an error occurred
• exc_val: Exception value if an error occurred
• exc_tb: Exception traceback if an error occurred

Logging:

• Error: "Sesión finalizada con error: {exc_val}" (if exception occurred)
• Info: "Sesión de {ShellClassName} finalizada correctamente" (if no exception)

run(command, timeout: Optional[float] = None) -> CommandResult

Template method that coordinates the command execution process.

Parameters:

• command: Command object containing executable and arguments
• timeout (Optional[float]): Custom timeout in seconds. If not provided, uses default_timeout

Returns:

• CommandResult: Object containing command execution results

Process Flow:

1. Lazy Binary Check: Verifies if the executable exists in PATH
2. Command Formatting: Calls _format_command() to prepare the final command list
3. Execution: Runs the command using subprocess.run() with:
   • Working directory from context
   • Environment variables from context
   • Captured stdout/stderr
   • Specified encoding
   • Timeout control
4. Result Processing: Creates and returns a CommandResult object

Exceptions:

• CommandNotFoundError: Raised when the executable is not found in PATH
• subprocess.TimeoutExpired: Raised when command execution exceeds timeout

Logging:

• Debug: "Executing: {command} in {working_directory}"
• Info: "Success: {executable}" (if command succeeds)
• Warning: "Failed: {executable} with code {return_code}" (if command fails)
• Error: "Timeout after {timeout}s" (if timeout occurs)

Usage Example

# Create a concrete shell implementation
class BashShell(Shell):
    def _format_command(self, executable: str, args: list[str]) -> list[str]:
        return [executable] + args

# Use the shell
with BashShell(logger=my_logger, default_timeout=60.0) as shell:
    result = shell.run(my_command, timeout=30.0)
    if result.is_success():
        print(f"Output: {result.standard_output}")
    

Design Patterns Used

Dependencies

• subprocess: For command execution
• shutil: For binary path checking
• time: For execution time measurement
• abc: For abstract base class functionality