Stage improved testing

.ast-grep/rules/python-rule-add-trailing-comma.yml

@@ -0,0 +1,29 @@
+# .ast-grep/python-rule-add-trailing-comma.yml
+id: python-rule-add-trailing-comma
+rule:
+  all:
+    - matches: python-rule-argument-last-without-comma
+    - not:
+        pattern:
+          $LAST_ARG,
+language: python
+message: "Consider adding a trailing comma."
+description: Rule for improving future maintainability by pre-emptivly adding trailing commas.
+severity: hint
+fix:
+  $LAST_ARG,
+examples:
+  - name: Argument list with missing trailing comma
+    code: |
+      # trivial example should match
+      warnings.warn(
+        "This should match. because there is no trailing comma.",
+        stacklevel=2
+      )
+  - name: Resulting argument list with trailing comma
+    code: |
+      # trivial example should no-longer match
+      warnings.warn(
+        "This should match. because there is no trailing comma.",
+        stacklevel=2,
+      )

.ast-grep/utils/python/structure/argument-last-without-comma.yml

@@ -0,0 +1,30 @@
+# .ast-grep/utils/python/structure/argument-last-without-comma.yml
+# Argument Structure utils
+id: python-rule-argument-last-without-comma
+rule:
+  any:
+    - kind: identifier
+    - kind: integer
+    - kind: float
+    - kind: string
+    - kind: keyword_argument
+      matches: python-rule-keyword-argument-inside-list-with-comma
+  nthChild:
+    position: 1
+    reverse: true
+  inside:
+    all:
+      - kind: argument_list
+        matches: python-rule-argument-list-with-comma
+  precedes:
+    pattern: )
+  pattern:
+    $LAST_ARG
+  all:
+    - not:
+        pattern:
+          $LAST_ARG,
+    - not:
+        pattern:
+          $$$, $LAST_ARG)
+language: python

.ast-grep/utils/python/structure/argument-list-with-comma.yml

@@ -0,0 +1,13 @@
+# .ast-grep/utils/python/structure/argument-list-with-comma.yml
+# Argument Structure utils
+id: python-rule-argument-list-with-comma
+rule:
+  kind: argument_list
+  pattern: |
+      $_FULL_ARG_LIST
+  has:
+    all:
+      - regex: "[,]"
+      - regex: "\
+          "
+language: python

.ast-grep/utils/python/structure/keyword-argument-inside-list-with-comma.yml

