[v7,04/21] dts: exceptions docstring update

  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(-)
  

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."
>