[TESTING] Implemented CEP-8 exit-code refactoring and updated test code (- WIP #117 & PR #175 -)

> [!NOTE]
> Fixes commits d6fa180..f7f7777

Changes in file .coderabbit.yaml:
  - Improved review directions slightly for project.

Changes in file .coveragerc:
  - ignore untested corner-case for import errors that are never thrown.

Changes in file docs/Makefile:
  - minor changes to cleanup logic.

Changes in file multicast/__init__.py:
  - related changes to implementing new exceptions components.
  - related changes to implementing new exit-code logic to [align with CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161#4-adhere-to-posix-standards)
  - minor improvements to mtool abstract class.

Changes in file multicast/__main__.py:
  - now adheres to [CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161)
    - overhauled `doStep method` to implementing new exit-code logic to [align with CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161#4-adhere-to-posix-standards)
    - refactored `main` function to implementing new exit-code logic to [align with CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161#4-adhere-to-posix-standards)
    - refactored `useTool` method to implementing new exit-code logic to [align with CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161#4-adhere-to-posix-standards)
  - related changes to implementing new exceptions components.
  - formalized implementation style of returning tuple of (success bool, details or None) from `doStep`
  - other minor odd changes

Changes in file multicast/exceptions.py:
  - improved class CommandExecutionError to allow more use-cases
  - other minor odd changes

Changes in file multicast/hear.py:
  - formalized implementation style of returning tuple of (success bool, details or None) from `doStep`

Changes in file multicast/recv.py:
  - related changes to implementing new exceptions components.
  - formalized implementation style of returning tuple of (success bool, details or None) from `doStep`

Changes in file multicast/send.py:
  - related changes to implementing new exceptions components.
  - formalized implementation style of returning tuple of (success bool, details or None) from `doStep`
  - refactored SAY logic to use skt.py utilities for a more single responsibility style design

Changes in file tests/__init__.py:
  - Fixed a few regressions caused by implementing new exit-code logic
  - other minor odd changes

Changes in file tests/profiling.py:
  - Fixed a few regressions caused by implementing new exit-code logic
  - other minor odd changes

Changes in file tests/test_fuzz.py:
  - identified and resolved several regressions related to implementing new exit-code logic

Changes in file tests/test_hear_data_processing.py:
  - identified and resolved several regressions related to implementing new exit-code logic

Changes in file tests/test_hear_keyboard_interrupt.py:
  - identified and resolved several regressions related to implementing new exit-code logic
  - properly stablized the `ctrl^C` testing (- WIP #53 -)
  - other minor odd changes

Changes in file tests/test_usage.py:
  - Fixed dozens of regressions caused by implementing new exit-code logic
  - Fixed dozens of regressions caused by implementing consistant `tuple` return logic in `doStep` methods
  - Refactored some tests for new behavior like accepting `--groups None`
  - other minor odd changes

### ChangeLog:

Changes in file .coderabbit.yaml:
 reviews:

Changes in file .coveragerc:
 include = multicast/*,tests/*

Changes in file docs/Makefile:
 init: ../docs/

Changes in file multicast/__init__.py:
 def __call__(self, *args, **kwargs):
 def buildArgs(cls, calling_parser_group):

Changes in file multicast/__main__.py:
 def doStep(self, *args, **kwargs):
 def main(*argv):
 def useTool(tool, **kwargs):

Changes in file multicast/exceptions.py:
 class CommandExecutionError(RuntimeError):
 def __init__(self, *args, **kwargs):
 def exit_on_exception(func):

Changes in file multicast/hear.py:
 def doStep(self, *args, **kwargs):

Changes in file multicast/recv.py:
 def setupArgs(cls, parser):

Changes in file multicast/send.py:
 def _sayStep(group, port, data):
 def doStep(self, *args, **kwargs):

Changes in file tests/__init__.py:
 Unknown Changes

Changes in file tests/profiling.py:
 def nothing(*args, **kwargs):

Changes in file tests/test_fuzz.py:
 def test_multicast_sender_with_random_data(self, data):
 def test_say_works_WHEN_using_stdin_GIVEN_alnum_of_any_size_fuzz_input(self, tex

Changes in file tests/test_hear_data_processing.py:
 class RecvDataProcessingTestSuite(context.BasicUsageTestSuite):

Changes in file tests/test_hear_keyboard_interrupt.py:
 def test_hear_keyboard_interrupt(self):

Changes in file tests/test_usage.py:
 def test_Usage_Error_WHEN_the_help_command_is_called(self):
 def test_Usage_Error_WHEN_the_help_sub_command_is_called(self):
 def test_aborts_WHEN_calling_multicast_GIVEN_invalid_tools(self):
 def test_hear_is_stable_WHEN_calling_multicast_GIVEN_invalid_tool(self):
 def test_hear_works_WHEN_fuzzed_and_say_works(self):
 def test_hear_works_WHEN_say_works(self):
 def test_noop_stable_WHEN_calling_multicast_GIVEN_noop_args(self):
 def test_say_works_WHEN_using_stdin(self):

Author: reactive-firewall

.coderabbit.yaml

@@ -9,8 +9,14 @@ reviews:
     # Code Review Instructions
 
     - Ensure the code follows best practices and coding standards.
+    - Check for security vulnerabilities and potential issues.
+    - Ensure the code follows the **DRY, AHA, and SOLID** principles.
+    - Our "Code Review Checklist Guide" is documented in
+      [CEP-4](https://gist.github.com/reactive-firewall/cc041f10aad1d43a5ef15f50a6bbd5a5)
     - For **Python** code, follow
-      [PEP 20](https://www.python.org/dev/peps/pep-0020/) and
+      [PEP 20](https://www.python.org/dev/peps/pep-0020/),
+      [PEP 483](https://peps.python.org/pep-0483/),
+      [PEP 729](https://peps.python.org/pep-0729/), and
       [CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161)
       standards.
     - For **BASH** and **Shellscript** code, follow
@@ -19,25 +25,27 @@ reviews:
       standards.
     - Check all **BASH** files start with an
       [extensive disclaimer](https://gist.github.com/reactive-firewall/866b42d175ae3ebefcb2a5878b30ea17).
-    - Check for security vulnerabilities and potential issues.
-    - Ensure the code follows the **DRY, AHA, and SOLID** principles.
 
     # Documentation Review Instructions
     - Verify that documentation and comments are clear and comprehensive.
     - Verify that documentation and comments are free of spelling mistakes.
     - Verify that technical documentation includes a "References" section at
       the end of documentation, using the same format as actual RFCs, with
       both "Normative References" and "Informative References".
+    - Ensure that that documentation and comments follow
+      [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20)
 
     # Test Code Review Instructions
     - Ensure that test code is automated, comprehensive, and follows testing best practices.
     - Verify that all critical functionality is covered by tests.
-    - Ensure that test code follow
-      [CEP-8](https://gist.github.com/reactive-firewall/d840ee9990e65f302ce2a8d78ebe73f6)
+    - For **test** code, *also* follow
+      [CEP-9](https://gist.github.com/reactive-firewall/d840ee9990e65f302ce2a8d78ebe73f6)
 
     # Misc.
     - Confirm that the code meets the project's requirements and objectives.
     - Confirm that copyright years are up-to date whenever a file is changed.
+    - For **Python** code, consider [PEP 290](https://peps.python.org/pep-0290/) whenever a python
+      (e.g. has the extension '.py') file is changed.
   request_changes_workflow: true
   high_level_summary: true
   high_level_summary_placeholder: '@coderabbitai summary'
@@ -81,7 +89,7 @@ reviews:
         3. You may assume the file 'README.md' will contain GitHub flavor Markdown.
     - path: '**/*.py'
       instructions: >-
-        When reviewing Python code for this project:
+        When reviewing **Python** code for this project:
 
         1. Prioritize portability over clarity, especially when dealing with cross-Python compatibility. However, with the priority in mind, do still consider improvements to clarity when relevant.
 
@@ -96,7 +104,7 @@ reviews:
         6. Verify Flake8's configuration file is located at ".flake8.ini"
     - path: tests/*
       instructions: >-
-        When reviewing test code:
+        When reviewing **test** code:
 
         1. Prioritize portability over clarity, especially when dealing with cross-Python compatibility. However, with the priority in mind, do still consider improvements to clarity when relevant.
 
@@ -167,6 +175,7 @@ reviews:
           - 'CEP-8'
           - 'CEP-7'
           - 'CEP-5'
+          - 'CEP-4'
           - 'Shellscript'
           - 'bash'
         disabled_rules:

.coveragerc

@@ -12,6 +12,7 @@ exclude_lines =
     pragma: no cover
     from . import
     pass
+    except ImportError
     except Exception
     except BaseException
     # Don't complain if tests don't hit defensive assertion code:

docs/Makefile

@@ -68,8 +68,9 @@ init: ../docs/
 	@ln -sf ../LICENSE.md $(SRCDIR)/LICENSE.md
 
 clean:
-	@-rm -rf $(BUILDDIR)/* 2>/dev/null || true
-	@-rm -rfRd $(SRCDIR)/apidocs/* 2>/dev/null || true
+	@-rm -rf $(SRCDIR)/$(BUILDDIR)/* 2>/dev/null || true
+	@-rm -fd $(SRCDIR)/$(BUILDDIR) 2>/dev/null || true
+	@-rm -rfd $(SRCDIR)/apidocs/* 2>/dev/null || true
 	@-unlink $(SRCDIR)/README.md 2>/dev/null || true
 	@-unlink $(SRCDIR)/tests 2>/dev/null || true
 	@-unlink $(SRCDIR)/LICENSE.md 2>/dev/null || true

multicast/__init__.py

@@ -473,7 +473,7 @@ def buildArgs(cls, calling_parser_group):
 		return calling_parser_group
 
 	@classmethod
-	def parseArgs(cls, arguments=None):
+	def parseArgs(cls, arguments):
 		"""
 		Will attempt to parse the given CLI arguments.
 
@@ -595,7 +595,7 @@ def setupArgs(cls, parser):  # pragma: no cover
 		pass  # skipcq - abstract method
 
 	@abc.abstractmethod
-	def doStep(self, *args):  # pragma: no cover
+	def doStep(self, *args, **kwargs):  # pragma: no cover
 		"""
 		Abstracts the __call__ behavior for sub-classing the tool.
 

multicast/__main__.py

@@ -66,6 +66,7 @@
 __all__ = [
 	"""__package__""", """__module__""", """__name__""", """__doc__""",
 	"""McastNope""", """McastRecvHearDispatch""", """McastDispatch""", """main""",
+	"""TASK_OPTIONS""",
 ]
 
 
@@ -79,52 +80,59 @@
 
 
 try:
-	from . import sys as _sys
-except Exception as impErr:
+	from . import sys
+except ImportError as impErr:
 	# Throw more relevant Error
 	raise ImportError(str("[CWE-440] Error Importing Python")) from impErr
 
 
-if 'multicast.__version__' not in _sys.modules:
+if 'multicast.__version__' not in sys.modules:
 	from . import __version__ as __version__  # skipcq: PYL-C0414
 else:  # pragma: no branch
-	__version__ = _sys.modules["""multicast.__version__"""]
+	__version__ = sys.modules["""multicast.__version__"""]
 
 
-if 'multicast._MCAST_DEFAULT_PORT' not in _sys.modules:
+if 'multicast._MCAST_DEFAULT_PORT' not in sys.modules:
 	from . import _MCAST_DEFAULT_PORT as _MCAST_DEFAULT_PORT  # skipcq: PYL-C0414
 else:  # pragma: no branch
-	_MCAST_DEFAULT_PORT = _sys.modules["""multicast._MCAST_DEFAULT_PORT"""]
+	_MCAST_DEFAULT_PORT = sys.modules["""multicast._MCAST_DEFAULT_PORT"""]
 
 
-if 'multicast._MCAST_DEFAULT_GROUP' not in _sys.modules:
+if 'multicast._MCAST_DEFAULT_GROUP' not in sys.modules:
 	from . import _MCAST_DEFAULT_GROUP as _MCAST_DEFAULT_GROUP  # skipcq: PYL-C0414
 else:  # pragma: no branch
-	_MCAST_DEFAULT_GROUP = _sys.modules["""multicast._MCAST_DEFAULT_GROUP"""]
+	_MCAST_DEFAULT_GROUP = sys.modules["""multicast._MCAST_DEFAULT_GROUP"""]
 
 
-if 'multicast.mtool' not in _sys.modules:
+if 'multicast.exceptions' not in sys.modules:
+	# pylint: disable=useless-import-alias  -  skipcq: PYL-C0414
+	from . import exceptions as exceptions  # skipcq: PYL-C0414
+else:  # pragma: no branch
+	exceptions = sys.modules["""multicast.exceptions"""]
+
+
+if 'multicast.mtool' not in sys.modules:
 	from . import mtool as mtool  # skipcq: PYL-C0414
 else:  # pragma: no branch
-	mtool = _sys.modules["""multicast.mtool"""]
+	mtool = sys.modules["""multicast.mtool"""]
 
 
-if 'multicast.recv' not in _sys.modules:
+if 'multicast.recv' not in sys.modules:
 	from . import recv as recv  # pylint: disable=useless-import-alias  -  skipcq: PYL-C0414
 else:  # pragma: no branch
-	recv = _sys.modules["""multicast.recv"""]
+	recv = sys.modules["""multicast.recv"""]
 
 
-if 'multicast.send' not in _sys.modules:
+if 'multicast.send' not in sys.modules:
 	from . import send as send  # pylint: disable=useless-import-alias  -  skipcq: PYL-C0414
 else:  # pragma: no branch
-	send = _sys.modules["""multicast.send"""]
+	send = sys.modules["""multicast.send"""]
 
 
-if 'multicast.hear' not in _sys.modules:
+if 'multicast.hear' not in sys.modules:
 	from . import hear as hear  # pylint: disable=useless-import-alias  -  skipcq: PYL-C0414
 else:  # pragma: no branch
-	hear = _sys.modules["""multicast.hear"""]
+	hear = sys.modules["""multicast.hear"""]
 
 
 class McastNope(mtool):
@@ -256,7 +264,11 @@ def doStep(self, *args, **kwargs):
 			tuple: A "tuple" set to None.
 
 		"""
-		return self.NoOp(*args, **kwargs)
+		_None_from_NoOp = self.NoOp(*args, **kwargs)
+		return (
+			True if _None_from_NoOp is None else False,
+			None if _None_from_NoOp is None else _None_from_NoOp  # noqa
+		)
 
 
 class McastRecvHearDispatch(mtool):
@@ -530,17 +542,17 @@ def useTool(tool, **kwargs):
 		_is_done = False
 		if (tool is not None) and (tool in cached_list):
 			try:
-				theResult = TASK_OPTIONS[tool].__call__([], **kwargs)
-				_is_done = True
+				(_is_done, theResult) = TASK_OPTIONS[tool].__call__([], **kwargs)
 			except Exception as e:  # pragma: no branch
 				theResult = str(
 					"""CRITICAL - Attempted '[{t}]: {args}' just failed! :: {errs}"""
 				).format(
 					t=tool, args=kwargs, errs=e
 				)
+				_is_done = False
 		return (_is_done, theResult)  # noqa
 
-	def doStep(self, *args):
+	def doStep(self, *args, **kwargs):
 		"""
 		Executes the multicast tool based on parsed arguments.
 
@@ -553,36 +565,40 @@ def doStep(self, *args):
 		Returns:
 			A tuple containing the exit status and the result of the tool execution.
 		"""
-		__EXIT_MSG = (1, "Unknown")
+		__EXIT_MSG = (64, exceptions.EXIT_CODES[64][1])
 		try:
-			try:
-				(argz, _) = type(self).parseArgs(*args)
-				service_cmd = argz.cmd_tool
-				argz.__dict__.__delitem__("""cmd_tool""")
-				_TOOL_MSG = (self.useTool(service_cmd, **argz.__dict__))
-				if _TOOL_MSG[0]:
-					__EXIT_MSG = (0, _TOOL_MSG)
-				elif (_sys.stdout.isatty()):  # pragma: no cover
-					print(_TOOL_MSG)
-			except Exception as inerr:  # pragma: no branch
-				w = str("WARNING - An error occurred while")
-				w += str(" handling the arguments.")
-				w += str(" Refused.")
-				if (_sys.stdout.isatty()):  # pragma: no cover
-					print(w)
-					print(str(inerr))
-					print(str(inerr.args))
-				del inerr  # skipcq - cleanup any error leaks early
-				__EXIT_MSG = (2, "NoOp")
-		except BaseException:  # pragma: no branch
-			e = str("CRITICAL - An error occurred while handling")
-			e += str(" the dispatch.")
-			if (_sys.stdout.isatty()):  # pragma: no cover
-				print(str(e))
-			__EXIT_MSG = (3, "STOP")
+			(argz, _) = type(self).parseArgs(*args)
+			service_cmd = argz.cmd_tool
+			argz.__dict__.__delitem__("""cmd_tool""")
+			_TOOL_MSG = (self.useTool(service_cmd, **argz.__dict__))
+			if _TOOL_MSG[0]:
+				__EXIT_MSG = (0, _TOOL_MSG)
+			else:
+				__EXIT_MSG = (70, _TOOL_MSG)
+				if (sys.stdout.isatty()):  # pragma: no cover
+					print(str(_TOOL_MSG))
+		except Exception as err:  # pragma: no branch
+			exit_code = exceptions.get_exit_code_from_exception(err)
+			__EXIT_MSG = (
+				False, str(
+					"""CRITICAL - Attempted '[{t}]: {args}' just failed! :: {code} {errs}"""
+				).format(
+					t=__name__, args=args, code=exit_code, errs=err
+				)
+			)
+			if (sys.stderr.isatty()):
+				print(
+					"WARNING - An error occurred while handling the arguments. Refused.",
+					file=sys.stderr
+				)
+				print(
+					f"{exceptions.EXIT_CODES[exit_code][1]}: {err}\n{err.args}",
+					file=sys.stderr
+				)
 		return __EXIT_MSG  # noqa
 
 
+@exceptions.exit_on_exception
 def main(*argv):
 	"""
 	Do main event stuff.
@@ -597,12 +613,11 @@ def main(*argv):
 	The expected return codes are as follows:
 		= 0:  Any nominal state (i.e. no errors and possibly success)
 		≥ 1:  Any erroneous state (includes simple failure)
-		= 2:  Any failed state
-		= 3:  Any undefined (but assumed erroneous) state
+		> 2:  Any failed state
 		< 0:  Implicitly erroneous and treated the same as abs(exit_code) would be.
 
 	Args:
-		*argv: the array of arguments. Usually _sys.argv[1:]
+		*argv: the array of arguments. Usually sys.argv[1:]
 
 	Returns:
 		tuple: the underlying exit code int, and optional detail string.
@@ -695,9 +710,9 @@ def main(*argv):
 
 
 if __name__ in '__main__':
-	__EXIT_CODE = (2, "NoOp")
-	if (_sys.argv is not None) and (len(_sys.argv) > 1):
-		__EXIT_CODE = main(_sys.argv[1:])
-	elif (_sys.argv is not None):
+	__EXIT_CODE = (1, exceptions.EXIT_CODES[1][1])
+	if (sys.argv is not None) and (len(sys.argv) > 1):
+		__EXIT_CODE = main(sys.argv[1:])
+	elif (sys.argv is not None):
 		__EXIT_CODE = main([str(__name__), """-h"""])
 	exit(__EXIT_CODE[0])  # skipcq: PYL-R1722 - intentionally allow overwriteing exit for testing