Repository navigation
docs(conf): resolve decorated overload aliases and qualify colliding third-party classes (#1917, #1918, #1920) - #1929
Merged
Merged
Conversation
…third-party classes (#1917, #1918, #1920) - Move the signature autodoc_preserve_defaults stores on a functools.wraps wrapper onto the wrapped function, so sphinx-autodoc-typehints reads the _read_packet overloads in their own module and Data_Packet renders as the Packet class (#1917). - Record the classes each pcapkit module binds during the module walk, and qualify a third-party class whose bare name another recorded class shares, so the Extractor frame types read scapy.packet.Packet | dpkt.dpkt.Packet | pyshark.packet.packet.Packet (#1918). - Name a class from a package with no usable inventory by a literal instead of an unresolvable role, keeping aenum's exported name (#1920). - Add a tests/project unit test per issue, update the #1858 formatter test, and name the new gated classes in tests/_dependency_gates.py. Closes #1917 Closes #1918 Refs #1920
JarryShaw
added
docs
Owner
Author
|
GOOD TO GO at |
JarryShaw
added
review: good-to-go
Contributor
|
Coverage: 90.07% (unit tier, Python 3.15,
Per-file detail: the |
This was referenced Oct 19, 2026
Merged
JarryShaw
removed
the
review: good-to-go
JarryShaw
added a commit
that referenced
this pull request
Oct 19, 2026
- Restate the test's docstrings as what each check asserts, and rename test_no_dead_target_comes_back to test_no_dead_target_appears. - Demote the pcapkit.vendor.__main__.run cite in vendor/default.py to a literal beside the documented module; the CLI module documents no functions. - Scan pcapkit/vendor/ apart from the two templates still carrying aenum roles, and pin pcapkit.vendor.__main__.run as a dead target. - Scan docs/source/conf.py too: its class formatter now writes literals for packages outside intersphinx_mapping (#1929), and its source has no such role. Closes #1919 Refs #1920
JarryShaw
added a commit
that referenced
this pull request
Oct 19, 2026
…1920) (#1928) * docs: retarget or demote cross-references that cannot resolve (#1919, #1920) - Demote roles naming aenum, pcap, pcapfile and pyshark to literals across hand-written docs and docstrings: their objects.inv has no py: objects (#934). - Demote dpkt, scapy and cryptography targets their inventories lack, such as the top-level dpkt module and scapy.all; link the engine list to project pages. - Retarget warnings.catch_warnings to :class:, dictdumper.Dumper to dictdumper.dumper.Dumper, Dumper._append_dict to the PLIST and JSON writers, and Mapping.items to collections.abc.Mapping. - Demote warnings.filters, abc.ABCMeta.__new__, _declared_keywords and OptionEnumField.post_process, which have no entry anywhere. - Document pcapkit.utilities.compat.final and EnumMeta.registry, and qualify the EnumMeta.registry references. - Add a test rejecting roles into inventory-less packages across docs/ and pcapkit/, and pinning the retired targets and the new entries. Refs #1919 Refs #1920 * docs: state the #1919 test's checks without timed context (#1919) - Restate the test's docstrings as what each check asserts, and rename test_no_dead_target_comes_back to test_no_dead_target_appears. - Demote the pcapkit.vendor.__main__.run cite in vendor/default.py to a literal beside the documented module; the CLI module documents no functions. - Scan pcapkit/vendor/ apart from the two templates still carrying aenum roles, and pin pcapkit.vendor.__main__.run as a dead target. - Scan docs/source/conf.py too: its class formatter now writes literals for packages outside intersphinx_mapping (#1929), and its source has no such role. Closes #1919 Refs #1920
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Searched for similar pull requests
Followed the coding style (
make pylint,make mypy,make isort)make testpasses, and a test case covers the changeAdded a changelog entry — N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657
docs— documentation only#1917.
autodoc_preserve_defaultswrites__signature__onto the@seeksetwrapper, so sphinx-autodoc-typehints evaluated_read_packet's overloads incorekit.decorators. A newautodoc-before-process-signaturehook,sign_wrapped_function, moves the signature to the wrapped function when it matches. The return type that rendered as→ Data_Packetnow reads→ Packetand links.#1918.
format_classqualifies a third-party class when another class bound by the pcapkit modules shares its bare name, givingscapy.packet.Packet | dpkt.dpkt.Packet | pyshark.packet.packet.Packet. dictdumper'sDumperis qualified too, sincedumpkit.common.Dumpershares its name.#1920, formatter part. Packages without an inventory get a qualified literal instead of an unresolved role. The hand-written roles are in #1928.
The pinned docs build (Sphinx 9.1.0, typehints 3.15.0) has 0 warnings. Each new test fails with its fix reverted. They need the pinned typehints, so they skip under an older one.
Closes #1917
Closes #1918
Refs #1920