[STYLE] Refactoring for modern python code-style (e.g. 3.9+)

.coderabbit.yaml

@@ -105,7 +105,7 @@ reviews:
         5. As a general rule, undocumented function definitions and class definitions in the project's Python code are assumed incomplete. Please consider suggesting a short summary of the code for any of these incomplete definitions as docstrings when reviewing.
 
         6. Verify Flake8's configuration file is located at ".flake8.ini"
-    - path: tests/*
+    - path: 'tests/*'
       instructions: >-
         When reviewing **test** code:
 
@@ -138,14 +138,14 @@ reviews:
         'tests/requirements.txt' for testing the project.
 
         Consider these the records of truth regarding project test code dependencies.
-    - path: .github/**
+    - path: '.github/**'
       instructions: >-
         * When the project is hosted on GitHub: All GitHub-specific configurations, templates, and tools should be found in the '.github' directory tree.
 
         * 'actionlint' erroneously generates false positives when dealing with GitHub's `${{ ... }}` syntax in conditionals.
 
         * 'actionlint' erroneously generates incorrect solutions when suggesting the removal of valid `${{ ... }}` syntax.
-    - path: docs/*
+    - path: 'docs/*'
       instructions: >-
         When a project contains a `docs/` directory:
 

.github/tool_checkmake.sh

@@ -80,6 +80,7 @@ fi
 function check_command() {
 	test -z "$1" && { printf "%s\n" "::warning file=${SCRIPT_NAME},title=BUG::Command name is required to check for existence." >&2 ; exit 64 ; } ;
 	local cmd="$1" ;
+	# shellcheck disable=SC2086
 	test -x "$(command -v ${cmd})" || { printf "%s\n" "::error file=${SCRIPT_NAME},title=MISSING::Required command '${cmd}' is not found." >&2 ; exit 126 ; } ;
 }  # end check_command()
 # propagate/export function to sub-shells

.github/tool_shlock_helper.sh

@@ -94,6 +94,6 @@ if [[ ( $# -eq 0 ) ]] ; then
 	test -e "${LOCK_FILE}" || false  ;
 	EXIT_CODE=0 ;
 fi
-
+# shellcheck disable=SC2086
 exit ${EXIT_CODE:-126};
 

.github/workflows/makefile-lint.yml

@@ -56,6 +56,7 @@ jobs:
           YAML_ARGS: "${{ vars.YAML_ARGS }}"
         run: |
           printf "Validating workflow with args: %s\n" "${YAML_ARGS}"
+          # shellcheck disable=SC2086
           yamllint ${YAML_ARGS} .github/workflows/makefile-lint.yml
       - name: Install checkmake
         if: ${{ success() }}

.github/workflows/markdown-lint.yml

@@ -42,6 +42,7 @@ jobs:
           YAML_ARGS: "${{ vars.YAML_ARGS }}"
         run: |
           printf "Validating workflow with args: %s\n" "${YAML_ARGS}"
+          # shellcheck disable=SC2086
           yamllint ${YAML_ARGS} .github/workflows/markdown-lint.yml
 
       - name: Lint YAML config for markdown
@@ -50,6 +51,7 @@ jobs:
           YAML_ARGS: "${{ vars.YAML_ARGS }}"
         run: |
           printf "Validating workflow with args: %s\n" "${YAML_ARGS}"
+          # shellcheck disable=SC2086
           yamllint ${YAML_ARGS} .markdownlint.yaml
 
       - name: Install NPM Dependencies

docs/FAQ.md

@@ -243,7 +243,7 @@ work so far as this Multicast module is concerned.
   to the specific commit you're working on, set the `DOCS_BUILD_REF` environment variable:
 
   ```bash
-  export DOCS_BUILD_REF=$(${GIT:-git} rev-parse --verify HEAD)
+  export DOCS_BUILD_REF=$("${GIT:-git}" rev-parse --verify HEAD)
   make build-docs  # or your own documentation build command
   ```
 

docs/conf.py

@@ -36,7 +36,6 @@
 	'v2.0'
 """
 
-
 import sys
 import os
 from urllib.parse import quote
@@ -72,17 +71,25 @@
 # for md us 'autodoc2' (pip install sphinx-autodoc2)
 # for rst use 'sphinx.ext.autodoc'
 extensions = [
-	"""sphinx.ext.napoleon""", """autodoc2""", """sphinx.ext.autosectionlabel""",
-	"""sphinx.ext.githubpages""", """myst_parser""", """sphinx_design""",
-	"""sphinx.ext.autosummary""", """sphinx.ext.doctest""", """sphinx.ext.todo""",
-	"""sphinx.ext.linkcode""", """sphinx.ext.viewcode""", """sphinx.ext.intersphinx""",
+	"""sphinx.ext.napoleon""",
+	"""autodoc2""",
+	"""sphinx.ext.autosectionlabel""",
+	"""sphinx.ext.githubpages""",
+	"""myst_parser""",
+	"""sphinx_design""",
+	"""sphinx.ext.autosummary""",
+	"""sphinx.ext.doctest""",
+	"""sphinx.ext.todo""",
+	"""sphinx.ext.linkcode""",
+	"""sphinx.ext.viewcode""",
+	"""sphinx.ext.intersphinx""",
 ]
 
 # for md auto-docs
 autodoc2_packages = [
+	"tests",
 	"multicast",
 	"tests.context",
-	"tests",
 ]
 
 autodoc2_render_plugin = "myst"
@@ -92,11 +99,11 @@
 
 # The suffix of source filenames.
 source_suffix = {
+	".yml": "yaml",
 	".md": "markdown",
 	".txt": "markdown",
-	".rst": "restructuredtext",
-	".yml": "yaml",
 	"Makefile": "makefile",
+	".rst": "restructuredtext",
 }
 
 # The encoding of source files. Official sphinx docs recommend utf-8-sig.
@@ -132,8 +139,18 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
-	"_build", ".github", ".circleci", "codecov_env", ".DS_Store", "**/.git", "dist",
-	"../tests/tests/**", "www", "**/docs", "../multicast/multicast/**", "*~"
+	"*~",
+	"www",
+	"dist",
+	"_build",
+	".github",
+	"**/docs",
+	"**/.git",
+	".DS_Store",
+	".circleci",
+	"codecov_env",
+	"../tests/tests/**",
+	"../multicast/multicast/**",
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
@@ -161,7 +178,6 @@
 # pygments_style_dark ="monokai"
 pygments_style_dark = "github-dark"
 
