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 7CF0443380; Mon, 20 Nov 2023 17:36:01 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 012AB42DDE; Mon, 20 Nov 2023 17:36:01 +0100 (CET) Received: from mail-ed1-f54.google.com (mail-ed1-f54.google.com [209.85.208.54]) by mails.dpdk.org (Postfix) with ESMTP id 14F6842DD2 for ; Mon, 20 Nov 2023 17:35:59 +0100 (CET) Received: by mail-ed1-f54.google.com with SMTP id 4fb4d7f45d1cf-5484ef5e3d2so4404458a12.3 for ; Mon, 20 Nov 2023 08:35:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1700498158; x=1701102958; darn=dpdk.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=S/syRJCk3J5s0WSfCRcu16LNVkZVG6RduwZYgkJBxzY=; b=qT/M42CfmnqfVe7baqlpYGNoylPcID0LmoDC2lnE4jHeLi+NPSGqPJt9g969qx3w2L 2vOb63+VzwrEuFP6s+BhHJQc37pn3/tMOTyc3YFYFh5Io4w7BgJVonD6UC3t8Tl4YfTT 5fD3lM6paDsb+kqTBEQvxcGdWoLLTzMEsTACDSNWIWlFBo55BoQe0Qr2aNWQcALxXSRM o+Tqz62JXqdIKAPRXbiszvmUxmhD1Pl5Fh2OmIiB45v/HRaEo19J3RzVMC+/rPdoWKnp XiB3k6b1mgfZrLELFGTmqEQlbAw9GumMg/X3bEhIsAWr/5QEe9C9ePUBvppvAzyNIHP1 0WDg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700498158; x=1701102958; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=S/syRJCk3J5s0WSfCRcu16LNVkZVG6RduwZYgkJBxzY=; b=g3xBpslETOIhQ+egz2XcoIZ7Nrsyd81S6pcxY9YTtZyrJ2DzOBcY+woj2uUYduKeYf QG1F23uHL7YEaJXvPMrTGHQ+TMGxCOD5geky3vEeUPLzQ76X2jn+lS+48uJhVd4GPy/T WueHEm349cpTL0QORBTU69kUOVsg7mEWtkKGsK/pn2KO0v9olPM+6DUMshjZadh6afl5 UIRALJqQ/tUkUgzntNxxX1sts+8OFAjrXf0BQI4cJ7DrZsFPq5ukqV2bi/vvKl/s2wkE 96rUhDL3HmPJKveFqnYopCupmVG1ASIxooeXdal7jukGzOLCTw5Arp8K4+GdcnaSUur/ JUfw== X-Gm-Message-State: AOJu0Yx2BVMx3RoD9ggy6GvGG91rewv0VFbgIUIzxeEaKuhBGqS4BZFB q4CRTQQBlG9UWYhkk+cMvTxACKRPW6TimBT2YCbDwg== X-Google-Smtp-Source: AGHT+IHFR0hGzUUlxxd6k9htNkpAPanS/2Qtdu07SOhtx2GqYTHjmeKND2g/DiKNYGqaFl0SxAD4512OaVyR2A7hbdA= X-Received: by 2002:a17:906:73d7:b0:9fe:4acc:d2e2 with SMTP id n23-20020a17090673d700b009fe4accd2e2mr2502103ejl.39.1700498158199; Mon, 20 Nov 2023 08:35:58 -0800 (PST) MIME-Version: 1.0 References: <20231108125324.191005-23-juraj.linkes@pantheon.tech> <20231115130959.39420-1-juraj.linkes@pantheon.tech> <20231115130959.39420-5-juraj.linkes@pantheon.tech> In-Reply-To: From: =?UTF-8?Q?Juraj_Linke=C5=A1?= Date: Mon, 20 Nov 2023 17:35:47 +0100 Message-ID: Subject: Re: [PATCH v7 04/21] dts: exceptions docstring update To: Yoan Picchi Cc: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com, dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 Mon, Nov 20, 2023 at 5:22=E2=80=AFPM Yoan Picchi wrote: > > On 11/15/23 13:09, Juraj Linke=C5=A1 wrote: > > Format according to the Google format and PEP257, with slight > > deviations. > > > > Signed-off-by: Juraj Linke=C5=A1 > > --- > > 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* > Ack, will fix. > > """ > > > > 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 re= turn code. > > """ > > > > + #: > > NO_ERR =3D 0 > > + #: > > GENERIC_ERR =3D 1 > > + #: > > CONFIG_ERR =3D 2 > > + #: > > REMOTE_CMD_EXEC_ERR =3D 3 > > + #: > > SSH_ERR =3D 4 > > + #: > > DPDK_BUILD_ERR =3D 10 > > + #: > > TESTCASE_VERIFY_ERR =3D 20 > > + #: > > BLOCKING_TESTSUITE_ERR =3D 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] =3D ErrorSeverity.GENERIC_ERR > > > > > > class SSHTimeoutError(DTSError): > > - """ > > - Command execution timeout. > > - """ > > + """The SSH execution of a command timed out.""" > > > > + #: > > severity: ClassVar[ErrorSeverity] =3D ErrorSeverity.SSH_ERR > > _command: str > > > > def __init__(self, command: str): > > + """Define the meaning of the first argument. > > + > > + Args: > > + command: The executed command. > > + """ > > self._command =3D 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] =3D ErrorSeverity.SSH_ERR > > _host: str > > _errors: list[str] > > > > def __init__(self, host: str, errors: list[str] | None =3D 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 att= empt. > > + """ > > self._host =3D host > > self._errors =3D [] if errors is None else errors > > > > def __str__(self) -> str: > > + """Include the errors in the string representation.""" > > message =3D f"Error trying to connect with {self._host}." > > if self._errors: > > message +=3D 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] =3D 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 =3D 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] =3D ErrorSeverity.CONFIG_ERR > > > > > > class RemoteCommandExecutionError(DTSError): > > - """ > > - Raised when a command executed on a Node returns a non-zero exit s= tatus. > > - """ > > + """An unsuccessful execution of a remote command.""" > > > > + #: > > severity: ClassVar[ErrorSeverity] =3D ErrorSeverity.REMOTE_CMD_EX= EC_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 comma= nd. > > + """ > > self.command =3D command > > self._command_return_code =3D command_return_code > > > > def __str__(self) -> str: > > + """Include both the command and return code in the string repr= esentation.""" > > 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] =3D ErrorSeverity.REMOTE_CMD_EX= EC_ERR > > > > > > class DPDKBuildError(DTSError): > > - """ > > - Raised when DPDK build fails for any reason. > > - """ > > + """A DPDK build failure.""" > > > > + #: > > severity: ClassVar[ErrorSeverity] =3D ErrorSeverity.DPDK_BUILD_ER= R > > > > > > class TestCaseVerifyError(DTSError): > > - """ > > - Used in test cases to verify the expected behavior. > > - """ > > + """A test case failure.""" > > > > + #: > > severity: ClassVar[ErrorSeverity] =3D ErrorSeverity.TESTCASE_VERI= FY_ERR > > > > > > class BlockingTestSuiteError(DTSError): > > + """A failure in a blocking test suite.""" > > + > > + #: > > severity: ClassVar[ErrorSeverity] =3D ErrorSeverity.BLOCKING_TEST= SUITE_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 =3D suite_name > > > > def __str__(self) -> str: > > + """Add some context to the string representation.""" > > return f"Blocking suite {self._suite_name} failed." >