From 3a09a6e396d9a109f7c01eed1f7a64f97b42acad Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Mon, 19 Oct 2026 00:30:59 -0400 Subject: [PATCH] docs(docs): fourth whole-repo pass over the non-API docs (#1103) Accuracy: - registry-protocol: a loud BaseError logs CRITICAL and installs the exception hooks; it no longer sets sys.tracebacklimit - pep: only the docs build installs .[all,dev] on macOS; SCTP named as the one checksum verifier - protocol-layer-placement: ARP and RARP have different EtherTypes - extension-header-subclassing: IPsec is not already in the MRO - engines index: PyPCAP's Python range matches its <3.12 marker - releasing, mint-criterion: stale line citations fixed or dropped Counts and timed context removed from workflows, ext, conf.py, the layer-placement page, pep and the pcapkit index. Clarity: the engine-gap exceptions on the overview, ext and pep pages, the gate-only sentence and tier sentence in workflows, and grammar in the API index pages; unresolved str and copyreg references fixed. Refs #1103 --- docs/source/conf.py | 6 ++-- .../extension-header-subclassing.rst | 2 +- .../conventions/mint-criterion.rst | 2 +- .../conventions/protocol-layer-placement.rst | 8 ++--- .../conventions/registry-protocol.rst | 6 ++-- .../conventions/sentinel-convention.rst | 4 +-- docs/source/contributing/pep.rst | 24 ++++++------- docs/source/contributing/releasing.rst | 2 +- docs/source/contributing/workflows.rst | 34 ++++++++++--------- docs/source/ext.rst | 21 ++++++------ docs/source/index.rst | 25 ++++++++------ docs/source/pcapkit/dumpkit/index.rst | 2 +- .../pcapkit/foundation/engines/index.rst | 17 +++++----- .../pcapkit/foundation/reassembly/index.rst | 8 ++--- .../pcapkit/foundation/traceflow/index.rst | 2 +- docs/source/pcapkit/index.rst | 2 +- docs/source/pcapkit/interface/index.rst | 6 ++-- .../pcapkit/protocols/application/index.rst | 4 +-- .../pcapkit/protocols/internet/index.rst | 4 +-- docs/source/pcapkit/protocols/link/index.rst | 4 +-- .../pcapkit/protocols/transport/index.rst | 4 +-- docs/source/pcapkit/vendor/index.rst | 4 +-- 22 files changed, 98 insertions(+), 93 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 6ee709c74e..2eb56ae380 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -543,9 +543,9 @@ def save_enum_member_docstring(app: 'Sphinx', what: str, name: str, # pylint: d registry member's docstring is the registry's own text, so the colon is usually a URL's: ``H.323 [http://standard.pictel.com/...]`` rendered as *Type:* ``H.323 [http`` above the description ``//standard.pictel.com/...``, - on 51 members. The bogus type was also parsed as a cross-reference, which is - where the ``http`` and ``Echo`` ``more than one target found`` warnings came - from. + and every member whose first docstring line holds a colon split the same + way. The bogus type was also parsed as a cross-reference, which is where the + ``http`` and ``Echo`` ``more than one target found`` warnings came from. Args: app: Sphinx application. diff --git a/docs/source/contributing/conventions/extension-header-subclassing.rst b/docs/source/contributing/conventions/extension-header-subclassing.rst index b7f9edefec..4293943990 100644 --- a/docs/source/contributing/conventions/extension-header-subclassing.rst +++ b/docs/source/contributing/conventions/extension-header-subclassing.rst @@ -113,7 +113,7 @@ class for it, so nothing implements the classification, but a future one inherit Explicit Base Declarations ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Name the second base **explicitly**, even though it is already in the MRO. +Name the second base **explicitly**, even where it is already in the MRO. :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` derives :class:`~pcapkit.protocols.internet.internet.Internet`, so every extension header reaches ``Internet`` transitively and an ``__mro__`` check cannot tell the two groups diff --git a/docs/source/contributing/conventions/mint-criterion.rst b/docs/source/contributing/conventions/mint-criterion.rst index d7eeb6c497..9b79f34877 100644 --- a/docs/source/contributing/conventions/mint-criterion.rst +++ b/docs/source/contributing/conventions/mint-criterion.rst @@ -10,7 +10,7 @@ a ``_missing_`` override, which decides what happens when a value has no member. MRO, so they carry no declared-but-unassigned range to resolve. The rest define one themselves, except the transport subclasses of :class:`~pcapkit.const.reg.apptype.apptype.AppType`, which inherit -``AppType._missing_`` (:file:`pcapkit/const/reg/apptype/apptype.py:2994`). The +``AppType._missing_`` (:file:`pcapkit/const/reg/apptype/apptype.py`). The behaviours below follow from it, and which one a given range gets is a **design decision, not a style preference**: diff --git a/docs/source/contributing/conventions/protocol-layer-placement.rst b/docs/source/contributing/conventions/protocol-layer-placement.rst index 999bcc470a..31a795d2b6 100644 --- a/docs/source/contributing/conventions/protocol-layer-placement.rst +++ b/docs/source/contributing/conventions/protocol-layer-placement.rst @@ -54,8 +54,8 @@ Why Function and Not Encapsulation :rfc:`1122` settles this inside one document. It lists **RARP in the application layer** at :rfc:`1122#section-1.1.3`, among the *"support protocols, used for host name mapping, booting, and management"*, while **ARP** sits in the Link Layer chapter -at :rfc:`1122#section-2.3.2`. Two sibling protocols, one frame format, one EtherType, -two layers -- decided on function alone. +at :rfc:`1122#section-2.3.2`. Sibling protocols sharing one frame format, each under +its own EtherType, in different layers -- decided on function alone. OSI says the same by construction. ITU-T X.200 §9.2.4.4 has a protocol declare its own layer in terms of *"functions which pertain to a particular layer"*, and clause 7 @@ -65,7 +65,7 @@ IANA Assignments Carry No Layer Claim ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Every registry this package dispatches on -- *Protocol Numbers*, *Ether Types*, -and *Service Name and Transport Protocol Port Number* -- have **no layer field**. +and *Service Name and Transport Protocol Port Number* -- has **no layer field**. *Protocol Numbers* frames itself as identifying *"the next level protocol"*, i.e. the **encapsulated** one. A registry assignment is evidence of encapsulation and of nothing else. @@ -87,7 +87,7 @@ Routing Protocols: Control Plane, Not Data Plane **"APPLICATION LAYER - ROUTING PROTOCOLS"**, with OSPF at §7.2.2, while :rfc:`1812#section-4.1` reads *"This chapter and chapter 5 discuss the protocols used at the Internet Layer: IP, ICMP, and IGMP."* So a routing protocol is application-layer -and the internet layer holds three protocols. +and the internet layer holds only IP, ICMP and IGMP. **X.200 does not contradict this, and must not be cited as though it did.** X.200 §7.5.2.1 says the Network Layer provides transport *"independence of routing and relay diff --git a/docs/source/contributing/conventions/registry-protocol.rst b/docs/source/contributing/conventions/registry-protocol.rst index 7833f7b171..a9ce06d871 100644 --- a/docs/source/contributing/conventions/registry-protocol.rst +++ b/docs/source/contributing/conventions/registry-protocol.rst @@ -261,9 +261,9 @@ course: they should follow the house convention and not be loud. Both answers are on the issue deliberately, and the reversal is the ruling. What it settles is not the one keyword -- it is the tie-breaker. A loud -:class:`~pcapkit.utilities.exceptions.BaseError` sets :data:`sys.tracebacklimit` to -``0`` **process-wide**, the -:issue:`362` hazard, so loudness is +:class:`~pcapkit.utilities.exceptions.BaseError` logs a :data:`logging.CRITICAL` +record, the :issue:`362` hazard, and outside development mode installs +:mod:`pcapkit`'s exception hooks **process-wide**, so loudness is paid for by the whole library rather than by the override's own callers. The argument against changing them was that ``quiet=True`` exists on the base for a name miss inside a *successful* call at ``Method.get`` and these two had no such caller; diff --git a/docs/source/contributing/conventions/sentinel-convention.rst b/docs/source/contributing/conventions/sentinel-convention.rst index 7e4dfc6a36..277b389355 100644 --- a/docs/source/contributing/conventions/sentinel-convention.rst +++ b/docs/source/contributing/conventions/sentinel-convention.rst @@ -145,7 +145,7 @@ the differences are **needs, not inconsistencies**: ``__reduce__`` returns its module-level name, so :mod:`pickle` stores a reference to that name and every protocol loads the same object back. A guarded ``__new__`` alone would not do, since pickle protocols 0 and 1 rebuild through - :func:`copyreg._reconstructor`, which calls :meth:`object.__new__` directly. That + ``copyreg._reconstructor``, which calls :meth:`object.__new__` directly. That path also limits pickles written before :issue:`1842`: one of ``NO_VALUE``, ``NO_DEFAULT`` or ``ABSENT`` at protocol 0 or 1 still loads, but as a second instance, because nothing on the class can intercept it. @@ -153,7 +153,7 @@ the differences are **needs, not inconsistencies**: ``__repr__`` Every sentinel has it, from the base. It is the object's own name -- ``NULL``, ``NO_VALUE``, ``NO_DEFAULT``, ``ABSENT`` -- as ``repr(None)`` is ``'None'``, and - :func:`str` gives the same. That is what a signature, :func:`help` and a traceback + :class:`str` gives the same. That is what a signature, :func:`help` and a traceback show. ``__setattr__`` / ``__delattr__`` diff --git a/docs/source/contributing/pep.rst b/docs/source/contributing/pep.rst index 60d8d2ece1..c0a038c4b8 100644 --- a/docs/source/contributing/pep.rst +++ b/docs/source/contributing/pep.rst @@ -119,7 +119,7 @@ either, and are the one item on this list that is not simply a table entry: the high-order 32 bits are never transmitted, so recovering them is stateful, and they widen both the ICV coverage and the AEAD associated data. -Some structural notes matter to anyone starting. Adding an integrity algorithm +The structure limits what a new row can do. Adding an integrity algorithm that is not an HMAC needs more than a row -- :class:`~pcapkit.protocols.internet.esp.IntegritySuite` records the digest as the name of a :mod:`hashlib` constructor, which AES-XCBC and AES-CMAC are not. @@ -421,7 +421,7 @@ process inflates them by up to 73%, so each shape wants its own interpreter. Recursive Dissection, With a Depth Limit ---------------------------------------- -**Decided for now, open to revisit.** Each layer dissects the next from inside +**Decided, open to revisit.** Each layer dissects the next from inside its own parse, so dissecting a frame recurses once per layer, at 9 to 12 Python frames a layer. Deep nesting -- IP in IP, stacked 802.1Q tags, long chains of IPv6 extension headers -- used to exhaust the recursion limit and leave the rest @@ -537,10 +537,9 @@ both of the following are worth knowing before reaching for them: since May 2024. It does mean ``pip install pypcapkit[PyPCAP]`` can fail to build. Since there is no wheel to fall back on, the extra is kept **out of** ``all``: otherwise ``pip install pypcapkit[all]`` would demand a compiler and - the libpcap development files from every user, and would break the docs, conda - and release workflows -- all of which install ``.[all]`` or ``.[all,dev]`` -- - on the macOS runner, where :file:`pcap.h` is present but no - ``libpcap.dylib`` is. + the libpcap development files from every user, and would break the docs + build, which installs ``.[all,dev]`` on the macOS runner, where :file:`pcap.h` + is present but no ``libpcap.dylib`` is. That is solved, though not by changing the ``PyPCAP`` extra. `pcap-ct `__ re-implements the ``pypcap`` API in pure @@ -571,8 +570,8 @@ keeping IPv4 and TCP. Each gap is announced through an :class:`~pcapkit.utilities.warnings.AttributeWarning` or an outright exception rather than by silently returning nothing, save that `pypcapfile`_ leaves TCP behind a VLAN tag, in a tunnel or behind an extension header (an IPv6 one, or AH -in IPv4) out without one -- :doc:`/pcapkit/foundation/engines/index` tabulates -them. +in IPv4) out of TCP reassembly and flow tracing without a warning -- +:doc:`/pcapkit/foundation/engines/index` tabulates them. Adding a further engine does not mean adding handler methods to :class:`~pcapkit.foundation.extraction.Extractor`, as the thread describes. A new engine subclasses @@ -808,8 +807,8 @@ These protocols parse a checksum or CRC field — :class:`~pcapkit.protocols.application.ospf.OSPF`, :class:`~pcapkit.protocols.transport.sctp.SCTP`, :class:`~pcapkit.protocols.transport.tcp.TCP` and -:class:`~pcapkit.protocols.transport.udp.UDP` — and only one of them checks -whether the value is *right*: +:class:`~pcapkit.protocols.transport.udp.UDP` — and of them only SCTP checks +whether the value is *right*, through :attr:`SCTP.checksum_valid `. For the others the field is recorded and never questioned, so a corrupted capture parses as cleanly as an intact one. @@ -956,8 +955,9 @@ produced. That is why an ordinary commit does not publish: the version string has not moved, so each job's own check finds its target already there and every one of -them skips, as does the full-suite release test gate ahead of them. Changing the version string is what flips every one of those checks, and -the next push then tags and publishes. So: +them skips, as does the full-suite release test gate ahead of them. Changing the +version string is what flips every one of those checks, and the next push then +tags and publishes. So: .. list-table:: :header-rows: 1 diff --git a/docs/source/contributing/releasing.rst b/docs/source/contributing/releasing.rst index df6187e108..9ad5760c88 100644 --- a/docs/source/contributing/releasing.rst +++ b/docs/source/contributing/releasing.rst @@ -62,7 +62,7 @@ Either run the script, or move both fields by hand in the same commit. This is the **only** edit a person makes to get a release started -- the tag, the Release, and every upload are the workflow's job from here. Other checks run unconditionally on the same path, though none is a step in *this* -process: the ``changelog`` job (``unit-tests.yml:1624-1643``) fails outright if +process: the ``changelog`` job (``unit-tests.yml:1624-1650``) fails outright if ``CHANGELOG.md`` has drifted from its source entry under :file:`docs/source/changelog/`, and the release-body step warns, without failing, if that entry's heading still reads "unreleased" diff --git a/docs/source/contributing/workflows.rst b/docs/source/contributing/workflows.rst index ed56ffdba0..05dc0f88ee 100644 --- a/docs/source/contributing/workflows.rst +++ b/docs/source/contributing/workflows.rst @@ -244,8 +244,8 @@ rather than the event, so its gate can run whichever way the run was raised, onc ``workflow_run`` Edges ---------------------- -These edges come from grepping every ``on:`` block rather than from a -hand-maintained list: +Each edge cites the ``on:`` block it comes from, so grepping those blocks +re-derives the list: * ``.github/workflows/cron-vendor.yml:14-16`` -- **Vendor Update** fires on completion of **Unit Tests**. @@ -262,9 +262,9 @@ hand-maintained list: success, failure, or skipped -- and regardless of what triggered it, including a pull request's own run of Unit Tests. Every downstream workflow therefore re-checks ``github.event.workflow_run.event`` -and ``.head_branch`` (or, for Create Release and Coverage Comment, ``.conclusion``) itself before -doing anything with an outward effect; none of the filtering happens in the -``on:`` block. +and ``.head_branch`` (or, for Create Release and Coverage Comment, +``.conclusion``) itself before doing anything with an outward effect; none of +the filtering happens in the ``on:`` block. Those checks say nothing about *which* commit was verified. A ``workflow_run`` checks out ``github.sha``, ``main``'s tip when the event is raised, not @@ -319,13 +319,13 @@ source entry) and ``python-versions``, which reads ``gate``'s version (see `Python Versions`_ below). It skips the rest -- the matrix jobs, ``test``, ``test-ktlo``, ``integration``, ``integration-ktlo``, ``engine-tests`` (a job per engine, each looping over its Python versions), ``pypcap-parity``, -``pypcap-parity-ktlo`` and ``unittest-ordering``, each of which has already run once for this commit -from Unit Tests' own ``push`` trigger (and, all but ``unittest-ordering``, -which runs on ``main`` pushes only, from its ``pull_request`` trigger), so -running any of them again per caller would -test the same commit several times over -- the docs-only path's ``changes`` -and ``project-tests``, and ``required-checks`` (see `Required Status -Checks`_ below), gated out by their own ``if:`` rather than by having +``pypcap-parity-ktlo`` and ``unittest-ordering``, each of which has already run +once for this commit from Unit Tests' own ``push`` trigger (and, all but +``unittest-ordering``, which runs on ``main`` pushes only, from its +``pull_request`` trigger), so running any of them again per caller would test +the same commit several times over. It also skips the docs-only path's +``changes`` and ``project-tests``, and ``required-checks`` (see `Required Status +Checks`_ below), which are gated out by their own ``if:`` rather than by having already run. ``changelog`` carries no ``if:`` at all and runs on every path regardless -- deliberately, per its own comment (``unit-tests.yml:1612-1618``): ``create-release.yml`` feeds @@ -680,8 +680,10 @@ triggers; the ``gate-only: true`` reusable calls documented above skip it via ``if: ${{ always() && inputs.gate-only != true }}`` (``unit-tests.yml:1939``), so it is never produced -- and never expected -- on those paths. -Python versions come in two tiers (`#1633 `__), and an experimental one (`#1660 `__, -below), declared in :file:`.github/python-versions.toml` (see `Python Versions`_). +Python versions are tiered -- supported and KTLO +(`#1633 `__), and experimental +(`#1660 `__, below) -- in +:file:`.github/python-versions.toml` (see `Python Versions`_). The **supported** tier, 3.11-3.15, blocks: a failed leg fails ``Required checks passed`` or its own required ``Compat`` context. The **KTLO** tier -- end-of-life 3.7-3.10, still built and tested -- never blocks, is never a required context, and never shows a commit or a @@ -786,8 +788,8 @@ holds ``roundtrip`` (``ROUNDTRIP_SWEEP_GLOB`` in :file:`tests/_tiers.py`), and ``integration`` too: off ``latest`` its legs leave out the ``*roundtrip*_runtime.py`` modules (``ROUNDTRIP_RUNTIME_GLOB``), dropping them from ``fixture_tier_paths()``'s selection and adding the glob as an ``--ignore-glob``, -since pytest applies no ignore to a path it was handed. On 2026-10-14 they were 41 modules -and 8% of the unit tier's time in a serial 3.14 run (86 of 1,031 s), and 10-11% on the +since pytest applies no ignore to a path it was handed. On 2026-10-14 they took +8% of the unit tier's time in a serial 3.14 run (86 of 1,031 s), and 10-11% on the 3.14, 3.15 and 3.14t legs of run 38581834697, so the rest should take GraalPy 88-113 minutes (estimate). diff --git a/docs/source/ext.rst b/docs/source/ext.rst index 8d459e9ee5..d0a48ffae6 100644 --- a/docs/source/ext.rst +++ b/docs/source/ext.rst @@ -119,7 +119,7 @@ protocols, respectively. abstract base class for protocols, and it is not recommended to inherit from it directly, unless you are going to create a new protocol stack, e.g., a new miscellaneous protocol stack as in :mod:`pcapkit.protocols.misc` module. The - four layer base classes above, like the built-in miscellaneous protocols, + layer base classes above, like the built-in miscellaneous protocols, derive from :class:`~pcapkit.protocols.protocol.ProtocolBase` rather than from :class:`~pcapkit.protocols.protocol.Protocol`. @@ -426,15 +426,14 @@ The available engines and the file formats they read: whatsoever, so they support neither reassembly nor flow tracing; `PyPCAPFile`_ has no IPv6 decoder, so it supports IPv4 and TCP reassembly but not IPv6. What matters is that the gap is *announced* -- each engine warns, or raises, for the - capability it cannot provide, rather than silently producing an empty result, - save that `PyPCAPFile`_ leaves TCP behind a VLAN tag, in a tunnel or behind an - extension header (an IPv6 one, or AH in IPv4) out without a warning; that - `DPKT`_ leaves TCP in an IP-in-IP tunnel or behind an AH or IPv6 extension - header in IPv4, and IPv4 in IPv6 or IPv6 in IPv4, out without one; and the - `Scapy`_ engine reads IPv6 only as far as `Scapy`_ dissects it, which leaves - IPv6 behind some BSD loopback headers, and TCP and IPv6 fragments behind some - IPv6 extension headers, out without one. See - :doc:`pcapkit/foundation/engines/index` for the full table. + capability it cannot provide, rather than silently producing an empty result. + The exceptions pass without a warning: `PyPCAPFile`_ and `DPKT`_ leave TCP + behind some tags, tunnels and extension headers out of TCP reassembly and + flow tracing, `DPKT`_ also leaves IPv4 in IPv6, and IPv6 in IPv4, out of IP + reassembly, and the `Scapy`_ engine reads IPv6 only as far as `Scapy`_ + dissects it. See + :doc:`pcapkit/foundation/engines/index` for the full table, which names each + case. .. note:: @@ -599,7 +598,7 @@ The following code snippet shows how to create a new engine class: # NOTE: The following code snippet is to handle the flow tracing of # the network packets, i.e., to trace a series of packets as they - # will compose as a flow and/or stream. Before reassembly, we need + # will compose as a flow and/or stream. Before flow tracing, we need # to convert the packet to a tailored format, i.e., a dict-like object, # which is then passed to the flow tracing function. For more # information, please refer to the documentation of diff --git a/docs/source/index.rst b/docs/source/index.rst index 1638384c93..b3194fc084 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -147,15 +147,19 @@ Speed is not free. Every third-party engine supports **less** than the dissection at all, so they offer neither reassembly nor flow tracing, and :class:`~pcapkit.foundation.engines.pypcapfile.PyPCAPFile` has no IPv6 decoder, so IPv6 reassembly is unavailable. Each gap is announced with a warning or an -exception rather than silently returning nothing, save that -:class:`~pcapkit.foundation.engines.pypcapfile.PyPCAPFile` leaves TCP behind a -VLAN tag, in a tunnel or behind an extension header (an IPv6 one, or AH in IPv4) -out without one; that :class:`~pcapkit.foundation.engines.dpkt.DPKT` leaves -TCP in an IP-in-IP tunnel or behind an AH or IPv6 extension header in IPv4, and -IPv4 in IPv6 or IPv6 in IPv4, out without one; and -:class:`~pcapkit.foundation.engines.scapy.Scapy` reads IPv6 only as far as -`Scapy`_ dissects it, which leaves IPv6 behind some BSD loopback headers, and -TCP and IPv6 fragments behind some IPv6 extension headers, out without one. +exception rather than silently returning nothing, except for these, which pass +without a warning: + +- :class:`~pcapkit.foundation.engines.pypcapfile.PyPCAPFile` leaves TCP behind a + VLAN tag, in a tunnel or behind an extension header (an IPv6 one, or AH in + IPv4) out of TCP reassembly and flow tracing; +- :class:`~pcapkit.foundation.engines.dpkt.DPKT` leaves TCP in an IP-in-IP + tunnel or behind an AH or IPv6 extension header in IPv4 out of TCP reassembly + and flow tracing, and IPv4 in IPv6 or IPv6 in IPv4 out of IP reassembly; +- :class:`~pcapkit.foundation.engines.scapy.Scapy` reads IPv6 only as far as + `Scapy`_ dissects it, so IPv6 behind some BSD loopback headers, and TCP and + IPv6 fragments behind some IPv6 extension headers, go undissected. + :doc:`pcapkit/foundation/engines/index` tabulates them. Every engine also answers a preflight check -- @@ -231,7 +235,8 @@ compared with a measured row. .. [1] `PyPCAPFile`_ 0.12.0 imports :mod:`imp`, which Python removed in 3.12. -.. [2] `PyPCAP`_ 1.3.0 is unsupported on Python 3.12+. +.. [2] `PyPCAP`_ 1.3.0 does not build on Python 3.12+: its pre-generated + :file:`pcap.c` does not compile against that C API. .. [3] `PyShark`_ 0.6 cannot create the implicit event loop it expects on Python 3.14; it ran on 3.10--3.13. diff --git a/docs/source/pcapkit/dumpkit/index.rst b/docs/source/pcapkit/dumpkit/index.rst index 3784298bcf..2c8c7a6d13 100644 --- a/docs/source/pcapkit/dumpkit/index.rst +++ b/docs/source/pcapkit/dumpkit/index.rst @@ -5,7 +5,7 @@ Dump Utilities .. module:: pcapkit.dumpkit :mod:`pcapkit.dumpkit` is the collection of :mod:`pcapkit`'s own dumpers, -alike those in :mod:`dictdumper`. +like those in :mod:`dictdumper`. .. toctree:: :maxdepth: 2 diff --git a/docs/source/pcapkit/foundation/engines/index.rst b/docs/source/pcapkit/foundation/engines/index.rst index 08be02fe07..c54b98a872 100644 --- a/docs/source/pcapkit/foundation/engines/index.rst +++ b/docs/source/pcapkit/foundation/engines/index.rst @@ -3,11 +3,10 @@ Engine Support .. module:: pcapkit.foundation.engines -:mod:`pcapkit.foundation.engines` is a collection of engines -support for :mod:`pcapkit`, including but not limited to the -built-in PCAP and `PCAP-NG`_ file support, `Scapy`_, `PyShark`_, -`DPKT`_, `PyPCAP`_, `pcap-ct`_ and `PyPCAPFile`_ 3rd party engine -support. +:mod:`pcapkit.foundation.engines` holds the extraction engines of +:mod:`pcapkit`: the built-in PCAP and `PCAP-NG`_ readers, and the +`Scapy`_, `PyShark`_, `DPKT`_, `PyPCAP`_, `pcap-ct`_ and `PyPCAPFile`_ +3rd party engines. .. seealso:: @@ -178,9 +177,9 @@ a working build. .. seealso:: - :doc:`../../../index` covers the installation prerequisites in full, - including how ``pypcap``'s :file:`setup.py` looks for :file:`pcap.h` and why - a Homebrew ``libpcap`` is not always found. + The :doc:`project overview <../../../index>` covers the installation + prerequisites in full, including how ``pypcap``'s :file:`setup.py` looks + for :file:`pcap.h` and why a Homebrew ``libpcap`` is not always found. Choosing Between PyPCAP and PCAP_CT ----------------------------------- @@ -195,7 +194,7 @@ and different interpreter coverage: +---------------------------------------------------------------+---------------------+-------------------+---------------------------------------------------+ | Engine (``engine=``) | Distribution | Python | What it needs | +===============================================================+=====================+===================+===================================================+ -| :class:`~pcapkit.foundation.engines.pypcap.PyPCAP` | `PyPCAP`_ 1.3.0 | 3.10, 3.11 only | to build: a C compiler, ``pcap.h`` and a system | +| :class:`~pcapkit.foundation.engines.pypcap.PyPCAP` | `PyPCAP`_ 1.3.0 | 3.11 or older | to build: a C compiler, ``pcap.h`` and a system | | (``'pypcap'``) | (stable) | | libpcap -- no wheels are published | +---------------------------------------------------------------+---------------------+-------------------+---------------------------------------------------+ | :class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` | `pcap-ct`_ 1.3.0b3 | 3.10 and newer | to install: nothing -- ``py3-none-any`` wheels. | diff --git a/docs/source/pcapkit/foundation/reassembly/index.rst b/docs/source/pcapkit/foundation/reassembly/index.rst index 0d10928ec4..486f73559f 100644 --- a/docs/source/pcapkit/foundation/reassembly/index.rst +++ b/docs/source/pcapkit/foundation/reassembly/index.rst @@ -4,9 +4,9 @@ Packets Reassembly .. module:: pcapkit.foundation.reassembly -:mod:`pcapkit.foundation.reassembly` bases on algorithms described -in :rfc:`791` and :rfc:`815`, implements datagram reassembly -of IP and TCP packets. +:mod:`pcapkit.foundation.reassembly` implements datagram reassembly +of IP and TCP packets, based on the algorithms described in :rfc:`791` +and :rfc:`815`. .. seealso:: @@ -22,7 +22,7 @@ of IP and TCP packets. All reassembly classes are implemented as :class:`~pcapkit.foundation.reassembly.reassembly.ReassemblyBase` subclasses, which are responsible for processing extracted packets and -reassemble the datagrams to a nonfragmented packet. Below is a brief +reassembling the datagrams into unfragmented packets. Below is a brief diagram of the class hierarchy of :mod:`pcapkit.foundation.reassembly`: .. mermaid:: diff --git a/docs/source/pcapkit/foundation/traceflow/index.rst b/docs/source/pcapkit/foundation/traceflow/index.rst index e1780d24e2..05b5db96f7 100644 --- a/docs/source/pcapkit/foundation/traceflow/index.rst +++ b/docs/source/pcapkit/foundation/traceflow/index.rst @@ -25,7 +25,7 @@ for :mod:`pcapkit` package. All flow tracing classes are implemented as :class:`~pcapkit.foundation.traceflow.traceflow.TraceFlowBase` subclasses, which are responsible for processing extracted packets and -follow the flow and/or stream to provide more insights. Below is a brief +following the flow and/or stream to provide more insights. Below is a brief diagram of the class hierarchy of :mod:`pcapkit.foundation.traceflow`: .. mermaid:: diff --git a/docs/source/pcapkit/index.rst b/docs/source/pcapkit/index.rst index 712f12ed19..56bd34edbf 100644 --- a/docs/source/pcapkit/index.rst +++ b/docs/source/pcapkit/index.rst @@ -184,6 +184,6 @@ crawlers' :envvar:`PCAPKIT_VENDOR_RETRY`, :envvar:`PCAPKIT_CI_MODE`, every request. The tunable limits are new as variables (:issue:`1726`). A bad value of :envvar:`PCAPKIT_DEVMODE`, :envvar:`PCAPKIT_VERBOSE`, :envvar:`PCAPKIT_SPHINX`, :envvar:`PCAPKIT_CI_MODE` or - :envvar:`PCAPKIT_VENDOR_RETRY` now warns with + :envvar:`PCAPKIT_VENDOR_RETRY` warns with :exc:`~pcapkit.utilities.warnings.ConfigWarning` instead of being taken silently, or, for :envvar:`PCAPKIT_VENDOR_RETRY`, crashing the import. diff --git a/docs/source/pcapkit/interface/index.rst b/docs/source/pcapkit/interface/index.rst index 59aff646d9..da0b7fd518 100644 --- a/docs/source/pcapkit/interface/index.rst +++ b/docs/source/pcapkit/interface/index.rst @@ -3,8 +3,8 @@ User Interface .. module:: pcapkit.interface -:mod:`pcapkit.interface` defines several user-oriented -interfaces, variables, and etc. These interfaces are +:mod:`pcapkit.interface` defines the user-oriented +interfaces and constants. These interfaces are designed to help and simplify the usage of :mod:`pcapkit`. .. toctree:: @@ -23,7 +23,7 @@ The helpers the registrars share live in the .. note:: - Should you would like to have additional interfaces defined, + Should you wish to have additional interfaces defined, please feel free to open an issue on GitHub, or even better, submit a pull request. Your contribution is highly appreciated. diff --git a/docs/source/pcapkit/protocols/application/index.rst b/docs/source/pcapkit/protocols/application/index.rst index 991e9cd54b..5561a41080 100644 --- a/docs/source/pcapkit/protocols/application/index.rst +++ b/docs/source/pcapkit/protocols/application/index.rst @@ -5,7 +5,7 @@ Application Layer .. module:: pcapkit.protocols.data.application .. module:: pcapkit.protocols.schema.application -:mod:`pcapkit.protocols.application` is collection of all protocols in +:mod:`pcapkit.protocols.application` is the collection of all protocols in application layer, with detailed implementation and methods. Layer is decided by function rather than encapsulation, see :doc:`/contributing/conventions/protocol-layer-placement`. @@ -24,7 +24,7 @@ function rather than encapsulation, see .. todo:: - Implements BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP, NTP, ONC:RPC, + Implement BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP, NTP, ONC:RPC, POP, RIP, RTP, SIP, SMTP, SNMP, SSH, TELNET, TLS/SSL, XMPP. Protocol Registry diff --git a/docs/source/pcapkit/protocols/internet/index.rst b/docs/source/pcapkit/protocols/internet/index.rst index 09bf93617f..39f32a0cc5 100644 --- a/docs/source/pcapkit/protocols/internet/index.rst +++ b/docs/source/pcapkit/protocols/internet/index.rst @@ -5,7 +5,7 @@ Internet Layer .. module:: pcapkit.protocols.data.internet .. module:: pcapkit.protocols.schema.internet -:mod:`pcapkit.protocols.internet` is collection of all protocols in +:mod:`pcapkit.protocols.internet` is the collection of all protocols in internet layer, with detailed implementation and methods. .. toctree:: @@ -30,7 +30,7 @@ internet layer, with detailed implementation and methods. .. todo:: - Implements ECN, ICMP, ICMPv6, IGMP, Shim6. + Implement ECN, ICMP, ICMPv6, IGMP, Shim6. Protocol Registry ----------------- diff --git a/docs/source/pcapkit/protocols/link/index.rst b/docs/source/pcapkit/protocols/link/index.rst index 9e70c85817..346e50ebe4 100644 --- a/docs/source/pcapkit/protocols/link/index.rst +++ b/docs/source/pcapkit/protocols/link/index.rst @@ -5,7 +5,7 @@ Link Layer .. module:: pcapkit.protocols.data.link .. module:: pcapkit.protocols.schema.link -:mod:`pcapkit.protocols.link` is collection of all protocols in +:mod:`pcapkit.protocols.link` is the collection of all protocols in link layer, with detailed implementation and methods. .. versionremoved:: 1.5.0 @@ -33,7 +33,7 @@ link layer, with detailed implementation and methods. .. todo:: - Implements DSL, EAPOL, FDDI, ISDN, NDP, PPP. + Implement DSL, EAPOL, FDDI, ISDN, NDP, PPP. Protocol Registry ----------------- diff --git a/docs/source/pcapkit/protocols/transport/index.rst b/docs/source/pcapkit/protocols/transport/index.rst index b453bfe119..24328fca2d 100644 --- a/docs/source/pcapkit/protocols/transport/index.rst +++ b/docs/source/pcapkit/protocols/transport/index.rst @@ -5,7 +5,7 @@ Transport Layer .. module:: pcapkit.protocols.data.transport .. module:: pcapkit.protocols.schema.transport -:mod:`pcapkit.protocols.transport` is collection of all protocols in +:mod:`pcapkit.protocols.transport` is the collection of all protocols in transport layer, with detailed implementation and methods. .. toctree:: @@ -18,7 +18,7 @@ transport layer, with detailed implementation and methods. .. todo:: - Implements DCCP, RSVP. + Implement DCCP, RSVP. Protocol Registry ----------------- diff --git a/docs/source/pcapkit/vendor/index.rst b/docs/source/pcapkit/vendor/index.rst index 01f6783913..af878e121c 100644 --- a/docs/source/pcapkit/vendor/index.rst +++ b/docs/source/pcapkit/vendor/index.rst @@ -4,8 +4,8 @@ Vendor Crawlers .. module:: pcapkit.vendor -This module contains all web crawlers of :mod:`pcapkit`, which are -automatically generating the :mod:`pcapkit.const` module's constant +This module contains all web crawlers of :mod:`pcapkit`, which +automatically generate the :mod:`pcapkit.const` module's constant enumerations. The crawlers need the ``vendor`` extra, ``pip install "pypcapkit[vendor]"``.