[MEREGE]

* From PR #92 (89-setuptools-license-comment):
  [DOCUMENTATION] update the setuptools license comment (- WIP #89 -)

* From PR #91 (88-wheel-pkg-license-comment):
  [DOCUMENTATION] update the wheel license comment (- WIP #88 -)

* From PR #93 (patch-150-79-documentation):
  [TESTS] updated some of context.py doctests for cross-python stability (- WIP #79 -)
  [DOCUMENTATION] updated checkCovCommand documentation (- WIP #79 -)
  [DOCUMENTATION] updated checkPythonCommand documentation (- WIP #79 -)
  [DOCUMENTATION] updated checkStrOrByte documentation (- WIP #79 -)
  [DOCUMENTATION] updated BasicTestSuite documentation (- WIP #79 -)
  [DOCUMENTATION] updated MulticastTestSuite documentation (- WIP #79 -)
  [DOCUMENTATION] updated BasicIntegrationTestSuite documentation (- WIP #79 -)

* From PR #86 (patch-150-84-config-pip-flags):
  [REGRESSION] Fixed a minor typo (- WIP #84 -)
  [STYLE] Improvements to portability and maintainability of pip durring bootstrap (- WIP #84 -)

* From PR #87 (patch-150-85-deepsourceyml):
  [UPDATE] Update '.deepsource.yml' again (- WIP #85 -)
  [UPDATE] Update '.deepsource.yml' (- WIP #85 -)

Changes in file .deepsource.toml:
 - refactored deepsource config

Changes in file Makefile:
 - implemented new variables for pip's flags

Changes in file tests/context.py:
 - Greatly improved docstrings

Changes in file tests/requirements.txt:
 - slight improvement to licensing comments

Changes in file tests/test_basic.py:
 - improved docstrings slightly

Changes in file tests/test_usage.py:
  - improved docstrings slightly

Author: reactive-firewall

.deepsource.toml

@@ -1,9 +1,10 @@
 version = 1
 
 test_patterns = [
-    "tests/**,",
+    "tests/check_*",
     "tests/*.py",
     ".circleci/**",
+    ".github/workflows/*.yml",
     "testcases/**"
 ]
 
@@ -30,6 +31,7 @@ name = "python"
 enabled = true
 dependency_file_paths = [
   "requirements.txt",
+  "tests/requirements.txt",
   "setup.py"
 ]
 
@@ -39,4 +41,4 @@ dependency_file_paths = [
 
 [[analyzers]]
 name = "test-coverage"
-enabled = true
+enabled = true

Makefile

@@ -90,6 +90,18 @@ else
 	endif
 endif
 
+ifndef PIP_COMMON_FLAGS
+	# Define common pip install flags
+	PIP_COMMON_FLAGS := --use-pep517 --upgrade --upgrade-strategy eager
+endif
+
+# Define environment-specific pip install flags
+ifeq ($(shell uname),Darwin)
+	PIP_ENV_FLAGS := --break-system-packages
+else
+	PIP_ENV_FLAGS :=
+endif
+
 ifeq "$(WAIT)" ""
 	WAIT=wait
 endif
@@ -135,28 +147,28 @@ build: init ./setup.py
 	$(QUIET)$(ECHO) "build DONE."
 
 init:
-	$(QUIET)$(PYTHON) -m pip install --use-pep517 --upgrade --upgrade-strategy eager "pip>=19.0" "setuptools>=38.0" "wheel>=0.37" "build>=1.0.1" 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(PYTHON) -m pip install --use-pep517 --upgrade --upgrade-strategy eager -r requirements.txt 2>$(ERROR_LOG_PATH) || true
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) "pip>=19.0" "setuptools>=38.0" "wheel>=0.37" "build>=1.0.1" 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) -r requirements.txt 2>$(ERROR_LOG_PATH) || :
 	$(QUIET)$(ECHO) "$@: Done."
 
 install: init build must_be_root
-	$(QUIET)$(PYTHON) -m pip install --use-pep517 --upgrade --upgrade-strategy eager --break-system-packages -e "git+https://github.com/reactive-firewall/multicast.git#egg=multicast"
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) -e "git+https://github.com/reactive-firewall/multicast.git#egg=multicast"
 	$(QUITE)$(WAIT)
 	$(QUIET)$(ECHO) "$@: Done."
 
 uninstall:
-	$(QUIET)$(PYTHON) -m pip uninstall --use-pep517 --no-input -y multicast 2>$(ERROR_LOG_PATH) || true
+	$(QUIET)$(PYTHON) -m pip uninstall --use-pep517 $(PIP_ENV_FLAGS) --no-input -y multicast 2>$(ERROR_LOG_PATH) || :
 	$(QUITE)$(WAIT)
 	$(QUIET)$(ECHO) "$@: Done."
 
 purge: clean uninstall
-	$(QUIET)$(PYTHON) -W ignore ./setup.py uninstall 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(PYTHON) -W ignore ./setup.py clean 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(RMDIR) ./build/ 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(RMDIR) ./dist/ 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(RMDIR) ./.eggs/ 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(RM) ./test-reports/junit.xml 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(RMDIR) ./test-reports/ 2>$(ERROR_LOG_PATH) || true
+	$(QUIET)$(PYTHON) -W ignore ./setup.py uninstall 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(PYTHON) -W ignore ./setup.py clean 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(RMDIR) ./build/ 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(RMDIR) ./dist/ 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(RMDIR) ./.eggs/ 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(RM) ./test-reports/junit.xml 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(RMDIR) ./test-reports/ 2>$(ERROR_LOG_PATH) || :
 	$(QUIET)$(ECHO) "$@: Done."
 
 test: cleanup
@@ -176,7 +188,7 @@ test-reports:
 	$(QUIET)$(ECHO) "$@: Done."
 
 test-reqs: test-reports init
-	$(QUIET)$(PYTHON) -m pip install --use-pep517 --upgrade --upgrade-strategy eager -r tests/requirements.txt 2>$(ERROR_LOG_PATH) || true
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) -r tests/requirements.txt 2>$(ERROR_LOG_PATH) || true
 
 
 test-pytest: cleanup must_have_pytest test-reports
@@ -260,9 +272,9 @@ must_be_root:
 	if test $$runner != "root" ; then $(ECHO) "You are not root." ; exit 1 ; fi
 
 user-install: build
-	$(QUIET)$(PYTHON) -m pip install --use-pep517 --user --upgrade --upgrade-strategy eager "pip>=19.0" "setuptools>=38.0" "wheel>=0.37" "build>=1.0.1" 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(PYTHON) -m pip install --use-pep517 --user --upgrade --upgrade-strategy eager -r "https://raw.githubusercontent.com/reactive-firewall/multicast/stable/requirements.txt" 2>$(ERROR_LOG_PATH) || true
-	$(QUIET)$(PYTHON) -m pip install --use-pep517 --user --upgrade -e "git+https://github.com/reactive-firewall/multicast.git#egg=multicast"
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) --user "pip>=19.0" "setuptools>=38.0" "wheel>=0.37" "build>=1.0.1" 2>$(ERROR_LOG_PATH) || true
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) --user -r "https://raw.githubusercontent.com/reactive-firewall/multicast/stable/requirements.txt" 2>$(ERROR_LOG_PATH) || true
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) --user -e "git+https://github.com/reactive-firewall/multicast.git#egg=multicast"
 	$(QUITE)$(WAIT)
 	$(QUIET)$(ECHO) "$@: Done."
 

tests/context.py

@@ -247,7 +247,40 @@ def getPythonCommand():
 
 
 def checkCovCommand(args=[None]):
-	"""Utility Function."""
+	"""
+	Modifies the input command arguments to include coverage-related options when applicable.
+
+	This utility function checks if the first argument contains "coverage" and, if so,
+	modifies the argument list to include additional coverage run options. It's primarily
+	used internally by other functions in the testing framework.
+	Not intended to be run directly.
+
+	Args:
+		args (list): A list of command arguments, defaulting to [None].
+
+	Returns:
+		list: The modified list of arguments with 'coverage run' options added as applicable.
+
+	Examples:
+		>>> checkCovCommand(["python", "script.py"])
+		['python', 'script.py']
+
+		>>> checkCovCommand(["coverage", "script.py"])  # missing 'run'
+		['coverage', 'run', '-p', '--context=Integration', '--source=multicast', 'script.py']
+		
+		>>> checkCovCommand(["coverage run", "script.py"])  # NOT missing 'run'
+		['coverage', 'run', '-p', '--context=Integration', '--source=multicast', 'script.py']
+
+		>>> checkCovCommand(["/usr/bin/coverage", "test.py"])
+		['coverage', 'run', '-p', '--context=Integration', '--source=multicast', 'test.py']
+
+		>>> import sys
+		>>> test_fixutre = [str("{} -m coverage run").format(sys.executable), "test.py"]
+		>>> checkCovCommand(test_fixutre) #doctest: +ELLIPSIS
+		[..., '-m', 'coverage', 'run', '-p', '...', '--source=multicast', 'test.py']
+
+
+	"""
 	if sys.__name__ is None:  # pragma: no branch
 		raise ImportError("[CWE-758] Failed to import system. WTF?!!")
 	if str("coverage") in args[0]:
@@ -271,7 +304,38 @@ def checkCovCommand(args=[None]):
 
 
 def checkStrOrByte(theInput):
-	"""Checks for bytes that need decoded before always returning a string."""
+	"""
+	Converts the input to a string if possible, otherwise returns it as bytes.
+
+	This utility function is designed to handle both string and byte inputs,
+	ensuring consistent output type. It attempts to decode byte inputs to UTF-8
+	strings, falling back to bytes if decoding fails.
+
+	Args:
+		theInput: The input to be checked and potentially converted.
+					Can be None, str, bytes, or any other type.
+
+	Returns:
+		str: If the input is already a string or can be decoded to UTF-8.
+		bytes: If the input is bytes and cannot be decoded to UTF-8.
+	None: If the input is None.
+
+	Examples:
+		>>> checkStrOrByte("Hello")
+		'Hello'
+		>>> checkStrOrByte(b"Hello")
+		'Hello'
+		>>> checkStrOrByte(b'\\xff\\xfe')  # Non-UTF-8 bytes
+		b'\xff\xfe'
+		>>> checkStrOrByte(None) is None
+		True
+		>>> checkStrOrByte("")
+		''
+		>>> checkStrOrByte(b"")
+		''
+
+
+	"""
 	theOutput = None
 	if theInput is not None:  # pragma: no branch
 		theOutput = theInput
@@ -284,7 +348,45 @@ def checkStrOrByte(theInput):
 
 
 def checkPythonCommand(args, stderr=None):
-	"""function for backend subprocess check_output command."""
+	"""
+	Execute a Python command and return its output.
+
+	This function is a wrapper around subprocess.check_output with additional
+	error handling and output processing. It's designed to execute Python
+	commands or coverage commands, making it useful for running tests and
+	collecting coverage data.
+
+	Args:
+		args (list): A list of command arguments to be executed.
+		stderr (Optional[int]): File descriptor for stderr redirection.
+			Defaults to None.
+
+	Returns:
+		str: The command output as a string, with any byte output decoded to UTF-8.
+
+	Raises:
+		subprocess.CalledProcessError: If the command returns a non-zero exit status.
+
+	Examples:
+		>>> test_fixture_1 = [str(sys.executable), '-c', 'print("Hello, World!")']
+		>>> checkPythonCommand(test_fixture_1)
+		'Hello, World!\\n'
+
+		>>> import subprocess
+		>>> test_args_2 = [str(sys.executable), '-c', 'import sys; print("Error", file=sys.stderr)']
+		>>> checkPythonCommand(test_args_2, stderr=subprocess.STDOUT)
+		'Error\\n'
+
+		>>> test_fixture_e = [str(sys.executable), '-c', 'raise ValueError("Test error")']
+		>>> checkPythonCommand(test_fixture_e, stderr=subprocess.STDOUT) #doctest: +ELLIPSIS
+		'Traceback (most recent call last):\\n...ValueError...'
+
+		>>> test_fixture_s = [str(sys.executable), '-c', 'print(b"Bytes output")']
+		>>> isinstance(checkPythonCommand(test_fixture_s, stderr=subprocess.STDOUT), str)
+		True
+
+
+	"""
 	theOutput = None
 	try:
 		if (args is None) or (args is [None]) or (len(args) <= 0):  # pragma: no branch

tests/requirements.txt

@@ -54,7 +54,7 @@ pytest-enabler>=1.0.1
 pytest-flake8>=1.0.7
 # coverage - Apache 2.0 licence
 coverage>=6.2
-# wheel - builtin?? - PSF licence
+# wheel - MIT licence
 wheel>=0.37.0
 # pip - builtin?? - PSF licence
 pip>=19.0

tests/test_basic.py

@@ -36,7 +36,31 @@
 
 
 class BasicTestSuite(context.BasicUsageTestSuite):
-	"""Basic test cases."""
+	"""
+	A test suite containing basic test cases for the multicast module.
+
+	This class inherits from context.BasicUsageTestSuite and provides a set of
+	unit tests to verify the fundamental functionality and error handling of
+	the multicast module.
+
+	Test Methods:
+	- test_absolute_truth_and_meaning: An insanity test that always passes.
+	- test_Does_Pass_WHEN_Meta_Test: Verifies basic assertion methods.
+	- test_Does_Pass_WHEN_Using_Import_From_Syntax: Tests importing the multicast module.
+	- test_Error_WHEN_the_help_command_is_called: Checks if the --help option raises an exception.
+	- test_IsNone_WHEN_given_corner_case_input: Tests handling of invalid inputs.
+	- test_None_WHEN_Nothing: A placeholder for additional tests.
+	- test_Skip_UNLESS_linux_only: A test that only runs on Linux platforms.
+	- test_Skip_UNLESS_darwin_only: A test that only runs on macOS platforms.
+
+	Note:
+	Some tests are conditionally skipped based on the operating system.
+	The test methods use various assertion techniques to verify expected behaviors.
+
+	This test suite is designed to catch basic issues and ensure the core
+	functionality of the multicast module works as expected across different
+	platforms.
+	"""
 
 	__module__ = """tests.test_basic"""
 

tests/test_usage.py

@@ -73,7 +73,54 @@
 
 
 class MulticastTestSuite(context.BasicUsageTestSuite):
-	"""Special Multicast Usage test cases."""
+	"""
+	A test suite for special Multicast usage scenarios.
+
+	This test suite extends the BasicUsageTestSuite and focuses on testing various
+	aspects of the multicast functionality, including error handling, command-line
+	interface behavior, and basic send/receive operations.
+
+	Methods:
+	--------
+	test_aborts_WHEN_calling_multicast_GIVEN_invalid_tools():
+		Tests the behavior of the CLI tools when given invalid tool names.
+
+	test_say_is_stable_WHEN_calling_multicast_GIVEN_say_tool():
+		Verifies the stability of the 'SAY' command with various message arguments.
+
+	test_recv_aborts_WHEN_calling_multicast_GIVEN_invalid_args():
+		Checks if the 'RECV' command properly aborts when given invalid arguments.
+
+	test_hear_aborts_WHEN_calling_multicast_GIVEN_invalid_args():
+		Ensures the 'HEAR' command aborts correctly when provided with invalid arguments.
+
+	test_hear_is_stable_WHEN_calling_multicast_GIVEN_invalid_tool():
+		Tests the stability of the 'HEAR' command when given an invalid tool (--hex).
+
+	test_noop_stable_WHEN_calling_multicast_GIVEN_noop_args():
+		Verifies the stability of the 'NOOP' command.
+
+	test_help_works_WHEN_calling_multicast_GIVEN_help_tool():
+		Checks if the 'HELP' command functions correctly.
+
+	test_hear_works_WHEN_say_works():
+		Tests the basic send and receive functionality using 'SAY' and 'HEAR' commands.
+
+	test_recv_Errors_WHEN_say_not_used():
+		Verifies that 'RECV' command produces an error when 'SAY' is not used.
+
+	Notes:
+	------
+	- This test suite uses subprocess calls to test the multicast CLI interface.
+	- Some tests involve multiprocessing to simulate concurrent operations.
+	- Ensure proper network configuration for multicast tests to function correctly.
+
+	Warnings:
+	---------
+	- Some tests may require specific network conditions to pass successfully.
+	- Failure in these tests may indicate issues with the multicast implementation
+		or the testing environment rather than actual bugs in the code.
+	"""
 
 	__module__ = """tests.test_usage"""
 
@@ -331,7 +378,47 @@ def test_recv_Errors_WHEN_say_not_used(self):
 
 
 class BasicIntegrationTestSuite(context.BasicUsageTestSuite):
-	"""Basic functional test cases."""
+	"""
+	A test suite for basic functional integration tests of the multicast module.
+
+	This class inherits from context.BasicUsageTestSuite and provides a set of
+	test cases to verify the functionality of the multicast module's command-line
+	interface and core features.
+
+	The suite includes tests for:
+	- Printing usage information when called with the help argument
+	- Verifying command-specific help output
+	- Comparing responses between absolute and implicit module calls
+	- Checking version information output
+	- Validating error handling for invalid inputs
+	- Profiling and stability checks for the NOOP command
+
+	Attributes:
+		_thepython (str): Path to the Python interpreter used for testing.
+
+	Methods:
+		setUp(): Prepares the test environment before each test method is run.
+		test_prints_usage_WHEN_called_GIVEN_help_argument(): Verifies help output.
+		test_prints_usage_WHEN_called_GIVEN_cmd_and_help_argument(): Checks command-specific help.
+		test_equivilant_response_WHEN_absolute_vs_implicit(): Compares module call methods.
+		test_prints_version_WHEN_called_GIVEN_version_argument(): Validates version output.
+		test_Usage_Error_WHEN_the_help_command_is_called(): Ensures correct help output.
+		test_profile_WHEN_the_noop_command_is_called(): Profiles the NOOP command.
+		test_stable_WHEN_the_noop_command_is_called(): Checks NOOP command stability.
+		test_invalid_Error_WHEN_cli_called_GIVEN_bad_input(): Verifies error handling.
+
+	Note:
+		This test suite relies on the context module for utility functions and
+		the subprocess module for executing Python commands. It uses various
+		assertion methods to validate the expected behavior of the multicast module.
+
+	Example:
+		To run this test suite, use the unittest module's test runner:
+
+		```
+		python -m unittest tests.test_usage.BasicIntegrationTestSuite
+		```
+	"""
 
 	__module__ = """tests.test_usage"""