interactive_shell - Base Interactive Remote Shell

Common functionality for interactive shell handling.

The base class, InteractiveShell, is meant to be extended by subclasses that contain functionality specific to that shell type. These subclasses will often modify things like the prompt to expect or the arguments to pass into the application, but still utilize the same method for sending a command and collecting output. How this output is handled however is often application specific. If an application needs elevated privileges to start it is expected that the method for gaining those privileges is provided when initializing the class.

This class is designed for applications like primary applications in DPDK where only one instance of the application can be running at a given time and, for this reason, is managed using a context manager. This context manager starts the application when you enter the context and cleans up the application when you exit. Using a context manager for this is useful since it allows us to ensure the application is cleaned up as soon as you leave the block regardless of the reason.

The --timeout command line argument and the DTS_TIMEOUT environment variable configure the timeout of getting the output from command execution.

only_active(func: Callable[[Concatenate[T, P]], R]) → Callable[[Concatenate[T, P]], R]

This decorator will skip running the method if the SSH channel is not active.

class InteractiveShell

Bases: ABC

The base class for managing interactive shells.

This class shouldn’t be instantiated directly, but instead be extended. It contains methods for starting interactive shells as well as sending commands to these shells and collecting input until reaching a certain prompt. All interactive applications will use the same SSH connection, but each will create their own channel on that session.

Interactive shells are started and stopped using a context manager. This allows for the start and cleanup of the application to happen at predictable times regardless of exceptions or interrupts.

is_alive

True if the application has started successfully, False otherwise.

Type:

bool

__init__(node: Node, name: str | None = None, privileged: bool = False, app_params: Params = Params()) → None

Create an SSH channel during initialization.

Parameters:

  • node (Node) – The node on which to run start the interactive shell.

  • name (str | None) – Name for the interactive shell to use for logging. This name will be appended to the name of the underlying node which it is running on.

  • privileged (bool) – Enables the shell to run as superuser.

  • app_params (Params) – The command line parameters to be passed to the application on startup.

start_application(prompt: str | None = None) → None

Starts a new interactive application based on the path to the app.

This method is often overridden by subclasses as their process for starting may look different. Initialization of the shell on the host can be retried up to self._init_attempts - 1 times. This is done because some DPDK applications need slightly more time after exiting their script to clean up EAL before others can start.

Parameters:

prompt (str | None) – When starting up the application, expect this string at the end of stdout when the application is ready. If None, the class’ default prompt will be used.

Raises:

InteractiveCommandExecutionError – If the application fails to start within the allotted number of retries.

send_command(command: str, prompt: str | None = None, skip_first_line: bool = False) → str

Send command and get all output before the expected ending string.

Lines that expect input are not included in the stdout buffer, so they cannot be used for expect.

Example

If you were prompted to log into something with a username and password, you cannot expect username: because it won’t yet be in the stdout buffer. A workaround for this could be consuming an extra newline character to force the current prompt into the stdout buffer.

Parameters:

  • command (str) – The command to send.

  • prompt (str | None) – After sending the command, send_command will be expecting this string. If None, will use the class’s default prompt.

  • skip_first_line (bool) – Skip the first line when capturing the output.

Returns:

All output in the buffer before expected string.

Raises:
Return type:

str

abstract property path: PurePath

Path to the shell executable.