docs: #1103 round 2 whole-repo prose sweep

CONTRIBUTING.md

@@ -158,7 +158,9 @@ The job drives them through the `Makefile` rather than restating their flags (`v
 variables, so a check cannot come out clean locally and red in CI because the two drifted.
 
 **Those steps are advisory, not a gate.** Each carries `continue-on-error: true`, so a finding lands
-as a non-blocking annotation and a red linter will not fail your pull request. The workflow's
+as a non-blocking annotation and a red one will not fail your pull request. The job's `actionlint`
+step is the exception — it lints `.github/workflows/`, has no `Makefile` target, and carries no
+`continue-on-error`, so a finding there does fail the job. The workflow's
 header records which of them are clean and what each of the others would need before its
 `continue-on-error` line could be deleted. Read the job's run summary, where each step writes
 its verdict, and try not to add to the numbers.

docs/source/contributing/conventions/utilities-or-corekit.rst

@@ -9,11 +9,11 @@ who uses them. This rule can be checked from the import graph alone, and it need
 the fewest moves: one.
 
 :mod:`pcapkit.utilities` **is for cross-cutting services**: exceptions, warnings,
-logging, the compatibility layer, configuration, and wrappers around third-party
-libraries such as :mod:`~pcapkit.utilities.chardet`. The question to ask of a module
-is *could any code use this service, and does it import nothing from* :mod:`pcapkit`
-*outside* ``utilities``? Both halves have to hold, and *nothing* covers a top-level
-import, one inside a function and one under ``TYPE_CHECKING`` alike.
+logging, the compatibility layer, configuration, timestamp conversion, and wrappers
+around third-party libraries such as :mod:`~pcapkit.utilities.chardet`. The question
+to ask of a module is *could any code use this service, and does it import nothing
+from* :mod:`pcapkit` *outside* ``utilities``? Both halves have to hold, and *nothing*
+covers a top-level import, one inside a function and one under ``TYPE_CHECKING`` alike.
 :file:`tests/project/test_utilities_import_boundary_1735_unit.py` checks every module
 under :file:`pcapkit/utilities/` for it.
 

docs/source/pcapkit/protocols/index.rst

@@ -99,6 +99,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        Raw --> FTP_DATA
        ARP --> RARP
        IPv6_Ext --> AH & ESP
+       Internet --> HIP
 
        B --> C(Protocol)
        C --> D([user customisation ...])

pcapkit/corekit/context.py

@@ -20,13 +20,13 @@
 Rather than adding protocol specific keyword arguments to
 :class:`~pcapkit.foundation.extraction.Extractor`, such information is
 passed as a :class:`ContextRegistry` -- a mapping of protocol index ID
-(cf. :meth:`Protocol.id <pcapkit.protocols.protocol.Protocol.id>`)
+(cf. :meth:`ProtocolBase.id <pcapkit.protocols.protocol.ProtocolBase.id>`)
 to a :class:`ProtocolContext` instance. The registry is handed to
 :class:`~pcapkit.foundation.extraction.Extractor` once, and is then
 propagated down the protocol stack by
-:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`,
+:meth:`ProtocolBase._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`,
 so that a protocol nested arbitrarily deep can reach it through
-:meth:`Protocol._get_context <pcapkit.protocols.protocol.Protocol._get_context>`.
+:meth:`ProtocolBase._get_context <pcapkit.protocols.protocol.ProtocolBase._get_context>`.
 
 Example:
     Decoding an ESP tunnel end to end::
@@ -90,7 +90,7 @@ def protocol(cls) -> 'tuple[str, ...]':
         """Index ID of the protocol(s) this context applies to.
 
         The returned names are matched against
-        :meth:`Protocol.id <pcapkit.protocols.protocol.Protocol.id>`,
+        :meth:`ProtocolBase.id <pcapkit.protocols.protocol.ProtocolBase.id>`,
         and are case insensitive.
 
         """

pcapkit/corekit/decorators.py

@@ -67,9 +67,9 @@ def seekset(func: 'Callable[Concatenate[ProtocolBase, P], R_seekset]') -> 'Calla
     Important:
         This decorator function is designed for decorating *instance methods*.
 
-    The decorator will keep the current offset of :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>`,
+    The decorator will keep the current offset of :attr:`self._file <pcapkit.protocols.protocol.ProtocolBase._file>`,
     then call the decorated function. Afterwards, it will rewind the offset of
-    :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>` to the original and return the return value from
+    :attr:`self._file <pcapkit.protocols.protocol.ProtocolBase._file>` to the original and return the return value from
     the decorated function.
 
     Note:
@@ -79,7 +79,7 @@ def seekset(func: 'Callable[Concatenate[ProtocolBase, P], R_seekset]') -> 'Calla
                  *args: 'typing.Any', **kwargs: 'typing.Any') -> 'typing.Any'
 
     See Also:
