From 73213d1de9b797ff2d39b1d258260fd5664ef42e Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 25 Oct 2026 17:45:01 -0400 Subject: [PATCH] docs(protocols): sixth whole-repo pass over linktrans (#1103) Correct the ARP bool-guard notes: without the guard a bool reaches the generic ProtocolError, not a TypeError (#2166). State the L2TPv2 total_length note timelessly; drop the count of concrete VLAN tags and fix a verb agreement. --- docs/source/pcapkit/protocols/link/vlan.rst | 2 +- pcapkit/protocols/link/arp.py | 11 ++++++----- pcapkit/protocols/link/l2tpv2.py | 4 ++-- pcapkit/protocols/link/vlan.py | 4 ++-- 4 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/source/pcapkit/protocols/link/vlan.rst b/docs/source/pcapkit/protocols/link/vlan.rst index afc43a4ebc..74ef356735 100644 --- a/docs/source/pcapkit/protocols/link/vlan.rst +++ b/docs/source/pcapkit/protocols/link/vlan.rst @@ -5,7 +5,7 @@ VLAN - 802.1Q/802.1ad VLAN Tag Types :mod:`pcapkit.protocols.link.vlan` contains :class:`~pcapkit.protocols.link.vlan.VLAN` only, an abstract base class holding -the tag layout shared by every VLAN tag [*]_. The two concrete tags live in +the tag layout shared by every VLAN tag [*]_. The concrete tags live in modules of their own: .. list-table:: diff --git a/pcapkit/protocols/link/arp.py b/pcapkit/protocols/link/arp.py index b291ec3250..9864af3396 100644 --- a/pcapkit/protocols/link/arp.py +++ b/pcapkit/protocols/link/arp.py @@ -418,9 +418,10 @@ def _make_addr_resolve(self, addr: 'str | bytes', htype: 'int') -> 'bytes': """ # NOTE: checked before the ``htype`` dispatch, for the same reason as - # in ``_make_proto_resolve``: without it a ``bool`` reaches the MAC - # pattern or falls through unchanged, and fails later as a - # ``TypeError`` (#2166). + # in ``_make_proto_resolve``: without it a ``bool`` gets the generic + # ``ProtocolError`` the branches below raise for any non-address, + # rather than the ``FieldValueError`` ``_make_proto_resolve`` raises + # for one (#2166). if isinstance(addr, bool): raise FieldValueError( f'{self.__class__.__name__}: invalid hardware address: must not be a bool, ' @@ -492,8 +493,8 @@ def _make_proto_resolve(self, addr: 'IPv4Address | IPv6Address | str | bytes', p # NOTE: checked before the ``ptype`` dispatch, for the placement reason # ``_reject_bool`` in ``pcapkit.corekit.fields.ipaddress`` gives: the # non-IP branches below never reach ``parse_ip_address``, so without it - # a ``bool`` falls through them unchanged and fails later as a - # ``TypeError`` from ``len()`` (#2166). + # a ``bool`` gets their generic ``ProtocolError`` rather than the + # ``FieldValueError`` the IP branches raise for it (#2166). if isinstance(addr, bool): raise FieldValueError( f'{self.__class__.__name__}: invalid protocol address: must not be a bool, ' diff --git a/pcapkit/protocols/link/l2tpv2.py b/pcapkit/protocols/link/l2tpv2.py index 307e9519c8..298ec94776 100644 --- a/pcapkit/protocols/link/l2tpv2.py +++ b/pcapkit/protocols/link/l2tpv2.py @@ -429,8 +429,8 @@ def _make_data(cls, data: 'Data_L2TP') -> 'dict[str, Any]': # type: ignore[over 'version': data.version, # NOTE: Passed as ``total_length`` since ``length`` is the parse # length :class:`~pcapkit.protocols.protocol.ProtocolBase` takes, so - # under that key it never reached :meth:`make`, and the rebuild - # dropped both the Length field and the ``L`` flag (#1172). + # under that key it would never reach :meth:`make`, and the rebuild + # would drop both the Length field and the ``L`` flag (#1172). 'total_length': data.length, # NOTE: Passed so that a control message captured without ``L`` # rebuilds as captured, rather than gaining the Length field diff --git a/pcapkit/protocols/link/vlan.py b/pcapkit/protocols/link/vlan.py index eaa1648813..1787cffc54 100644 --- a/pcapkit/protocols/link/vlan.py +++ b/pcapkit/protocols/link/vlan.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.link.vlan` contains :class:`~pcapkit.protocols.link.vlan.VLAN` only, an abstract base class holding -the tag layout shared by every VLAN tag [*]_. The two concrete tags live in +the tag layout shared by every VLAN tag [*]_. The concrete tags live in modules of their own, since they are reached through different registry indices -- :class:`~pcapkit.protocols.link.c_tag.C_Tag` for the 802.1Q customer tag (``0x8100``) and :class:`~pcapkit.protocols.link.s_tag.S_Tag` for the 802.1ad @@ -39,7 +39,7 @@ would nest one ``c_tag`` inside another, leaving nothing in the output to say which of the two was the service tag. -Two distinct EtherTypes also means two distinct +Two distinct EtherTypes also mean two distinct :meth:`~pcapkit.protocols.protocol.Protocol.__index__` values, which is the project's rule for when protocols get separate modules: siblings that *share* an index may share a module, as :class:`~pcapkit.protocols.link.arp.InARP` shares