From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 71560432D6;
Wed, 8 Nov 2023 13:53:57 +0100 (CET)
Received: from mails.dpdk.org (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id A48B542E22;
Wed, 8 Nov 2023 13:53:34 +0100 (CET)
Received: from mail-lf1-f50.google.com (mail-lf1-f50.google.com
[209.85.167.50]) by mails.dpdk.org (Postfix) with ESMTP id 3FCE542E0B
for <dev@dpdk.org>; Wed, 8 Nov 2023 13:53:30 +0100 (CET)
Received: by mail-lf1-f50.google.com with SMTP id
2adb3069b0e04-507bd644a96so9842807e87.3
for <dev@dpdk.org>; Wed, 08 Nov 2023 04:53:30 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=pantheon.tech; s=google; t=1699448009; x=1700052809; darn=dpdk.org;
h=content-transfer-encoding:mime-version:references:in-reply-to
:message-id:date:subject:cc:to:from:from:to:cc:subject:date
:message-id:reply-to;
bh=1nf+Rn9xF8AJgKgVM5dfS3bAeJ3oXogtFzeJDmarYnY=;
b=OMn38aXUuQ1HAeFB/8ObVWlwDvtY/87/nET0k564QP6hpCOOfP29rz4ejN5wojFCMg
84G+XwgHrQCRNH7WSWUWwTd0jQoN8ZbOgea5syqaUCoWM3KGjHoM2VqBSmmQuoBfxBSR
5qwt48Oyonx6FFb9OfUq09m2DBC3NKLjIboYfrqJ1LvuVcciydOnjsAha1tQa5f8iBmN
xU9f9IG7/a58ff5zU+U01T66b9uWPQ3gvJILJQa4dtenmJw1QwMWshoWrjuaRpoqrvAF
TFmGJ2tRccFiQqTy4kB2D58bNMAsOnVN7T/AyqCX0C3/wCUbY/4iPvpbE9qXypsdlx35
Gw0Q==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20230601; t=1699448010; x=1700052810;
h=content-transfer-encoding:mime-version:references:in-reply-to
:message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc
:subject:date:message-id:reply-to;
bh=1nf+Rn9xF8AJgKgVM5dfS3bAeJ3oXogtFzeJDmarYnY=;
b=IaOS2MtiUuI2ldxJapvxgeKfRMnZvUKUEJJCOXma0jGXyRUBeATOp+4Fq834veTlEE
gISvPLnngelue2DEOs9OyDhKiBbiqwTxwzmBuqLFTElHQXvSlCIu9UmUMDfzqVGV15SA
wRolLgo7Ixmg2PFjyp/2fC9mBf1Nawvg0XL524Nn1y10u/rtjwbWgKY3WI/4g6+Qwfmy
DNox9Uj5JOxb50RrJ8zOkI8x4zJq+CCQ1eOkvyD7oW0OZvOXU5BIbItTdGyUkejocQvO
4UMAYMLE++52Ip4ZnWAygO0gqodlAxImJvpqMJdijC8c8AMa257U0x6Us8Bn+iIW4ugj
8tcA==
X-Gm-Message-State: AOJu0YyttIUyA5Hdc6PB5WP7L/xP8z+DDrFIbmEI5xy7/OG1XO6q1jvb
Zpgz2WTRTMGzV/Mk6knD63KYGg==
X-Google-Smtp-Source: AGHT+IF6PN4p2bA0mcw6u0ImMYv/6aGvSKyVAKGaoZz7J0zk8WsCQw1GREOdkovbcFxOqlEIZh5YBg==
X-Received: by 2002:a05:6512:4811:b0:509:4405:d5a8 with SMTP id
eo17-20020a056512481100b005094405d5a8mr1205112lfb.68.1699448009601;
Wed, 08 Nov 2023 04:53:29 -0800 (PST)
Received: from jlinkes-PT-Latitude-5530.pantheon.local
(81.89.53.154.host.vnet.sk. [81.89.53.154])
by smtp.gmail.com with ESMTPSA id
v10-20020aa7dbca000000b0052ff9bae873sm6589289edt.5.2023.11.08.04.53.28
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Wed, 08 Nov 2023 04:53:29 -0800 (PST)
From: =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech>
To: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com,
bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu,
paul.szczepanek@arm.com, yoan.picchi@foss.arm.com
Cc: dev@dpdk.org, =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech>
Subject: [PATCH v6 04/23] dts: exceptions docstring update
Date: Wed, 8 Nov 2023 13:53:05 +0100
Message-Id: <20231108125324.191005-4-juraj.linkes@pantheon.tech>
X-Mailer: git-send-email 2.34.1
In-Reply-To: <20231108125324.191005-1-juraj.linkes@pantheon.tech>
References: <20231106171601.160749-1-juraj.linkes@pantheon.tech>
<20231108125324.191005-1-juraj.linkes@pantheon.tech>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
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(-)
diff --git a/dts/framework/__init__.py b/dts/framework/__init__.py
index d551ad4bf0..662e6ccad2 100644
--- a/dts/framework/__init__.py
+++ b/dts/framework/__init__.py
@@ -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.
+"""
diff --git a/dts/framework/exception.py b/dts/framework/exception.py
index 7489c03570..ee1562c672 100644
--- a/dts/framework/exception.py
+++ b/dts/framework/exception.py
@@ -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 exception 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,43 +96,53 @@ 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: "
f"{self._command_return_code}"
@@ -118,35 +150,41 @@ def __str__(self) -> str:
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."
--
2.34.1