From e0db51b97e5dd1a663a361a738d9a5d11f60d052 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 25 Oct 2026 00:44:37 -0400 Subject: [PATCH] docs(protocols): fifth whole-repo pass over application, misc and the protocol base (#1103) - keep_short_read: the key is listed in Data.__included__, not an ordinary one (#2003) - register_frame/register_block/_option/_record/_secrets: meth is a method name or a (parser, constructor) pair, not a single callable - SHB pre_pack: the magic is not palindromic; NRB length is the Block Total Length - Frame._ghdr holds the data model; the CB padding comment names the right idiom; HTTP/2 __length_hint__ is a hint, not a total length - ngap.rst: unnamed values, not IEs; misc/index.rst grammar - document the helpers rendered text names: Schema._cut_short_read, keep_short_read, replay_short_read, _cut_last_line, _malformed_line_message Prose only; AST unchanged. tests/project docs tests and nearby protocol tests pass. --- .../pcapkit/protocols/application/ngap.rst | 2 +- docs/source/pcapkit/protocols/index.rst | 6 ++++++ docs/source/pcapkit/protocols/misc/index.rst | 2 +- docs/source/pcapkit/protocols/misc/pcapng.rst | 2 ++ pcapkit/protocols/application/httpv2.py | 6 ++++-- pcapkit/protocols/misc/pcap/frame.py | 2 +- pcapkit/protocols/misc/pcapng.py | 18 +++++++++++++----- pcapkit/protocols/schema/misc/pcapng.py | 13 ++++++++----- pcapkit/protocols/schema/schema.py | 9 +++++---- 9 files changed, 41 insertions(+), 19 deletions(-) diff --git a/docs/source/pcapkit/protocols/application/ngap.rst b/docs/source/pcapkit/protocols/application/ngap.rst index 67e9be11d9..a4a17cfad2 100644 --- a/docs/source/pcapkit/protocols/application/ngap.rst +++ b/docs/source/pcapkit/protocols/application/ngap.rst @@ -95,7 +95,7 @@ Known Limitations * **The specification version is that of the installed decoder, not this package's.** The IE and procedure enumerations were generated from ``NGAP_Constants`` of |pycrate|_ 0.8.1 (Release-18-era). A |pycrate|_ that - carries a newer NGAP will decode IEs that + carries a newer NGAP will decode values that :class:`~pcapkit.const.ngap.procedure_code.ProcedureCode` and :class:`~pcapkit.const.ngap.protocol_ie.ProtocolIE` do not name. Such a value resolves to a non-registering member called ``Unassigned`` rather than diff --git a/docs/source/pcapkit/protocols/index.rst b/docs/source/pcapkit/protocols/index.rst index b076ee2130..855de5a812 100644 --- a/docs/source/pcapkit/protocols/index.rst +++ b/docs/source/pcapkit/protocols/index.rst @@ -202,6 +202,8 @@ Header Schema .. autoattribute:: __fields__ :no-value: + .. automethod:: _cut_short_read + .. autoclass:: pcapkit.protocols.schema.schema.EnumSchema :no-members: :show-inheritance: @@ -219,6 +221,10 @@ Header Schema .. autodecorator:: pcapkit.protocols.schema.schema.schema_final +.. autofunction:: pcapkit.protocols.schema.schema.keep_short_read + +.. autofunction:: pcapkit.protocols.schema.schema.replay_short_read + Internal Definitions ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/pcapkit/protocols/misc/index.rst b/docs/source/pcapkit/protocols/misc/index.rst index 3620256414..1abf5ea54f 100644 --- a/docs/source/pcapkit/protocols/misc/index.rst +++ b/docs/source/pcapkit/protocols/misc/index.rst @@ -6,7 +6,7 @@ Auxiliary Protocols .. module:: pcapkit.protocols.schema.misc :mod:`pcapkit.protocols.misc` contains the auxiliary protocol implementations. -Such includes the PCAP header classes, the PCAP-NG +These include the PCAP header classes, the PCAP-NG :class:`~pcapkit.protocols.misc.pcapng.PCAPNG` class, the :class:`~pcapkit.protocols.misc.raw.Raw` class for not-supported protocols, and the :class:`~pcapkit.protocols.misc.null.NoPayload` class for indication of diff --git a/docs/source/pcapkit/protocols/misc/pcapng.rst b/docs/source/pcapkit/protocols/misc/pcapng.rst index 8afc473662..77518260f0 100644 --- a/docs/source/pcapkit/protocols/misc/pcapng.rst +++ b/docs/source/pcapkit/protocols/misc/pcapng.rst @@ -585,6 +585,8 @@ shared with the PCAP frame header and documented in .. autofunction:: pcapkit.protocols.schema.misc.pcapng.zigbee_key_trailing .. autofunction:: pcapkit.protocols.schema.misc.pcapng.zigbee_key_held .. autofunction:: pcapkit.protocols.schema.misc.pcapng._spb_data_length +.. autofunction:: pcapkit.protocols.schema.misc.pcapng._cut_last_line +.. autofunction:: pcapkit.protocols.schema.misc.pcapng._malformed_line_message Data Models ----------- diff --git a/pcapkit/protocols/application/httpv2.py b/pcapkit/protocols/application/httpv2.py index ed534f1bd5..57ae267bba 100644 --- a/pcapkit/protocols/application/httpv2.py +++ b/pcapkit/protocols/application/httpv2.py @@ -490,7 +490,9 @@ def register_frame(cls, code: 'Enum_Frame', meth: 'str | tuple[FrameParser, Fram Args: code: HTTP frame type code. - meth: Method name or callable to parse and/or construct the frame. + meth: Name of the ``_read_http_${name}`` and ``_make_http_${name}`` + methods, or a ``(parser, constructor)`` pair of callables; see + :attr:`__frame__`. Warns: RegistryWarning: If a different entry is already registered for @@ -512,7 +514,7 @@ def register_frame(cls, code: 'Enum_Frame', meth: 'str | tuple[FrameParser, Fram ########################################################################## def __length_hint__(self) -> 'Literal[9]': - """Total length of corresponding protocol.""" + """Return an estimated length for the object.""" return 9 ########################################################################## diff --git a/pcapkit/protocols/misc/pcap/frame.py b/pcapkit/protocols/misc/pcap/frame.py index 7279ce58e5..d7af6efe99 100644 --- a/pcapkit/protocols/misc/pcap/frame.py +++ b/pcapkit/protocols/misc/pcap/frame.py @@ -473,7 +473,7 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Opt """ #: int: frame index number self._fnum = num - #: pcapkit.protocols.misc.pcap.header.Header: Global header of the PCAP file. + #: pcapkit.protocols.data.misc.pcap.header.Header: Global header of the PCAP file. self._ghdr = header #: pcapkit.const.reg.linktype.LinkType: next layer protocol index diff --git a/pcapkit/protocols/misc/pcapng.py b/pcapkit/protocols/misc/pcapng.py index d0cee5873a..0f987a59b5 100644 --- a/pcapkit/protocols/misc/pcapng.py +++ b/pcapkit/protocols/misc/pcapng.py @@ -1073,7 +1073,9 @@ def register_block(cls, code: 'Enum_BlockType', meth: 'str | tuple[BlockParser, Args: code: PCAP-NG block type code. - meth: Method name or callable to parse and/or construct the block. + meth: Name of the ``_read_block_${name}`` and ``_make_block_${name}`` + methods, or a ``(parser, constructor)`` pair of callables; see + :attr:`__block__`. Warns: RegistryWarning: If a different entry is already registered for @@ -1096,7 +1098,9 @@ def register_option(cls, code: 'Enum_OptionType', meth: 'str | tuple[OptionParse Args: code: PCAP-NG option type code. - meth: Method name or callable to parse and/or construct the option. + meth: Name of the ``_read_option_${name}`` and + ``_make_option_${name}`` methods, or a ``(parser, constructor)`` + pair of callables; see :attr:`__option__`. Warns: RegistryWarning: If a different entry is already registered for @@ -1120,7 +1124,9 @@ def register_record(cls, code: 'Enum_RecordType', meth: 'str | tuple[RecordParse Args: code: PCAP-NG name resolution record type code. - meth: Method name or callable to parse and/or construct the name resolution record. + meth: Name of the ``_read_record_${name}`` and + ``_make_record_${name}`` methods, or a ``(parser, constructor)`` + pair of callables; see :attr:`__record__`. Warns: RegistryWarning: If a different entry is already registered for @@ -1143,7 +1149,9 @@ def register_secrets(cls, code: 'Enum_SecretsType', meth: 'str | tuple[SecretsPa Args: code: PCAP-NG decryption secrets type code. - meth: Method name or callable to parse and/or construct the decryption secrets. + meth: Name of the ``_read_secrets_${name}`` and + ``_make_secrets_${name}`` methods, or a ``(parser, constructor)`` + pair of callables; see :attr:`__secrets__`. Warns: RegistryWarning: If a different entry is already registered for @@ -4851,7 +4859,7 @@ def _make_block_cb(self, block: 'Optional[Data_CustomBlock]' = None, *, # NOTE: ``-n % 4`` is the octet count needed to reach the next 32-bit # boundary, and zero when already there. Integer arithmetic throughout, - # unlike the ``math.ceil(n / 4) * 4 - n`` idiom used elsewhere in this + # unlike the ``math.ceil(n / 4) * 4`` idiom used elsewhere in this # file, which routes a length through a float. cb_data = data.pack() if isinstance(data, Schema) else data cb_data += bytes(-len(cb_data) % 4) diff --git a/pcapkit/protocols/schema/misc/pcapng.py b/pcapkit/protocols/schema/misc/pcapng.py index fd56a00da6..9a55e68584 100644 --- a/pcapkit/protocols/schema/misc/pcapng.py +++ b/pcapkit/protocols/schema/misc/pcapng.py @@ -1318,10 +1318,13 @@ def pre_pack(self, packet: 'dict[str, Any]') -> 'None': This method is expected to directly modify any data stored in the ``packet`` and thus no return is required. - The Byte-Order Magic is not carried by any field of the schema -- - :attr:`magic` is the palindromic constant, identical in either byte - order -- so it is seeded here from the byte order the packet data - asks for, and from the host byte order when it asks for none. + :func:`shb_byteorder_callback` takes the byte order from the + Byte-Order Magic as :attr:`match` reads it, and a constructed block + has no :attr:`match` to read -- a forward match packs no octets -- + nor can :attr:`magic` stand in, since it holds the same constant in + either byte order. So :attr:`match` is seeded here from the byte + order the packet data asks for, and from the host byte order when it + asks for none; a ``match`` already in ``packet`` is kept. """ if 'match' in packet: @@ -2050,7 +2053,7 @@ def __init__(self, type: 'Enum_OptionType', length: 'int', ip: 'IPv6Address | by class NameResolutionBlock(BlockType, code=Enum_BlockType.Name_Resolution_Block): """Header schema for PCAP-NG Name Resolution Block (NRB).""" - #: Record total length. + #: Block total length. length: 'int' = UInt32Field(callback=byteorder_callback) #: Name resolution records. records: 'list[NameResolutionRecord]' = OptionAreaField( diff --git a/pcapkit/protocols/schema/schema.py b/pcapkit/protocols/schema/schema.py index be88a4ed2a..ba76d7a9d2 100644 --- a/pcapkit/protocols/schema/schema.py +++ b/pcapkit/protocols/schema/schema.py @@ -1486,10 +1486,11 @@ def keep_short_read(protocol: 'ProtocolBase') -> 'None': Called by the layer base classes once a parse is done. When the data ended inside one of the header's fields, ``info`` gains the ``__short_read__`` record :meth:`Schema.unpack` made, so that :func:`replay_short_read` can - cut the rebuild back to what was captured (:issue:`1458`). The key is an - ordinary one, so :meth:`Info.to_dict ` - carries it and ``from_data(info.to_dict())`` replays it too; it is absent - for a header that was captured whole. + cut the rebuild back to what was captured (:issue:`1458`). The key is listed + in :attr:`Data.__included__ `, + so :meth:`Info.to_dict ` carries it + and ``from_data(info.to_dict())`` replays it too; it is absent for a header + that was captured whole. """ header = cast('Optional[Schema]', getattr(protocol, '__header__', None))