Merge pull request #170 from feature-exit-code-handling

[STYLE] Refactor exceptions and exit-code utilities (- WIP #117 & #157 -)

Author: reactive-firewall

multicast/__init__.py

@@ -27,9 +27,15 @@
 # skipcq
 __all__ = [
 	"""__package__""", """__module__""", """__name__""", """__version__""", """__prologue__""",
-	"""__doc__""", """skt""", """skt.__package__""", """skt.__module__""", """skt.__name__""",
+	"""__doc__""", """exceptions""", """exceptions.CommandExecutionError""",
+	"""exceptions.get_exit_code_from_exception""",
+	"""exceptions.get_exit_code_from_exception.__func__""",
+	"""exceptions.exit_on_exception""", """exceptions.exit_on_exception.__func__""",
+	"""get_exit_code_from_exception""", """exit_on_exception""",
+	"""skt""", """skt.__package__""", """skt.__module__""", """skt.__name__""",
 	"""skt.__file__""", """skt.genSocket""", """skt.genSocket.__func__""", """genSocket""",
 	"""skt.endSocket""", """skt.endSocket.__func__""", """endSocket""",
+	"""EXIT_CODES""", """EXCEPTION_EXIT_CODES""",
 	"""_BLANK""", """_MCAST_DEFAULT_PORT""", """_MCAST_DEFAULT_GROUP""",
 	"""_MCAST_DEFAULT_TTL""", """mtool""", """recv""", """send""", """hear""",
 	"""recv.McastRECV""", """send.McastSAY""", """hear.McastHEAR""",
@@ -352,6 +358,25 @@
 	raise ModuleNotFoundError("FAIL: we could not import Abstract base class. ABORT.") from None
 
 
+global EXIT_CODES  # skipcq: PYL-W0604
+global EXCEPTION_EXIT_CODES  # skipcq: PYL-W0604
+if 'multicast.exceptions' not in sys.modules:
+	# pylint: disable=cyclic-import - skipcq: PYL-R0401, PYL-C0414
+	from . import exceptions  # pylint: disable=cyclic-import - skipcq: PYL-R0401, PYL-C0414
+else:  # pragma: no branch
+	exceptions = sys.modules["""multicast.exceptions"""]
+
+EXIT_CODES = exceptions.EXIT_CODES
+
+EXCEPTION_EXIT_CODES = exceptions.EXCEPTION_EXIT_CODES
+
+CommandExecutionError = exceptions.CommandExecutionError
+
+get_exit_code_from_exception = exceptions.get_exit_code_from_exception
+
+exit_on_exception = exceptions.exit_on_exception
+
+
 class mtool(abc.ABC):
 	"""
 	Class for Multicast tools.

multicast/exceptions.py

@@ -0,0 +1,268 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# Python Multicast Repo
+# ..................................
+# Copyright (c) 2017-2024, Mr. Walls
+# ..................................
+# Licensed under MIT (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# ..........................................
+# http://www.github.com/reactive-firewall/python-repo/LICENSE.md
+# ..........................................
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Provides multicast exception features.
+
+Use for handling exit codes and exceptions from multicast. Contains classes and functions to
+handle exceptions and errors for/from the multicast module.
+
+Caution: See details regarding dynamic imports [documented](../__init__.py) in this module.
+
+Minimal Acceptance Testing:
+
+	First set up test fixtures by importing multicast.
+
+	Testcase 0: Multicast should be importable.
+
+		>>> import multicast
+		>>> multicast.exceptions is not None
+		True
+		>>> multicast.__doc__ is not None
+		True
+		>>>
+
+	Testcase 1: Recv should be automatically imported.
+		A: Test that the multicast component is initialized.
+		B: Test that the exceptions component is initialized.
+		C: Test that the exceptions component has __doc__
+
+		>>> multicast is not None
+		True
+		>>> multicast.exceptions is not None
+		True
+		>>> multicast.exceptions.__doc__ is not None
+		True
+		>>> type(multicast.exceptions.__doc__) == type(str(''''''))
+		True
+		>>>
+
+	Testcase 2: Exceptions should be detailed with some metadata.
+		A: Test that the __MAGIC__ variables are initialized.
+		B: Test that the __MAGIC__ variables are strings.
+
+		>>> multicast.exceptions is not None
+		True
+		>>> multicast.exceptions.__module__ is not None
+		True
+		>>> multicast.exceptions.__package__ is not None
+		True
+		>>> type(multicast.exceptions.__doc__) == type(multicast.exceptions.__module__)
+		True
+		>>>
+
+"""
+
+
+__package__ = """multicast"""  # skipcq: PYL-W0622
+"""
+The package of this program.
+
+Minimal Acceptance Testing:
+
+	First set up test fixtures by importing multicast.
+
+	Testcase 0: Multicast should be importable.
+
+		>>> import multicast
+		>>>
+
+	Testcase 1: Recv should be automatically imported.
+
+		>>> multicast.recv.__package__ is not None
+		True
+		>>>
+		>>> multicast.recv.__package__ == multicast.__package__
+		True
+		>>>
+
+"""
+
+
+__module__ = """multicast.exceptions"""
+"""
+The module of this program.
+
+Minimal Acceptance Testing:
+
+	First set up test fixtures by importing multicast.
+
+	Testcase 0: Multicast should be importable.
+
+		>>> import multicast
+		>>>
+
+	Testcase 1: Exceptions should be automatically imported.
+
+		>>> multicast.exceptions.__module__ is not None
+		True
+		>>>
+
+"""
+
+
+__file__ = """multicast/exceptions.py"""
+"""The file of this component."""
+
+
+__name__ = """multicast.exceptions"""  # skipcq: PYL-W0622
+"""The name of this component.
+
+	Minimal Acceptance Testing:
+
+	First set up test fixtures by importing multicast.
+
+	Testcase 0: Multicast should be importable.
+
+		>>> import multicast
+		>>>
+
+	Testcase 1: Recv should be automatically imported.
+
+		>>> multicast.exceptions.__name__ is not None
+		True
+		>>>
+
+"""
+
+
+try:
+	from . import sys  # skipcq: PYL-C0414
+	from . import argparse  # skipcq: PYL-C0414
+except Exception as err:
+	baton = ImportError(err, str("[CWE-758] Module failed completely."))
+	baton.module = __module__
+	baton.path = __file__
+	baton.__cause__ = err
+	raise baton from err
+
+
+class CommandExecutionError(RuntimeError):
+	"""
+	Exception raised when a command execution fails.
+
+	Attributes:
+		message (str) -- Description of the error.
+		exit_code (int) -- The exit code associated with the error.
+
+	Meta-Testing:
+
+		Testcase 1: Initialization with message and exit code.
+			A. - Initializes the error.
+			B. - checks inheritance.
+			C. - checks each attribute.
+
+			>>> error = CommandExecutionError("Failed to execute command", exit_code=1)
+			>>> isinstance(error, RuntimeError)
+			True
+			>>> error.message
+			'Failed to execute command'
+			>>> error.exit_code
+			1
+	"""
+
+	def __init__(self, *args, **kwargs):
+		"""
+		Initialize CommandExecutionError with a message and exit code.
+
+		Parameters:
+			message (str) -- Description of the error.
+			exit_code (int) -- The exit code associated with the error.
+			*args: Variable length argument list.
+			**kwargs: Arbitrary keyword arguments.
+
+		Meta-Testing:
+
+			Testcase 1: Initialization with different exit code:
+				A. - Initializes a CommandExecutionError with a specific exit code.
+				B. - Checks the message is still set, as super class would.
+				C. - check the specific exit code is 2.
+
+				>>> error = CommandExecutionError("Error message", 2)
+				>>> error.message
+				'Error message'
+				>>> error.exit_code
+				2
+		"""
+		if len(args) > 0 and isinstance(args[-1], int):
+			exit_code = args[-1]
+			args = args[:-1]
+		else:
+			exit_code = kwargs.pop("exit_code", 1)
+		super().__init__(*args, **kwargs)
+		self.message = args[0] if args else kwargs.get("message", "An error occurred")
+		self.exit_code = exit_code
+
+
+EXIT_CODES = {
+	0: (None, 'Success'),
+	1: (RuntimeError, 'General Error'),
+	2: (OSError, 'Misuse of Shell Builtins'),
+	64: (argparse.ArgumentError, 'Usage Error'),
+	65: (ValueError, 'Data Error'),
+	66: (FileNotFoundError, 'No Input'),
+	69: (ConnectionError, 'Unavailable Service'),
+	70: (Exception, 'Internal Software Error'),
+	77: (PermissionError, 'Permission Denied'),
+	125: (BaseException, 'Critical Failure'),
+	126: (AssertionError, 'Command Invoked Cannot Execute'),
+	127: (ModuleNotFoundError, 'Command Not Found'),
+	129: (None, 'Hangup (SIGHUP)'),
+	130: (KeyboardInterrupt, 'Interrupt (SIGINT)'),
+	134: (None, 'Abort (SIGABRT)'),
+	137: (None, 'Killed (SIGKILL)'),
+	141: (BrokenPipeError, 'Broken Pipe (SIGPIPE)'),
+	143: (SystemExit, 'Terminated (SIGTERM)'),
+	255: (None, 'Exit Status Out of Range'),
+}
+
+
+EXCEPTION_EXIT_CODES = {exc: code for code, (exc, _) in EXIT_CODES.items() if exc}
+
+
+def get_exit_code_from_exception(exc):
+	for exc_class in EXCEPTION_EXIT_CODES:
+		if isinstance(exc, exc_class):
+			return EXCEPTION_EXIT_CODES[exc_class]
+	return 70  # Default to 'Internal Software Error'
+
+
+def exit_on_exception(func):
+	def wrapper(*args, **kwargs):
+		try:
+			return func(*args, **kwargs)
+		except SystemExit as exc:
+			# Handle SystemExit exceptions, possibly from argparse
+			exit_code = exc.code if isinstance(exc.code, int) else 2
+			if (sys.stdout.isatty()):
+				print(
+					f"{EXIT_CODES.get(exit_code, (1, 'General Error'))[1]}: {exc}",
+					file=sys.stderr
+				)
+			raise SystemExit(code=exit_code) from exc
+			# otherwise sys.exit(exit_code)
+		except BaseException as exc:
+			exit_code = get_exit_code_from_exception(exc)
+			if (sys.stdout.isatty()):
+				print(
+					f"{EXIT_CODES[exit_code][1]}: {exc}",
+					file=sys.stderr
+				)
+			raise SystemExit(code=exit_code) from exc
+			# otherwise sys.exit(exit_code)
+	return wrapper

tests/check_spelling

@@ -127,6 +127,9 @@ check_command git ;
 hash -p ./.github/tool_shlock_helper.sh shlock || exit 255 ;
 check_command shlock ;
 
+
+SCRIPT_FILE="test/check_spelling"
+
 # Set codespell options
 CODESPELL_OPTIONS="--quiet-level=4 --builtin clear,rare,code -L assertIn"
 
@@ -153,6 +156,19 @@ else
 		exit 126 ;
 fi
 
+function report_summary() {
+	printf "::group::%s\n" "Results" ;
+	# Improved reporting based on EXIT_CODE
+	case "${EXIT_CODE}" in
+		0) printf "::notice title=OK::%s\n" "OK: Found no detected spelling errors." ;;
+		1) printf "::error file=${SCRIPT_FILE},line=${BASH_LINENO:-0},title=CHECK-SPELLING::%s\n" "FAIL: General failure during script execution." >&2 ;;
+		3) printf "::error file=${SCRIPT_FILE},line=${BASH_LINENO:-0},title=CONFIGURATION::%s\n" "FAIL: Gathering repostory's requirements failed." >&2 ;;  # git ls-tree command failed
+		126) printf "::warning file=${SCRIPT_FILE},line=${BASH_LINENO:-0},title=SKIPPED::%s\n" "SKIP: Unable to continue script execution." >&2 ;;
+		*) printf "::error file=${SCRIPT_FILE},line=${BASH_LINENO:-0},title=FAILED::%s\n" "FAIL: Detected spelling errors." >&2 ;;
+	esac
+	printf "::endgroup::\n" ;
+}
+
 # this is how test files are found:
 
 # THIS IS THE ACTUAL TEST
