[v7,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(-)
Comments
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š <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.
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."
On Mon, Nov 20, 2023 at 5:22 PM Yoan Picchi <yoan.picchi@foss.arm.com> wrote:
>
> 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š <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.
>
> 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 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."
>
@@ -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 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."