fix(foundation): keep a user's verbose callback on every engine (#1874)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Stacked on #1867. It contains #1867's commits until that merges, so merge #1867 first. This PR's own commits are 9cbb10e4b (the fix) and e24f384fb (docs and CI).

• Extractor records in a private _vfunc_default flag whether
  verbose=True asked for the default printer; a callable leaves it unset.
• The scapy, dpkt, pyshark, pypcap, pcap-ct and pypcapfile engines install
  their own printer only when that flag is set, so a caller's callback is
  no longer replaced. The verbose=True output is unchanged.
• Note the fix in Extractor's 1.5.0 versionchanged block, and correct the
  _flag_v comment, which said it gated the per-frame call.
• Test each installed engine end to end on in.pcap, with a recording
  callback and with verbose=True, and add fake-extractor cases for the
  engines that cannot run here.

Closes #1874

Follow-up commit: ext.rst's custom-engine example now tests ext._vfunc_default, _vfunc_default is documented on the extraction page, and the new test module is added to every engine leg's TEST_PATHS (an in-place, line-neutral edit). The PyPCAP and PyPCAPFile end-to-end cases first run in CI, because neither engine builds here.

[JarryShaw]

Verdict: GOOD TO GO at e24f384fb. A Sonnet cross-review found no defects.

• Runtime. On in.pcap, a verbose= callable now runs once per frame on the default, dpkt and Scapy engines. Each call gets (extractor, frame), and the frame is the same object as extractor.frame[i]. On 817208c8a it ran zero times and the engine printed its own lines.
• No change for bools. verbose=True output is byte-identical to before, and verbose=False prints nothing on either tree.
• Engines. All six third-party engines now read _vfunc_default. No reader of _flag_v is left in the package.
• Fail-before. Run against the old pcapkit/, the new tests fail for the right reasons. Reverting any single engine to _flag_v breaks exactly one test.
• Workflow. The five TEST_PATHS lines differ only by the new module, and the YAML still parses.
• Tests: tests/foundation tests/cli tests/interface gave 523 passed and 17 skipped; tests/project gave 992 passed and 1 skipped (unrelated).
• Unverified. Real extraction on PyShark, PyPCAP, PCAP_CT and PyPCAPFile, because those libraries are not installable on 3.14 here. The mock-based tests cover their gates.
• Note, not a blocker. _flag_v is still set and documented but nothing in the package reads it now. A custom engine written to the old docs keeps its old behaviour.

[JarryShaw]

Verdict: GOOD TO GO at 657ef260f. This is the rebase onto #1867's 5b0e9fdbe.

• git range-diff shows both commits unchanged, and the cumulative diff of this PR's own commits is byte-identical to before.
• The verbose-callback tests (6 passed, with the same 8 skips for engines that can't install here), test_extraction.py, test_tier_guard.py and the docs(foundation): Extractor._vfunc's annotation is commented out, so its documented attribute renders empty #1839 signature test all pass.
• A callback still runs once per frame on the default, dpkt and Scapy engines, and verbose=True output is byte-identical.

Merge #1867 first.

[JarryShaw]

Not following, if there's a user provided callback, how will it be called then? My initial plan is to have user's callback replace the default printer and being called in the printer's place when version flag is set.

[JarryShaw]

That is what this PR does. The user's callback takes the printer's place, and nothing else changes. At 657ef260f:

• verbose=<callable>. Extractor stores the callback as _vfunc, sets _flag_v = True and sets _vfunc_default = False (extraction.py:1311-1313).
• verbose=True. It sets _vfunc_default = True and installs the PCAP/PCAP-NG printer (:1295-1307).
• Every engine calls ext._vfunc(ext, frame) once per frame, for example engines/scapy.py:431 and engines/dpkt.py:530.
• Third-party engines replace _vfunc with their own printer only when _vfunc_default is set (scapy.py:387), because their frames are not pcapkit Frames.

The bug in #1874 was that check. The engines tested _flag_v, which is also True for a callback, so they overwrote the user's callback with their printer. Now the callback stays in _vfunc and runs where the printer would have run. Measured on in.pcap: a recording callback runs once per frame on the default, dpkt and Scapy engines, where before it never ran on dpkt or Scapy. verbose=True output is byte-identical to before.

[github-actions]

Coverage: 90.05% (unit tier, Python 3.15, 657ef260f, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2462	69	780	35	96.55%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2916	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17406	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4407	2342	1010	157	43.27%

Per-file detail: the coverage-html artifact of this run.