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

docs/source/pcapkit/const/ipv6.rst

@@ -10,7 +10,7 @@ enumerations include:
 
 .. list-table::
 
-   * - :class:`IPv6_Extension_Header <pcapkit.const.ipv6.extension_header.ExtensionHeader>`
+   * - :class:`IPv6_ExtensionHeader <pcapkit.const.ipv6.extension_header.ExtensionHeader>`
      - IPv6 Extension Header Types [*]_
    * - :class:`IPv6_Option <pcapkit.const.ipv6.option.Option>`
      - Destination Options and Hop-by-Hop Options [*]_

docs/source/pcapkit/const/reg.rst

@@ -15,7 +15,7 @@ implementations. Available enumerations include:
      - Ethertype IEEE 802 Numbers [*]_
    * - :class:`TRANSTYPE <pcapkit.const.reg.transtype.TransType>`
      - Transport Layer Protocol Numbers [*]_
-   * - :class:`APPTYPE <pcapkit.const.reg.apptype.AppType>`
+   * - :class:`APPTYPE <pcapkit.const.reg.apptype.apptype.AppType>`
      - Application Layer Protocol Numbers (Service Name and Transport Protocol Port Number Registry) [*]_
 
 Link-Layer Header Type Values

docs/source/pcapkit/corekit/fields/field.rst

@@ -3,6 +3,11 @@ Base Fields
 
 .. module:: pcapkit.corekit.fields.field
 
+.. versionremoved:: 1.3.0
+
+   ``pcapkit.corekit.fields.field._Field``, renamed
+   :class:`~pcapkit.corekit.fields.field.FieldBase` with no alias left behind.
+
 .. versionremoved:: 1.5.0
 
    ``pcapkit.corekit.fields.field.NoValueType``, now

docs/source/pcapkit/vendor/default.rst

@@ -3,8 +3,8 @@ Base Crawler
 
 .. module:: pcapkit.vendor.default
 
-:mod:`pcapkit.vendor.default` contains :class:`~pcapkit.vendor.default.Vendor`
-only, which is the base meta class for all vendor crawlers.
+:mod:`pcapkit.vendor.default` exports :class:`~pcapkit.vendor.default.Vendor`
+only, which is the base class for all vendor crawlers.
 
 .. autoclass:: pcapkit.vendor.default.Vendor
    :no-members:

docs/source/pcapkit/vendor/http.rst

@@ -19,7 +19,7 @@ vendor crawlers include:
      - HTTP/1.\* Method [*]_
    * - :class:`HTTP_Setting <pcapkit.vendor.http.setting.Setting>`
      - HTTP/2 Settings [*]_
-   * - :class:`HTTP_Status <pcapkit.vendor.http.status_code.StatusCode>`
+   * - :class:`HTTP_StatusCode <pcapkit.vendor.http.status_code.StatusCode>`
      - HTTP/1.\* Status Code [*]_
 
 HTTP/2 Error Code

docs/source/pcapkit/vendor/ipv6.rst

@@ -10,7 +10,7 @@ vendor crawlers include:
 
 .. list-table::
 
-   * - :class:`IPv6_Extension_Header <pcapkit.vendor.ipv6.extension_header.ExtensionHeader>`
+   * - :class:`IPv6_ExtensionHeader <pcapkit.vendor.ipv6.extension_header.ExtensionHeader>`
      - IPv6 Extension Header Types [*]_
    * - :class:`IPv6_Option <pcapkit.vendor.ipv6.option.Option>`
      - Destination Options and Hop-by-Hop Options [*]_

docs/source/pcapkit/vendor/ipx.rst

@@ -23,8 +23,14 @@ IPX Packet Types
 This module contains the vendor crawler for **IPX Packet Types**,
 which is automatically generating :class:`pcapkit.const.ipx.packet.Packet`.
 
+.. note::
+
+   This crawler does not crawl. Its table is gone from the Wikipedia article,
+   so the data is maintained by hand in the ``DATA`` mapping of
+   :mod:`pcapkit.vendor.ipx.packet`, and the class defines no ``LINK``.
+
 .. autoclass:: pcapkit.vendor.ipx.packet.Packet
-   :members: FLAG, LINK
+   :members: FLAG
    :show-inheritance:
 
 Socket Types

docs/source/pcapkit/vendor/reg.rst

@@ -15,7 +15,7 @@ implementations. Available vendor crawlers include:
      - Ethertype IEEE 802 Numbers [*]_
    * - :class:`TRANSTYPE <pcapkit.vendor.reg.transtype.TransType>`
      - Transport Layer Protocol Numbers [*]_
-   * - :class:`APPTYPE <pcapkit.vendor.reg.apptype.AppType>`
+   * - :class:`APPTYPE <pcapkit.vendor.reg.apptype.apptype.AppType>`
      - Application Layer Protocol Numbers (Service Name and Transport Protocol Port Number Registry) [*]_
 
 Link-Layer Header Type Values

pcapkit/const/ipv6/__init__.py

@@ -11,7 +11,7 @@
 
 .. list-table::
 
-   * - :class:`IPv6_Extension_Header <pcapkit.const.ipv6.extension_header.ExtensionHeader>`
+   * - :class:`IPv6_ExtensionHeader <pcapkit.const.ipv6.extension_header.ExtensionHeader>`
      - IPv6 Extension Header Types [*]_
    * - :class:`IPv6_Option <pcapkit.const.ipv6.option.Option>`
      - Destination Options and Hop-by-Hop Options [*]_

pcapkit/const/mh/__init__.py

@@ -89,7 +89,7 @@
      - Link-Layer Address (LLA) Option Code [*]_
    * - :class:`MH_CGAType <pcapkit.const.mh.cga_type.CGAType>`
      - CGA Extension Type Tags [*]_
-   * - :class:`MH_CGAExtension <pcapkit.const.mh.cga_type.CGAExtension>`
+   * - :class:`MH_CGAExtension <pcapkit.const.mh.cga_extension.CGAExtension>`
      - CGA Extension Type Values [*]_
    * - :class:`MH_CGASec <pcapkit.const.mh.cga_sec.CGASec>`
      - CGA SEC [*]_

pcapkit/const/pcapng/option_type.py

@@ -24,7 +24,14 @@
 
 
 class OptionType(EnumRegistry, StrEnum):
-    """[OptionType] Option Types"""
+    """[OptionType] Option Types
+
+    .. versionchanged:: 1.1.0
+
+       A member converts with :class:`int` to its option code, and compares,
+       orders and hashes as that code.
+
+    """
 
     if TYPE_CHECKING:
         #: Short name of the option type.

pcapkit/const/reg/apptype/apptype.py

@@ -73,9 +73,9 @@ class TransportProtocol(EnumLookup, IntEnum):
     # any other one that happens to equal it. Treating every int as a whole is
     # exactly what that ruling above asks for, and it is also why this
     # renumbering changes what specific ints mean, not only what composed ones
-    # do: ``tcp | udp`` (``3``) used to name no registry and now resolves as
+    # do: ``tcp | udp`` (``3``) used to name no registry and resolves as
     # ``sctp``'s own value, and a bare, uncomposed ``4`` -- previously
-    # ``sctp``'s value -- now resolves as ``dccp``'s, silently, with no
+    # ``sctp``'s value -- resolves as ``dccp``'s, silently, with no
     # exception, since a real member sits at ``4`` either way. A caller holding
     # an integer under the old spacing (composed or not) can therefore land on a
     # different real transport's registry after this change, not merely be
@@ -109,7 +109,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         here is already lower-case, so a lowered ``key`` still hits the base's
         exact ``_member_map_`` lookup.
 
-        Case folding is now the *only* thing this override adds. It used to
+        Case folding is the *only* thing this override adds. It used to
         convert the base's name-miss exception as well -- this class raised
         :exc:`ValueError` where the base raised :exc:`KeyError` -- and the
         ruling given in review of the work for :issue:`877`, implemented in GitHub issue
@@ -125,7 +125,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         four transport registries, and they land there only because their own
         ``get()`` takes an :class:`int` port and never accepts a name at all,
         rather than from any name-miss policy. So there was no policy here to
-        preserve, and a name miss now reaches the caller as
+        preserve, and a name miss reaches the caller as
         :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The
         maintainer's ruling given in review of the work for :issue:`808`, that
         :class:`TransportProtocol` is not to be extended at all, is untouched by
@@ -179,8 +179,8 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         # TransportProtocol is not to be extended at all. A name that is not a
         # declared member used to mint a brand-new one here, at ``max_val + 1``
         # (before that, ``max_val * 2``) -- an unbounded, ever-growing set of
-        # transport protocols nothing ever asked for. There is nothing left to walk
-        # now: it is simply refused, exactly like any other unrecognised name --
+        # transport protocols nothing ever asked for. There is nothing left to walk:
+        # it is simply refused, exactly like any other unrecognised name --
         # including one spelling a composite, e.g. ``'tcp|udp'``. ``'|'`` used to be
         # intercepted here on its own, so a composite in disguise never got minted
         # into a member whose own name lied about being a single transport; a
@@ -233,6 +233,11 @@ class AppType(EnumRegistry, StrEnum):
     makes it subclassable at all, since :mod:`aenum` refuses to extend an
     enumeration that already has members.
 
+    .. versionchanged:: 1.1.1
+
+       A member converts with :class:`int` to its port number, and compares,
+       orders and hashes as that port.
+
     .. versionchanged:: 1.5.0
 
        Split by transport protocol (:issue:`732`): :mod:`pcapkit.const.reg.apptype`
