docs(corekit): fourth whole-repo pass over corekit, const and vendor (#1103)

docs/source/pcapkit/corekit/context.rst

@@ -18,7 +18,7 @@ and known only to the caller.
 Rather than adding protocol-specific keyword arguments to
 :class:`~pcapkit.foundation.extraction.Extractor`, such information is passed
 as a :class:`~pcapkit.corekit.context.ContextRegistry` -- a mapping of protocol
-index ID (c.f. :meth:`Protocol.id <pcapkit.protocols.protocol.Protocol.id>`) to
+index ID (cf. :meth:`Protocol.id <pcapkit.protocols.protocol.Protocol.id>`) to
 a :class:`~pcapkit.corekit.context.ProtocolContext` instance. It is handed to
 :class:`~pcapkit.foundation.extraction.Extractor` once and propagated down the
 protocol stack by

docs/source/pcapkit/corekit/version.rst

@@ -5,7 +5,7 @@ Version Info
 
 :mod:`pcapkit.corekit.version` contains the :obj:`tuple`-like class
 :class:`~pcapkit.corekit.version.VersionInfo`, modelled on
-:class:`sys.version_info`.
+:data:`sys.version_info`.
 
 .. autoclass:: pcapkit.corekit.version.VersionInfo
    :no-members:

pcapkit/const/reg/apptype/apptype.py

@@ -2846,10 +2846,12 @@ def register_alias(cls, port: 'int', name: 'str') -> 'AppType':  # pylint: disab
 
         GitHub issue :issue:`807`'s third ask, deliberately scoped to **this**
         per-transport registry: ``TCP.register_alias(...)`` never touches
-        :class:`UDP`'s members, which is what keeps an alias registered on one
-        transport from leaking onto a transport IANA never assigned it -- e.g.
-        registering ``www`` as an alias of ``http`` on :class:`TCP` and
-        :class:`UDP` leaves it absent from :class:`SCTP`'s port 80, exactly as
+        :class:`~pcapkit.const.reg.apptype.udp.UDP`'s members, which is what
+        keeps an alias registered on one transport from leaking onto a
+        transport IANA never assigned it -- e.g. registering ``www`` as an alias
+        of ``http`` on :class:`~pcapkit.const.reg.apptype.tcp.TCP` and
+        :class:`~pcapkit.const.reg.apptype.udp.UDP` leaves it absent from
+        :class:`~pcapkit.const.reg.apptype.sctp.SCTP`'s port 80, exactly as
         IANA itself never registered it there.
 
         No new storage: the new member simply joins :data:`__registry__` at

pcapkit/const/reg/apptype/dccp.py

@@ -50,7 +50,7 @@ class DCCP(AppType):
     __registry__: 'MultiDict[int, DCCP]' = MultiDict()
 
     #: The canonical service for each port IANA assigns more than one to, i.e.
-    #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with.
+    #: what ``AppType.get()`` answers with.
     #: Taken from :file:`/etc/services`, which is what
     #: :func:`socket.getservbyport` reads -- IANA names no precedence among the
     #: services it registers on one port, and registry row order does not supply

pcapkit/const/reg/apptype/sctp.py

@@ -54,7 +54,7 @@ class SCTP(AppType):
     __registry__: 'MultiDict[int, SCTP]' = MultiDict()
 
     #: The canonical service for each port IANA assigns more than one to, i.e.
-    #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with.
+    #: what ``AppType.get()`` answers with.
     #: Taken from :file:`/etc/services`, which is what
     #: :func:`socket.getservbyport` reads -- IANA names no precedence among the
     #: services it registers on one port, and registry row order does not supply

pcapkit/const/reg/apptype/tcp.py

@@ -906,7 +906,7 @@ class TCP(AppType):
     __registry__: 'MultiDict[int, TCP]' = MultiDict()
 
     #: The canonical service for each port IANA assigns more than one to, i.e.
-    #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with.
+    #: what ``AppType.get()`` answers with.
     #: Taken from :file:`/etc/services`, which is what
     #: :func:`socket.getservbyport` reads -- IANA names no precedence among the
     #: services it registers on one port, and registry row order does not supply

pcapkit/const/reg/apptype/udp.py

@@ -373,7 +373,7 @@ class UDP(AppType):
     __registry__: 'MultiDict[int, UDP]' = MultiDict()
 
     #: The canonical service for each port IANA assigns more than one to, i.e.
-    #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with.
+    #: what ``AppType.get()`` answers with.
     #: Taken from :file:`/etc/services`, which is what
     #: :func:`socket.getservbyport` reads -- IANA names no precedence among the
     #: services it registers on one port, and registry row order does not supply

pcapkit/corekit/context.py

@@ -20,7 +20,7 @@
 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
-(c.f. :meth:`Protocol.id <pcapkit.protocols.protocol.Protocol.id>`)
+(cf. :meth:`Protocol.id <pcapkit.protocols.protocol.Protocol.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

pcapkit/corekit/decorators.py

@@ -180,7 +180,7 @@ def behold(*args: 'P.args', **kwargs: 'P.kwargs') -> 'R_beholder':
             # NOTE: ``alias=proto`` matches what ``_import_next_layer`` passes, so
             # a payload that failed to parse still reports the code it arrived
             # with, which is what ``Data_Raw.protocol`` means. A plain integer has
-            # no ``name`` and still renders as ``Raw`` in the protochain, c.f.
+            # no ``name`` and still renders as ``Raw`` in the protochain, cf.
             # ``Raw.__post_init__``, so this only adds a name where the registry
             # key is an enumeration.
             #
@@ -289,7 +289,7 @@ def unpack(*args: 'P.args', **kwargs: 'P.kwargs') -> 'R_prepare':
         if length == 0 and not declared_length:
             # Quiet: this is the frame reader's ordinary "no more packets"
             # signal, caught as such by
-            # ``pcapkit.foundation.extraction.Extractor`` and friends -- c.f.
+            # ``pcapkit.foundation.extraction.Extractor`` and friends -- cf.
             # ``pcapkit.protocols.protocol.ProtocolBase._read_unpack``'s
             # ``StructError(..., quiet=True, eof=True)`` for the same pattern.
             raise StreamEOFError('prepare: end of stream', quiet=True)

pcapkit/corekit/enum.py

@@ -372,10 +372,10 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'Self':
           -- the interpreter's own, unless an earlier loud error installed
           :mod:`pcapkit`'s. The name miss is
           :exc:`~pcapkit.utilities.exceptions.EnumKeyError` with
-          ``quiet=True``, because it is in-library control flow -- at
-          :meth:`~pcapkit.const.http.method.Method.get` it is part of a
-          *successful* call, since that override catches it in order to build
-          an unregistered member. The value miss is quiet through the block
+          ``quiet=True``, because it is in-library control flow -- in the
+          ``get`` override of :class:`~pcapkit.const.http.method.Method` it is
+          part of a *successful* call, since that override catches it in order
+          to build an unregistered member. The value miss is quiet through the block
           described above, as ruled on :issue:`1845` on the ground that this
           method is mostly called from protocol parsing: a value it cannot
           resolve is input for the caller to handle, not a fault to report. A

pcapkit/corekit/fields/__init__.py

@@ -5,7 +5,7 @@
 
 .. module:: pcapkit.corekit.fields
 
-:mod:`pcapkit.corekit.fields` is collection of protocol fields,
+:mod:`pcapkit.corekit.fields` is a collection of protocol fields,
 descriptive of the structure of protocol headers.
 
 """

pcapkit/corekit/fields/collections.py

@@ -208,7 +208,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'byte
         # of :exc:`~pcapkit.utilities.exceptions.ProtocolError` from
         # :meth:`TCP._read_mode_sack
         # <pcapkit.protocols.transport.tcp.TCP._read_mode_sack>`, depending on
-        # unrelated things that ran earlier in the same process. C.f. #525.
+        # unrelated things that ran earlier in the same process. Cf. #525.
         # Importing at module level, once, for the life of this module object,
         # closes that off: ``SchemaField`` then stays whatever class this
         # module resolved at its own import time, regardless of what happens to
@@ -224,7 +224,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'byte
         # ``SACK`` option declaring more octets than the option area holds leaves
         # ``sack``'s ``ListField`` reading ``SACKBlock`` off an exhausted stream.
         # Remembering where the previous item ended is what bounds the iteration
-        # count, since it does not depend on what the schema reports. C.f. #431,
+        # count, since it does not depend on what the schema reports. Cf. #431,
         # which is the same defect in the ``OptionField`` subclass.
         #
         # ``start`` is where the field itself begins. The comparison needs stream
@@ -306,7 +306,7 @@ class OptionField(ListField, Generic[_TS]):
            does not depend on packet data the shortcut has not read.
 
         All of that is true of every ``OptionField`` declared in this package. A
-        base schema registered from outside it -- c.f.
+        base schema registered from outside it -- cf.
         :mod:`pcapkit.foundation.registry` -- need not satisfy it, and is **not**
         rejected: such a base schema is unpacked in full. It parses correctly and
         pays the cost of the second parse. Only the shortcut is withheld, so a base schema whose type field
@@ -434,7 +434,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list
         # over-reads leaves ``length`` above zero with ``file`` already exhausted,
         # every field of the next option reads ``b''``, and an option that read
         # nothing reports ``len(data) == 0`` and leaves ``length`` untouched --
-        # which spins forever, with no exception and no diagnostic. C.f. #431.
+        # which spins forever, with no exception and no diagnostic. Cf. #431.
         #
         # Remembering where the previous option ended gives the loop a measure of
         # progress that does not depend on what a schema reports, and one octet of
@@ -481,7 +481,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list
         # octets with zeros, so the option would rebuild octets that were never
         # there: a HIP ``ACK`` declaring 256 octets with 4 present, or an MH
         # ``PadN`` declaring 3 with none. Nothing downstream can tell, because
-        # the schema records the zeros as values. C.f. #1325.
+        # the schema records the zeros as values. Cf. #1325.
         #
         # So the stream is read through a proxy that notes any short read, and
         # an option that began with at least one octet present and then read

pcapkit/corekit/fields/field.py

@@ -430,7 +430,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> '_T':
         # cannot recover data that was never in the buffer, only zero-fill for
         # it, and no field this large is legitimate to begin with. Honouring it
         # would allocate and zero-fill up to ``length`` octets on nothing but
-        # the packet's own say-so. C.f. #554.
+        # the packet's own say-so. Cf. #554.
         ceiling = config.MAX_ZERO_PAD_LENGTH
         if ceiling != -1 and length > ceiling and len(buffer) < length:
             raise FieldValueError(
@@ -442,7 +442,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> '_T':
         # declared length just under :data:`~pcapkit.utilities.config.MAX_ZERO_PAD_LENGTH` passes it every
         # time it is declared, so 200 of them amplify 4,800 wire octets into
         # 50.0 MiB of retained zeros with the ceiling doing exactly what it was
-        # written to do. C.f. #573.
+        # written to do. Cf. #573.
         #
         # ``max(length, 0)`` is defensive rather than a case anything is known to
         # reach. :attr:`length` here resolves through :func:`struct.calcsize`, so

pcapkit/corekit/fields/ipaddress.py

@@ -103,7 +103,7 @@ def _reject_bool(value: 'object', description: str) -> 'None':
         :class:`~ipaddress.IPv4Address`'s version mismatches -- and that
         asymmetry is exactly what let this slip past :issue:`469`'s otherwise
         equivalent guard for :meth:`MH._make_opt_mn_id
-        <pcapkit.protocols.internet.mh.MH._make_opt_mn_id>` (c.f.
+        <pcapkit.protocols.internet.mh.MH._make_opt_mn_id>` (cf.
         :issue:`491`).
 
         Every caller checks this *before* dispatching on the value's type,
@@ -114,7 +114,7 @@ def _reject_bool(value: 'object', description: str) -> 'None':
         ``_make_*`` that must know the address family before it can build the
         schema converts the argument itself and so never hands this module a
         :obj:`bool` at all. :func:`parse_ip_address` is where those callers
-        reach this guard (c.f. :issue:`508`).
+        reach this guard (cf. :issue:`508`).
 
     """
     if isinstance(value, bool):
@@ -145,7 +145,7 @@ def parse_ip_address(value: 'IPv4Address | IPv6Address | bytes | int | str',
         The converted address.
 
     Raises:
-        FieldValueError: If ``value`` is a :obj:`bool` (c.f.
+        FieldValueError: If ``value`` is a :obj:`bool` (cf.
             :func:`_reject_bool`), is not a valid IP address, or is not of
             ``version``.
 
@@ -260,7 +260,7 @@ def pre_process(self, value: '_AT | bytes | int | str', packet: 'dict[str, Any]'
             Processed field value.
 
         Raises:
-            FieldValueError: If ``value`` is a :obj:`bool` (c.f.
+            FieldValueError: If ``value`` is a :obj:`bool` (cf.
                 :func:`_reject_bool`), is not a valid IP address, or is the
                 wrong IP version for this field.
 
@@ -373,7 +373,7 @@ class _RawMaskIPv4Interface(ipaddress.IPv4Interface):
     in :attr:`netmask`, so :meth:`IPv4InterfaceField.pre_process` writes them
     back unchanged.
 
-    :func:`str`, :func:`repr` and :mod:`pickle` use the ``address/mask``
+    :class:`str`, :func:`repr` and :mod:`pickle` use the ``address/mask``
     form, which :meth:`IPv4InterfaceField.pre_process` packs back to the same
     octets. The mask is dotted, except when it is hostmask-shaped (ones, then
     zeros, read from the low bit): :func:`ipaddress.ip_interface` would read
@@ -389,7 +389,7 @@ class _RawMaskIPv4Interface(ipaddress.IPv4Interface):
     and the prefix length all describe the address alone (``/32``); only
     :attr:`netmask`, :attr:`hostmask`, :attr:`with_netmask` and
     :attr:`with_hostmask` carry the mask. :attr:`with_netmask` is always
-    dotted, so it is not the round-trip form; :func:`str` is.
+    dotted, so it is not the round-trip form; :class:`str` is.
 
     """
 
@@ -467,7 +467,7 @@ def _is_hostmask(mask: 'IPv4Address') -> 'bool':
     return not value & (value + 1)
 
 
-#: Hex spelling of a literal mask, as :func:`str` writes a hostmask-shaped one.
+#: Hex spelling of a literal mask, as :class:`str` writes a hostmask-shaped one.
 _HEX_MASK = re.compile(r'0[xX][0-9a-fA-F]{8}')
 
 
@@ -584,7 +584,7 @@ def pre_process(self, value: 'IPv4Interface | bytes | int | str', packet: 'dict[
             Processed field value.
 
         Raises:
-            FieldValueError: If ``value`` is a :obj:`bool` (c.f.
+            FieldValueError: If ``value`` is a :obj:`bool` (cf.
                 :func:`_reject_bool`), is not a valid IP interface, or is the
                 wrong IP version for this field.
 
@@ -595,7 +595,7 @@ def pre_process(self, value: 'IPv4Interface | bytes | int | str', packet: 'dict[
             taken literally: a dotted mask that is neither a netmask nor a
             hostmask, such as ``'10.0.0.1/255.0.255.0'``, or eight hex
             digits, such as ``'10.0.0.1/0x000000ff'``. Those are the forms
-            :func:`str` gives a :class:`_RawMaskIPv4Interface`.
+            :class:`str` gives a :class:`_RawMaskIPv4Interface`.
 
         """
         _reject_bool(value, 'invalid IP interface')
@@ -689,7 +689,7 @@ def pre_process(self, value: 'IPv6Interface | bytes | int | str', packet: 'dict[
             Processed field value.
 
         Raises:
-            FieldValueError: If ``value`` is a :obj:`bool` (c.f.
+            FieldValueError: If ``value`` is a :obj:`bool` (cf.
                 :func:`_reject_bool`), is not a valid IP interface, or is the
                 wrong IP version for this field.
 

pcapkit/corekit/fields/numbers.py

@@ -355,7 +355,7 @@ def pre_process(self, value: 'int', packet: 'dict[str, Any]') -> 'int | bytes':
             integer code for. The flag is therefore consulted **after** the
             rebuild rather than before it, since deciding first and rebuilding
             second would let the template and the value being returned
-            disagree. C.f. :issue:`591`.
+            disagree. Cf. :issue:`591`.
 
             That width is a **ceiling** of the bit length over eight, and it is
             written as one. ``math.ceil(value.bit_length() // 8)`` is not a
@@ -850,9 +850,8 @@ def _unregistered_member(namespace: 'Type[StdlibEnum] | Type[AenumEnum]',
             still raises. Nothing on the
             parse or reconstruction path does that to a value it just resolved
             this way, which is what keeps this safe to return from
-            ``post_process``. A direct call to
-            :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` for the same port
-            does not come through here, and it does not mint either: it
+            ``post_process``. A direct call to ``AppType.get()`` for the same
+            port does not come through here, and it does not mint either: it
             builds an unregistered member of its own, through the registry's
             ``_unregistered_member`` -- measured on this tree,
             ``AppType.get(54321, proto=tcp)`` returns
@@ -1090,8 +1089,7 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'AppTy
             the port itself, when the registry declares none.
 
         Notes:
-            This peeks at what
-            :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` itself would
+            This peeks at what ``AppType.get()`` itself would
             consult -- the per-port rows via ``__registry__.getlist``, then the
             documented IANA spans via
             :meth:`~pcapkit.const.reg.apptype.apptype.AppType._missing_` -- and
@@ -1121,8 +1119,8 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'AppTy
             :meth:`~pcapkit.const.reg.apptype.apptype.AppType._missing_`, which
             raises a bare :exc:`ValueError` for it. That call sits inside an
             ``except ValueError`` that absorbs a foreign miss, and
-            :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` rejects the
-            out-of-range case deliberately, so that it is never minted over -- a
+            ``AppType.get()`` rejects the out-of-range case deliberately, so
+            that it is never minted over -- a
             catch keyed on exception type alone cannot see the difference
             between that and a "no member has this value", so it would quietly
             turn the rejection into a miss. Within the width, ``_missing_``

pcapkit/corekit/infoclass.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.corekit.infoclass` contains :obj:`dict` like class
 :class:`~pcapkit.corekit.infoclass.Info`, which is originally
-designed to work alike :func:`dataclasses.dataclass` as introduced
+designed to work like :func:`dataclasses.dataclass` as introduced
 in :pep:`557`, and the immutable multi-mapping classes
 :class:`~pcapkit.corekit.infoclass.MultiInfo` and
 :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` that a finalised