[v8,04/21] dts: exceptions docstring update
Checks
Commit Message
Format according to the Google format and PEP257, with slight
deviations.
Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
---
dts/framework/__init__.py | 12 ++++-
dts/framework/exception.py | 106 +++++++++++++++++++++++++------------
2 files changed, 83 insertions(+), 35 deletions(-)
@@ -1,3 +1,13 @@
# SPDX-License-Identifier: BSD-3-Clause
-# Copyright(c) 2022 PANTHEON.tech s.r.o.
+# Copyright(c) 2022-2023 PANTHEON.tech s.r.o.
# Copyright(c) 2022 University of New Hampshire
+
+"""Libraries and utilities for running DPDK Test Suite (DTS).
+
+The various modules in the DTS framework offer:
+
+* Connections to nodes, both interactive and non-interactive,
+* A straightforward way to add support for different operating systems of remote nodes,
+* Test suite setup, execution and teardown, along with test case setup, execution and teardown,
+* Pre-test suite setup and post-test suite teardown.
+"""
@@ -3,8 +3,10 @@
# Copyright(c) 2022-2023 PANTHEON.tech s.r.o.
# Copyright(c) 2022-2023 University of New Hampshire
-"""
-User-defined exceptions used across the framework.
+"""DTS exceptions.
+
+The exceptions all have different severities expressed as an integer.
+The highest severity of all raised exceptions is used as the exit code of DTS.
"""
from enum import IntEnum, unique
@@ -13,59 +15,79 @@
@unique
class ErrorSeverity(IntEnum):
- """
- The severity of errors that occur during DTS execution.
+ """The severity of errors that occur during DTS execution.
+
All exceptions are caught and the most severe error is used as return code.
"""
+ #:
NO_ERR = 0
+ #:
GENERIC_ERR = 1
+ #:
CONFIG_ERR = 2
+ #:
REMOTE_CMD_EXEC_ERR = 3
+ #:
SSH_ERR = 4
+ #:
DPDK_BUILD_ERR = 10
+ #:
TESTCASE_VERIFY_ERR = 20
+ #:
BLOCKING_TESTSUITE_ERR = 25
class DTSError(Exception):
- """
- The base exception from which all DTS exceptions are derived.
- Stores error severity.
+ """The base exception from which all DTS exceptions are subclassed.
+
+ Do not use this exception, only use subclassed exceptions.
"""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.GENERIC_ERR
class SSHTimeoutError(DTSError):
- """
- Command execution timeout.
- """
+ """The SSH execution of a command timed out."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.SSH_ERR
_command: str
def __init__(self, command: str):
+ """Define the meaning of the first argument.
+
+ Args:
+ command: The executed command.
+ """
self._command = command
def __str__(self) -> str:
- return f"TIMEOUT on {self._command}"
+ """Add some context to the string representation."""
+ return f"{self._command} execution timed out."
class SSHConnectionError(DTSError):
- """
- SSH connection error.
- """
+ """An unsuccessful SSH connection."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.SSH_ERR
_host: str
_errors: list[str]
def __init__(self, host: str, errors: list[str] | None = None):
+ """Define the meaning of the first two arguments.
+
+ Args:
+ host: The hostname to which we're trying to connect.
+ errors: Any errors that occurred during the connection attempt.
+ """
self._host = host
self._errors = [] if errors is None else errors
def __str__(self) -> str:
+ """Include the errors in the string representation."""
message = f"Error trying to connect with {self._host}."
if self._errors:
message += f" Errors encountered while retrying: {', '.join(self._errors)}"
@@ -74,76 +96,92 @@ def __str__(self) -> str:
class SSHSessionDeadError(DTSError):
- """
- SSH session is not alive.
- It can no longer be used.
- """
+ """The SSH session is no longer alive."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.SSH_ERR
_host: str
def __init__(self, host: str):
+ """Define the meaning of the first argument.
+
+ Args:
+ host: The hostname of the disconnected node.
+ """
self._host = host
def __str__(self) -> str:
- return f"SSH session with {self._host} has died"
+ """Add some context to the string representation."""
+ return f"SSH session with {self._host} has died."
class ConfigurationError(DTSError):
- """
- Raised when an invalid configuration is encountered.
- """
+ """An invalid configuration."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.CONFIG_ERR
class RemoteCommandExecutionError(DTSError):
- """
- Raised when a command executed on a Node returns a non-zero exit status.
- """
+ """An unsuccessful execution of a remote command."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.REMOTE_CMD_EXEC_ERR
+ #: The executed command.
command: str
_command_return_code: int
def __init__(self, command: str, command_return_code: int):
+ """Define the meaning of the first two arguments.
+
+ Args:
+ command: The executed command.
+ command_return_code: The return code of the executed command.
+ """
self.command = command
self._command_return_code = command_return_code
def __str__(self) -> str:
+ """Include both the command and return code in the string representation."""
return f"Command {self.command} returned a non-zero exit code: {self._command_return_code}"
class RemoteDirectoryExistsError(DTSError):
- """
- Raised when a remote directory to be created already exists.
- """
+ """A directory that exists on a remote node."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.REMOTE_CMD_EXEC_ERR
class DPDKBuildError(DTSError):
- """
- Raised when DPDK build fails for any reason.
- """
+ """A DPDK build failure."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.DPDK_BUILD_ERR
class TestCaseVerifyError(DTSError):
- """
- Used in test cases to verify the expected behavior.
- """
+ """A test case failure."""
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.TESTCASE_VERIFY_ERR
class BlockingTestSuiteError(DTSError):
+ """A failure in a blocking test suite."""
+
+ #:
severity: ClassVar[ErrorSeverity] = ErrorSeverity.BLOCKING_TESTSUITE_ERR
_suite_name: str
def __init__(self, suite_name: str) -> None:
+ """Define the meaning of the first argument.
+
+ Args:
+ suite_name: The blocking test suite.
+ """
self._suite_name = suite_name
def __str__(self) -> str:
+ """Add some context to the string representation."""
return f"Blocking suite {self._suite_name} failed."