Skip to content

docs: bare 'dict' in :type: fields resolves to AppType.dict, an IANA service enum member, not the builtin #717

Description

@JarryShaw

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    blockedDeferred pending another issue or decision; see the last comment for what unblocks itbugdocsPull requests that change documentation only (docs: subject prefix)

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions