Skip to content

Commit e85e915

Browse files
authored
docs(docs): sixth whole-repo pass over docs (#1103) (#2213)
Prose only, in the contributing pages and conf.py's comments: - test-coverage: KNOWN_DEGRADED entries carry any-of error fragments, and the asserted table is DispatchRegistryTests.KNOWN_DEGRADED. - workflows: the ruleset also requires Lint; restate change-relative passages (Cron Head, the schedule spread, the experimental split, the DPKT cut, PyUp) as behaviour. - releasing: github's quoted guard matches create-release.yml; rewrite "Until #888", "before that removal", "as before" and past-tense third-party behaviour. - registry-protocol: TransportProtocol overrides get too; drop "used to", "now", "no longer", "as before". - pep, process, sentinel, placement, extension-header, mint-criterion and conf.py: drop change-relative and ambiguous wording; UDP 1701 is L2TPv2.
1 parent dfc68f9 commit e85e915

11 files changed

Lines changed: 116 additions & 127 deletions

‎docs/source/conf.py‎

Lines changed: 5 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1247,26 +1247,11 @@ def read_own_enum_new(obj: type, name: str, *defargs: 'Any') -> 'Any':
12471247
return safe_getattr(obj, name, *defargs)
12481248

12491249

1250-
# NB: handlers used to sit here -- ``remove_module_docstring``,
1251-
# ``process_docstring``, ``process_fields`` and ``source_read`` -- each with its
1252-
# ``app.connect`` call commented out in ``setup`` below, so none of them had run
1253-
# for as long as they had been in the file. They are deleted rather than restored,
1254-
# because restoring them would either duplicate work done properly elsewhere or make the
1255-
# build unusable:
1256-
#
1257-
# ``remove_module_docstring`` and ``process_docstring`` were both attempts at the
1258-
# same thing -- flipping :data:`typing.TYPE_CHECKING` and reloading each module
1259-
# so autodoc could see the ``if TYPE_CHECKING:`` names. ``bind_type_checking_names``
1260-
# above solves that, per module and without mutating a global mid-build.
1261-
#
1262-
# ``process_fields`` only ever printed; the ``lines.append`` that was its point
1263-
# was itself commented out.
1264-
#
1265-
# ``source_read`` printed every document's entire source text, which on this
1266-
# project is several thousand pages of build log.
1267-
#
1268-
# If the ``TYPE_CHECKING`` behaviour is ever wanted again, ``bind_type_checking_names``
1269-
# is where it belongs, not a reload hook.
1250+
# NB: the ``TYPE_CHECKING`` names belong to ``bind_type_checking_names`` above,
1251+
# not to a hook that flips :data:`typing.TYPE_CHECKING` and reloads each module:
1252+
# the binding does the same per module, without mutating a global mid-build. Nor
1253+
# should a ``source-read`` handler print each document: on this project that is
1254+
# several thousand pages of build log.
12701255

12711256

12721257
def setup(app: 'Sphinx') -> None:

‎docs/source/contributing/conventions/extension-header-subclassing.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -148,8 +148,8 @@ was left behind, and that was deliberate. The owner ruled that the
148148
``IPv6_GenericExt`` name goes for good: it was an intermediate state, and it was never
149149
released.
150150

151-
What makes that safe rather than merely decided: the old name existed on ``main`` from
152-
``b3551cb63`` to ``93cf940b3``, under four hours on one day, and no release tag falls
151+
What makes that safe rather than merely decided: ``IPv6_GenericExt`` existed on
152+
``main`` from ``b3551cb63`` to ``93cf940b3``, under four hours on one day, and no release tag falls
153153
between the two commits -- ``git tag --contains`` names the same tags for both -- so it
154154
appears in **no** release and the break has no callers to inconvenience. Do not
155155
reintroduce it as an alias, and do not cite it as a former public name.

‎docs/source/contributing/conventions/mint-criterion.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,8 +143,8 @@ than one range block -- and
143143
:mod:`pcapkit.const.ipx.socket`'s ``Registered by Xerox``. A company name is the
144144
assignment, for the reason in the next section.
145145

146-
Further ranges in that file carry a suffixed name without being company names at
147-
all: ``IEEE802.3 Length Field``, which names a field in a standard, and
146+
Further ranges in :mod:`pcapkit.const.reg.ethertype` carry a suffixed name without
147+
being company names at all: ``IEEE802.3 Length Field``, which names a field in a standard, and
148148
``Berkeley Trailer encap/IP``, which names an encapsulation. Neither is among the company names, and
149149
neither is suffixed for the reason the next section gives.
150150

‎docs/source/contributing/conventions/process.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@ once:
4444
``PyShark``, ``PyPCAPFile``, ``PyPCAP`` and ``PCAP_CT`` are not core addons, so
4545
they are on demand -- one extra at a time, ``pip install pypcapkit[Scapy]`` and so
4646
on. This holds however easy they are to install, and it is what the ruling
47-
changed: some of them used to be in ``all``.
48-
* ``PyPCAP`` **and** ``PCAP_CT`` **were already excluded for installability**, which the
47+
changed: the 1.4 ``all`` carried some of them.
48+
* ``PyPCAP`` **and** ``PCAP_CT`` **are also excluded for installability**, a reason the
4949
ruling leaves untouched. ``pypcap`` is an sdist-only C extension needing a
5050
compiler and the libpcap development files; ``pcap-ct`` and ``libpcap`` are
5151
published only as pre-releases, and ``all`` should not be how somebody acquires a

‎docs/source/contributing/conventions/protocol-layer-placement.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -153,12 +153,12 @@ Each is deliberate. Do not "fix" any of them.
153153

154154
**A parsing base may live in another subpackage.**
155155
:mod:`pcapkit.protocols.application.rarp` imports
156-
:class:`~pcapkit.protocols.link.arp.ARP` from :mod:`pcapkit.protocols.link.arp`. This
157-
is the first ``application/ → link/`` dependency in the package, and it is the honest
158-
consequence of letting layer and parser disagree.
156+
:class:`~pcapkit.protocols.link.arp.ARP` from :mod:`pcapkit.protocols.link.arp`. That
157+
``application/ → link/`` dependency is the honest consequence of letting layer and
158+
parser disagree.
159159

160160
**The dispatch tier is decoupled from the subpackage.** A protocol's subpackage says
161-
nothing about which registry reaches it, and the move did not touch any dispatch key:
161+
nothing about which registry reaches it, and no dispatch key depends on it:
162162

163163
.. list-table::
164164
:header-rows: 1

‎docs/source/contributing/conventions/registry-protocol.rst‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ The owner ruled on :issue:`877` that a registry may subclass a bare base enum ou
4545
subclassing that base in turn for use by the mutable ones. So a **closed** set
4646
inherits :class:`~pcapkit.corekit.enum.EnumLookup`
4747
directly and is never handed a ``register`` it would have to refuse; an **open**
48-
registry inherits :class:`~pcapkit.corekit.enum.EnumRegistry` exactly as before.
48+
registry inherits :class:`~pcapkit.corekit.enum.EnumRegistry`.
4949

5050
What settled the split is the owner's own second thought about carrying ``register``
5151
on the base: if the base carries ``register``, there is no principled reason for it
@@ -54,9 +54,9 @@ Following that through leaves :class:`~pcapkit.corekit.enum.EnumRegistry` holdin
5454
a few methods, too thin to justify a second class -- so the two tiers collapse into one,
5555
which is the opposite of what was ruled.
5656

57-
**Both tiers are plain classes, and that is load-bearing.** Inserting a parent above
58-
:class:`~pcapkit.corekit.enum.EnumRegistry` leaves the member data type exactly where
59-
it was -- ``LinkType -> EnumRegistry -> EnumLookup -> IntEnum -> int`` -- so
57+
**Both tiers are plain classes, and that is load-bearing.** The parent above
58+
:class:`~pcapkit.corekit.enum.EnumRegistry` leaves the member data type with the enum
59+
base -- ``LinkType -> EnumRegistry -> EnumLookup -> IntEnum -> int`` -- so
6060
``_member_type_`` still comes from the enum base. Had either tier subclassed
6161
``aenum.Enum`` in order to "be an enum", it would have become the member type
6262
itself and broken ``int``, ``str`` and flag registries at once.
@@ -348,15 +348,15 @@ resolvable.
348348

349349
And a folding override carries **only** the fold.
350350
:meth:`TransportProtocol.get <pcapkit.const.reg.apptype.apptype.TransportProtocol.get>` is
351-
the worked example: since :issue:`923` it lowers ``key``, forwards ``default`` verbatim
352-
and delegates to ``super().get()``, and that is all it does. It used to convert the base's
353-
name-miss :exc:`KeyError` into a :exc:`ValueError` as well, and :issue:`923`'s ruling
354-
retired that; the :issue:`808` refusal to extend the class at all is untouched by the
355-
retirement, since only the exception class moved. ``Criticality.get`` went further and was
351+
the worked example: it lowers ``key``, forwards ``default`` verbatim and delegates to
352+
``super().get()``, and that is all it does. :issue:`923`'s ruling retired the conversion
353+
of the base's name-miss :exc:`KeyError` into a :exc:`ValueError` that it also carried;
354+
the :issue:`808` refusal to extend the class at all is untouched by the retirement,
355+
since only the exception class moved. ``Criticality.get`` went further and was
356356
deleted: conversion was the *only* thing it added over the base, so once that went there
357357
was nothing left for an override to hold, and the class inherits
358-
:meth:`~pcapkit.corekit.enum.EnumLookup.get` unchanged. **An override that would now be
359-
empty is deleted, not kept as a pass-through** -- a ``get`` that only calls
358+
:meth:`~pcapkit.corekit.enum.EnumLookup.get` unchanged. **An override left with nothing
359+
to add is deleted, not kept as a pass-through** -- a ``get`` that only calls
360360
``super().get()`` reads as though it were doing something, and the next reader has to diff
361361
it against the base to find out that it is not.
362362

@@ -525,10 +525,9 @@ That leaves the classes with something to decide:
525525
:class:`~pcapkit.protocols.internet.mh.LocalizedRoutingStatus` never carried a
526526
``get`` at all, so they had no string lookup to fold.
527527
:class:`~pcapkit.protocols.application.ngap.Criticality` had one when this audit
528-
was taken and no longer does: :issue:`877` re-parented it onto
528+
was taken and inherits ``get`` unchanged: :issue:`877` re-parented it onto
529529
:class:`~pcapkit.corekit.enum.EnumLookup` and :issue:`923` retired the exception
530-
conversion that was the override's only remaining job, so it inherits ``get``
531-
unchanged.
530+
conversion that was the override's only remaining job.
532531
- **case-sensitive** -- conforms
533532
* - :class:`~pcapkit.protocols.misc.pcapng.WireGuardKeyLabel`
534533
- ``draft-tuexen-opsawg-pcapng``
@@ -609,7 +608,8 @@ rather than changing it.
609608
:class:`~pcapkit.const.ftp.command.Command`,
610609
:class:`~pcapkit.const.ftp.command.FEATCode`,
611610
:class:`~pcapkit.const.http.method.Method`,
612-
:class:`~pcapkit.const.pcapng.option_type.OptionType` and
611+
:class:`~pcapkit.const.pcapng.option_type.OptionType`,
612+
:class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol` and
613613
:class:`~pcapkit.const.reg.apptype.apptype.AppType` -- and probing one of those
614614
measures the override rather than the base. The unconditionally clean witness is
615615
``tests/corekit/test_enum_lookup_base_unit.py``'s own ``_Str``, a purpose-built

‎docs/source/contributing/conventions/sentinel-convention.rst‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,11 @@ leaves the type out of it. The type stays importable by its dotted path there, f
6262
annotation or an ``is`` guard; it is only ``import *`` that does not offer it. The
6363
``__all__`` there does name :class:`~pcapkit.corekit.sentinels.Sentinel`, the abstract
6464
base every sentinel type shares, since that is no sentinel's own type. A private
65-
sentinel such as ``ABSENT`` is in neither, which is what private means here -- dropping
66-
its leading underscore did not add it to either list, and
65+
sentinel such as ``ABSENT`` is in neither, which is what private means here, and
6766
:class:`~pcapkit.corekit.sentinels.AbsentType` and
6867
:data:`~pcapkit.corekit.sentinels.ABSENT` are documented on
6968
:doc:`the sentinels API page </pcapkit/corekit/sentinels>` as private and not for
70-
public use rather than left off it, since the name alone no longer says so.
69+
public use rather than left off it, since nothing in the name says so.
7170

7271
.. note::
7372

‎docs/source/contributing/conventions/test-coverage.rst‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ known-failure table keep their cases in a generator, beside the captures it also
3939
* - :file:`tests/protocols/test_dispatch_registry_unit.py`
4040
- :file:`examples/generators/dispatch.py`
4141
- every ``__proto__`` entry dispatches to the class ``PINNED_TARGETS`` names;
42-
known failures in ``KNOWN_DEGRADED`` (:issue:`496`)
42+
known degrades in ``DispatchRegistryTests.KNOWN_DEGRADED``, which the
43+
generator's own ``KNOWN_DEGRADED`` mirrors for its command-line report
44+
(:issue:`496`)
4345

4446
The rules those tables carry:
4547

@@ -56,7 +58,8 @@ The rules those tables carry:
5658
Routing a case around a defect hides it: the generator's ``HIP_COPIES`` once put two
5759
parameters in every HIP packet, so the unrepresentable length of a lone one
5860
(:issue:`651`) was never constructed.
59-
``KNOWN_DEGRADED`` entries have a different shape -- a fragment and a reason -- and
61+
``KNOWN_DEGRADED`` entries have a different shape -- the fragments of the probe's
62+
``'error'`` value the entry accepts, any one of which may match, and a reason -- and
6063
they record why the probe's placeholder payload cannot reach the target, not a
6164
defect to fix, so the name-and-issue rule does not apply to them.
6265
* **A regression is fixed; a pre-existing defect is recorded.** A case that a change

‎docs/source/contributing/pep.rst‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ What is left, and why:
198198
It wants a registry of its own rather than
199199
:meth:`~pcapkit.protocols.protocol.Protocol._decode_next_layer`, which is
200200
only ever called at a layer boundary and appends to the frame's protocol chain.
201-
An MLD address record inside a mobility option did not follow MH on the wire,
201+
An MLD address record inside a mobility option does not follow MH on the wire,
202202
so putting it in that chain would make ``layer=`` and ``protocol=`` limits
203203
behave wrongly. Changing the parsed shape from :obj:`bytes` to
204204
:class:`~pcapkit.protocols.misc.raw.Raw` also changes what existing captures dump to, so
@@ -276,7 +276,7 @@ complaint and yields nothing useful.
276276
:attr:`TCP.__proto__ <pcapkit.protocols.transport.tcp.TCP.__proto__>` and
277277
:attr:`UDP.__proto__ <pcapkit.protocols.transport.udp.UDP.__proto__>`, out of
278278
a registry carrying every IANA service name: TCP 20 to FTP-DATA and 21 to FTP,
279-
ports 80 and 8080 to HTTP on both TCP and UDP, and UDP 1701 to L2TP.
279+
ports 80 and 8080 to HTTP on both TCP and UDP, and UDP 1701 to L2TPv2.
280280
* :class:`~pcapkit.const.sctp.payload_protocol_identifier.PayloadProtocolIdentifier`
281281
-- the values in :attr:`SCTP.__proto__
282282
<pcapkit.protocols.transport.sctp.SCTP.__proto__>`: PPIDs 60 and 66, each to
@@ -386,8 +386,8 @@ suspect -- is 0.0% of its own cost and 4.4% of a parse, and the logging
386386
integration is 0.03% even in the heaviest shape, since every call site is a lazy
387387
``%s``. The IO-batching idea the thread proposed was never the bottleneck.
388388

389-
The larger wins this section listed, all outside the parse path, have landed in
390-
full or in part:
389+
The larger costs this section listed all lie outside the parse path, and each is
390+
addressed in full or in part:
391391

392392
* **The flow dumper reopens its output file once per frame**, in
393393
:class:`~pcapkit.dumpkit.pcap.PCAPIO`'s ``__call__``. It does not
@@ -407,11 +407,11 @@ full or in part:
407407
measured at 86% of the IP-reassembly cost plus a 133 ms garbage-collection
408408
bill. Whether unfragmented frames should be emitted at all is the design
409409
question that is left, and it is worth settling deliberately.
410-
* **Done.** Every option was parsed twice -- 2274 schema unpacks for 1137
411-
options, the pre-parse always discarded, about 15% of a PCAP-NG extraction.
412-
:class:`~pcapkit.corekit.fields.collections.OptionField` reads only the base
413-
schema's type field to choose the option schema, rather than unpacking the
414-
whole base schema and throwing it away.
410+
* **Done.** :class:`~pcapkit.corekit.fields.collections.OptionField` reads only
411+
the base schema's type field to choose the option schema, rather than unpacking
412+
the whole base schema and throwing it away. Unpacking it parsed every option
413+
twice -- 2274 schema unpacks for 1137 options, the pre-parse always discarded,
414+
about 15% of a PCAP-NG extraction.
415415

416416
Some traps for anyone benchmarking this library. ``reassembly=True`` and
417417
``trace=True`` are **no-ops** without ``ip=``/``tcp=``, so a benchmark that passes
@@ -423,10 +423,10 @@ Recursive Dissection, With a Depth Limit
423423

424424
**Decided, open to revisit.** Each layer dissects the next from inside
425425
its own parse, so dissecting a frame recurses once per layer, at 9 to 12 Python
426-
frames a layer. Deep nesting -- IP in IP, stacked 802.1Q tags, long chains of
427-
IPv6 extension headers -- used to exhaust the recursion limit and leave the rest
428-
of the frame raw, silently, at a depth that varied with the interpreter and the
429-
caller's stack (:issue:`1604`, :issue:`1610`).
426+
frames a layer. Without a bound, deep nesting -- IP in IP, stacked 802.1Q tags,
427+
long chains of IPv6 extension headers -- exhausts the recursion limit and leaves the
428+
rest of the frame raw, silently, at a depth that varies with the interpreter and
429+
the caller's stack (:issue:`1604`, :issue:`1610`).
430430

431431
Recursion stays, with a counted bound:
432432
:data:`~pcapkit.utilities.config.FRAME_LAYER_LIMIT` caps a frame at 64 layers by
@@ -622,9 +622,9 @@ Anyone wanting to run the tests wants the repository, which is where they are.
622622

623623
``dictdumper``'s ``PLIST`` writer formats every :class:`~datetime.datetime` as
624624
``'%Y-%m-%dT%H:%M:%S.%fZ'``, always with six fractional digits, and
625-
:mod:`plistlib`'s ``<date>`` pattern admits none, so :func:`plistlib.load`
626-
failed on every ``format='plist'`` report with ``AttributeError: 'NoneType'
627-
object has no attribute 'groupdict'``. The upstream defect is
625+
:mod:`plistlib`'s ``<date>`` pattern admits none, so without the workaround
626+
below :func:`plistlib.load` fails on every ``format='plist'`` report with
627+
``AttributeError: 'NoneType' object has no attribute 'groupdict'``. The upstream defect is
628628
`JarryShaw/DictDumper#122 <https://github.com/JarryShaw/DictDumper/issues/122>`__.
629629
:func:`pcapkit.dumpkit.common.make_dumper` works around it (:issue:`1448`): it
630630
writes each date in UTC to whole seconds, as :func:`plistlib.dump` does. The

0 commit comments

Comments
 (0)