From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 12BFA43380; Mon, 20 Nov 2023 17:22:44 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id EF29242DDE; Mon, 20 Nov 2023 17:22:41 +0100 (CET) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mails.dpdk.org (Postfix) with ESMTP id 8514B42DD2 for ; Mon, 20 Nov 2023 17:22:40 +0100 (CET) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 561C9FEC; Mon, 20 Nov 2023 08:23:26 -0800 (PST) Received: from [10.57.74.8] (unknown [10.57.74.8]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 5DB723F6C4; Mon, 20 Nov 2023 08:22:38 -0800 (PST) Message-ID: Date: Mon, 20 Nov 2023 16:22:38 +0000 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v7 04/21] dts: exceptions docstring update Content-Language: en-US To: =?UTF-8?Q?Juraj_Linke=C5=A1?= , thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com Cc: dev@dpdk.org References: <20231108125324.191005-23-juraj.linkes@pantheon.tech> <20231115130959.39420-1-juraj.linkes@pantheon.tech> <20231115130959.39420-5-juraj.linkes@pantheon.tech> From: Yoan Picchi In-Reply-To: <20231115130959.39420-5-juraj.linkes@pantheon.tech> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org On 11/15/23 13:09, Juraj Linkeš wrote: > Format according to the Google format and PEP257, with slight > deviations. > > Signed-off-by: Juraj Linkeš > --- > 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. all raised exception*s* > """ > > 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."