-
 pygments_options = {
 	"""tabsize""": 4,
 	"""stripall""": False,
@@ -268,12 +284,11 @@
 # html_use_opensearch = ''
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = "html"
+#html_file_suffix = ".html"
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "multicast_doc"
 
-
 # -- Options for MyST markdown parser -------------------------------------------
 # see https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html
 
@@ -287,7 +302,11 @@
 myst_linkify_fuzzy_links = False
 
 # Focus only on github markdown
-myst_gfm_only = True
+# NOTE: We keep myst_gfm_only = False because setting it to True
+# (see PR #240) caused a regression where the 'toc.md' contents
+# fence broke. Re-enabling GitHub Flavored Markdown exclusively
+# should be approached with caution to avoid that issue.
+myst_gfm_only = False
 
 myst_html_meta = {
 	"github_url": f"https://github.com/reactive-firewall/{project}"
@@ -340,13 +359,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-	(
-		"index",
-		"Documentation.tex",
-		"Multicast Documentation",
-		"reactive-firewall",
-		"manual"
-	),
+	("index", "Documentation.tex", "Multicast Documentation", "reactive-firewall", "manual"),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -369,39 +382,29 @@
 # If false, no module index is generated.
 # latex_domain_indices = True
 
-
 # -- Options for manual page output --------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-	(
-		"index",
-		"multicast",
-		"Multicast Documentation",
-		["reactive-firewall"],
-		1
-	)
-]
+man_pages = [("index", "multicast", "Multicast Documentation", ["reactive-firewall"], 1)]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
 
-
 # -- Options for Texinfo output ------------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
 	(
-		"index",
-		"Multicast",
-		"Multicast Documentation",
-		"reactive-firewall",
-		"Multicast",
-		"Multicast Python Module.",
-		"Miscellaneous"
+	"index",
+	"Multicast",
+	"Multicast Documentation",
+	"reactive-firewall",
+	"Multicast",
+	"Multicast Python Module.",
+	"Miscellaneous"
 	),
 ]
 
@@ -418,22 +421,19 @@
 
 linkcode_url_prefix: str = f"https://github.com/reactive-firewall/{project}"
 
+suffix = """/issues/%s"""
+
 extlinks = {
 	"""issue""": (
-		str("""{prefix}/{suffix}""").format(
-			prefix=linkcode_url_prefix, suffix="""/issues/%s"""
-		),
-		"""issue #%s"""
+	f"{linkcode_url_prefix}/{suffix}",
+	"""issue #%s"""
 	)
 }
 
 # try to link with official python3 documentation.
 # see https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html for more
 intersphinx_mapping = {
-	"""python""": (
-		"""https://docs.python.org/3""",
-		(None, """python-inv.txt""")
-	)
+	"""python""": ("""https://docs.python.org/3""", (None, """python-inv.txt"""))
 }
 
 

docs/utils.py

@@ -18,6 +18,7 @@
 
 import re
 
+
 def _validate_git_ref(ref: str) -> str:
 	"""
 	Validate if the provided string is a valid Git reference.
@@ -104,6 +105,6 @@ def slugify_header(s: str) -> str:
 			'cep-7-documentation-guide'
 	"""
 	# First, remove special characters and convert to lowercase
-	text = re.sub(r'[^\w\- ]', '', s).strip().lower()
+	text = re.sub(r'[^\w\- ]', "", s).strip().lower()
 	# Then replace consecutive spaces or dashes with a single dash
-	return re.sub(r'[-\s]+', '-', text)
+	return re.sub(r'[-\s]+', "-", text)