Extend ExecResult API

* property `ok`
* methods `check_exit_code` and `raise_for_status`

Author: penguinolog

.pylintrc

@@ -31,8 +31,6 @@ limit-inference-results=100
 load-plugins=pylint.extensions.docparams,
              pylint.extensions.docstyle,
              pylint.extensions.overlapping_exceptions,
-             pylint.extensions.emptystring,
-             pylint.extensions.comparetozero,
              pylint.extensions.check_elif,
              pylint.extensions.for_any_all,
              pylint.extensions.code_style,
@@ -90,6 +88,8 @@ disable=locally-disabled,
         broad-except,
         logging-fstring-interpolation,
         logging-format-interpolation,
+        consider-alternative-union-syntax,
+        deprecated-typing-alias,
         invalid-name
 
 # Enable the message, report, category or checker with the given id(s). You can

doc/source/ExecResult.rst

@@ -126,6 +126,38 @@ API: ExecResult
 
         :rtype: int | ExitCodes
 
+    .. py:attribute:: ok
+
+        ``bool``
+
+        Exit code is EX_OK
+
+    .. py:method:: check_exit_code(expected_codes=(0,), raise_on_err=True, error_info=None, exception_class=CalledProcessError, logger=LOGGER)
+
+        Check exit code and log/raise for unexpected code.
+
+        :param error_info: optional additional error information
+        :type error_info: str | None
+        :param raise_on_err: raise `exception_class` in case of error
+        :type raise_on_err: bool
+        :param expected_codes: iterable expected exit codes
+        :type expected_codes: Iterable[int | ExitCodes]
+        :param exception_class: exception class for usage in case of errors (subclass of CalledProcessError)
+        :type exception_class: type[exceptions.CalledProcessError]
+        :param logger: logger instance for error log
+        :type logger: logging.Logger
+        :raises exceptions.CalledProcessError: unexpected exit code and raise_on_err enabled
+
+    .. py:method:: raise_for_status(expected_codes=(0,), exception_class=CalledProcessError)
+
+        Requests-like exit code checker.
+
+        :param expected_codes: iterable expected exit codes
+        :type expected_codes: Iterable[int | ExitCodes]
+        :param exception_class: exception class for usage in case of errors (subclass of CalledProcessError)
+        :type exception_class: type[exceptions.CalledProcessError]
+        :raises exceptions.CalledProcessError: unexpected exit code and raise_on_err enabled
+
     .. py:attribute:: started
 
         ``datetime.datetime``

exec_helpers/api.py

