docs(foundation): third whole-repo pass over foundation, toolkit, dumpkit, interface and utilities (#1103)

docs/source/pcapkit/dumpkit/null.rst

@@ -4,7 +4,7 @@ Null Dumper
 .. module:: pcapkit.dumpkit.null
 
 :mod:`pcapkit.dumpkit.null` is the dumper for the **NotImplemented** format,
-alike those in :mod:`dictdumper`.
+like those in :mod:`dictdumper`.
 
 .. note::
 

docs/source/pcapkit/dumpkit/pcap.rst

@@ -3,7 +3,7 @@ PCAP Dumper
 
 .. module:: pcapkit.dumpkit.pcap
 
-:mod:`pcapkit.dumpkit.pcap` is the dumper for the PCAP format, alike those in
+:mod:`pcapkit.dumpkit.pcap` is the dumper for the PCAP format, like those in
 :mod:`dictdumper`.
 
 .. autoclass:: pcapkit.dumpkit.pcap.PCAPIO

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

@@ -20,8 +20,11 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
    Importing a narrower submodule leaves them empty, and
    :class:`~scapy.utils.PcapReader` then returns every frame as one opaque
    :class:`~scapy.packet.Raw` layer without raising, so the engine would dissect
-   nothing and say so only on :data:`sys.stderr`. See :meth:`Scapy.__init__` for
-   why naming the layer modules individually is not a cheaper route.
+   nothing and say so only on :data:`sys.stderr`. Naming the layer modules
+   individually is not a cheaper route: it repairs the link layer but leaves the
+   payload table short, so :file:`dhcp.pcapng` still comes back as
+   ``Ethernet / IP / UDP / Raw``, and such a list would go stale silently as
+   `Scapy`_ gains layer types.
 
    One side effect: :mod:`scapy.all` loads :mod:`scapy.layers.dcerpc`, which
    reaches `Scapy`_'s TLS layer and there triggers a
@@ -107,7 +110,7 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
 
 .. important::
 
-   `PyShark`_ has **two** requirements beyond installing it, and neither is
+   `PyShark`_ has requirements beyond installing it, and none is
    visible to an import -- the package imports cleanly and then fails when used,
    which is why
    :meth:`~pcapkit.foundation.engines.pyshark.PyShark.unsupported_reason` checks
@@ -264,7 +267,7 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
 
       pip install pypcapkit[PCAP_CT]
 
-   The two engines together cover every interpreter the project supports, and
+   Together these engines cover every interpreter the project supports, and
    ``PCAP_CT`` covers all of it on its own:
 
    =========================================================================  ==================
@@ -342,10 +345,10 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
    ================  ===========================================================
    System libpcap    Result
    ================  ===========================================================
-   1.11.0            correct -- the same four frames and the same sub-second
+   1.11.0            correct -- the same frames and the same sub-second
                      timestamps as
                      :class:`~pcapkit.foundation.engines.pcapng.PCAPNG`
-   1.5.3             four frames, but nonsense sub-second timestamps
+   1.5.3             the same frames, but nonsense sub-second timestamps
                      (``1102274184.0000002`` and the like), silently and with no
                      error
    ================  ===========================================================
@@ -438,15 +441,15 @@ Backend Detection
 
 .. module:: pcapkit.foundation.engines._pcap_backend
 
-Two unrelated PyPI distributions install a top-level module named :mod:`pcap` --
+Unrelated PyPI distributions install a top-level module named :mod:`pcap` --
 `PyPCAP`_, a Cython binding shipped as a single extension module, and `pcap-ct`_,
 a :mod:`ctypes` reimplementation shipped as a package. They therefore collide,
 and ``import pcap`` resolves to whichever the import system finds first.
 :class:`~pcapkit.foundation.engines.pypcap.PyPCAP` and
 :class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` each have to know which one
 they actually got rather than assume, and this module is the one place that
-answers it -- deliberately shared, since the two engines must agree and two
-copies of the detection would be two chances to disagree. It is *only* detection,
+answers it -- deliberately shared, since the engines must agree and a copy of
+the detection in each would be a chance to disagree. It is *only* detection,
 and it imports nothing from :mod:`pcapkit`, so it cannot introduce an import
 cycle.
 

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

@@ -42,7 +42,7 @@ every extraction engine.
          :attr:`__engine_module__` class attribute.
 
    .. property:: registry
-      :type: python:dict[str, ModuleDescriptor[EngineBase] | typing.Type[EngineBase]]
+      :type: dict[str, ModuleDescriptor[EngineBase] | typing.Type[EngineBase]]
 
       Mapping of engine names to engine classes.
 
@@ -80,3 +80,5 @@ Type Variables
 
 .. data:: _T
    :type: typing.Any
+
+   Frame type the engine reads.

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

@@ -236,8 +236,8 @@ actually got, via
 * declines to run on the other one, through ``unsupported_reason()``, with a
   message naming the ``engine=`` string that does want it; and
 * warns with an :class:`~pcapkit.utilities.warnings.EngineWarning` when it finds
-  both installed, since that state makes one of the two engines permanently
-  unselectable and nothing else would explain why.
+  both installed, since that state leaves one engine permanently unselectable
+  and nothing else would explain why.
 
 .. _PCAP-NG: https://wiki.wireshark.org/Development/PcapNg
 .. _libpcap: https://pypi.org/project/libpcap/

docs/source/pcapkit/foundation/extraction.rst

@@ -7,17 +7,17 @@ File Extractor
 :class:`~pcapkit.foundation.extraction.Extractor` only,
 which synthesises file I/O and protocol analysis,
 coordinates information exchange in all network layers,
-extracts parameters from a PCAP file.
+and extracts parameters from a PCAP file.
 
 .. seealso::
 
    |pypcap|_, |pcap-ct|_ and |pypcapfile|_ are supported by
    :class:`pcapkit.foundation.engines.pypcap.PyPCAP` (``engine='pypcap'``),
    :class:`pcapkit.foundation.engines.pcap_ct.PCAP_CT` (``engine='pcap_ct'``)
    and :class:`pcapkit.foundation.engines.pypcapfile.PyPCAPFile`
-   (``engine='pypcapfile'``). All three support less than the ``default``
-   engine does; :doc:`engines/index` tabulates the gaps, and :doc:`../../index`
-   documents their installation prerequisites.
+   (``engine='pypcapfile'``). Each supports less than the ``default``
+   engine does; :doc:`engines/index` tabulates the gaps, and the
+   :doc:`main page <../../index>` documents their installation prerequisites.
 
 .. autoclass:: pcapkit.foundation.extraction.Extractor
    :no-members:
@@ -107,6 +107,8 @@ Type Variables
 .. data:: _P
    :type: typing.Any
 
+   Frame type the extractor yields, as read by its engine.
+
 .. |pypcap| replace:: ``pypcap``
 .. _pypcap: https://github.com/pynetwork/pypcap
 .. |pcap-ct| replace:: ``pcap-ct``

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

@@ -61,6 +61,10 @@ Auxiliary Data
    :members:
    :show-inheritance:
 
+.. autoclass:: pcapkit.foundation.reassembly.data.data.Completion
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pcapkit.foundation.reassembly.data.data.Deferred
    :members:
    :show-inheritance:

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

@@ -29,7 +29,7 @@ Data Models
    :module: pcapkit.foundation.reassembly.data.ip
    :type: typing.Tuple[~pcapkit.foundation.reassembly.data.ip._AT, ~pcapkit.foundation.reassembly.data.ip._AT, int, pcapkit.const.reg.transtype.TransType]
 
-   Data module for buffer ID.
+   Data model for buffer ID.
 
 .. autoclass:: pcapkit.foundation.reassembly.data.ip.Buffer
    :members:
@@ -49,3 +49,5 @@ Type Variables
 .. data:: _AT
    :module: pcapkit.foundation.reassembly.data.ip
    :type: ipaddress.IPv4Address | ipaddress.IPv6Address
+
+   IP address type.

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

@@ -16,6 +16,7 @@ origin. Please refer to :doc:`ip` for more information.
    .. autoattribute:: __protocol_type__
    .. autoattribute:: __callback_fn__
       :no-value:
+   .. autoattribute:: __timeout__
 
 Terminology
 -----------
@@ -25,7 +26,7 @@ Terminology
    reasm.ipv4.packet
        Data structure for **IPv4 datagram reassembly**
        (:meth:`IPv4.reassembly <pcapkit.foundation.reassembly.reassembly.Reassembly.reassembly>`)
-       is as following, with ``ipv4`` the protocol instance
+       is as follows, with ``ipv4`` the protocol instance
        (``frame['IPv4']``) and ``ipv4_info`` its :attr:`~pcapkit.protocols.protocol.Protocol.info`
        -- the header fields come off the latter, the raw octets off the former:
 
@@ -53,7 +54,7 @@ Terminology
    reasm.ipv4.datagram
        Data structure for **reassembled IPv4 datagram** (element from
        :attr:`IPv4.datagram <pcapkit.foundation.reassembly.reassembly.Reassembly.datagram>`
-       *tuple*) is as following:
+       *tuple*) is as follows:
 
        .. code-block:: text
 
@@ -118,7 +119,7 @@ Terminology
    reasm.ipv4.buffer
        Data structure for internal buffering when performing reassembly algorithms
        (:attr:`IPv4._buffer <pcapkit.foundation.reassembly.reassembly.Reassembly._buffer>`)
-       is as following:
+       is as follows:
 
        .. code-block:: text
 
@@ -175,4 +176,4 @@ Terminology
           :attr:`~pcapkit.foundation.reassembly.data.data.Completion.PARTIAL`,
           which is what tells "these fragments are gone" apart from "these
           fragments had not arrived yet". See
-          :meth:`~pcapkit.foundation.reassembly.reassembly.ReassemblyBase.expire`.
+          :meth:`~pcapkit.foundation.reassembly.reassembly.Reassembly.expire`.

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

@@ -16,6 +16,7 @@ origin. Please refer to :doc:`ip` for more information.
    .. autoattribute:: __protocol_type__
    .. autoattribute:: __callback_fn__
       :no-value:
+   .. autoattribute:: __timeout__
 
 Terminology
 -----------
@@ -25,7 +26,7 @@ Terminology
    reasm.ipv6.packet
        Data structure for **IPv6 datagram reassembly**
        (:meth:`IPv6.reassembly <pcapkit.foundation.reassembly.reassembly.Reassembly.reassembly>`)
-       is as following, with ``ipv6_info`` the IPv6
+       is as follows, with ``ipv6_info`` the IPv6
        :attr:`~pcapkit.protocols.protocol.Protocol.info` and
        ``ipv6_frag_info`` the Fragment header's:
 
@@ -61,7 +62,7 @@ Terminology
           does count it -- it is a header length, and the Fragment header is one
           of the extension headers it has walked -- so the ``pcap`` and
           ``pcapng`` adapters subtract it back off. The ``dpkt`` and ``scapy``
-          adapters leave it out of the three fields too, but as best effort,
+          adapters leave it out of those fields too, but as best effort,
           not as a contract (:issue:`1687`).
 
        .. note::
@@ -86,7 +87,7 @@ Terminology
    reasm.ipv6.datagram
        Data structure for **reassembled IPv6 datagram** (element from
        :attr:`IPv6.datagram <pcapkit.foundation.reassembly.reassembly.Reassembly.datagram>`
-       *tuple*) is as following:
+       *tuple*) is as follows:
 
        .. code-block:: text
 
@@ -151,18 +152,20 @@ Terminology
 
           ``completed`` and ``conflict`` are independent signals: a datagram
           can be :attr:`~pcapkit.foundation.reassembly.data.data.Completion.COMPLETE`
-          and still carry a non-empty ``conflict``. :rfc:`791` resolves an
-          overlapping fragment's disagreement itself -- "this procedure will
-          use the more recently arrived copy in the data buffer" -- the
-          opposite resolution from TCP's first-write-wins
-          (:rfc:`9293#section-3.10`) -- so a contested
-          range never leaves a hole on its own, and ``conflict`` is what lets
-          a caller tell a clean datagram from a contested one.
+          and still carry a non-empty ``conflict``. IPv6 reassembly shares
+          IPv4's resolution of an overlapping fragment's disagreement, the one
+          :rfc:`791` gives -- "this procedure will use the more recently
+          arrived copy in the data buffer" -- the opposite resolution from
+          TCP's first-write-wins (:rfc:`9293#section-3.10`), rather than
+          abandoning the datagram as :rfc:`8200#section-4.5` has a receiving
+          node do. So a contested range never leaves a hole on its own, and
+          ``conflict`` is what lets a caller tell a clean datagram from a
+          contested one.
 
    reasm.ipv6.buffer
        Data structure for internal buffering when performing reassembly algorithms
        (:attr:`IPv6._buffer <pcapkit.foundation.reassembly.reassembly.Reassembly._buffer>`)
-       is as following:
+       is as follows:
 
        .. code-block:: text
 

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

@@ -40,7 +40,7 @@ that implement datagram reassembly of IP and TCP packets.
          value can be set by :attr:`__protocol_type__` class attribute.
 
    .. property:: registry
-      :type: python:dict[str, ModuleDescriptor[ReassemblyBase] | typing.Type[ReassemblyBase]]
+      :type: dict[str, ModuleDescriptor[ReassemblyBase] | typing.Type[ReassemblyBase]]
 
       Mapping of protocol names to reassembly classes.
 

docs/source/pcapkit/foundation/reassembly/tcp.rst

@@ -19,6 +19,8 @@ which reconstructs fragmented TCP packets back to origin.
    .. autoattribute:: __protocol_type__
    .. autoattribute:: __callback_fn__
       :no-value:
+   .. autoattribute:: __timeout__
+   .. autoattribute:: __window__
 
 Algorithm
 =========
@@ -157,7 +159,7 @@ Terminology
    reasm.tcp.packet
        Data structure for **TCP datagram reassembly**
        (:meth:`TCP.reassembly <pcapkit.foundation.reassembly.reassembly.Reassembly.reassembly>`)
-       is as following:
+       is as follows:
 
        .. code-block:: python
 
@@ -195,7 +197,7 @@ Terminology
    reasm.tcp.datagram
        Data structure for **reassembled TCP datagram** (element from
        :attr:`TCP.datagram <pcapkit.foundation.reassembly.reassembly.Reassembly.datagram>`
-       *tuple*) is as following:
+       *tuple*) is as follows:
 
        .. code-block:: text
 
