From 4ecbdc432bcc7c626546b9e4c7f14b6be9888c38 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Mon, 19 Oct 2026 00:21:51 -0400 Subject: [PATCH] docs(protocols): fourth whole-repo pass over application, misc and the protocol base (#1103) Accuracy: - PCAP-NG registry comments describe what a value is: a str naming the _read_*/_make_* methods, falling back to the *_unknown pair, or a (parser, constructor) pair; they claimed a single parsing method. - _EnumRegistry.__missing__ gets its own docstring; it rendered the inherited defaultdict pseudo-code, which describes inserting a miss. Wording: - "c.f." becomes "see" (or "compare" where a comparison is meant), and "&" becomes "and", in the next-layer registry comments. - Module docstrings and their pages read "implements an extractor for". - Raw.__post_init__ and a PCAP-NG schema docstring lose garbled clauses. Counts: - A comment in ProtocolBase._make_index no longer counts lines. Refs #1103 --- .../pcapkit/protocols/application/ftp.rst | 2 +- .../pcapkit/protocols/application/httpv1.rst | 2 +- .../pcapkit/protocols/application/httpv2.rst | 2 +- .../pcapkit/protocols/application/ngap.rst | 4 +- .../pcapkit/protocols/application/ospf.rst | 2 +- docs/source/pcapkit/protocols/misc/pcap.rst | 4 +- docs/source/pcapkit/protocols/misc/pcapng.rst | 2 +- docs/source/pcapkit/protocols/misc/raw.rst | 2 +- docs/source/pcapkit/protocols/protocol.rst | 2 +- pcapkit/protocols/application/__init__.py | 2 +- pcapkit/protocols/application/ftp.py | 2 +- pcapkit/protocols/application/httpv1.py | 2 +- pcapkit/protocols/application/httpv2.py | 2 +- pcapkit/protocols/application/ngap.py | 6 +-- pcapkit/protocols/application/ospf.py | 6 +-- pcapkit/protocols/misc/pcap/frame.py | 12 ++--- pcapkit/protocols/misc/pcap/header.py | 2 +- pcapkit/protocols/misc/pcapng.py | 44 ++++++++++--------- pcapkit/protocols/misc/raw.py | 6 +-- pcapkit/protocols/protocol.py | 20 ++++----- pcapkit/protocols/schema/application/ospf.py | 4 +- pcapkit/protocols/schema/misc/pcapng.py | 2 +- pcapkit/protocols/schema/schema.py | 14 ++++++ 23 files changed, 82 insertions(+), 64 deletions(-) diff --git a/docs/source/pcapkit/protocols/application/ftp.rst b/docs/source/pcapkit/protocols/application/ftp.rst index fbd9652214..720a294511 100644 --- a/docs/source/pcapkit/protocols/application/ftp.rst +++ b/docs/source/pcapkit/protocols/application/ftp.rst @@ -5,7 +5,7 @@ FTP - File Transfer Protocol :mod:`pcapkit.protocols.application.ftp` contains :class:`~pcapkit.protocols.application.ftp.FTP`, -which implements extractor for File Transfer Protocol +which implements an extractor for File Transfer Protocol (FTP) [*]_, and :class:`~pcapkit.protocols.application.ftp.FTP_DATA` for its data channel. diff --git a/docs/source/pcapkit/protocols/application/httpv1.rst b/docs/source/pcapkit/protocols/application/httpv1.rst index 658d49785e..e3735cc674 100644 --- a/docs/source/pcapkit/protocols/application/httpv1.rst +++ b/docs/source/pcapkit/protocols/application/httpv1.rst @@ -5,7 +5,7 @@ HTTP/1.* - Hypertext Transfer Protocol :mod:`pcapkit.protocols.application.httpv1` contains :class:`~pcapkit.protocols.application.httpv1.HTTP`, -which implements extractor for Hypertext Transfer +which implements an extractor for Hypertext Transfer Protocol (HTTP/1.*) [*]_, and its :class:`~pcapkit.protocols.application.httpv1.Type` enumeration. The structure of an HTTP/1.* message is described as below: diff --git a/docs/source/pcapkit/protocols/application/httpv2.rst b/docs/source/pcapkit/protocols/application/httpv2.rst index fe1cbb6c1b..fc3ad16e28 100644 --- a/docs/source/pcapkit/protocols/application/httpv2.rst +++ b/docs/source/pcapkit/protocols/application/httpv2.rst @@ -5,7 +5,7 @@ HTTP/2 - Hypertext Transfer Protocol :mod:`pcapkit.protocols.application.httpv2` contains :class:`~pcapkit.protocols.application.httpv2.HTTP` -only, which implements extractor for Hypertext Transfer +only, which implements an extractor for Hypertext Transfer Protocol (HTTP/2) [*]_, whose structure is described as below: diff --git a/docs/source/pcapkit/protocols/application/ngap.rst b/docs/source/pcapkit/protocols/application/ngap.rst index efe0ce09f2..ed9358a222 100644 --- a/docs/source/pcapkit/protocols/application/ngap.rst +++ b/docs/source/pcapkit/protocols/application/ngap.rst @@ -5,7 +5,7 @@ NGAP - NG Application Protocol :mod:`pcapkit.protocols.application.ngap` contains :class:`~pcapkit.protocols.application.ngap.NGAP`, -which implements extractor for the NG Application Protocol +which implements an extractor for the NG Application Protocol (NGAP) [*]_, as specified in 3GPP TS 38.413, and the enumerations its data models report with: :class:`~pcapkit.protocols.application.ngap.PDUKind`, @@ -18,7 +18,7 @@ It runs over SCTP and is named by the DATA chunk's *payload protocol identifier* rather than by a port, so :class:`NGAP` is registered on :attr:`SCTP.__proto__ ` under PPID 60 (``NG_Application_Protocol``) and PPID 66 -(``NGAP_over_DTLS_over_SCTP``), c.f. +(``NGAP_over_DTLS_over_SCTP``); see :func:`pcapkit.foundation.registry.protocols.register_sctp`. An SCTP DATA chunk that names NGAP carries exactly one ``NGAP-PDU``, encoded diff --git a/docs/source/pcapkit/protocols/application/ospf.rst b/docs/source/pcapkit/protocols/application/ospf.rst index 52c9fd6ee8..8ce566a691 100644 --- a/docs/source/pcapkit/protocols/application/ospf.rst +++ b/docs/source/pcapkit/protocols/application/ospf.rst @@ -5,7 +5,7 @@ OSPF - Open Shortest Path First :mod:`pcapkit.protocols.application.ospf` contains :class:`~pcapkit.protocols.application.ospf.OSPF` only, -which implements extractor for Open Shortest Path +which implements an extractor for Open Shortest Path First (OSPF) [*]_, whose structure is described as below: diff --git a/docs/source/pcapkit/protocols/misc/pcap.rst b/docs/source/pcapkit/protocols/misc/pcap.rst index 32fa1d3376..da27a46058 100644 --- a/docs/source/pcapkit/protocols/misc/pcap.rst +++ b/docs/source/pcapkit/protocols/misc/pcap.rst @@ -18,7 +18,7 @@ Global Header :mod:`pcapkit.protocols.misc.pcap.header` contains :class:`~pcapkit.protocols.misc.pcap.header.Header` only, -which implements extractor for global headers [*]_ +which implements an extractor for global headers [*]_ of PCAP, whose structure is described as below: .. code-block:: c @@ -99,7 +99,7 @@ Frame Header :mod:`pcapkit.protocols.misc.pcap.frame` contains :class:`~pcapkit.protocols.misc.pcap.frame.Frame` only, -which implements extractor for frame headers [*]_ of PCAP, +which implements an extractor for frame headers [*]_ of PCAP, whose structure is described as below: .. code-block:: c diff --git a/docs/source/pcapkit/protocols/misc/pcapng.rst b/docs/source/pcapkit/protocols/misc/pcapng.rst index f589fc9ece..e56eb22006 100644 --- a/docs/source/pcapkit/protocols/misc/pcapng.rst +++ b/docs/source/pcapkit/protocols/misc/pcapng.rst @@ -6,7 +6,7 @@ PCAP-NG File Format :mod:`pcapkit.protocols.misc.pcapng` contains :class:`~pcapkit.protocols.misc.pcapng.PCAPNG`, -which implements extractor for PCAP-NG file format [*]_, and the +which implements an extractor for PCAP-NG file format [*]_, and the :class:`~pcapkit.protocols.misc.pcapng.PacketDirection`, :class:`~pcapkit.protocols.misc.pcapng.PacketReception` and :class:`~pcapkit.protocols.misc.pcapng.WireGuardKeyLabel` enumerations. diff --git a/docs/source/pcapkit/protocols/misc/raw.rst b/docs/source/pcapkit/protocols/misc/raw.rst index a24a846255..dd43093ee0 100644 --- a/docs/source/pcapkit/protocols/misc/raw.rst +++ b/docs/source/pcapkit/protocols/misc/raw.rst @@ -5,7 +5,7 @@ Raw Packet Data :mod:`pcapkit.protocols.misc.raw` contains :class:`~pcapkit.protocols.misc.raw.Raw` only, which implements -extractor for unknown protocol, and constructs a +an extractor for unknown protocols, and constructs a :class:`~pcapkit.protocols.protocol.Protocol` like object. .. autoclass:: pcapkit.protocols.misc.raw.Raw diff --git a/docs/source/pcapkit/protocols/protocol.rst b/docs/source/pcapkit/protocols/protocol.rst index 07955fcb82..93084459f5 100644 --- a/docs/source/pcapkit/protocols/protocol.rst +++ b/docs/source/pcapkit/protocols/protocol.rst @@ -12,7 +12,7 @@ new protocol stack; a new protocol in an existing layer subclasses that layer's base class -- :class:`~pcapkit.protocols.link.link.Link`, :class:`~pcapkit.protocols.internet.internet.Internet`, :class:`~pcapkit.protocols.transport.transport.Transport` or -:class:`~pcapkit.protocols.application.application.Application` -- instead, c.f. +:class:`~pcapkit.protocols.application.application.Application` -- instead; see :doc:`/ext`. The built-in protocol families, those layer classes included, derive from :class:`~pcapkit.protocols.protocol.ProtocolBase`, whose metaclass is :class:`~pcapkit.protocols.protocol.ProtocolMeta`; both are listed under diff --git a/pcapkit/protocols/application/__init__.py b/pcapkit/protocols/application/__init__.py index aed8aee962..3602b93445 100644 --- a/pcapkit/protocols/application/__init__.py +++ b/pcapkit/protocols/application/__init__.py @@ -14,7 +14,7 @@ # SSH, TELNET, TLS/SSL, XMPP. # # NB: NGAP's decoder below is an optional -# dependency, c.f. pcapkit.protocols.application.ngap. Importing the module +# dependency; see pcapkit.protocols.application.ngap. Importing the module # is free -- ``pycrate`` is imported inside the parse path, not here. # Base Class for Application Layer diff --git a/pcapkit/protocols/application/ftp.py b/pcapkit/protocols/application/ftp.py index 5ab11f1c47..8f608ad342 100644 --- a/pcapkit/protocols/application/ftp.py +++ b/pcapkit/protocols/application/ftp.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.application.ftp` contains :class:`~pcapkit.protocols.application.ftp.FTP`, -which implements extractor for File Transfer Protocol +which implements an extractor for File Transfer Protocol (FTP) [*]_, and :class:`~pcapkit.protocols.application.ftp.FTP_DATA` for its data channel. diff --git a/pcapkit/protocols/application/httpv1.py b/pcapkit/protocols/application/httpv1.py index f2448191e8..fdb673b2ae 100644 --- a/pcapkit/protocols/application/httpv1.py +++ b/pcapkit/protocols/application/httpv1.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.application.httpv1` contains :class:`~pcapkit.protocols.application.httpv1.HTTP`, -which implements extractor for Hypertext Transfer +which implements an extractor for Hypertext Transfer Protocol (HTTP/1.*) [*]_, and its :class:`~pcapkit.protocols.application.httpv1.Type` enumeration. The structure of an HTTP/1.* message is described as below: diff --git a/pcapkit/protocols/application/httpv2.py b/pcapkit/protocols/application/httpv2.py index 94891e742a..86a18e0255 100644 --- a/pcapkit/protocols/application/httpv2.py +++ b/pcapkit/protocols/application/httpv2.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.application.httpv2` contains :class:`~pcapkit.protocols.application.httpv2.HTTP` -only, which implements extractor for Hypertext Transfer +only, which implements an extractor for Hypertext Transfer Protocol (HTTP/2) [*]_, whose structure is described as below: diff --git a/pcapkit/protocols/application/ngap.py b/pcapkit/protocols/application/ngap.py index 70e50d3b18..76b6742e07 100644 --- a/pcapkit/protocols/application/ngap.py +++ b/pcapkit/protocols/application/ngap.py @@ -7,7 +7,7 @@ :mod:`pcapkit.protocols.application.ngap` contains :class:`~pcapkit.protocols.application.ngap.NGAP`, -which implements extractor for the NG Application Protocol +which implements an extractor for the NG Application Protocol (NGAP) [*]_, as specified in 3GPP TS 38.413, and the enumerations its decoded fields resolve to. @@ -16,7 +16,7 @@ identifier* rather than by a port, so :class:`NGAP` is registered on :attr:`SCTP.__proto__ ` under PPID 60 (``NG_Application_Protocol``) and PPID 66 -(``NGAP_over_DTLS_over_SCTP``), c.f. +(``NGAP_over_DTLS_over_SCTP``); see :func:`pcapkit.foundation.registry.protocols.register_sctp`. An SCTP DATA chunk that names NGAP carries exactly one ``NGAP-PDU``, encoded @@ -125,7 +125,7 @@ __all__ = ['NGAP', 'PDUKind', 'Criticality'] -#: Cached ``NGAP-PDU`` object, c.f. :func:`load_pycrate`. :data:`NotImplemented` +#: Cached ``NGAP-PDU`` object; see :func:`load_pycrate`. :data:`NotImplemented` #: means the import has not been attempted yet, :data:`None` that it was #: attempted and |pycrate|_ is not installed, and anything else is the loaded #: object. "Not installed" is kept apart from "not attempted" so that a capture diff --git a/pcapkit/protocols/application/ospf.py b/pcapkit/protocols/application/ospf.py index b94fd76bde..714b96569b 100644 --- a/pcapkit/protocols/application/ospf.py +++ b/pcapkit/protocols/application/ospf.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.application.ospf` contains :class:`~pcapkit.protocols.application.ospf.OSPF` only, -which implements extractor for Open Shortest Path +which implements an extractor for Open Shortest Path First (OSPF) [*]_, whose structure is described as below: @@ -116,7 +116,7 @@ class OSPF(Application[Data_OSPF, Schema_OSPF], #: :attr:`alias` are needed *during* :meth:`read` -- :meth:`self._decode_next_layer #: ` builds the #: protocol chain out of :attr:`alias` -- and ``_info`` is not assigned until - #: :meth:`read` has returned. c.f. ``ARP._acnm`` on + #: :meth:`read` has returned. See ``ARP._acnm`` on #: :class:`~pcapkit.protocols.link.arp.ARP`, which has the same constraint. _version: 'int' @@ -388,7 +388,7 @@ def _make_id_numbers(self, id: 'IPv4Address | str | bytes | bytearray') -> 'byte ID bytes. Raises: - FieldValueError: If ``id`` is a :obj:`bool` (c.f. + FieldValueError: If ``id`` is a :obj:`bool` (see :func:`~pcapkit.corekit.fields.ipaddress.parse_ip_address`). Notes: diff --git a/pcapkit/protocols/misc/pcap/frame.py b/pcapkit/protocols/misc/pcap/frame.py index 0938ac1618..472f4f9980 100644 --- a/pcapkit/protocols/misc/pcap/frame.py +++ b/pcapkit/protocols/misc/pcap/frame.py @@ -7,7 +7,7 @@ :mod:`pcapkit.protocols.misc.pcap.frame` contains :class:`~pcapkit.protocols.misc.pcap.frame.Frame` only, -which implements extractor for frame headers [*]_ of PCAP, +which implements an extractor for frame headers [*]_ of PCAP, whose structure is described as below: .. code-block:: c @@ -100,9 +100,9 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame], # Defaults. ########################################################################## - #: Protocol index mapping for - #: decoding next layer, c.f. :meth:`self._decode_next_layer ` - #: & :meth:`self._import_next_layer `. + #: Protocol index mapping for decoding the next layer; see + #: :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. __proto__ = collections.defaultdict( @@ -334,7 +334,7 @@ def read(self, length: 'Optional[int]' = None, *, _read: 'bool' = True, # on the tail of this record followed by the head of the next one. # So the start is recorded before the unpack, in # :meth:`self.__post_init__ <__post_init__>`, and seeked to - # absolutely, as the PCAP-NG reader does, c.f. + # absolutely, as the PCAP-NG reader does; see # :meth:`pcapkit.protocols.misc.pcapng.PCAPNG.read`. seek_cur = _seek_set + self.length + _ilen @@ -349,7 +349,7 @@ def read(self, length: 'Optional[int]' = None, *, _read: 'bool' = True, # running past its block (:issue:`1405`): ``incl_len`` and ``cap_len`` # stay as declared, so the record rebuilds byte-exactly, and the # packet is the octets present. A writer must not copy the declared - # length, c.f. :meth:`PCAPIO._append_value + # length; see :meth:`PCAPIO._append_value # ` (:issue:`1541`). held = len(self._data) - self.length if held < _ilen: diff --git a/pcapkit/protocols/misc/pcap/header.py b/pcapkit/protocols/misc/pcap/header.py index f1d5c17094..255ff92c40 100644 --- a/pcapkit/protocols/misc/pcap/header.py +++ b/pcapkit/protocols/misc/pcap/header.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.misc.pcap.header` contains :class:`~pcapkit.protocols.misc.pcap.header.Header` only, -which implements extractor for global headers [*]_ +which implements an extractor for global headers [*]_ of PCAP, whose structure is described as below: .. code-block:: c diff --git a/pcapkit/protocols/misc/pcapng.py b/pcapkit/protocols/misc/pcapng.py index 02c3323ad5..95d96e7e4a 100644 --- a/pcapkit/protocols/misc/pcapng.py +++ b/pcapkit/protocols/misc/pcapng.py @@ -7,7 +7,7 @@ :mod:`pcapkit.protocols.misc.pcapng` contains :class:`~pcapkit.protocols.misc.pcapng.PCAPNG`, -which implements extractor for PCAP-NG file format [*]_, and the +which implements an extractor for PCAP-NG file format [*]_, and the :class:`~pcapkit.protocols.misc.pcapng.PacketDirection`, :class:`~pcapkit.protocols.misc.pcapng.PacketReception` and :class:`~pcapkit.protocols.misc.pcapng.WireGuardKeyLabel` enumerations. @@ -727,9 +727,9 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], # Defaults. ########################################################################## - #: Protocol index mapping for - #: decoding next layer, c.f. :meth:`self._decode_next_layer ` - #: & :meth:`self._import_next_layer `. + #: Protocol index mapping for decoding the next layer; see + #: :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. __proto__ = collections.defaultdict( @@ -743,10 +743,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], }, ) # type: DefaultDict[Enum_LinkType | int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]] - #: Block type to method mapping. Method names are expected to be referred - #: to the class by ``_read_block_${name}`` and/or ``_make_block_${name}``, - #: and if such name not found, the value should then be a method that can - #: parse the block by itself. + #: Block type to method mapping. A :obj:`str` value names the + #: ``_read_block_${name}`` and ``_make_block_${name}`` methods, which fall + #: back to ``_read_block_unknown`` and ``_make_block_unknown`` when not + #: defined, as an unregistered code does; any other value is a + #: ``(parser, constructor)`` pair of callables. __block__ = collections.defaultdict( lambda: 'unknown', { @@ -764,10 +765,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], }, ) # type: DefaultDict[Enum_BlockType | int, str | tuple[BlockParser, BlockConstructor]] - #: Block option type to method mapping. Method names are expected to be - #: referred to the class by ``_read_option_${name}`` and/or ``_make_option_${name}``, - #: and if such name not found, the value should then be a method that can - #: parse the option by itself. + #: Block option type to method mapping. A :obj:`str` value names the + #: ``_read_option_${name}`` and ``_make_option_${name}`` methods, which fall + #: back to ``_read_option_unknown`` and ``_make_option_unknown`` when not + #: defined, as an unregistered code does; any other value is a + #: ``(parser, constructor)`` pair of callables. __option__ = collections.defaultdict( lambda: 'unknown', { @@ -814,10 +816,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], }, ) # type: DefaultDict[Union[Enum_OptionType, Tuple[str, int]], str | tuple[OptionParser, OptionConstructor]] - #: Name Resolution Block record type to method mapping. Method names are expected - #: to be referred to the class by ``_read_record_${name}`` and/or ``_make_record_${name}``, - #: and if such name not found, the value should then be a method that can - #: parse the record by itself. + #: Name Resolution Block record type to method mapping. A :obj:`str` value + #: names the ``_read_record_${name}`` and ``_make_record_${name}`` methods, + #: which fall back to ``_read_record_unknown`` and ``_make_record_unknown`` + #: when not defined, as an unregistered code does; any other value is a + #: ``(parser, constructor)`` pair of callables. __record__ = collections.defaultdict( lambda: 'unknown', { @@ -827,10 +830,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG], }, ) # type: DefaultDict[Enum_RecordType | int, str | tuple[RecordParser, RecordConstructor]] - #: Decryption secrets type to method mapping. Method names are expected to - #: be referred to the class by ``_read_secrets_${name}`` and/or ``_make_secrets_${name}``, - #: and if such name not found, the value should then be a method that can - #: parse the decryption secrets by itself. + #: Decryption secrets type to method mapping. A :obj:`str` value names the + #: ``_read_secrets_${name}`` and ``_make_secrets_${name}`` methods, which + #: fall back to ``_read_secrets_unknown`` and ``_make_secrets_unknown`` when + #: not defined, as an unregistered code does; any other value is a + #: ``(parser, constructor)`` pair of callables. __secrets__ = collections.defaultdict( lambda: 'unknown', { diff --git a/pcapkit/protocols/misc/raw.py b/pcapkit/protocols/misc/raw.py index 3ac5e69de1..0a1549f2fb 100644 --- a/pcapkit/protocols/misc/raw.py +++ b/pcapkit/protocols/misc/raw.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.misc.raw` contains :class:`~pcapkit.protocols.misc.raw.Raw` only, which implements -extractor for unknown protocol, and constructs a +an extractor for unknown protocols, and constructs a :class:`~pcapkit.protocols.protocol.Protocol` like object. """ @@ -114,8 +114,8 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'None': """Post initialisation hook. - Would :mod:`pcapkit` encounter malformed packets, the original parsing - error instance will be provided as in ``error``. + When :mod:`pcapkit` meets a malformed packet, the original parsing + error instance is given as ``error``. Args: file: Source packet stream. diff --git a/pcapkit/protocols/protocol.py b/pcapkit/protocols/protocol.py index f4b7d52174..aaa4533db4 100644 --- a/pcapkit/protocols/protocol.py +++ b/pcapkit/protocols/protocol.py @@ -413,13 +413,13 @@ def _check_construction_keywords(cls: 'type', kwargs: 'dict[str, Any]', #: contextvars.ContextVar[int]: How many layers of the frame being dissected -#: come before the next one :meth:`ProtocolBase._parse_next_layer` parses, c.f. +#: come before the next one :meth:`ProtocolBase._parse_next_layer` parses; see #: :data:`~pcapkit.utilities.config.FRAME_LAYER_LIMIT`. _frame_depth = contextvars.ContextVar('_frame_depth', default=0) #: contextvars.ContextVar[bool]: Whether a payload is being rebuilt by #: :meth:`ProtocolBase._make_payload`, so that the layer it is rebuilt for -#: parses the same octets again, c.f. :data:`~pcapkit.utilities.config.FRAME_LAYER_LIMIT`. +#: parses the same octets again; see :data:`~pcapkit.utilities.config.FRAME_LAYER_LIMIT`. _rebuilding = contextvars.ContextVar('_rebuilding', default=False) @@ -509,9 +509,9 @@ class ProtocolBase(Generic[_PT, _ST], metaclass=ProtocolMeta): #: :class:`~pcapkit.protocols.misc.raw.Raw`, and thus its layer is :obj:`None`. __layer__: 'Optional[Literal["Link", "Internet", "Transport", "Application"]]' = None - #: Protocol index mapping for decoding next layer, c.f. + #: Protocol index mapping for decoding the next layer; see #: :meth:`self._decode_next_layer ` - #: & :meth:`self._import_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:`Protocol` subclass. __proto__: 'DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]' = collections.defaultdict( @@ -565,7 +565,7 @@ class ProtocolBase(Generic[_PT, _ST], metaclass=ProtocolMeta): #: built without ``__init__``. __reconstructing__: 'bool' = False - #: Caller supplied parsing context, c.f. :mod:`pcapkit.corekit.context`. + #: Caller supplied parsing context; see :mod:`pcapkit.corekit.context`. #: :meth:`self.__init__ ` replaces this with a real #: :class:`~pcapkit.corekit.context.ContextRegistry`; the class-level #: :data:`None` is what an instance built without ``__init__`` (e.g. @@ -1223,8 +1223,8 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional While parsing, it is republished as ``__packet__`` so that :meth:`self.unpack ` -- and through it the schema -- can see it; see the note below. - __context__: Caller supplied parsing context (:attr:`self._exctx `), - c.f. :mod:`pcapkit.corekit.context`: a + __context__: Caller supplied parsing context (:attr:`self._exctx `; + see :mod:`pcapkit.corekit.context`): a :class:`~pcapkit.corekit.context.ContextRegistry`, a :class:`~pcapkit.corekit.context.ProtocolContext`, a mapping of names to :class:`~pcapkit.corekit.context.ProtocolContext`, or an @@ -1986,8 +1986,8 @@ def _make_index(cls, name: 'str | int | StdlibEnum | AenumEnum', default: 'Optio else: # Caught by the handler below, so this never escapes: it jumps # to the shared "name is not in namespace" path. A pcapkit - # exception here would log at CRITICAL for something handled - # two lines later. + # exception here would log at CRITICAL for something the + # ``except`` below handles. raise KeyError(name) except KeyError as error: if default is None: @@ -2497,7 +2497,7 @@ class Protocol(ProtocolBase, Generic[_PT, _ST]): """User-facing abstract base class for third-party protocols. Inherit it directly only to create a new protocol stack; a new protocol in - an existing layer subclasses that layer's base class instead, c.f. + an existing layer subclasses that layer's base class instead; see :doc:`/ext`. The built-in protocol families do not derive from this class but from :class:`ProtocolBase`, whose metaclass is :class:`ProtocolMeta`. diff --git a/pcapkit/protocols/schema/application/ospf.py b/pcapkit/protocols/schema/application/ospf.py index a6ac4932f8..f0aba5afd3 100644 --- a/pcapkit/protocols/schema/application/ospf.py +++ b/pcapkit/protocols/schema/application/ospf.py @@ -95,8 +95,8 @@ class OSPF(Schema): #: Payload. payload: 'bytes' = PayloadField(length=lambda pkt: pkt['length'] - 24) #: Octets captured past the Packet Length, such as the message digest - #: that cryptographic authentication appends (:rfc:`2328#appendix-D.4.3`), - #: c.f. :attr:`IPv4.trailer `. + #: that cryptographic authentication appends (:rfc:`2328#appendix-D.4.3`); + #: compare :attr:`IPv4.trailer `. trailer: 'bytes' = PayloadField(default=b'') if TYPE_CHECKING: diff --git a/pcapkit/protocols/schema/misc/pcapng.py b/pcapkit/protocols/schema/misc/pcapng.py index 0154ecb926..8ad7073344 100644 --- a/pcapkit/protocols/schema/misc/pcapng.py +++ b/pcapkit/protocols/schema/misc/pcapng.py @@ -287,7 +287,7 @@ def nonnegative(length: 'Callable[[dict[str, Any]], int]') -> 'Callable[[dict[st Flooring rather than refusing is the choice :func:`bounded_area` makes too: a block read has no catch point above :meth:`FieldBase.unpack `, so one refusal aborts the - whole extraction rather than one block, so a capture cut short by its + whole extraction rather than one block, and a capture cut short by its snapshot length must keep parsing. The end of the file is the one case that is *not* a floor, since there no block is being read at all -- see :meth:`PCAPNG._check_block_floor `, which reports it diff --git a/pcapkit/protocols/schema/schema.py b/pcapkit/protocols/schema/schema.py index a0f9345036..2f62dbd08f 100644 --- a/pcapkit/protocols/schema/schema.py +++ b/pcapkit/protocols/schema/schema.py @@ -1217,6 +1217,20 @@ class _EnumRegistry(collections.defaultdict): """ def __missing__(self, key: 'Any') -> 'Any': + """Return the fallback for an unregistered ``key``, without storing it. + + Args: + key: Registry key that is not registered. + + Returns: + What :attr:`~collections.defaultdict.default_factory` returns. The + registry is left as it was, so ``key`` stays unregistered. + + Raises: + KeyError: If :attr:`~collections.defaultdict.default_factory` is + :data:`None`. + + """ if self.default_factory is None: raise KeyError(key) return self.default_factory()