-        :meth:`pcapkit.protocols.protocol.Protocol._read_packet`
+        :meth:`pcapkit.protocols.protocol.ProtocolBase._read_packet`
 
     :param func: decorated function
     :meta decorator:
@@ -130,7 +130,7 @@ def beholder(
                  *args: 'typing.Any', **kwargs: 'typing.Any') -> 'pcapkit.protocols.protocol.ProtocolBase'
 
     See Also:
-        :meth:`pcapkit.protocols.protocol.Protocol._decode_next_layer`
+        :meth:`pcapkit.protocols.protocol.ProtocolBase._decode_next_layer`
 
     .. versionchanged:: 1.3.0
 

pcapkit/foundation/reassembly/data/data.py

@@ -134,7 +134,7 @@ class Deferred:
 
     Args:
         analyze: The analyser to call, i.e.
-            :meth:`Protocol.analyze <pcapkit.protocols.protocol.Protocol.analyze>`
+            :meth:`ProtocolBase.analyze <pcapkit.protocols.protocol.ProtocolBase.analyze>`
             bound to the reassembly object's protocol.
         proto: Payload protocol type.
         payload: Reassembled payload to parse.

pcapkit/protocols/application/application.py

@@ -86,7 +86,7 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None,
 
         See Also:
             For construction arguments, please refer to
-            :meth:`self.make <pcapkit.protocols.protocol.Protocol.make>`.
+            :meth:`self.make <pcapkit.protocols.protocol.ProtocolBase.make>`.
 
         """
         # call super post-init
@@ -144,7 +144,7 @@ def _decode_next_layer(self, dict_: '_PT', proto: 'Optional[int]' = None, length
             proto: next layer protocol index; only the ``-1`` sentinel
                 (the rest, undissected) is accepted
             length: valid (*non-padding*) length
-            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.Protocol.unpack>`)
+            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`)
 
         Returns:
             Current protocol with the undissected remainder as payload.
@@ -167,7 +167,7 @@ def _import_next_layer(self, proto: 'int', length: 'Optional[int]' = None, *,  #
             proto: next layer protocol index; only the ``-1`` sentinel
                 (the rest, undissected) is accepted
             length: valid (*non-padding*) length
-            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.Protocol.unpack>`)
+            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`)
 
         Returns:
             Instance of :class:`~pcapkit.protocols.misc.raw.Raw`, or of

pcapkit/protocols/application/ftp.py

@@ -312,7 +312,7 @@ def _decode_args(self, args: 'Optional[bytes]') -> 'tuple[Optional[str], Optiona
         """Decode arguments, recording how to encode them back.
 
         The arguments are decoded by :meth:`self.decode
-        <pcapkit.protocols.protocol.Protocol.decode>`. Where the result does
+        <pcapkit.protocols.protocol.ProtocolBase.decode>`. Where the result does
         not encode back to ``args`` as UTF-8 -- which :meth:`make` uses by
         default -- the detected charset is returned with it, or ``'latin-1'``
         (decoding again) if that does not reproduce ``args`` either, so that the

pcapkit/protocols/application/httpv1.py

@@ -418,7 +418,7 @@ def _decode_text(self, text: 'bytes') -> 'tuple[str, Optional[str]]':
         """Decode start-line text, recording how to encode it back.
 
         The text is decoded by :meth:`self.decode
