Repository navigation
docs: #719-style prose sweep after the #1090–#1102 defect wave #1103
Description
Is your feature request related to a problem? Please describe.
The defect wave #1090–#1102 changes code and docstrings in several modules, and #719's two rounds of prose sweeps predate those changes. The maintainer asked for another #719-style pass over the docs and comments once the wave lands.
Describe the solution you'd like
Re-read the prose that the wave's merged PRs touched or made stale: docstrings, comments, docs/ and pep.rst. Apply #719's rules: no churn, accuracy first, no timed context, and only prose changes, with an AST guard on every .py.
Blocked until
Every issue in #1090–#1102 is closed.
Describe alternatives you've considered
Folding the sweep into each fix PR was rejected: thirteen parallel PRs editing shared prose would conflict.
Activity
JarryShaw commentedon Oct 6, 2026
Add to this sweep:
ProtocolBase.pack()(protocol.py:559-576) rebuilds frommake(**kwargs)and ignores the instance's parsed or constructed state. A bareX(...).pack()therefore returns defaults. Neither the docstring nor the rst docs say so. This came up in the #1143 review.JarryShaw commentedon Oct 6, 2026
Add to this sweep, after #1147 merges:
docs/source/ext.rst:~266saysfrom_data"warnsUnknownFieldWarning" and that its keywords "come from your_make_data". Caller-supplied keywords now raiseUnsupportedCall._check_construction_keywordsdocstring describeskwargsas what remains after__init__.from_datacalls it as well now.JarryShaw commentedon Oct 6, 2026
Still blocked, with a new condition. Every issue in #1090–#1102 is closed, but the sweep is meant to run after all the defects the wave turned up are fixed, so that it reads the final docstrings once. It now unblocks when #1127, #1133, #1144, #1151, #1154, #1155 and #1156 are all closed.
JarryShaw commentedon Oct 7, 2026
Still blocked, with a new condition. All seven issues named in the last condition are now closed. Two more defects from the same audit are now being fixed, #1165 and #1167, and they edit
extraction.py,dumpkit/pcap.py,ipv4.pyandudp.py. The sweep unblocks once #1165 and #1167 are both closed, so it reads the final docstrings once.JarryShaw commentedon Oct 7, 2026
Condition extended: the #1169 cross-review turned up #1170, a defect in the same class that touches
ipv4.py,ipv6.py,udp.pyand the shared_import_next_layer. The sweep now unblocks once #1165, #1167 and #1170 are all closed.JarryShaw commentedon Oct 7, 2026
The previous condition is met: #1165, #1167 and #1170 are all closed. Two defects from the same audit are still in flight: #1172 (
l2tpv2.py) and #1173 (ipv6_route.py,mh.py,application.py). The sweep would read the docstrings of the files they edit, so it now unblocks when #1172 and #1173 are both closed. These are the last known items from this audit.JarryShaw commentedon Oct 7, 2026
Unblocked: #1172 and #1173 are both closed (#1174 and #1176 merged at 04:00Z and 04:01Z). Now
pending. Three later items are still open: #1175 (l2tpv2.py), #1177 (ipv6.py) and #1178 (ipv6_ext.py). The sweep skips those three files and they get a delta pass once each issue closes.JarryShaw commentedon Oct 7, 2026
Dispatched as three prose slices, each scoped to
git diff b10e7951b origin/main:protocols,schema-dataandfoundation-docs. The #1175/#1177/#1178 files are excluded.83 remaining items
test: fix the review findings on the tests prose pass (#1103)
docs(foundation): fix the review findings on the foundation pass (#1103)
docs(corekit): fix the review findings on the corekit pass (#1103)
docs(protocols): fix the review findings on the application pass (#1103)
docs(changelog): fix the review findings on the changelog pass (#1103)
docs(foundation): resolve the Completion cross-references (#1103)
docs(foundation): third whole-repo pass over foundation, toolkit, dum…
docs(protocols): third whole-repo pass over application, misc and the…
docs(protocols): third whole-repo pass over internet (#1103) (#1836)
docs(corekit): third whole-repo pass over corekit, const and vendor (#…
docs(ci): fix the review findings on the repo-files pass (#1103) (#1838)
JarryShaw commentedon Oct 16, 2026
Round 3: every PR has merged. The round-3 PRs, #1829–#1838, landed between 19:54Z and 23:11Z. Five of them merged before their review finished, and four of those reviews found defects. Their fixes went to
mainas docs-only or test-only follow-ups (5d86fcbf2,4ac931eed,e5f7fb66b), plus #1838. A combined clean build andtests/projectrun passed onmaintogether with every open round-3 PR before the last merges.Code-level findings are filed as #1839–#1863. Each was reproduced at
e5f7fb66band independently verified before filing.needs: decision): design(corekit):NO_VALUEloses its identity undercopy.deepcopyand pickle #1842, design(const):get(value, default)on an out-of-range value returns the default but logs a CRITICAL error and installs pcapkit's excepthook #1845, fix(const):LLACode.Wilcardmisspells RFC 5568's code 0, andLLACode.MHnames code 2 differently from the RFC #1848, fix(vendor):pcapkit-vendorfails with a bareModuleNotFoundErrorwithout the vendor extra, which conda users cannot install #1850, ci(conda): nothing retires aPLATFORM_PINSentry once upstream ships the wheel again #1851 and ci(vendor): the vendor-update leg commits regenerated const data without testing it #1853.wip): the rest. Exception: theconf.pyrendering fixes (docs: aenum and stdlib enum unions render asIntEnum | IntEnumandEnum | Enum#1858–docs: the viewcode module index links abuiltinspage that is never generated #1863) start once docs: sphinx-autodoc-typehints 3.15.0 renames the private_resolverthatconf.pyimports, so the next dependency bump breaks the docs build #1856's pin bump lands._resolverthatconf.pyimports, so the next dependency bump breaks the docs build #1856 is time-sensitive. sphinx-autodoc-typehints 3.15.0, released today, renamed the private moduleconf.pyimports, so the next weekly dependency bump would break the docs build.Blocked until #1839–#1863 are closed or decided. Round 4 then runs over the whole repo again, per the earlier ruling.