[PATCH] apply more changes from review (- WIP #184 -)

### ChangeLog:

Changes in file .circleci/config.yml:
 jobs:

Changes in file docs/FAQ.md:
 # FAQ

Changes in file docs/USAGE.md:
 ## Basic Library Usage
 ## CLI Usage

Changes in file docs/conf.py:
 Unknown Changes

Changes in file tests/check_pip:
 EXIT_CODE=1

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

Changes in file tests/test_build.py:
 Unknown Changes

Changes in file tests/test_exceptions.py:
 Unknown Changes

Changes in file tests/test_hear_cleanup.py:
 class HearCleanupTestSuite(context.BasicUsageTestSuite):
 def test_cleanup_on_exit(self):

Changes in file tests/test_hear_data_processing.py:
 Unknown Changes

Changes in file tests/test_hear_keyboard_interrupt.py:
 Unknown Changes

Changes in file tests/test_hear_server_activate.py:
 Unknown Changes

Author: reactive-firewall

.circleci/config.yml

@@ -1,11 +1,24 @@
 ---
 version: 2.1
+commands:
+  cleanup:
+    steps:
+      - run:
+          shell: /bin/bash
+          name: "Cleanup"
+          command: |
+            make clean
+          when: always
+
+parameters:
+  python-version:
+    type: string
+    default: "3.12"
+
 jobs:
   build:
     docker:
-      - image: cimg/python:3.10
-      - image: cimg/python:3.11
-      - image: cimg/python:3.12
+      - image: cimg/python:<< pipeline.parameters.python-version >>
     resource_class: medium
     environment:
       CI: cicleci
@@ -39,9 +52,7 @@ jobs:
 
   test:
     docker:
-      - image: cimg/python:3.10
-      - image: cimg/python:3.11
-      - image: cimg/python:3.12
+      - image: cimg/python:<< pipeline.parameters.python-version >>
     parallelism: 2
     resource_class: medium
     environment:
@@ -60,36 +71,18 @@ jobs:
           command: |
             python3 -m pip install --upgrade --user -r ./tests/requirements.txt || : ;
           when: on_success
-      - run:
-          shell: /bin/bash
-          name: "clean up for test"
-          command: |
-            make clean
-          when: always
+      - cleanup
       - run:
           shell: /bin/bash
           name: "Unit Tests"
           command: |
             make test
           when: on_success
-      - run:
-          shell: /bin/bash
-          name: "clean up from test"
-          command: |
-            make clean
-          when: always
-      - run:
-          shell: /bin/bash
-          name: "clean up from FAIL"
-          command: |
-            make clean
-          when: on_fail
+      - cleanup
 
   pytest:
     docker:
-      - image: cimg/python:3.10
-      - image: cimg/python:3.11
-      - image: cimg/python:3.12
+      - image: cimg/python:<< pipeline.parameters.python-version >>
     parallelism: 2
     resource_class: medium
     environment:
@@ -116,12 +109,7 @@ jobs:
           command: |
             python3 -m pip install --upgrade --user -r ./tests/requirements.txt || : ;
           when: on_success
-      - run:
-          shell: /bin/bash
-          name: "clean up for pytest"
-          command: |
-            make clean
-          when: always
+      - cleanup
       - run:
           shell: /bin/bash
           name: "pytest Unit Tests"
@@ -134,22 +122,11 @@ jobs:
       - store_artifacts:
           path: test-reports
           when: on_success
-      - run:
-          shell: /bin/bash
-          name: "clean up from pytest"
-          command: |
-            make clean
-          when: always
-      - run:
-          shell: /bin/bash
-          name: "clean up from FAIL"
-          command: |
-            make clean
-          when: on_fail
+      - cleanup
 
   lint:
     docker:
-      - image: cimg/python:3.11
+      - image: cimg/python:<< pipeline.parameters.python-version >>
     resource_class: medium
     environment:
       CI: cicleci
@@ -169,25 +146,17 @@ jobs:
           name: "install test-reqs attempt"
           command: |
             python3 -m pip install --user -r ./tests/requirements.txt || : ;
-      - run:
-          shell: /bin/bash
-          name: "clean up for test"
-          command: |
-            make clean
+      - cleanup
       - run:
           shell: /bin/bash
           name: "check code style and spelling"
           command: |
             make test-style || python3 -m flake8 --verbose --count --config=.flake8.ini
-      - run:
-          shell: /bin/bash
-          name: "clean up when done"
-          command: |
-            make clean
+      - cleanup
 
 workflows:
   version: 2
-  workflow:
+  test-matrix:
     jobs:
       - build
       - test:

docs/FAQ.md

@@ -5,8 +5,8 @@
 ```{toctree}
 :maxdepth: 3
 
-[Code of Conduct](https://github.com/reactive-firewall/multicast/.github/CODE_OF_CONDUCT.md)
-[Contributing](https://github.com/reactive-firewall/multicast/.github/CONTRIBUTING.md)
+[Code of Conduct](https://github.com/reactive-firewall/multicast/blob/master/.github/CODE_OF_CONDUCT.md)
+[Contributing](https://github.com/reactive-firewall/multicast/blob/master/.github/CONTRIBUTING.md)
 ```
 
 ### How do I get this running?

docs/USAGE.md

@@ -12,6 +12,7 @@ from multiprocessing import Process
 
 # set up some stuff
 _fixture_PORT_arg = int(59595)
+# Valid multicast addresses range from 224.0.0.0 to 239.255.255.255
 _fixture_mcast_GRP_arg = """224.0.0.1"""  # only use dotted notation for multicast group addresses
 _fixture_host_BIND_arg = """224.0.0.1"""  # only use dotted notation for multicast group addresses
 _fixture_host_IFACE_arg = None # Initial value representing no specific interface
@@ -100,7 +101,13 @@ I begin with it.
 CLI should work like so:
 
 ```plain
-multicast [-h|--help] [--use-std] [--daemon] (SAY|RECV|HEAR) [-h|--help] [--port PORT] [--iface IFACE] [--pipe|-m MESSAGE|--message MESSAGE] [--group BIND_GROUP] [--groups [JOIN_MCAST_GROUPS ...]]
+multicast [-h|--help] [--use-std] [--daemon] (SAY|RECV|HEAR)
+    [-h|--help]
+    [--port PORT]
+    [--iface IFACE]
+    [-m MESSAGE|--message MESSAGE]
+    [--group BIND_GROUP]
+    [--groups [JOIN_MCAST_GROUPS ...]]
 ```
 
 The commands are `SAY`, `RECV`, and `HEAR` for the CLI and are analogous to `send` listen/accept
@@ -110,7 +117,8 @@ and echo functions of a 1-to-1 connection.
 
 The `SAY` command is used to send data messages via multicast datagrams.
 
-* Note: the `--message` flag is expected with the `SAY` command, otherwise it behaves like `NOOP`.
+* Note: the `--message` flag is expected with the `SAY` command;
+  if not provided, it behaves like `NOOP`.
 * Note: the `--daemon` flag has no effect on the `SAY` command.
 
 ### `RECV`

docs/conf.py

@@ -15,6 +15,7 @@
 
 import sys
 import os
+from urllib.parse import quote
 
 # Define the branch reference for linkcode_resolve
 DOCS_BUILD_REF: str = os.environ.get("DOCS_BUILD_REF", "stable")
@@ -385,12 +386,16 @@
 
 
 def linkcode_resolve(domain, info):
-	if domain != "py" or not info["module"]:
+	if not isinstance(domain, str) or domain != "py":
+		return None
+	if not isinstance(info, dict) or "module" not in info or not info["module"]:
+		return None
+	if not isinstance(info["module"], str):
 		return None
 	filename = info["module"].replace(".", "/")
 	theResult = f"{linkcode_url_prefix}/blob/{DOCS_BUILD_REF}/{filename}.py"
 	if "/multicast.py" in theResult:
 		theResult = theResult.replace("/multicast.py", "/multicast/__init__.py")
 	if "/tests.py" in theResult:
 		theResult = theResult.replace("/tests.py", "/tests/__init__.py")
-	return theResult
+	return quote(theResult, safe=":/-._")

tests/check_pip

@@ -153,7 +153,7 @@ EXIT_CODE=1
 # Results:
 #	returns -- once cleanup has been done on a best-effort case.
 function cleanup() {
-	rm -f ${LOCK_FILE} 2>/dev/null || : ; wait ;
+	rm -f "${LOCK_FILE}" 2>/dev/null || : ; wait ;
 	# unset when done
 	unset LOCK_FILE 2>/dev/null || : ;
 	hash -d shlock 2>/dev/null || : ;

tests/context.py

@@ -940,10 +940,10 @@ def _should_get_package_version_WHEN_valid(self):
 		This helper method imports the package and extracts the __version__ attribute.
 
 		Returns:
-			version -- The version string of the package.
-
+			packaging.version.Version -- A validated version object from the __version__ attrbute.
 		Raises:
-			AssertionError -- If the version string cannot be retrieved.
+			AssertionError -- If the version string is invalid or cannot be retrieved.
+			ImportError -- If the multicast package cannot be imported.
 
 		"""
 		try:
@@ -957,6 +957,10 @@ def _should_get_package_version_WHEN_valid(self):
 			parsed_version = version.parse(_raw_version_fixture)
 			self.assertIsNotNone(parsed_version, """Version is not valid.""")
 			self.assertIsInstance(parsed_version, version.Version, """Version is not valid.""")
+			self.assertTrue(
+				len(parsed_version.release) >= 2,
+				"""Version must have at least major.minor components."""
+			)
 			return parsed_version
 		except ImportError:
 			self.fail("""Failed to import the multicast package to retrieve version.""")

tests/test_build.py

@@ -43,7 +43,17 @@ class TestPEP517Build(BasicUsageTestSuite):
 	__module__ = """tests.test_build"""
 
 	def test_build_with_pep517(self):
-		"""Test building the package using PEP 517 standards."""
+		"""
+		Test building the package using PEP 517 standards.
+
+		This test verifies:
+		1. Clean build environment setup
+		2. Successful package build (both sdist and wheel)
+		3. Presence of expected distribution files
+
+		References:
+		- PEP 517: https://peps.python.org/pep-0517/
+		"""
 		# Arguments need to clean
 		build_arguments = [
 			str("{} -m coverage run").format(sys.executable),

tests/test_exceptions.py

@@ -37,21 +37,42 @@
 
 
 class ExceptionsTestSuite(BasicUsageTestSuite):
+	"""
+	Test suite for validating the behavior of exception classes in the multicast package.
+
+	This suite focuses on testing the CommandExecutionError class, verifying its
+	initialization with different arguments and proper error propagation.
+	"""
 
 	__module__ = """tests.test_exceptions"""
 
 	__name__ = """tests.test_exceptions.ExceptionsTestSuite"""
 
 	def test_command_execution_error_with_args(self):
+		"""
+		Test CommandExecutionError initialization with custom message and exit code.
+
+		Verifies that both the message and exit code are correctly assigned when
+		explicitly provided during initialization.
+		"""
 		error = multicast.exceptions.CommandExecutionError("Test error", 42)
 		self.assertEqual(error.message, "Test error")
 		self.assertEqual(error.exit_code, 42)
 
 	def test_command_execution_error_default_exit_code(self):
+		"""Test CommandExecutionError initialization with default exit code.
+
+		Verifies that the exit code defaults to 1 when only a message is provided.
+		"""
 		error = multicast.exceptions.CommandExecutionError("Test error")
 		self.assertEqual(error.exit_code, 1)
 
 	def test_command_execution_error_with_cause(self):
+		"""Test CommandExecutionError initialization with a cause.
+
+		Verifies that the error properly chains exceptions when initialized with a
+		cause, maintaining both the cause reference and custom attributes.
+		"""
 		test_cause = RuntimeError("test")
 		self.assertIsNotNone(test_cause)
 		error = multicast.exceptions.CommandExecutionError(test_cause, "Test with cause", 77)

tests/test_hear_cleanup.py

@@ -51,8 +51,28 @@ class HearCleanupTestSuite(context.BasicUsageTestSuite):
 
 	__name__ = """tests.test_hear_cleanup.HearCleanupTestSuite"""
 
+	# Class-level constants
+	QUICK_JOIN_TIMEOUT = 1  # Quick check for process termination
+	ERROR_JOIN_TIMEOUT = 3  # Timeout when handling errors
+	FINAL_JOIN_TIMEOUT = 15  # Final wait for process cleanup
+
 	def test_cleanup_on_exit(self):
-		"""Tests the special hear and stop test"""
+		"""Test proper cleanup of McastHEAR when receiving STOP message.
+
+		Prerequisites:
+			- Available test port (self._the_test_port)
+			- Multicast group 224.0.0.1 accessible
+
+		Expected behavior:
+			1. Start McastHEAR process in daemon mode
+			2. Send "STOP Test" message
+			3. Verify process terminates cleanly
+			4. Ensure all resources are released
+
+		Success criteria:
+			- Process exits with code 0
+			- No lingering processes or sockets
+		"""
 		theResult = False
 		fail_fixture = str("""STOP --> HEAR == error""")
 		_fixture_port_num = self._the_test_port
@@ -77,15 +97,15 @@ def test_cleanup_on_exit(self):
 				self.assertIsNotNone(sender)
 				while p.is_alive():
 					sender(group="224.0.0.1", port=_fixture_port_num, ttl=1, data="STOP Test")
-					p.join(1)
+					p.join(self.QUICK_JOIN_TIMEOUT)
 				self.assertFalse(p.is_alive())
 			except Exception as _cause:
-				p.join(3)
+				p.join(self.ERROR_JOIN_TIMEOUT)
 				if p.is_alive():
 					p.terminate()
 					p.close()
 				raise unittest.SkipTest(fail_fixture) from _cause
-			p.join(15)
+			p.join(self.FINAL_JOIN_TIMEOUT)
 			self.assertIsNotNone(p.exitcode)
 			self.assertEqual(int(p.exitcode), int(0))
 			theResult = (int(p.exitcode) <= int(0))

tests/test_hear_data_processing.py

@@ -23,7 +23,7 @@
 try:
 	try:
 		import context
-	except Exception as _:  # pragma: no branch
+	except ImportError as _:  # pragma: no branch
 		del _  # skipcq - cleanup any error vars early
 		from . import context
 	if context.__name__ is None: