From 0e07faff581affad26368725b6a3cda54c161ae7 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Thu, 24 Sep 2026 20:10:00 -0400 Subject: [PATCH] docs(foundation): cite the real class statement in the engine-check note - `Extractor.register_engine`'s `# NOTE:` explained its `issubclass(engine, EngineBase)` gate by citing `engines/pcap.py` importing `EngineBase as Engine`. #750 removed that alias: the file now imports `EngineBase` under its own name and declares `class PCAP(EngineBase[Frame])`, so the parenthetical pointed a reader at a shape that is not there. - Cites the class statement rather than a line number, a line citation being the same staleness class. The conclusion is unchanged and still correct: the built-ins subclass the base directly to decline `Engine.__init_subclass__`'s auto-registration, which is why the gate is wide. `See #513.` kept. Comment-only. Verified no `as Engine` survives anywhere under `pcapkit/`, and that the file's AST is identical to `origin/main`'s (434 statements both sides), so coverage is unchanged. tests/foundation 259 passed / 11 skipped / 404 subtests passed, plus tests/test_base_class_contract.py. Fixes #756. --- pcapkit/foundation/extraction.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pcapkit/foundation/extraction.py b/pcapkit/foundation/extraction.py index ed0f9d669..e45ace797 100644 --- a/pcapkit/foundation/extraction.py +++ b/pcapkit/foundation/extraction.py @@ -428,10 +428,11 @@ def register_engine(cls, name: 'str', engine: 'ModuleDescriptor[Engine] | Type[E if isinstance(engine, ModuleDescriptor): engine = engine.klass # NOTE: checked against ``EngineBase`` rather than ``Engine``: every built-in - # engine subclasses the base directly (``engines/pcap.py`` imports it as - # ``EngineBase as Engine``) precisely so that it is *not* auto-registered by - # ``Engine.__init_subclass__``, which made this check reject pcapkit's own - # classes. ``Engine`` is itself an ``EngineBase``, so this only widens. See #513. + # engine subclasses the base directly (``engines/pcap.py`` declares + # ``class PCAP(EngineBase[Frame])``) precisely so that it is *not* + # auto-registered by ``Engine.__init_subclass__``, which made this check + # reject pcapkit's own classes. ``Engine`` is itself an ``EngineBase``, so + # this only widens. See #513. if not issubclass(engine, EngineBase): raise RegistryError(f'engine must be an Engine subclass, not {engine!r}') incumbent = cls.__engine__.get(name)