Skip to content

Commit 58fbca4

Browse files
authored
docs(foundation): third whole-repo pass over foundation, toolkit, dumpkit, interface and utilities (#1103) (#1834)
* docs(foundation): third whole-repo pass over foundation, toolkit, dumpkit, interface and utilities (#1103) Cross-references: - point TraceFlow.finish/index/dump, register_tcp/udp/sctp, Reassembly.expire and the class name properties at their documented targets; qualify Completion, Deferred, Index, Extractor and LinkType so they resolve from any module - document the per-protocol __timeout__ and TCP __window__ hooks, and the public dpkt timestamp and buffer helpers the adapters cite Rendered output: - move each toolkit adapter's reassembly condition into the body and keep Returns to one paragraph, which drops the empty paragraph Returns opened with - reword first lines napoleon split as a type, drop a python: prefix and a raw type prefix, hide the PyShark table reprs, drop a duplicated BufferID entry Counts: remove counted numbers from living prose; spec quantities, constants and measurements stay Accuracy and wording: Raises and Warns for TraceFlowBase.register_dumper, the __output__ value shape, the MH registrar parameters, trace()'s protocol, the IPv6 overlap note, the traceflow packet shape, make_dumper's return, the PCAP-NG Context summary, timed "this tree" wording, and typos and grammar Refs #1103 * docs(foundation): fix the review findings on the foundation pass (#1103) - EnumKeyError: restore the predicate a count removal dropped; re-wrap - config.rst: vendor.default reads and documents the vendor variables - Document Completion so the references to its members resolve - Point the __output__ references at TraceFlow, where it is documented - packet2timestamp: a nanosecond file yields a DecimalTimestamp - Render RecordTimestamp's attribute docs with :members: - Name the PyPCAP/PCAP_CT pair rather than count it; "each channel" - Re-wrap over-long lines in exceptions.py, reassembly.py and data.py Refs #1103 * docs(foundation): resolve the Completion cross-references (#1103) - Retarget the TIMEOUT comment's timeout link to Reassembly.timeout - Spell compat's StrEnum, aenum and __str__ as literals, since none of them is a documented object - Qualify the TLSKeyLabel isinstance claim to Python 3.11 and later, where compat.StrEnum is the stdlib class rather than aenum's - EnumKeyError: link Method and spell its private get as a literal Refs #1103
1 parent e5f7fb6 commit 58fbca4

65 files changed

Lines changed: 599 additions & 551 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/source/pcapkit/dumpkit/null.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Null Dumper
44
.. module:: pcapkit.dumpkit.null
55

66
:mod:`pcapkit.dumpkit.null` is the dumper for the **NotImplemented** format,
7-
alike those in :mod:`dictdumper`.
7+
like those in :mod:`dictdumper`.
88

99
.. note::
1010

‎docs/source/pcapkit/dumpkit/pcap.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ PCAP Dumper
33

44
.. module:: pcapkit.dumpkit.pcap
55

6-
:mod:`pcapkit.dumpkit.pcap` is the dumper for the PCAP format, alike those in
6+
:mod:`pcapkit.dumpkit.pcap` is the dumper for the PCAP format, like those in
77
:mod:`dictdumper`.
88

99
.. autoclass:: pcapkit.dumpkit.pcap.PCAPIO

‎docs/source/pcapkit/foundation/engines/3rdparty.rst‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,11 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
2020
Importing a narrower submodule leaves them empty, and
2121
:class:`~scapy.utils.PcapReader` then returns every frame as one opaque
2222
:class:`~scapy.packet.Raw` layer without raising, so the engine would dissect
23-
nothing and say so only on :data:`sys.stderr`. See :meth:`Scapy.__init__` for
24-
why naming the layer modules individually is not a cheaper route.
23+
nothing and say so only on :data:`sys.stderr`. Naming the layer modules
24+
individually is not a cheaper route: it repairs the link layer but leaves the
25+
payload table short, so :file:`dhcp.pcapng` still comes back as
26+
``Ethernet / IP / UDP / Raw``, and such a list would go stale silently as
27+
`Scapy`_ gains layer types.
2528

2629
One side effect: :mod:`scapy.all` loads :mod:`scapy.layers.dcerpc`, which
2730
reaches `Scapy`_'s TLS layer and there triggers a
@@ -107,7 +110,7 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
107110

108111
.. important::
109112

110-
`PyShark`_ has **two** requirements beyond installing it, and neither is
113+
`PyShark`_ has requirements beyond installing it, and none is
111114
visible to an import -- the package imports cleanly and then fails when used,
112115
which is why
113116
:meth:`~pcapkit.foundation.engines.pyshark.PyShark.unsupported_reason` checks
@@ -264,7 +267,7 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
264267
265268
pip install pypcapkit[PCAP_CT]
266269
267-
The two engines together cover every interpreter the project supports, and
270+
Together these engines cover every interpreter the project supports, and
268271
``PCAP_CT`` covers all of it on its own:
269272

270273
========================================================================= ==================
@@ -342,10 +345,10 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
342345
================ ===========================================================
343346
System libpcap Result
344347
================ ===========================================================
345-
1.11.0 correct -- the same four frames and the same sub-second
348+
1.11.0 correct -- the same frames and the same sub-second
346349
timestamps as
347350
:class:`~pcapkit.foundation.engines.pcapng.PCAPNG`
348-
1.5.3 four frames, but nonsense sub-second timestamps
351+
1.5.3 the same frames, but nonsense sub-second timestamps
349352
(``1102274184.0000002`` and the like), silently and with no
350353
error
351354
================ ===========================================================
@@ -438,15 +441,15 @@ Backend Detection
438441

439442
.. module:: pcapkit.foundation.engines._pcap_backend
440443

441-
Two unrelated PyPI distributions install a top-level module named :mod:`pcap` --
444+
Unrelated PyPI distributions install a top-level module named :mod:`pcap` --
442445
`PyPCAP`_, a Cython binding shipped as a single extension module, and `pcap-ct`_,
443446
a :mod:`ctypes` reimplementation shipped as a package. They therefore collide,
444447
and ``import pcap`` resolves to whichever the import system finds first.
445448
:class:`~pcapkit.foundation.engines.pypcap.PyPCAP` and
446449
:class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` each have to know which one
447450
they actually got rather than assume, and this module is the one place that
448-
answers it -- deliberately shared, since the two engines must agree and two
449-
copies of the detection would be two chances to disagree. It is *only* detection,
451+
answers it -- deliberately shared, since the engines must agree and a copy of
452+
the detection in each would be a chance to disagree. It is *only* detection,
450453
and it imports nothing from :mod:`pcapkit`, so it cannot introduce an import
451454
cycle.
452455

‎docs/source/pcapkit/foundation/engines/engine.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ every extraction engine.
4242
:attr:`__engine_module__` class attribute.
4343

4444
.. property:: registry
45-
:type: python:dict[str, ModuleDescriptor[EngineBase] | typing.Type[EngineBase]]
45+
:type: dict[str, ModuleDescriptor[EngineBase] | typing.Type[EngineBase]]
4646

4747
Mapping of engine names to engine classes.
4848

@@ -80,3 +80,5 @@ Type Variables
8080

8181
.. data:: _T
8282
:type: typing.Any
83+
84+
Frame type the engine reads.

‎docs/source/pcapkit/foundation/engines/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -236,8 +236,8 @@ actually got, via
236236
* declines to run on the other one, through ``unsupported_reason()``, with a
237237
message naming the ``engine=`` string that does want it; and
238238
* warns with an :class:`~pcapkit.utilities.warnings.EngineWarning` when it finds
239-
both installed, since that state makes one of the two engines permanently
240-
unselectable and nothing else would explain why.
239+
both installed, since that state leaves one engine permanently unselectable
240+
and nothing else would explain why.
241241

242242
.. _PCAP-NG: https://wiki.wireshark.org/Development/PcapNg
243243
.. _libpcap: https://pypi.org/project/libpcap/

‎docs/source/pcapkit/foundation/extraction.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,17 @@ File Extractor
77
:class:`~pcapkit.foundation.extraction.Extractor` only,
88
which synthesises file I/O and protocol analysis,
99
coordinates information exchange in all network layers,
10-
extracts parameters from a PCAP file.
10+
and extracts parameters from a PCAP file.
1111

1212
.. seealso::
1313

1414
|pypcap|_, |pcap-ct|_ and |pypcapfile|_ are supported by
1515
:class:`pcapkit.foundation.engines.pypcap.PyPCAP` (``engine='pypcap'``),
1616
:class:`pcapkit.foundation.engines.pcap_ct.PCAP_CT` (``engine='pcap_ct'``)
1717
and :class:`pcapkit.foundation.engines.pypcapfile.PyPCAPFile`
18-
(``engine='pypcapfile'``). All three support less than the ``default``
19-
engine does; :doc:`engines/index` tabulates the gaps, and :doc:`../../index`
20-
documents their installation prerequisites.
18+
(``engine='pypcapfile'``). Each supports less than the ``default``
19+
engine does; :doc:`engines/index` tabulates the gaps, and the
20+
:doc:`main page <../../index>` documents their installation prerequisites.
2121

2222
.. autoclass:: pcapkit.foundation.extraction.Extractor
2323
:no-members:
@@ -107,6 +107,8 @@ Type Variables
107107
.. data:: _P
108108
:type: typing.Any
109109

110+
Frame type the extractor yields, as read by its engine.
111+
110112
.. |pypcap| replace:: ``pypcap``
111113
.. _pypcap: https://github.com/pynetwork/pypcap
112114
.. |pcap-ct| replace:: ``pcap-ct``

‎docs/source/pcapkit/foundation/reassembly/index.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,10 @@ Auxiliary Data
6161
:members:
6262
:show-inheritance:
6363

64+
.. autoclass:: pcapkit.foundation.reassembly.data.data.Completion
65+
:members:
66+
:show-inheritance:
67+
6468
.. autoclass:: pcapkit.foundation.reassembly.data.data.Deferred
6569
:members:
6670
:show-inheritance:

‎docs/source/pcapkit/foundation/reassembly/ip/ip.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Data Models
2929
:module: pcapkit.foundation.reassembly.data.ip
3030
:type: typing.Tuple[~pcapkit.foundation.reassembly.data.ip._AT, ~pcapkit.foundation.reassembly.data.ip._AT, int, pcapkit.const.reg.transtype.TransType]
3131

32-
Data module for buffer ID.
32+
Data model for buffer ID.
3333

3434
.. autoclass:: pcapkit.foundation.reassembly.data.ip.Buffer
3535
:members:
@@ -49,3 +49,5 @@ Type Variables
4949
.. data:: _AT
5050
:module: pcapkit.foundation.reassembly.data.ip
5151
:type: ipaddress.IPv4Address | ipaddress.IPv6Address
52+
53+
IP address type.

‎docs/source/pcapkit/foundation/reassembly/ip/ipv4.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ origin. Please refer to :doc:`ip` for more information.
1616
.. autoattribute:: __protocol_type__
1717
.. autoattribute:: __callback_fn__
1818
:no-value:
19+
.. autoattribute:: __timeout__
1920

2021
Terminology
2122
-----------
@@ -25,7 +26,7 @@ Terminology
2526
reasm.ipv4.packet
2627
Data structure for **IPv4 datagram reassembly**
2728
(:meth:`IPv4.reassembly <pcapkit.foundation.reassembly.reassembly.Reassembly.reassembly>`)
28-
is as following, with ``ipv4`` the protocol instance
29+
is as follows, with ``ipv4`` the protocol instance
2930
(``frame['IPv4']``) and ``ipv4_info`` its :attr:`~pcapkit.protocols.protocol.Protocol.info`
3031
-- the header fields come off the latter, the raw octets off the former:
3132

@@ -53,7 +54,7 @@ Terminology
5354
reasm.ipv4.datagram
5455
Data structure for **reassembled IPv4 datagram** (element from
5556
:attr:`IPv4.datagram <pcapkit.foundation.reassembly.reassembly.Reassembly.datagram>`
56-
*tuple*) is as following:
57+
*tuple*) is as follows:
5758

5859
.. code-block:: text
5960
@@ -118,7 +119,7 @@ Terminology
118119
reasm.ipv4.buffer
119120
Data structure for internal buffering when performing reassembly algorithms
120121
(:attr:`IPv4._buffer <pcapkit.foundation.reassembly.reassembly.Reassembly._buffer>`)
121-
is as following:
122+
is as follows:
122123

123124
.. code-block:: text
124125
@@ -175,4 +176,4 @@ Terminology
175176
:attr:`~pcapkit.foundation.reassembly.data.data.Completion.PARTIAL`,
176177
which is what tells "these fragments are gone" apart from "these
177178
fragments had not arrived yet". See
178-
:meth:`~pcapkit.foundation.reassembly.reassembly.ReassemblyBase.expire`.
179+
:meth:`~pcapkit.foundation.reassembly.reassembly.Reassembly.expire`.

‎docs/source/pcapkit/foundation/reassembly/ip/ipv6.rst‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ origin. Please refer to :doc:`ip` for more information.
1616
.. autoattribute:: __protocol_type__
1717
.. autoattribute:: __callback_fn__
1818
:no-value:
19+
.. autoattribute:: __timeout__
1920

2021
Terminology
2122
-----------
@@ -25,7 +26,7 @@ Terminology
2526
reasm.ipv6.packet
2627
Data structure for **IPv6 datagram reassembly**
2728
(:meth:`IPv6.reassembly <pcapkit.foundation.reassembly.reassembly.Reassembly.reassembly>`)
28-
is as following, with ``ipv6_info`` the IPv6
29+
is as follows, with ``ipv6_info`` the IPv6
2930
:attr:`~pcapkit.protocols.protocol.Protocol.info` and
3031
``ipv6_frag_info`` the Fragment header's:
3132

@@ -61,7 +62,7 @@ Terminology
6162
does count it -- it is a header length, and the Fragment header is one
6263
of the extension headers it has walked -- so the ``pcap`` and
6364
``pcapng`` adapters subtract it back off. The ``dpkt`` and ``scapy``
64-
adapters leave it out of the three fields too, but as best effort,
65+
adapters leave it out of those fields too, but as best effort,
6566
not as a contract (:issue:`1687`).
6667

6768
.. note::
@@ -86,7 +87,7 @@ Terminology
8687
reasm.ipv6.datagram
8788
Data structure for **reassembled IPv6 datagram** (element from
8889
:attr:`IPv6.datagram <pcapkit.foundation.reassembly.reassembly.Reassembly.datagram>`
89-
*tuple*) is as following:
90+
*tuple*) is as follows:
9091

9192
.. code-block:: text
9293
@@ -151,18 +152,20 @@ Terminology
151152

152153
``completed`` and ``conflict`` are independent signals: a datagram
153154
can be :attr:`~pcapkit.foundation.reassembly.data.data.Completion.COMPLETE`
154-
and still carry a non-empty ``conflict``. :rfc:`791` resolves an
155-
overlapping fragment's disagreement itself -- "this procedure will
156-
use the more recently arrived copy in the data buffer" -- the
157-
opposite resolution from TCP's first-write-wins
158-
(:rfc:`9293#section-3.10`) -- so a contested
159-
range never leaves a hole on its own, and ``conflict`` is what lets
160-
a caller tell a clean datagram from a contested one.
155+
and still carry a non-empty ``conflict``. IPv6 reassembly shares
156+
IPv4's resolution of an overlapping fragment's disagreement, the one
157+
:rfc:`791` gives -- "this procedure will use the more recently
158+
arrived copy in the data buffer" -- the opposite resolution from
159+
TCP's first-write-wins (:rfc:`9293#section-3.10`), rather than
160+
abandoning the datagram as :rfc:`8200#section-4.5` has a receiving
161+
node do. So a contested range never leaves a hole on its own, and
162+
``conflict`` is what lets a caller tell a clean datagram from a
163+
contested one.
161164

162165
reasm.ipv6.buffer
163166
Data structure for internal buffering when performing reassembly algorithms
164167
(:attr:`IPv6._buffer <pcapkit.foundation.reassembly.reassembly.Reassembly._buffer>`)
165-
is as following:
168+
is as follows:
166169

167170
.. code-block:: text
168171

0 commit comments

Comments
 (0)