Same bug class as #709, found while fixing it and deliberately left out of scope there.
The collision
pcapkit/const/reg/apptype.py:9784 defines an AppType enum member named dict — IANA registered service
2628:
dict: 'AppType' = 2628, 'dict', TransportProtocol.get('tcp') | TransportProtocol.get('udp')
So when a hand-written :type: field says dict[...], Sphinx resolves dict against the project's own object
inventory, finds pcapkit.const.reg.apptype.AppType.dict, and links there instead of to the builtin. Same
mechanism as #709's bare Type resolving to pcapkit.const.l2tp.type.Type: a short name that happens to collide
with a pcapkit symbol.
Confirmed present in both the before and after docs builds during #714's cross-review, so it is pre-existing
and unrelated to that change.
The four affected sites
docs/source/pcapkit/corekit/fields/strings.rst:39 :type: str | bytes | dict[str, typing.Any]
docs/source/pcapkit/foundation/engines/engine.rst:40 :type: dict[str, ModuleDescriptor[EngineBase] | ...]
docs/source/pcapkit/foundation/traceflow/traceflow.rst:40 :type: dict[str, ModuleDescriptor[TraceFlowBase] | ...]
docs/source/pcapkit/foundation/reassembly/reassembly.rst:43 :type: dict[str, ModuleDescriptor[ReassemblyBase] | ...]
Line numbers are against origin/main at 3904c025a. Note that three of the four are the same files #714
edits — see the ordering note below.
The fix is documentation only
No library change. pcapkit/const/reg/apptype.py is machine-generated from the IANA registry and the member name
dict is correct — the service really is called that. The collision is a documentation-rendering problem, so the
fix belongs in the .rst files: qualify the reference so it resolves uniquely, the same way #709's Type sites
were qualified.
~python:dict or a plain :class:dict`` with an explicit target are both candidates. Whichever is chosen should
match whatever the .rst tree already does elsewhere for builtins — check before inventing a form, and confirm
against a built HTML anchor that the link lands on the Python builtin rather than merely going quiet. A reference
that stops warning while still pointing nowhere is worse than the warning.
Worth noting from #709: the ~-prefixed and fully-qualified forms render identically on the page, so the choice is
about resolution, not appearance.
Ordering
This should land after #714, which currently edits engine.rst, reassembly.rst and traceflow.rst and is
GOOD TO GO waiting only on CI. Touching those files now would either conflict with it or force a re-review and a
full CI cycle on a PR that has already earned its verdict. strings.rst is untouched by #714 and could move
independently, but there is little value in splitting a four-line docs change across two PRs.
Why it is worth fixing rather than tolerating
Each of these renders a wrong hyperlink in the published docs, not just a build warning — a reader clicking
dict on ReassemblyBase.__reassembly__'s signature lands on an IANA port-number enum member. That is the same
reason #709 was worth fixing, and #709's cross-review established that Sphinx picks the wrong target silently
in this situation rather than declining to link at all.
Same bug class as #709, found while fixing it and deliberately left out of scope there.
The collision
pcapkit/const/reg/apptype.py:9784defines anAppTypeenum member nameddict— IANA registered service2628:
So when a hand-written
:type:field saysdict[...], Sphinx resolvesdictagainst the project's own objectinventory, finds
pcapkit.const.reg.apptype.AppType.dict, and links there instead of to the builtin. Samemechanism as #709's bare
Typeresolving topcapkit.const.l2tp.type.Type: a short name that happens to collidewith a
pcapkitsymbol.Confirmed present in both the before and after docs builds during #714's cross-review, so it is pre-existing
and unrelated to that change.
The four affected sites
Line numbers are against
origin/mainat3904c025a. Note that three of the four are the same files #714edits — see the ordering note below.
The fix is documentation only
No library change.
pcapkit/const/reg/apptype.pyis machine-generated from the IANA registry and the member namedictis correct — the service really is called that. The collision is a documentation-rendering problem, so thefix belongs in the
.rstfiles: qualify the reference so it resolves uniquely, the same way #709'sTypesiteswere qualified.
~python:dictor a plain:class:dict`` with an explicit target are both candidates. Whichever is chosen shouldmatch whatever the
.rsttree already does elsewhere for builtins — check before inventing a form, and confirmagainst a built HTML anchor that the link lands on the Python builtin rather than merely going quiet. A reference
that stops warning while still pointing nowhere is worse than the warning.
Worth noting from #709: the
~-prefixed and fully-qualified forms render identically on the page, so the choice isabout resolution, not appearance.
Ordering
This should land after #714, which currently edits
engine.rst,reassembly.rstandtraceflow.rstand isGOOD TO GOwaiting only on CI. Touching those files now would either conflict with it or force a re-review and afull CI cycle on a PR that has already earned its verdict.
strings.rstis untouched by #714 and could moveindependently, but there is little value in splitting a four-line docs change across two PRs.
Why it is worth fixing rather than tolerating
Each of these renders a wrong hyperlink in the published docs, not just a build warning — a reader clicking
dictonReassemblyBase.__reassembly__'s signature lands on an IANA port-number enum member. That is the samereason #709 was worth fixing, and #709's cross-review established that Sphinx picks the wrong target silently
in this situation rather than declining to link at all.