@@ -527,7 +527,7 @@ def execute(
         self.logger.log(level=log_level, msg=f"Command {result.cmd!r} exit code: {result.exit_code!s}")
         return result
 
-    def __call__(  # pylint: disable=arguments-differ
+    def __call__(
         self,
         command: CommandT,
         verbose: bool = False,
@@ -658,48 +658,13 @@ def check_call(
             log_stderr=log_stderr,
             **kwargs,
         )
-        return self._handle_exit_code(
-            result=result,
+        result.check_exit_code(
+            expected_codes,
+            raise_on_err,
             error_info=error_info,
-            expected_codes=expected_codes,
-            raise_on_err=raise_on_err,
             exception_class=exception_class,
+            logger=self.logger,
         )
-
-    def _handle_exit_code(
-        self,
-        *,
-        result: exec_result.ExecResult,
-        error_info: ErrorInfoT,
-        expected_codes: ExpectedExitCodesT,
-        raise_on_err: bool,
-        exception_class: CalledProcessErrorSubClassT,
-    ) -> exec_result.ExecResult:
-        """Internal check_call logic (synchronous).
-
-        :param result: execution result for validation
-        :type result: exec_result.ExecResult
-        :param error_info: optional additional error information
-        :type error_info: str | None
-        :param raise_on_err: raise `exception_class` in case of error
-        :type raise_on_err: bool
-        :param expected_codes: iterable expected exit codes
-        :type expected_codes: Iterable[int | ExitCodes]
-        :param exception_class: exception class for usage in case of errors (subclass of CalledProcessError)
-        :type exception_class: type[exceptions.CalledProcessError]
-        :return: execution result
-        :rtype: exec_result.ExecResult
-        :raises exceptions.CalledProcessError: stderr presents and raise_on_err enabled
-        """
-        append: str = error_info + "\n" if error_info else ""
-        if result.exit_code not in expected_codes:
-            message = (
-                f"{append}Command {result.cmd!r} returned exit code {result.exit_code!s} "
-                f"while expected {expected_codes!s}"
-            )
-            self.logger.error(msg=message)
-            if raise_on_err:
-                raise exception_class(result=result, expected=expected_codes)
         return result
 
     def check_stderr(

exec_helpers/async_api/api.py

@@ -481,7 +481,7 @@ async def execute(
         self.logger.log(level=log_level, msg=f"Command {result.cmd!r} exit code: {result.exit_code!s}")
         return result
 
-    async def __call__(  # pylint: disable=invalid-overridden-method,arguments-differ
+    async def __call__(  # pylint: disable=invalid-overridden-method
         self,
         command: CommandT,
         verbose: bool = False,
@@ -610,48 +610,13 @@ async def check_call(
             log_stderr=log_stderr,
             **kwargs,
         )
-        return self._handle_exit_code(
-            result=result,
+        result.check_exit_code(
+            expected_codes,
+            raise_on_err,
             error_info=error_info,
-            expected_codes=expected_codes,
-            raise_on_err=raise_on_err,
             exception_class=exception_class,
+            logger=self.logger,
         )
-
-    def _handle_exit_code(
-        self,
-        *,
-        result: exec_result.ExecResult,
-        error_info: ErrorInfoT,
-        expected_codes: ExpectedExitCodesT,
-        raise_on_err: bool,
-        exception_class: CalledProcessErrorSubClassT,
-    ) -> exec_result.ExecResult:
-        """Internal check_call logic (synchronous).
-
-        :param result: execution result for validation
-        :type result: exec_result.ExecResult
-        :param error_info: optional additional error information
-        :type error_info: str | None
-        :param raise_on_err: raise `exception_class` in case of error
-        :type raise_on_err: bool
-        :param expected_codes: iterable expected exit codes
-        :type expected_codes: Iterable[int | ExitCodes]
-        :param exception_class: exception class for usage in case of errors (subclass of CalledProcessError)
-        :type exception_class: type[exceptions.CalledProcessError]
-        :return: execution result
-        :rtype: exec_result.ExecResult
-        :raises exceptions.CalledProcessError: stderr presents and raise_on_err enabled
-        """
-        append: str = error_info + "\n" if error_info else ""
-        if result.exit_code not in expected_codes:
-            message = (
-                f"{append}Command {result.cmd!r} returned exit code {result.exit_code!s} "
-                f"while expected {expected_codes!s}"
-            )
-            self.logger.error(msg=message)
-            if raise_on_err:
-                raise exception_class(result=result, expected=expected_codes)
         return result
 
     async def check_stderr(

exec_helpers/exec_result.py

@@ -52,6 +52,7 @@
 if typing.TYPE_CHECKING:
     import xml.etree.ElementTree  # nosec  # for typing only
     from collections.abc import Callable
+    from collections.abc import Collection
     from collections.abc import Iterable
     from collections.abc import Sequence
 
@@ -564,6 +565,65 @@ def exit_code(self, new_val: ExitCodeT) -> None:
             if self.__exit_code != proc_enums.INVALID:
                 self.__timestamp = datetime.datetime.now(tz=datetime.timezone.utc)
 
+    @property
+    def ok(self) -> bool:
+        """Exit code is EX_OK.
+
+        :return: Exit code is EX_OK
+        :rtype: bool
+        """
+        return self.exit_code == 0  # pylint: disable=use-implicit-booleaness-not-comparison-to-zero
+
+    def check_exit_code(
+        self,
+        expected_codes: Iterable[ExitCodeT] = (0,),
+        raise_on_err: bool = True,
+        *,
+        error_info: str | None = None,
+        exception_class: type[exceptions.CalledProcessError] = exceptions.CalledProcessError,
+        logger: logging.Logger = LOGGER,
+    ) -> None:
+        """Check exit code and log/raise for unexpected code.
+
+        :param error_info: optional additional error information
+        :type error_info: str | None
+        :param raise_on_err: raise `exception_class` in case of error
+        :type raise_on_err: bool
+        :param expected_codes: iterable expected exit codes
+        :type expected_codes: Iterable[int | ExitCodes]
+        :param exception_class: exception class for usage in case of errors (subclass of CalledProcessError)
+        :type exception_class: type[exceptions.CalledProcessError]
+        :param logger: logger instance for error log
+        :type logger: logging.Logger
+        :raises exceptions.CalledProcessError: unexpected exit code and raise_on_err enabled
+        """
+        append: str = error_info + "\n" if error_info else ""
+        expected = tuple(frozenset(expected_codes))
+        if self.exit_code not in expected:
+            message = f"{append}Command {self.cmd!r} returned exit code {self.exit_code!s} while expected {expected!s}"
+            logger.error(msg=message)
+            if raise_on_err:
+                self.raise_for_status(expected_codes=expected, exception_class=exception_class)
+
+    def raise_for_status(
+        self,
+        expected_codes: Collection[ExitCodeT] = (0,),
+        *,
+        exception_class: type[exceptions.CalledProcessError] = exceptions.CalledProcessError,
+    ) -> None:
+        """Requests-like exit code checker.
+
+        :param expected_codes: iterable expected exit codes
+        :type expected_codes: Iterable[int | ExitCodes]
+        :param exception_class: exception class for usage in case of errors (subclass of CalledProcessError)
+        :type exception_class: type[exceptions.CalledProcessError]
+        :raises exceptions.CalledProcessError: unexpected exit code and raise_on_err enabled
+        """
+        if self.exit_code in expected_codes:
+            return
+
+        raise exception_class(self, expected_codes)
+
     @property
     def started(self) -> datetime.datetime | None:
         """Timestamp of command start.