@@ -0,0 +1,17 @@
+# .ast-grep/utils/python/structure/keyword-argument-inside-list-with-comma.yml
+# Argument Structure utils
+id: python-rule-keyword-argument-inside-list-with-comma
+rule:
+  kind: keyword_argument
+  inside:
+    all:
+      - kind: argument_list
+        matches: python-rule-argument-list-with-comma
+      - regex: |
+          [^(]*[^,]
+  nthChild:
+    position: 1
+    reverse: true
+  pattern:
+    $_KW_ARG
+language: python

.coveragerc

@@ -34,6 +34,7 @@ exclude_lines =
     if __name__ in u"__main__":
     if __name__ .. .__main__.:
     if __sys_path__ not in sys.path:
+    if __debug__
     os.abort()
     exit
 
@@ -52,6 +53,7 @@ partial_branches =
     if __name__ in u'__main__':
     if __name__ in u"__main__":
     if __name__ in '__main__':
+    if __debug__
     if __sys_path__ not in sys.path:
     # don't complain about sys.modules
     sys.modules

.github/workflows/codeql-analysis.yml

@@ -44,7 +44,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3.28.13
+      uses: github/codeql-action/init@45775bd8235c68ba998cffa5171334d58593da47  # v3.28.15
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -55,7 +55,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3.28.13
+      uses: github/codeql-action/autobuild@45775bd8235c68ba998cffa5171334d58593da47  # v3.28.15
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -69,4 +69,4 @@ jobs:
     #    make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3.28.13
+      uses: github/codeql-action/analyze@45775bd8235c68ba998cffa5171334d58593da47  # v3.28.15

.github/workflows/scorecard.yml

@@ -30,7 +30,7 @@ jobs:
         with:
           persist-credentials: false
       - name: "Run analysis"
-        uses: ossf/scorecard-action@15bc21f12b2fbbb36fa93d5f2e786f6b18ffe048  # v2.4.1
+        uses: ossf/scorecard-action@405dced65a1dcc6bc335115002f0690b1f1e49bb  # v2.4.1
         with:
           results_file: results.sarif
           results_format: sarif
@@ -53,6 +53,6 @@ jobs:
           retention-days: 5
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@1b549b9259bda1cb5ddde3b41741a82a2d15a841  # v3.28.13
+        uses: github/codeql-action/upload-sarif@45775bd8235c68ba998cffa5171334d58593da47  # v3.28.15
         with:
           sarif_file: results.sarif

Makefile

@@ -1,3 +1,3 @@
 #!/usr/bin/env make -f
 
 # Multicast Python Module
@@ -212,9 +212,17 @@
 	$(QUIET)$(RMDIR) ./dist/ 2>$(ERROR_LOG_PATH) || :
 	$(QUIET)$(RMDIR) ./.eggs/ 2>$(ERROR_LOG_PATH) || :
 
-purge: legacy-purge
+purge-test-reports::
 	$(QUIET)$(RM) ./test-reports/*.xml 2>$(ERROR_LOG_PATH) || :
 	$(QUIET)$(RMDIR) ./test-reports/ 2>$(ERROR_LOG_PATH) || :
+
+purge-coverage-artifacts: legacy-purge
+	$(QUIET)$(RM) ./coverage_* 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(RM) ./.coverage.* 2>$(ERROR_LOG_PATH) || :
+	$(QUIET)$(RM) ./coverage_doctests.xml 2>$(ERROR_LOG_PATH) || :
+
+purge: purge-coverage-artifacts purge-test-reports
+	$(QUIET)$(WAIT)
 	$(QUIET)$(ECHO) "$@: Done."
 
 test: just-test
@@ -223,6 +231,12 @@
 	$(QUIET)$(COVERAGE) report -m --include=* 2>$(ERROR_LOG_PATH) || : ;
 	$(QUIET)$(ECHO) "$@: Done."
 
+test-mod: test-mat
+	$(QUIET)$(DO_FAIL) ;
+	$(QUIET)$(COVERAGE) combine 2>$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(COVERAGE) report -m --include=* 2>$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(ECHO) "$@: Done."
+
 test-tox: build
 	$(QUIET)tox -v -- || tail -n 500 .tox/py*/log/py*.log 2>$(ERROR_LOG_PATH)
 	$(QUIET)$(COVERAGE) combine 2>$(ERROR_LOG_PATH) || : ;
@@ -253,18 +267,20 @@
 	$(QUIET)$(WAIT) ;
 	$(QUIET)$(DO_FAIL) ;
 
-test-mat: test-mat-build test-mat-bootstrap test-mat-basic test-mat-say test-mat-hear test-mat-usage test-mat-doctests ## Run all minimum acceptance tests
+test-mat: cleanup MANIFEST.in test-mat-build test-mat-bootstrap test-mat-basic test-mat-say test-mat-hear test-mat-usage test-mat-doctests ## Run all minimum acceptance tests
 	$(QUIET)$(WAIT) ;
 	$(QUIET)$(DO_FAIL) ;
 
-test-mat-doctests: MANIFEST.in ## Run doctests MAT category (doctests are special)
+test-mat-doctests: test-reports MANIFEST.in ## Run doctests MAT category (doctests are special)
 	$(QUIET)if [ -n "$$TESTS_USE_PYTEST" ]; then \
 		$(ECHO) "SKIP: The target '$@' is not compatable with pytests;"; \
 		$(ECHO) "Try 'make test-mat-doctests' instead."; \
 	else \
 		$(COVERAGE) run -p --source=multicast -m tests.run_selective --group mat --category doctests || DO_FAIL="exit 2" ; \
-		$(COVERAGE) combine 2>$(ERROR_LOG_PATH) || : ; \
-		$(COVERAGE) xml --include=* 2>$(ERROR_LOG_PATH) || : ; \
+		$(QUIET)$(WAIT) ; \
+		$(COVERAGE) combine --keep --data-file=coverage_doctests ./.coverage.* 2>$(ERROR_LOG_PATH) || : ; \
+		$(COVERAGE) report -m --include=* --data-file=coverage_doctests 2>$(ERROR_LOG_PATH) || : ; \
+		$(COVERAGE) xml -o test-reports/coverage_doctests.xml --include=* --data-file=coverage_doctests 2>$(ERROR_LOG_PATH) || : ; \
 	fi
 	$(QUIET)$(WAIT) ;
 	$(QUIET)$(DO_FAIL) ;

docs/conf.py

@@ -123,7 +123,7 @@
 # The short X.Y version.
 version = "v2.0"
 # The full version, including alpha/beta/rc tags.
-release = "v2.0.5"
+release = "v2.0.6"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

multicast/__init__.py

@@ -22,6 +22,7 @@
 import socket
 import struct
 import abc
+import logging
 
 # skipcq
 __all__ = [
@@ -52,6 +53,7 @@
 	"""EXIT_CODES""",
 	"""EXCEPTION_EXIT_CODES""",
 	"""_BLANK""",
+	"""_MCAST_DEFAULT_BUFFER_SIZE""",  # added in version 2.0.6
 	"""_MCAST_DEFAULT_PORT""",
 	"""_MCAST_DEFAULT_GROUP""",
 	"""_MCAST_DEFAULT_TTL""",
@@ -114,7 +116,7 @@
 
 global __version__  # skipcq: PYL-W0604
 
-__version__ = "2.0.5"
+__version__ = "2.0.6"
 """The version of this program.
 
 	Minimal Acceptance Testing:
@@ -156,6 +158,7 @@
 
 Attributes:
 	__version__ (str): The version of this package.
+	_MCAST_DEFAULT_BUFFER_SIZE (int): Default buffer size for multicast communication (1316).
 	_MCAST_DEFAULT_PORT (int): Default port for multicast communication (59259).
 	_MCAST_DEFAULT_GROUP (str): Default multicast group address ('224.0.0.1').
 	_MCAST_DEFAULT_TTL (int): Default TTL for multicast packets (1).
@@ -215,6 +218,57 @@
 		>>>
 
 
+"""
+
+global _MCAST_DEFAULT_BUFFER_SIZE  # skipcq: PYL-W0604
+
+_MCAST_DEFAULT_BUFFER_SIZE = 1316
+"""
+	Arbitrary buffer size to use by default, though any value below 65507 should work.
+
+	Minimal Testing:
+
+	First set up test fixtures by importing multicast.
+
+		>>> import multicast
+		>>>
+
+	Testcase 0: Multicast should have a default buffer size.
+		A: Test that the _MCAST_DEFAULT_BUFFER_SIZE attribute is initialized.
+		B: Test that the _MCAST_DEFAULT_BUFFER_SIZE attribute is an int.
+
+		>>> multicast._MCAST_DEFAULT_BUFFER_SIZE is not None
+		True
+		>>> type(multicast._MCAST_DEFAULT_BUFFER_SIZE) is type(1)
+		True
+		>>>
+		>>> multicast._MCAST_DEFAULT_BUFFER_SIZE > int(1)
+		True
+		>>>
+
+	Testcase 1: Multicast should validate buffer size constraints.
+		A: Test that the _MCAST_DEFAULT_BUFFER_SIZE attribute is initialized.
+		B: Test that the _MCAST_DEFAULT_BUFFER_SIZE attribute is an int.
+		C: Test that the _MCAST_DEFAULT_BUFFER_SIZE attribute is RFC-791 & RFC-768 compliant.
+		D: Test that the _MCAST_DEFAULT_BUFFER_SIZE attribute is a smaller than fragment thresholds
+			for typical ethernet MTUs by default.
+
+		>>> multicast._MCAST_DEFAULT_BUFFER_SIZE is not None
+		True
+		>>> type(multicast._MCAST_DEFAULT_BUFFER_SIZE) is type(1)
+		True
+		>>>
+		>>> multicast._MCAST_DEFAULT_BUFFER_SIZE >= int(56)
+		True
+		>>>
+		>>> multicast._MCAST_DEFAULT_BUFFER_SIZE <= int(65527)
+		True
+		>>>
+		>>> multicast._MCAST_DEFAULT_BUFFER_SIZE <= int(1500)
+		True
+		>>>
+
+
 """
 
 global _MCAST_DEFAULT_PORT  # skipcq: PYL-W0604
@@ -351,6 +405,13 @@
 
 """
 
+if logging.__name__ is not None:  # pragma: no branch
+	logging.getLogger(__module__).addHandler(logging.NullHandler())
+	logging.getLogger(__module__).debug(
+		"Loading %s",  # lazy formatting to avoid PYL-W1203
+		__module__,
+	)
+
 if sys.__name__ is None:
 	raise ModuleNotFoundError(
 		"FAIL: we could not import sys. We're like in the matrix! ABORT."
@@ -365,7 +426,13 @@
 if socket.__name__ is None:
 	raise ModuleNotFoundError("FAIL: we could not import socket. ABORT.") from None
 else:  # pragma: no branch
-	socket.setdefaulttimeout(int(_MCAST_DEFAULT_TTL))
+	_tmp_mcast_value = int(_MCAST_DEFAULT_TTL)
+	logging.getLogger(__module__).debug(
+		"Setting default socket timeout to %d",  # lazy formatting to avoid PYL-W1203
+		_tmp_mcast_value,
+	)
+	socket.setdefaulttimeout(_tmp_mcast_value)
+	del _tmp_mcast_value  # skipcq - cleanup any bootstrap/setup leaks early
 
 if struct.__name__ is None:
 	raise ModuleNotFoundError("FAIL: we could not import struct. ABORT.") from None
@@ -407,15 +474,23 @@
 if _config is None:
 	raise ImportError("FAIL: we could not import environment. ABORT.") from None
 else:
+	logging.getLogger(__module__).debug("Configuring overrides and defaults.")
 	_MCAST_DEFAULT_PORT = _config["port"]
 	_MCAST_DEFAULT_GROUP = _config["group"]
 	_MCAST_DEFAULT_TTL = _config["ttl"]
+	_MCAST_DEFAULT_BUFFER_SIZE = _config["buffer_size"]
 	global _MCAST_DEFAULT_BIND_IP  # skipcq: PYL-W0604
 	_MCAST_DEFAULT_BIND_IP = _config["bind_addr"]
 	global _MCAST_DEFAULT_GROUPS  # skipcq: PYL-W0604
 	_MCAST_DEFAULT_GROUPS = _config["groups"]
-	global _MCAST_DEFAULT_BUFFER  # skipcq: PYL-W0604
-	_MCAST_DEFAULT_BUFFER = _config["buffer_size"]
+	if __debug__:  # pragma: no branch
+		logging.getLogger(__module__).info("Overrides and defaults are configured.")
+		logging.getLogger(__module__).debug("Defaults:")
+		for key, value in _config.items():
+			logging.getLogger(__module__).debug(
+				"\t%s=%s",  # lazy formatting to avoid PYL-W1203
+				key, value,
+			)
 
 del _config  # skipcq - cleanup any bootstrap/setup leaks early
 
@@ -491,6 +566,10 @@ def buildArgs(cls, calling_parser_group):
 
 		"""
 		if calling_parser_group is None:  # pragma: no branch
+			logging.getLogger(__module__).debug(
+				"Building %s arguments.",  # lazy formatting to avoid PYL-W1203
+				__name__,
+			)
 			calling_parser_group = argparse.ArgumentParser(
 				prog=str(cls.__name__ if cls.__proc__ is None else cls.__proc__),
 				description=cls.__prologue__,