From e39264934a4940fa653608d703f8c24e948d97c3 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 25 Oct 2026 17:53:27 -0400 Subject: [PATCH] docs(protocols): sixth whole-repo pass over appmisc (#1103) Fix stale or false prose in the application, misc and protocol-base slice: the PCAP-NG section context wording after the section_context rename, the Raw error type, the register RegistryError class, and the make() kwargs claim; restate change-relative and timed comments as timeless behaviour. Prose only; AST guard clean. --- pcapkit/protocols/application/http.py | 14 +++++++------- pcapkit/protocols/data/application/httpv2.py | 4 ++-- pcapkit/protocols/data/misc/pcapng.py | 4 ++-- pcapkit/protocols/data/misc/raw.py | 3 ++- pcapkit/protocols/misc/pcap/frame.py | 6 +++--- pcapkit/protocols/misc/pcapng.py | 17 ++++++++++------- pcapkit/protocols/misc/raw.py | 10 +++++----- pcapkit/protocols/protocol.py | 3 ++- pcapkit/protocols/schema/misc/pcapng.py | 8 ++++---- 9 files changed, 37 insertions(+), 32 deletions(-) diff --git a/pcapkit/protocols/application/http.py b/pcapkit/protocols/application/http.py index 8f97995d32..996beb7327 100644 --- a/pcapkit/protocols/application/http.py +++ b/pcapkit/protocols/application/http.py @@ -511,12 +511,12 @@ def _guess_version(self, length: 'int', **kwargs: 'Any') -> 'HTTP': :exc:`~pcapkit.utilities.exceptions.ProtocolError` becomes under :func:`~pcapkit.corekit.decorators.beholder`. The nine-octet frame header is therefore never used to *identify* HTTP/2 ahead of HTTP/1: as identification it misfires on - binary HTTP/1 bodies, which is precisely how garbage text was classified HTTP/2 to - begin with. A bare frame is parsed as HTTP/2 only by the fall-through below, and only - if its header is one a conforming sender could write (see ``_test_http2_frame()``): a - frame type :rfc:`9113` defines, no undefined flag, and a stream that type may be sent - on. Nine zero octets -- a ``DATA`` frame on stream 0, a protocol error under - :rfc:`9113#section-6.1` -- are not guessed as HTTP/2. + binary HTTP/1 bodies, and classifies garbage text as HTTP/2. A bare frame is parsed + as HTTP/2 only by the fall-through below, and only if its header is one a conforming + sender could write (see ``_test_http2_frame()``): a frame type :rfc:`9113` defines, + no undefined flag, and a stream that type may be sent on. Nine zero octets -- a + ``DATA`` frame on stream 0, a protocol error under :rfc:`9113#section-6.1` -- are not + guessed as HTTP/2. """ # NOTE: Positive identification, before any parse attempt. The preface is @@ -605,7 +605,7 @@ def _guess_version(self, length: 'int', **kwargs: 'Any') -> 'HTTP': # ` re-raises a # negative-length template as # :exc:`~pcapkit.utilities.exceptions.ProtocolError` -- so the - # suppression only guards whatever path is not yet known to do likewise. + # suppression only guards whatever path is not known to do likewise. # # Suppressing it on the *first* arm is wrong: nine byte patterns over # lengths 0-24 raised only ``ProtocolError`` through ``httpv1.HTTP``, so diff --git a/pcapkit/protocols/data/application/httpv2.py b/pcapkit/protocols/data/application/httpv2.py index 088fc102fb..8bcbd2ddfe 100644 --- a/pcapkit/protocols/data/application/httpv2.py +++ b/pcapkit/protocols/data/application/httpv2.py @@ -31,8 +31,8 @@ class Flags(Data): """Data model for HTTP/2 flags.""" - # NOTE: ``__value__`` is a dunder key, which ``to_dict`` carries only so - # named (#2003); the rebuild reads it, and the dumps write it, as before. + # NOTE: ``__value__`` is a dunder key, which ``to_dict`` carries only when + # it is named here (#2003); the rebuild reads it, and the dumps write it. __included__ = ['__value__'] if TYPE_CHECKING: diff --git a/pcapkit/protocols/data/misc/pcapng.py b/pcapkit/protocols/data/misc/pcapng.py index 0e23025f74..0437d156bb 100644 --- a/pcapkit/protocols/data/misc/pcapng.py +++ b/pcapkit/protocols/data/misc/pcapng.py @@ -66,8 +66,8 @@ class PCAPNG(Protocol): """Data model for PCAP-NG file blocks.""" # NOTE: ``__truncated_raw__`` is a dunder key, which ``to_dict`` carries - # only so named (#2003); the rebuild reads it, and the dumps write it, as - # before. + # only when it is named here (#2003); the rebuild reads it, and the dumps + # write it. __included__ = ['__truncated_raw__'] #: Block type. diff --git a/pcapkit/protocols/data/misc/raw.py b/pcapkit/protocols/data/misc/raw.py index 3e9938d3be..3c1aac7ae9 100644 --- a/pcapkit/protocols/data/misc/raw.py +++ b/pcapkit/protocols/data/misc/raw.py @@ -27,7 +27,8 @@ class Raw(Protocol): #: Original enumeration of this protocol. protocol: 'Optional[int]' - #: error instance when parsing packet data + #: Message saying why the packet data is kept raw, if any: the error its + #: parse raised, or the dissection limit it is past. error: 'Optional[Exception]' if TYPE_CHECKING: diff --git a/pcapkit/protocols/misc/pcap/frame.py b/pcapkit/protocols/misc/pcap/frame.py index d7af6efe99..04ffa35c6f 100644 --- a/pcapkit/protocols/misc/pcap/frame.py +++ b/pcapkit/protocols/misc/pcap/frame.py @@ -103,7 +103,7 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame], #: :meth:`self._decode_next_layer ` #: and :meth:`self._import_next_layer `. #: Each value is a :class:`~pcapkit.corekit.module.ModuleDescriptor` naming the - #: module and class, or a :class:`~pcapkit.protocols.protocol.Protocol` subclass. + #: module and class, or a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass. __proto__ = collections.defaultdict( lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'), { @@ -149,11 +149,11 @@ def register(cls, code: 'Enum_LinkType', protocol: 'ModuleDescriptor[ProtocolBas Arguments: code: protocol code as in :class:`~pcapkit.const.reg.linktype.LinkType` protocol: module descriptor or a - :class:`~pcapkit.protocols.protocol.Protocol` subclass + :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass Raises: pcapkit.utilities.exceptions.RegistryError: If ``protocol`` is not a - class, or not a :class:`~pcapkit.protocols.protocol.Protocol` subclass. + class, or not a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass. Warns: pcapkit.utilities.warnings.RegistryWarning: If this link type is diff --git a/pcapkit/protocols/misc/pcapng.py b/pcapkit/protocols/misc/pcapng.py index fc7416f721..5715640e13 100644 --- a/pcapkit/protocols/misc/pcapng.py +++ b/pcapkit/protocols/misc/pcapng.py @@ -691,7 +691,7 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], """ if TYPE_CHECKING: - #: PCAP-NG context manager. + #: Section context of the block; see :attr:`section_context`. _ctx: 'Optional[Context]' #: PCAP-NG block type. @@ -738,7 +738,7 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], #: :meth:`self._decode_next_layer ` #: and :meth:`self._import_next_layer `. #: Each value is a :class:`~pcapkit.corekit.module.ModuleDescriptor` naming the - #: module and class, or a :class:`~pcapkit.protocols.protocol.Protocol` subclass. + #: module and class, or a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass. __proto__ = collections.defaultdict( lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'), { @@ -957,8 +957,11 @@ def section_context(self) -> 'Context': """Section context of current PCAP-NG block. Raises: - UnsupportedCall: On a Section Header Block, which has no section - context of its own. + UnsupportedCall: If the block holds no section context: a block + given ``ctx=None``, or a Section Header Block, which starts a + section rather than reading one, unless the + :class:`~pcapkit.foundation.engines.pcapng.PCAPNG` engine read + it and assigned it the section it opens. .. versionadded:: 1.5.0 @@ -1058,11 +1061,11 @@ def register(cls, code: 'Enum_LinkType', protocol: 'ModuleDescriptor[ProtocolBas Arguments: code: protocol code as in :class:`~pcapkit.const.reg.linktype.LinkType` protocol: module descriptor or a - :class:`~pcapkit.protocols.protocol.Protocol` subclass + :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass Raises: pcapkit.utilities.exceptions.RegistryError: If ``protocol`` is not a - class, or not a :class:`~pcapkit.protocols.protocol.Protocol` subclass. + class, or not a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass. Warns: pcapkit.utilities.warnings.RegistryWarning: If this link type is @@ -1516,7 +1519,7 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Opt self._sect = sct #: int: Block index number. self._fnum = num - #: pcapkit.foundation.engines.pcapng.Context: Context of the PCAP-NG file. + #: pcapkit.foundation.engines.pcapng.Context: Section context of the PCAP-NG file. self._ctx = ctx #: collections.Counter: Counter for option types. self._opt = collections.Counter() # type: Counter[Enum_OptionType] diff --git a/pcapkit/protocols/misc/raw.py b/pcapkit/protocols/misc/raw.py index 58467df3e3..e301106196 100644 --- a/pcapkit/protocols/misc/raw.py +++ b/pcapkit/protocols/misc/raw.py @@ -69,7 +69,7 @@ def read(self, length: 'Optional[int]' = None, *, error: 'Optional[Exception]' = Args: length: Length of packet data. - error: Parsing errors if any. + error: Message saying why the data is kept raw, if any. alias: Original enumeration of the unknown protocol. **kwargs: Arbitrary keyword arguments. @@ -114,14 +114,14 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'None': """Post initialisation hook. - When :mod:`pcapkit` meets a malformed packet, the original parsing - error instance is given as ``error``. + When :mod:`pcapkit` meets a malformed packet, or a layer past a + dissection limit, the message saying so is given as ``error``. Args: file: Source packet stream. length: Length of packet data. - error: Parsing error if any (for parsing), an :class:`Exception` - instance or :obj:`None`. + error: Message saying why the data is kept raw, if any (for + parsing), a :obj:`str` or :obj:`None`. alias: Original enumeration of the unknown protocol, an :obj:`int` or :obj:`None`. **kwargs: Arbitrary keyword arguments. diff --git a/pcapkit/protocols/protocol.py b/pcapkit/protocols/protocol.py index 22be926a7d..894efb1786 100644 --- a/pcapkit/protocols/protocol.py +++ b/pcapkit/protocols/protocol.py @@ -1346,7 +1346,8 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional # NOTE: Construction only. A keyword that names no parameter of this # protocol is a mistake rather than a value. Every ``make`` in the tree - # ends its signature with ``**kwargs`` and never reads it, so an unknown + # ends its signature with ``**kwargs``, and none but the dispatching + # ``HTTP.make`` reads it, so an unknown # keyword would reach the schema as nothing at all and the field would # keep its default -- ``TCP_BASE`` asking for ``seq=1``, which # ``TCP.make`` spells ``seq_no``, would yield ``seq = 0`` with no warning diff --git a/pcapkit/protocols/schema/misc/pcapng.py b/pcapkit/protocols/schema/misc/pcapng.py index 920a6b853d..00ef5d6b4c 100644 --- a/pcapkit/protocols/schema/misc/pcapng.py +++ b/pcapkit/protocols/schema/misc/pcapng.py @@ -579,10 +579,10 @@ def secrets_area(packet: 'dict[str, Any]') -> 'int': Length less its 20 framing octets, and never below zero. ``secrets_length`` is a 32-bit wire field. Read as declared, a length past - the block read the trailing Block Total Length and the blocks after it as - secrets, and past :data:`~pcapkit.utilities.config.MAX_ZERO_PAD_LENGTH` the - read raised :exc:`~pcapkit.utilities.exceptions.FieldValueError` from inside - the block's schema, which ended the whole extraction (:issue:`1980`). This + the block would read the trailing Block Total Length and the blocks after it + as secrets, and past :data:`~pcapkit.utilities.config.MAX_ZERO_PAD_LENGTH` + the read would raise :exc:`~pcapkit.utilities.exceptions.FieldValueError` + from inside the block's schema, ending the whole extraction (:issue:`1980`). This is the Secrets Data counterpart of :func:`captured_area`: the block keeps its declared ``secrets_length``, the secrets are the octets the block holds, and the padding and option area are sized from those octets.