@@ -254,7 +256,7 @@ Terminology
    reasm.tcp.buffer
        Data structure for internal buffering when performing reassembly algorithms
        (:attr:`TCP._buffer <pcapkit.foundation.reassembly.reassembly.Reassembly._buffer>`)
-       is as following:
+       is as follows:
 
        .. code-block:: text
 
@@ -375,9 +377,4 @@ Type Variables
    :module: pcapkit.foundation.reassembly.data.tcp
    :type: ipaddress.IPv4Address | ipaddress.IPv6Address
 
-.. data:: BufferID
-   :module: pcapkit.foundation.reassembly.data.tcp
-   :type: typing.Tuple[~pcapkit.foundation.reassembly.data.tcp._AT, int, ~pcapkit.foundation.reassembly.data.tcp._AT, int]
-   :no-index:
-
-   Buffer ID data structure.
+   IP address type.

docs/source/pcapkit/foundation/traceflow/tcp.rst

@@ -32,7 +32,7 @@ Terminology
    trace.tcp.packet
        Data structure for **TCP flow tracing**
        (:meth:`TraceFlow.dump <pcapkit.foundation.traceflow.traceflow.TraceFlow.dump>`)
-       is as following:
+       is as follows:
 
        .. code-block:: python
 
@@ -60,7 +60,7 @@ Terminology
    trace.tcp.buffer
        Data structure for internal buffering when performing flow tracing algorithms
        (:attr:`TraceFlow._buffer <pcapkit.foundation.traceflow.traceflow.TraceFlow._buffer>`)