-        <pcapkit.protocols.protocol.Protocol.decode>`. Where the result does
+        <pcapkit.protocols.protocol.ProtocolBase.decode>`. Where the result does
         not encode back to ``text`` as UTF-8 -- which :meth:`make` uses by
         default -- the detected charset is returned with it, or ``'latin-1'``
         (decoding again) if that does not reproduce ``text`` either, so that the

pcapkit/protocols/application/httpv2.py

@@ -251,7 +251,7 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_HTTP'
         if length is None:
             # ``0 < ... < 9`` rather than ``... < 9``: an exhausted stream
             # (``len(self) == 0``) is left alone, so ``length`` reaches
-            # :meth:`Protocol.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`
+            # :meth:`ProtocolBase.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`
             # still ``None`` and its ``prepare`` decorator raises
             # :exc:`StreamEOFError` as documented above; only a *non-empty*
             # short stream is rejected as malformed here.

pcapkit/protocols/application/ngap.py

@@ -31,7 +31,7 @@
 (``pip install pypcapkit[NGAP]``). :mod:`pcapkit` imports and works without
 it; an NGAP payload simply degrades to the opaque payload path, exactly as an
 unregistered PPID would, because
-:meth:`~pcapkit.protocols.protocol.Protocol._import_next_layer`, which
+:meth:`~pcapkit.protocols.protocol.ProtocolBase._import_next_layer`, which
 :class:`~pcapkit.protocols.transport.sctp.SCTP` inherits, is wrapped in
 :func:`~pcapkit.corekit.decorators.beholder` and falls back to
 :class:`~pcapkit.protocols.misc.raw.Raw`.

pcapkit/protocols/application/ospf.py

