Format according to the Google format and PEP257, with slight
deviations.
Signed-off-by: Juraj Linkeš <juraj.lin...@pantheon.tech>
---
dts/framework/remote_session/__init__.py | 39 +++++-
.../remote_session/remote_session.py | 128 +++++++++++++-----
dts/framework/remote_session/ssh_session.py | 16 +--
3 files changed, 135 insertions(+), 48 deletions(-)
diff --git a/dts/framework/remote_session/__init__.py
b/dts/framework/remote_session/__init__.py
index 5e7ddb2b05..51a01d6b5e 100644
--- a/dts/framework/remote_session/__init__.py
+++ b/dts/framework/remote_session/__init__.py
@@ -2,12 +2,14 @@
# Copyright(c) 2023 PANTHEON.tech s.r.o.
# Copyright(c) 2023 University of New Hampshire
-"""
-The package provides modules for managing remote connections to a remote host
(node),
-differentiated by OS.
-The package provides a factory function, create_session, that returns the
appropriate
-remote connection based on the passed configuration. The differences are in the
-underlying transport protocol (e.g. SSH) and remote OS (e.g. Linux).
+"""Remote interactive and non-interactive sessions.
+
+This package provides modules for managing remote connections to a remote host
(node).
+
+The non-interactive sessions send commands and return their output and exit
code.
+
+The interactive sessions open an interactive shell which is continuously open,
+allowing it to send and receive data within that particular shell.
"""
# pylama:ignore=W0611
@@ -26,10 +28,35 @@
def create_remote_session(
node_config: NodeConfiguration, name: str, logger: DTSLOG
) -> RemoteSession:
+ """Factory for non-interactive remote sessions.
+
+ The function returns an SSH session, but will be extended if support
+ for other protocols is added.
+
+ Args:
+ node_config: The test run configuration of the node to connect to.
+ name: The name of the session.
+ logger: The logger instance this session will use.
+
+ Returns:
+ The SSH remote session.
+ """
return SSHSession(node_config, name, logger)
def create_interactive_session(
node_config: NodeConfiguration, logger: DTSLOG
) -> InteractiveRemoteSession:
+ """Factory for interactive remote sessions.
+
+ The function returns an interactive SSH session, but will be extended if
support
+ for other protocols is added.
+
+ Args:
+ node_config: The test run configuration of the node to connect to.
+ logger: The logger instance this session will use.
+
+ Returns:
+ The interactive SSH remote session.
+ """
return InteractiveRemoteSession(node_config, logger)
diff --git a/dts/framework/remote_session/remote_session.py
b/dts/framework/remote_session/remote_session.py
index 0647d93de4..629c2d7b9c 100644
--- a/dts/framework/remote_session/remote_session.py
+++ b/dts/framework/remote_session/remote_session.py
@@ -3,6 +3,13 @@
# Copyright(c) 2022-2023 PANTHEON.tech s.r.o.
# Copyright(c) 2022-2023 University of New Hampshire
+"""Base remote session.
+
+This module contains the abstract base class for remote sessions and defines
+the structure of the result of a command execution.
+"""
+
+
import dataclasses
from abc import ABC, abstractmethod
from pathlib import PurePath
@@ -15,8 +22,14 @@
@dataclasses.dataclass(slots=True, frozen=True)
class CommandResult:
- """
- The result of remote execution of a command.
+ """The result of remote execution of a command.
+
+ Attributes:
+ name: The name of the session that executed the command.
+ command: The executed command.
+ stdout: The standard output the command produced.
+ stderr: The standard error output the command produced.
+ return_code: The return code the command exited with.
"""
name: str
@@ -26,6 +39,7 @@ class CommandResult:
return_code: int
def __str__(self) -> str:
+ """Format the command outputs."""
return (
f"stdout: '{self.stdout}'\n"
f"stderr: '{self.stderr}'\n"
@@ -34,13 +48,24 @@ def __str__(self) -> str:
class RemoteSession(ABC):
- """
- The base class for defining which methods must be implemented in order to
connect
- to a remote host (node) and maintain a remote session. The derived classes
are
- supposed to implement/use some underlying transport protocol (e.g. SSH) to
- implement the methods. On top of that, it provides some basic services
common to
- all derived classes, such as keeping history and logging what's being
executed
- on the remote node.
+ """Non-interactive remote session.
+
+ The abstract methods must be implemented in order to connect to a remote
host (node)
+ and maintain a remote session.
+ The subclasses must use (or implement) some underlying transport protocol
(e.g. SSH)
+ to implement the methods. On top of that, it provides some basic services
common to all
+ subclasses, such as keeping history and logging what's being executed on
the remote node.
+
+ Attributes:
+ name: The name of the session.
+ hostname: The node's hostname. Could be an IP (possibly with port,
separated by a colon)
+ or a domain name.
+ ip: The IP address of the node or a domain name, whichever was used in
`hostname`.
+ port: The port of the node, if given in `hostname`.
+ username: The username used in the connection.
+ password: The password used in the connection. Most frequently empty,
+ as the use of passwords is discouraged.
+ history: The executed commands during this session.
"""
name: str
@@ -59,6 +84,16 @@ def __init__(
session_name: str,
logger: DTSLOG,
):
+ """Connect to the node during initialization.
+
+ Args:
+ node_config: The test run configuration of the node to connect to.
+ session_name: The name of the session.
+ logger: The logger instance this session will use.
+
+ Raises:
+ SSHConnectionError: If the connection to the node was not
successful.
+ """
self._node_config = node_config
self.name = session_name
@@ -79,8 +114,13 @@ def __init__(
@abstractmethod
def _connect(self) -> None:
- """
- Create connection to assigned node.
+ """Create a connection to the node.
+
+ The implementation must assign the established session to self.session.
+
+ The implementation must except all exceptions and convert them to an
SSHConnectionError.
+
+ The implementation may optionally implement retry attempts.
"""
def send_command(
@@ -90,11 +130,24 @@ def send_command(
verify: bool = False,
env: dict | None = None,
) -> CommandResult:
- """
- Send a command to the connected node using optional env vars
- and return CommandResult.
- If verify is True, check the return code of the executed command
- and raise a RemoteCommandExecutionError if the command failed.
+ """Send `command` to the connected node.
+
+ The :option:`--timeout` command line argument and the
:envvar:`DTS_TIMEOUT`
+ environment variable configure the timeout of command execution.
+
+ Args:
+ command: The command to execute.
+ timeout: Wait at most this long in seconds to execute `command`.
+ verify: If :data:`True`, will check the exit code of `command`.
+ env: A dictionary with environment variables to be used with
`command` execution.
+
+ Raises:
+ SSHSessionDeadError: If the session isn't alive when sending
`command`.
+ SSHTimeoutError: If `command` execution timed out.
+ RemoteCommandExecutionError: If verify is :data:`True` and
`command` execution failed.
+
+ Returns:
+ The output of the command along with the return code.
"""
self._logger.info(
f"Sending: '{command}'" + (f" with env vars: '{env}'" if env else
"")
@@ -115,29 +168,36 @@ def send_command(
def _send_command(
self, command: str, timeout: float, env: dict | None
) -> CommandResult:
- """
- Use the underlying protocol to execute the command using optional env
vars
- and return CommandResult.
+ """Send a command to the connected node.
+
+ The implementation must execute the command remotely with `env`
environment variables
+ and return the result.
+
+ The implementation must except all exceptions and raise an
SSHSessionDeadError if
+ the session is not alive and an SSHTimeoutError if the command
execution times out.
