docs(foundation): teach custom engines to keep a user's verbose callback (#1874)

- The custom-engine example in ext.rst tests `ext._vfunc_default`, not
  `ext._flag_v`, and says why: a `verbose=` callable must be kept.
- Document `Extractor._vfunc_default` on the extraction page.
- Run the verbose-callback module on every engine-tests leg, and update
  the tier guard test that pins the PyShark leg's TEST_PATHS line.

Refs #1874

Author: JarryShaw

.github/workflows/unit-tests.yml

@@ -1030,11 +1030,11 @@ jobs:
           fi
 
           case "$ENGINE" in
-            Scapy) TEST_PATHS="tests/toolkit/test_scapy_unit.py tests/foundation/engines/test_scapy_engine.py tests/protocols/transport/test_sctp_unit.py" ;;
-            PyShark) TEST_PATHS="tests/toolkit/test_pyshark_unit.py tests/foundation/engines/test_pyshark_engine.py" ;;
-            PyPCAPFile) TEST_PATHS="tests/toolkit/test_pypcapfile_unit.py tests/foundation/engines/test_pypcapfile_engine.py" ;;
-            PyPCAP) TEST_PATHS="tests/toolkit/test_pypcap_unit.py tests/foundation/engines/test_pypcap_engine.py tests/foundation/engines/test_pcap_backend.py" ;;
-            PCAP_CT) TEST_PATHS="tests/toolkit/test_pcap_ct_unit.py tests/foundation/engines/test_pcap_ct_engine.py tests/foundation/engines/test_pcap_backend.py" ;;
+            Scapy) TEST_PATHS="tests/toolkit/test_scapy_unit.py tests/foundation/engines/test_scapy_engine.py tests/protocols/transport/test_sctp_unit.py tests/foundation/engines/test_engine_verbose_callback_1874_unit.py" ;;
+            PyShark) TEST_PATHS="tests/toolkit/test_pyshark_unit.py tests/foundation/engines/test_pyshark_engine.py tests/foundation/engines/test_engine_verbose_callback_1874_unit.py" ;;
+            PyPCAPFile) TEST_PATHS="tests/toolkit/test_pypcapfile_unit.py tests/foundation/engines/test_pypcapfile_engine.py tests/foundation/engines/test_engine_verbose_callback_1874_unit.py" ;;
+            PyPCAP) TEST_PATHS="tests/toolkit/test_pypcap_unit.py tests/foundation/engines/test_pypcap_engine.py tests/foundation/engines/test_pcap_backend.py tests/foundation/engines/test_engine_verbose_callback_1874_unit.py" ;;
+            PCAP_CT) TEST_PATHS="tests/toolkit/test_pcap_ct_unit.py tests/foundation/engines/test_pcap_ct_engine.py tests/foundation/engines/test_pcap_backend.py tests/foundation/engines/test_engine_verbose_callback_1874_unit.py" ;;
           esac
           echo "Running: $TEST_PATHS"
           # shellcheck disable=SC2086

docs/source/ext.rst

@@ -512,9 +512,13 @@ The following code snippet shows how to create a new engine class:
            # check if there's any extraction protocol and/or layer thresholds
            # set by the user (some engines may not support this feature); or
            # to set up the verbose handler for the underlying engine module,
-           # as in the following code snippet.
+           # as in the following code snippet. Install it only when the user
+           # asked for the default output, i.e., `verbose=True`, which sets
+           # `ext._vfunc_default`: a callable given as `verbose=` is the
+           # user's own handler, already stored as `ext._vfunc`, so it must
+           # be kept rather than replaced.
 
-           if ext._flag_v:  # check if verbose mode is enabled
+           if ext._vfunc_default:  # check if the default verbose output is requested
                # NOTE: PyPCAPKit has its own bundled supporting functions for
                # third-party libraries, e.g., the `packet2chain` function is
                # to convert a given Packet instance of the Scapy library to a

docs/source/pcapkit/foundation/extraction.rst

@@ -89,6 +89,7 @@ and extracts parameters from a PCAP file.
 
    .. autoattribute:: _eof_mark
    .. autoattribute:: _vfunc
+   .. autoattribute:: _vfunc_default
 
    .. autoattribute:: _exnam
    .. autoattribute:: _exeng

tests/test_tier_guard.py

@@ -2410,7 +2410,8 @@ def test_a_commented_out_test_paths_arm_does_not_silently_win(self) -> None:
 
         """
         live = ('PyShark) TEST_PATHS="tests/toolkit/test_pyshark_unit.py '
-                'tests/foundation/engines/test_pyshark_engine.py" ;;')
+                'tests/foundation/engines/test_pyshark_engine.py '
+                'tests/foundation/engines/test_engine_verbose_callback_1874_unit.py" ;;')
         doctored = doctored_workflow(
             self,
             live,
@@ -2422,7 +2423,8 @@ def test_a_commented_out_test_paths_arm_does_not_silently_win(self) -> None:
         pyshark_jobs = [job for job in jobs if job.name == 'engine-tests' and 'PyShark' in job.extras]
         self.assertEqual(len(pyshark_jobs), 1)
         self.assertEqual(pyshark_jobs[0].paths, ('tests/toolkit/test_pyshark_unit.py',
-                                                 'tests/foundation/engines/test_pyshark_engine.py'))
+                                                 'tests/foundation/engines/test_pyshark_engine.py',
+                                                 'tests/foundation/engines/test_engine_verbose_callback_1874_unit.py'))
 
     def test_the_undoctored_workflow_produces_no_unexplained_gap(self) -> None:
         """The control: the tests above fail for the doctoring, not by default."""