@@ -112,9 +112,9 @@ class OSPF(Application[Data_OSPF, Schema_OSPF],
     """
     #: Version number of corresponding protocol, as read off the header. Held on
     #: the instance rather than read back out of :attr:`self._info
-    #: <pcapkit.protocols.protocol.Protocol._info>` because :attr:`name` and
+    #: <pcapkit.protocols.protocol.ProtocolBase._info>` because :attr:`name` and
     #: :attr:`alias` are needed *during* :meth:`read` -- :meth:`self._decode_next_layer
-    #: <pcapkit.protocols.protocol.Protocol._decode_next_layer>` builds the
+    #: <pcapkit.protocols.protocol.ProtocolBase._decode_next_layer>` builds the
     #: protocol chain out of :attr:`alias` -- and ``_info`` is not assigned until
     #: :meth:`read` has returned. See ``ARP._acnm`` on
     #: :class:`~pcapkit.protocols.link.arp.ARP`, which has the same constraint.
@@ -403,7 +403,7 @@ def _make_id_numbers(self, id: 'IPv4Address | str | bytes | bytearray') -> 'byte
 
             The description below uses :attr:`self.__class__.__name__
             <type.__name__>` rather than :attr:`self.alias
-            <pcapkit.protocols.protocol.Protocol.alias>`, because ``alias``
+            <pcapkit.protocols.protocol.ProtocolBase.alias>`, because ``alias``
             here reads ``self._version``, which :meth:`read` only assigns
             from the wire -- unavailable to a construction-only instance that
             never went through :meth:`read`.

pcapkit/protocols/data/data.py

@@ -19,7 +19,7 @@ class Data(Info):
     The ``__next_name__``, ``__next_type__`` and ``__short_read__`` keys are
     metadata, listed in :attr:`~pcapkit.corekit.infoclass.Info.__included__`
     and :attr:`~pcapkit.corekit.infoclass.Info.__excluded__`:
-    :meth:`Protocol.from_data <pcapkit.protocols.protocol.ProtocolBase.from_data>`
+    :meth:`ProtocolBase.from_data <pcapkit.protocols.protocol.ProtocolBase.from_data>`
     dispatches the payload on the first two and on nothing else, and cuts a
     short read back on the third. :meth:`to_dict` carries them, so that
     ``from_data(info.to_dict())`` rebuilds as ``from_data(info)`` does, while

pcapkit/protocols/data/internet/hip.py

@@ -520,9 +520,7 @@ class CertParameter(Parameter):
     #: Certificate group -- :rfc:`8002#section-2`'s "Group ID grouping
     #: multiple related CERT parameters". An arbitrary number, since that
     #: section leaves the CERT group namespace to each sending host, so no
-    #: registry stands behind it; it used to decode through the
-    #: Diffie-Hellman group registry and report a group of ``7`` as the curve
-    #: ``NIST_P_256``. See :issue:`2283`.
+    #: registry stands behind it. See :issue:`2283`.
     cert_group: 'int'
     #: Certificate count.
     cert_count: 'int'

pcapkit/protocols/internet/esp.py

@@ -1470,7 +1470,7 @@ def _make_opaque(self, spi: 'int', seq: 'int', total: 'int', payload_data: 'byte
 
         The payload is surfaced as :class:`~pcapkit.protocols.misc.raw.Raw`
         -- which is what a next header of :data:`None` resolves to -- so that
-        :attr:`self.payload <pcapkit.protocols.protocol.Protocol.payload>`
+        :attr:`self.payload <pcapkit.protocols.protocol.ProtocolBase.payload>`
         and the protocol chain behave as they do for any other protocol, and
         the trailer fields are left :data:`None` rather than guessed at.
 

pcapkit/protocols/internet/internet.py

@@ -431,7 +431,7 @@ def _decode_next_layer(self, dict_: '_PT', proto: 'Optional[int]' = None,  # pyl
             dict\_: info buffer
             proto: next layer protocol index
             length: valid (*non-padding*) length
-            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.Protocol.unpack>`)
+            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`)
             version: IP version
             ipv6_exthdr: protocol chain of IPv6 extension headers
             payload: payload from packet. If not provided, will extract from
@@ -480,7 +480,7 @@ def _import_next_layer(self, proto: 'int', length: 'Optional[int]' = None, *,  #
         Arguments:
             proto: next layer protocol index
             length: valid (*non-padding*) length
-            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.Protocol.unpack>`)
+            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`)
             version: IP protocol version
             extension: if is extension header
             payload: payload from packet. If not provided, will extract from

pcapkit/protocols/internet/ipv6.py

@@ -506,7 +506,7 @@ def _decode_next_layer(self, ipv6: 'Data_IPv6', proto: 'Optional[int]' = None,
             ipv6: info buffer
             proto: next layer protocol index
             length: valid (*not padding*) length
-            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.Protocol.unpack>`)
+            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`)
 
         Returns:
             Current protocol with next layer extracted.
@@ -685,7 +685,7 @@ def _import_next_layer(self, proto: 'int', length: 'Optional[int]' = None, *,  #
         Arguments:
             proto: next layer protocol index
             length: valid (*non-padding*) length
-            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.Protocol.unpack>`)
+            packet: packet info (passed from :meth:`self.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`)
             version: IP protocol version
             extension: if is extension header
             payload: payload from packet. If not provided, will extract from

pcapkit/protocols/internet/ipv6_ext.py

@@ -108,7 +108,7 @@ class for that code instead (see the bottom of the module), so dispatch
    ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
    have dedicated classes. When one of *those* raises,
    :func:`~pcapkit.corekit.decorators.beholder`
-   (:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
+   (:meth:`ProtocolBase._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
    would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
    ``next`` and crashes the walk as in path 1.
    :meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>`
@@ -299,7 +299,7 @@ def protocol(self) -> 'Optional[Enum_ExtensionHeader] | Optional[str]':
 
         In the *fallback* role (this instance parsed this module's own schema)
         this is **not** the base
-        :attr:`Protocol.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`
+        :attr:`ProtocolBase.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`
         meaning ("name of next layer protocol"). On the owner's ruling for
         GitHub issue :issue:`891` it is deliberately repointed at this
         instance's *own* identity, i.e. which header's format it parsed, such as

pcapkit/protocols/internet/mh.py

@@ -575,11 +575,10 @@ class FastBindingAcknowledgmentStatus(EnumLookup, IntEnum):
         :class:`~pcapkit.corekit.enum.EnumLookup`, like every other
         :class:`int`-valued registry here, so a key that is neither an
         :class:`int` nor a :class:`str` raises
-        :exc:`~pcapkit.utilities.exceptions.EnumValueError`. A ``get`` override
-        was rejected (decided on :issue:`935`; the override was deleted, not
-        widened to accept ``default``): this class mints no alias
-        (``__members__`` and ``list(cls)`` hold the same members), so an override
-        could only repeat the base's dual :class:`int`/name resolution.
+        :exc:`~pcapkit.utilities.exceptions.EnumValueError`. This class mints
+        no alias (``__members__`` and ``list(cls)`` hold the same members), so
+        an override could only repeat the base's dual :class:`int`/name
+        resolution (see :issue:`935`).
 
     """
 
@@ -646,11 +645,10 @@ class IPv6AddressPrefixCode(EnumLookup, IntEnum):
         :class:`~pcapkit.corekit.enum.EnumLookup`, like every other
         :class:`int`-valued registry here, so a key that is neither an
         :class:`int` nor a :class:`str` raises
-        :exc:`~pcapkit.utilities.exceptions.EnumValueError`. A ``get`` override
-        was rejected (decided on :issue:`935`; the override was deleted, not
-        widened to accept ``default``): this class mints no alias
-        (``__members__`` and ``list(cls)`` hold the same members), so an override
-        could only repeat the base's dual :class:`int`/name resolution.
+        :exc:`~pcapkit.utilities.exceptions.EnumValueError`. This class mints
+        no alias (``__members__`` and ``list(cls)`` hold the same members), so
+        an override could only repeat the base's dual :class:`int`/name
+        resolution (see :issue:`935`).
 
     """
 

pcapkit/protocols/link/arp.py

@@ -420,7 +420,7 @@ def _make_addr_resolve(self, addr: 'str | bytes | bytearray', htype: 'int') -> '
         Notes:
             The messages are prefixed with :attr:`self.__class__.__name__
             <type.__name__>` rather than :attr:`self.alias
-            <pcapkit.protocols.protocol.Protocol.alias>`, for the reason
+            <pcapkit.protocols.protocol.ProtocolBase.alias>`, for the reason
             :meth:`_make_proto_resolve` gives.
 
         """
@@ -480,7 +480,7 @@ def _make_proto_resolve(self, addr: 'IPv4Address | IPv6Address | str | bytes', p
 
             The messages are prefixed with :attr:`self.__class__.__name__
             <type.__name__>` rather than :attr:`self.alias
-            <pcapkit.protocols.protocol.Protocol.alias>`, even though the
+            <pcapkit.protocols.protocol.ProtocolBase.alias>`, even though the
             latter is this project's usual choice: :attr:`alias` here reads
             ``self._acnm``, which :meth:`read` only assigns once the operation
             code is known, and this method runs from :meth:`make` -- before

pcapkit/protocols/link/c_tag.py

@@ -71,7 +71,7 @@ def alias(self) -> 'Literal["802.1Q"]':
     #: class-name default -- a rename must not silently move the output key.
     @property
     def info_name(self) -> 'Literal["c_tag"]':
-        """Key name of the :attr:`~pcapkit.protocols.protocol.Protocol.info` dict."""
+        """Key name of the :attr:`~pcapkit.protocols.protocol.ProtocolBase.info` dict."""
         return 'c_tag'
 
     ##########################################################################