@@ -2583,7 +2588,7 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[
         # cast is for mypy alone: ``dict.get`` accepts any hashable key at run
         # time regardless of its declared key type, but mypy holds ``.get`` to
         # the dict's own ``TransportProtocol`` keys, and does not know ``proto``
-        # can genuinely be a bare :class:`int` here now that GitHub issue #808
+        # can genuinely be a bare :class:`int` here, since GitHub issue #808
         # dropped the ``IntFlag`` base -- see the annotation on ``proto`` above.
         subclass = cls.__registries__.get(cast('TransportProtocol', proto))
         if subclass is not None:
@@ -2600,10 +2605,10 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[
         # here whenever it matches no real member's value, e.g. a stray bit like
         # ``17``. A composite built by hand used to reach here just as reliably,
         # since no combination of the old power-of-two bits ever equalled a
-        # single real member's value; that is no longer true under this class's
-        # current sequential numbering --
+        # single real member's value; that is not true under this class's
+        # sequential numbering --
         # ``TransportProtocol.tcp | TransportProtocol.udp`` (``3``) is
-        # ``sctp``'s own value now, so it resolves at the dict lookup above
+        # ``sctp``'s own value, so it resolves at the dict lookup above
         # instead of reaching this point at all. A composite used to get its own
         # :exc:`~pcapkit.utilities.exceptions.ProtocolError`, decoded through
         # :func:`~pcapkit.utilities.compat.show_flag_values` and naming every

pcapkit/corekit/decorators.py

@@ -119,6 +119,10 @@ def beholder(
     See Also:
         :meth:`pcapkit.protocols.protocol.Protocol._decode_next_layer`
 
+    .. versionchanged:: 1.3.0
+
+       Logs the exception it absorbs, and prints its traceback in verbose mode.
+
     :param func: decorated function
     :meta decorator:
     """

pcapkit/corekit/enum.py

@@ -215,6 +215,13 @@ def _validate_value(cls, value: 'Any') -> 'None':
         * :meth:`EnumRegistry.register`, before minting -- the one point at which
           a caller can introduce a value no member carries yet.
 
+        Of the registries that override :meth:`EnumRegistry.register` to mint
+        through a path of their own,
+        :meth:`OptionType.register <pcapkit.const.pcapng.option_type.OptionType.register>`
+        calls it at the same point and
+        :meth:`AppType.register <pcapkit.const.reg.apptype.apptype.AppType.register>`
+        does not.
+
         :meth:`EnumRegistry.register_alias` does not call it, and does not need
         to: it refuses any ``value`` that is not already registered, so the value
         it aliases has necessarily passed validation already.

pcapkit/corekit/fields/field.py

@@ -6,6 +6,11 @@
 
 :mod:`pcapkit.corekit.fields.field` contains the base field classes.
 
+.. versionremoved:: 1.3.0
+
+   ``pcapkit.corekit.fields.field._Field``, renamed
+   :class:`~pcapkit.corekit.fields.field.FieldBase` with no alias left behind.
+
 .. versionremoved:: 1.5.0
 
    ``pcapkit.corekit.fields.field.NoValueType``, now
@@ -141,9 +146,8 @@ def _zero_pad_budget() -> 'Iterator[list[int]]':
 class FieldMeta(abc.ABCMeta, Generic[_T]):
     """Meta class to add dynamic support to :class:`FieldBase`.
 
-    This meta class is used to generate necessary attributes for the
-    :class:`FieldBase` class. It can be useful to reduce unnecessary
-    registry calls and simplify the customisation process.
+    It defines nothing of its own, so a field class is built exactly as by
+    :class:`abc.ABCMeta`.
 
     """
 

pcapkit/corekit/fields/ipaddress.py

@@ -132,9 +132,9 @@ def parse_ip_address(value: 'IPv4Address | IPv6Address | bytes | int | str',
         value: Address as the caller gave it -- an :mod:`ipaddress` object,
             which is returned unchanged, or anything :mod:`ipaddress` accepts.
         description: Human-readable description of what ``value`` is, used to
-            build the :exc:`FieldValueError` message. Callers in a protocol
-            should carry their usual context into it, e.g.
-            ``f'{self.alias}: [OptNo {type}] care-of address'``.
+            build the :exc:`~pcapkit.utilities.exceptions.FieldValueError`
+            message. Callers in a protocol should carry their usual context
+            into it, e.g. ``f'{self.alias}: [OptNo {type}] care-of address'``.
         version: IP version to demand, ``4`` or ``6``, or :obj:`None` to take
             whichever family ``value`` describes. Pass it where the wire format
             fixes the family, so that an :class:`int` is widened to the right
@@ -176,7 +176,7 @@ def parse_ip_address(value: 'IPv4Address | IPv6Address | bytes | int | str',
         dispatch on the value's type, for the placement reason :issue:`469`
         gives and :func:`_reject_bool` repeats.
 
-        This raises :exc:`FieldValueError` and not
+        This raises :exc:`~pcapkit.utilities.exceptions.FieldValueError` and not
         :exc:`~pcapkit.utilities.exceptions.ProtocolError`, which is deliberate
         even though two sibling guards for the same mistake --
         :meth:`MH._make_opt_mn_id