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 C8D634366A;
	Mon,  4 Dec 2023 11:25:03 +0100 (CET)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 0AE5340EE3;
	Mon,  4 Dec 2023 11:24:38 +0100 (CET)
Received: from mail-wm1-f52.google.com (mail-wm1-f52.google.com
 [209.85.128.52]) by mails.dpdk.org (Postfix) with ESMTP id 13F7040DFD
 for <dev@dpdk.org>; Mon,  4 Dec 2023 11:24:35 +0100 (CET)
Received: by mail-wm1-f52.google.com with SMTP id
 5b1f17b1804b1-40c0a0d068bso9348645e9.3
 for <dev@dpdk.org>; Mon, 04 Dec 2023 02:24:35 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=pantheon.tech; s=google; t=1701685475; x=1702290275; 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=wjMjWbqHGp5MGkpbw1QW6JBQYnzdCysgXfdMDvK6Qbg=;
 b=fzU2oe/pG6/IGYfICjfR+Mp9t9whuma974IRdA1e+XT84na+IWE0xS7vuUq3XaWwku
 VeXKKDHgG0N9ZLgbdADBHtp/jqvyXEcQZeZyC+v8BN9L+5RIxPBrMRgHJRGmyxo0fkzb
 xCmK0SUxCJz140ARiCspQEEcnHF4jZkqAXxk/9OnLXA5A5DwvqiOwnclYG5y8JNiMVxH
 ITfh5FfJwqGailpq/oQeflpDMgnH4W60rDdOt54Fgfrr1YZMnmks2W+oH/Nwi1e8HcuB
 /jF+Z7vam5hSl8V9kGu0Nl638lyQyQFiv8/waZXM/sdJVR10uCzUqlbXIb07c5TfOmzK
 oPGw==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1701685475; x=1702290275;
 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=wjMjWbqHGp5MGkpbw1QW6JBQYnzdCysgXfdMDvK6Qbg=;
 b=nRuvpEuqRT1Ph0zig9dltQ9le4lermChxzfz+GjPhyT0MGcLNo1X9Y/agYazYM3DJc
 VYBMViyKZQIZRPFbeKGPk3wXzwobAg8UGLtWsQN/TLqyPJYhAg9PyQ5B5u5BRvB1qpaQ
 JoO0YjW5j7p4OhLyNGoYcs/7qfN/GoA7rZbYZQA+9IkvEewv6vEySAw65sponAeMw7+p
 qq4ONjb7EQXs1E85gphDEFONFi+RO8iPUi9jHe5GRoScV39C0+4zRKShQm5AKEc4RDb1
 c030OBeZ5XsjPxxHAW9QaVX3yuggJV7/lPIeXzoNhZTTvGTqBS+CTNaO2WiaabuZWHQM
 fs/g==
X-Gm-Message-State: AOJu0Yy7sJyiCptC4Z8wU7RtSnXfh+GUmHLi1Hg8+ZAg8B4ZX6cdkcRS
 Wt/Y1ZviV5jogjP6Yz7SE12nWZCGbD53FsOTYu6Xqg==
X-Google-Smtp-Source: AGHT+IGaGs0FZxrwDYbWJQATu/K8Z36MXHSUfB+ZUPd1A0nrLyRum/JsrZRq9yBlWYzmn0C/kQc6jQ==
X-Received: by 2002:a05:600c:520e:b0:40b:5e22:97c with SMTP id
 fb14-20020a05600c520e00b0040b5e22097cmr3123453wmb.107.1701685474711; 
 Mon, 04 Dec 2023 02:24:34 -0800 (PST)
Received: from jlinkes-PT-Latitude-5530.pantheon.local ([81.89.53.154])
 by smtp.gmail.com with ESMTPSA id
 m28-20020a05600c3b1c00b0040b2b38a1fasm14255415wms.4.2023.12.04.02.24.33
 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
 Mon, 04 Dec 2023 02:24:34 -0800 (PST)
From: =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech>
To: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu,
 probb@iol.unh.edu, paul.szczepanek@arm.com, yoan.picchi@foss.arm.com,
 Luca.Vizzarro@arm.com
Cc: dev@dpdk.org, =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech>
Subject: [PATCH v9 04/21] dts: exceptions docstring update
Date: Mon,  4 Dec 2023 11:24:12 +0100
Message-Id: <20231204102429.106709-5-juraj.linkes@pantheon.tech>
X-Mailer: git-send-email 2.34.1
In-Reply-To: <20231204102429.106709-1-juraj.linkes@pantheon.tech>
References: <20231123151344.162812-1-juraj.linkes@pantheon.tech>
 <20231204102429.106709-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 151e4d3aa9..658eee2c38 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 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."
-- 
2.34.1