@@ -161,8 +177,9 @@ if _TEST_ROOT_DIR=$(git rev-parse --show-superproject-working-tree 2>/dev/null);
 	if [ -z "${_TEST_ROOT_DIR}" ]; then
 		_TEST_ROOT_DIR=$(git rev-parse --show-toplevel 2>/dev/null)
 	fi
-else
-	printf "\t%s\n" "FAIL: missing valid repository or source structure" >&2
+		printf "::debug::%s\n" "Found ${_TEST_ROOT_DIR} ..." ;
+	else
+		printf "::error file=${SCRIPT_FILE},line=${BASH_LINENO:-0},title=${FUNCNAME:-$0}::%s\n" "FAIL: missing valid repository or source structure" >&2
 	EXIT_CODE=40
 fi
 
@@ -172,23 +189,19 @@ FILES_TO_CHECK=$(git ls-tree -r --full-tree --name-only HEAD -- *.md *.py *.txt
 # Enable auto-correction if '--fix' argument is provided
 if [[ "$1" == "--fix" ]]; then
 	CODESPELL_OPTIONS="--write-changes --interactive 2 ${CODESPELL_OPTIONS}"
-	printf "%s\n" "Auto-correction enabled."
+	printf "::debug::%s\n" "Auto-correction enabled."
 fi
 
 # THIS IS THE ACTUAL TEST
 # Iterate over files and run codespell
 for FILE in $FILES_TO_CHECK; do
-	printf "%s\n" "Checking ${FILE}" ;
+	printf "::group::%s\n" "Checking ${FILE}" ;
 	{ codespell $CODESPELL_OPTIONS "${FILE}" || EXIT_CODE=$? ;} 2>/dev/null ; wait ;
+	printf "::endgroup::\n" ;
 done
 
 # cleaning up and reporting
-
-if [[ ("${EXIT_CODE}" -eq 0) ]] ; then
-	printf "%s\n" "OK: Found no detected spelling errors." ;
-else
-	printf "%s\n" "FAIL: Found spelling errors." ;
-fi
+report_summary
 
 cleanup || rm -f ${LOCK_FILE} 2>/dev/null || : ;