From f9edcd3f364fcaa7df969213149457dd4faade19 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Wed, 23 Sep 2026 10:12:32 -0400 Subject: [PATCH] fix(traceflow): qualify the bare `Type[Dumper]` autodoc references (#709) - `TraceFlow._foutio`'s `#:` comment named a bare `Type[Dumper]`, which Napoleon resolves against every class named `Type` in the project (five of them), so Sphinx warns `more than one target found for cross-reference 'Type'` as soon as anything documents that attribute. - `TraceFlow.__output__` carried the identical bare `Type[Dumper]` in its own `#:` comment, the same latent defect even though nothing currently triggers it. - Qualified both as `~typing.Type[Dumper]`, matching the convention already used for this exact ambiguity in `pcapkit/protocols/__init__.py` and seven sibling files (`frame.py`, `sctp.py`, `link.py`, `tcp.py`, `internet.py`, `udp.py`, `pcapng.py`). - Verified by temporarily mirroring the `autoattribute:: _foutio` directive a pending docs change adds: the bare form reproduces the warning, the qualified form clears it, confirmed against the rendered `typing.Type` link in the built HTML. Build: `sphinx-build -b html` succeeds with no new warnings of any kind. --- pcapkit/foundation/traceflow/traceflow.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pcapkit/foundation/traceflow/traceflow.py b/pcapkit/foundation/traceflow/traceflow.py index 5474d6d13..6eaa1375b 100644 --- a/pcapkit/foundation/traceflow/traceflow.py +++ b/pcapkit/foundation/traceflow/traceflow.py @@ -143,7 +143,7 @@ class TraceFlowBase(Generic[_DT, _BT, _IT, _PT], metaclass=TraceFlowMeta): # Defaults. ########################################################################## - #: DefaultDict[str, tuple[ModuleDescriptor[Dumper] | Type[Dumper], str | None]]: + #: DefaultDict[str, tuple[ModuleDescriptor[Dumper] | ~typing.Type[Dumper], str | None]]: #: Format dumper mapping for writing output files. The values should be a #: tuple representing the module name and class name, or a #: :class:`dictdumper.dumper.Dumper` subclass, and corresponding file extension. @@ -403,7 +403,7 @@ def __init__(self, fout: 'Optional[str]', format: 'Optional[str]', # pylint: di # dump I/O object fio, ext = self.make_fout(fout, format) - #: Type[Dumper]: Dumper class. + #: ~typing.Type[Dumper]: Dumper class. self._foutio = fio #: Optional[str]: Output file extension. self._fdpext = ext