-       is as following:
+       is as follows:
 
        .. code-block:: text
 
@@ -110,7 +110,7 @@ Terminology
    trace.tcp.index
        Data structure for **TCP flow tracing** (element from
        :attr:`TraceFlow.index <pcapkit.foundation.traceflow.traceflow.TraceFlow.index>`
-       *tuple*) is as following:
+       *tuple*) is as follows:
 
        .. code-block:: text
 
@@ -126,21 +126,23 @@ Terminology
            |     |                       opened the flow
            |     |--> 'reverse': (tuple) frame index the other way; empty when
            |     |                      tracing unidirectionally
-           |     |--> 'packet': (Optional[tuple]) one reassembled datagram per
-           |                    direction, or None when analyse is off
+           |     |--> 'packet': (Optional[tuple]) reassembled datagrams, one per
+           |                    direction and acknowledgement number, or None
+           |                    when analyse is off
            |--> (Info) data ...
 
        ``forward`` and ``reverse`` partition ``index``, so
        ``frame_number in flow.forward`` answers which way a packet went without
        taking the label apart. ``forward`` is the direction of the packet that
        opened the flow, whose endpoints the label names first.
 
-       ``packet`` is the conversation's application layer: one reassembled datagram
-       per direction, present only when the tracer was constructed with
-       ``analyse=True``. It is reassembled on the *first read*, and each datagram's
+       ``packet`` is the conversation's application layer: its reassembled
+       datagrams, one per direction and acknowledgement number, present only when
+       the tracer was constructed with ``analyse=True``. It is reassembled on the
+       *first read*, and each datagram's
        own :attr:`~pcapkit.foundation.reassembly.data.tcp.Datagram.packet` is
        parsed later still, so a caller that wanted only frame numbers pays for
-       neither. The tracer does not reassemble the stream itself -- it feeds
+       none of it. The tracer does not reassemble the stream itself -- it feeds
        :class:`~pcapkit.foundation.reassembly.tcp.TCP`, whose :rfc:`815` algorithm
        handles the reordering and retransmission that concatenating payloads in
        capture order would corrupt.
@@ -173,3 +175,5 @@ Type Variables
 .. data:: _AT
    :module: pcapkit.foundation.traceflow.data.tcp
    :type: ipaddress.IPv4Address | ipaddress.IPv6Address
+
+   IP address type.

docs/source/pcapkit/foundation/traceflow/traceflow.rst

@@ -37,7 +37,7 @@ which is an abstract base class for all flow tracing classes.
          value can be set by :attr:`__protocol_type__` class attribute.
 
    .. property:: registry
-      :type: python:dict[str, ModuleDescriptor[TraceFlowBase] | typing.Type[TraceFlowBase]]
+      :type: dict[str, ModuleDescriptor[TraceFlowBase] | typing.Type[TraceFlowBase]]
 
       Mapping of protocol names to flow tracing classes.