You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
EngineBase is excluded from __all__ and documented :no-members:, so a public return type will expose no API #1024
Surfaced by the cross-review on #1023, which narrows Extractor.engine's declared return type from Engine to EngineBase. That is the honest declaration — every built-in engine subclasses the base directly — but the base is currently set up as an internal name:
Its docstring says it is for internal use only and points customisation at Engine.
docs/source/pcapkit/foundation/engines/engine.rst:71 documents it under Internal Definitions with :no-members:, while Engine carries all the member stubs.
So once #1023 lands, a public property declares a return type whose own documentation exposes no API, and a reader following the type has nowhere to go. The run-time behaviour is unchanged and nothing breaks; this is a documentation-shape problem.
Two ways to close it, and they are not exclusive:
Move the member stubs onto EngineBase in engine.rst and leave Engine documenting only its registration hook, which is the one thing it actually adds.
Export EngineBase in __all__, on the grounds that a type named in a public signature is part of the public surface whatever its docstring says.
Option 1 is the smaller change and probably sufficient. Option 2 is a real API decision, since the class docstring currently tells third parties not to use it — and that in-house-versus-third-party split is the subject of #1016, so the two should be settled together rather than independently.
Two smaller items found in the same pass, both safe to fold in here:
Four _exeng docstrings cross-reference Engine.read_frame / Engine.close (pcapkit/foundation/extraction.py:773, :775, :1114, :1326). They are valid Sphinx targets so the build is fine, but they will be inconsistent with the attribute's declared type, and they cannot simply be repointed at EngineBase while it is :no-members: — which is the same knot as above.
Surfaced by the cross-review on #1023, which narrows
Extractor.engine's declared return type fromEnginetoEngineBase. That is the honest declaration — every built-in engine subclasses the base directly — but the base is currently set up as an internal name:pcapkit/foundation/engines/engine.pysets__all__ = ['Engine'], excludingEngineBase.Engine.docs/source/pcapkit/foundation/engines/engine.rst:71documents it under Internal Definitions with:no-members:, whileEnginecarries all the member stubs.So once #1023 lands, a public property declares a return type whose own documentation exposes no API, and a reader following the type has nowhere to go. The run-time behaviour is unchanged and nothing breaks; this is a documentation-shape problem.
Two ways to close it, and they are not exclusive:
EngineBaseinengine.rstand leaveEnginedocumenting only its registration hook, which is the one thing it actually adds.EngineBasein__all__, on the grounds that a type named in a public signature is part of the public surface whatever its docstring says.Option 1 is the smaller change and probably sufficient. Option 2 is a real API decision, since the class docstring currently tells third parties not to use it — and that in-house-versus-third-party split is the subject of #1016, so the two should be settled together rather than independently.
Two smaller items found in the same pass, both safe to fold in here:
pcapkit/foundation/engines/pcap.py:98-101carries the same verbless sentence that fix(foundation): declare the engine-typed slots as EngineBase, not Engine #1023 repaired inextraction.py— "will also be save the currentPCAPengine instance"._exengdocstrings cross-referenceEngine.read_frame/Engine.close(pcapkit/foundation/extraction.py:773,:775,:1114,:1326). They are valid Sphinx targets so the build is fine, but they will be inconsistent with the attribute's declared type, and they cannot simply be repointed atEngineBasewhile it is:no-members:— which is the same knot as above.Related: #1022, #1023, #1016.