From ec2afbc80d34f6e00ed87db3ea81f66d51142382 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Thu, 15 Oct 2026 18:36:53 -0400 Subject: [PATCH] docs(protocols): second whole-repo pass over application, misc and the protocol base (#1103) Version directives, 1.1.0-1.4.1 backfill: - Protocol: versionchanged 1.3.0. The built-in families moved onto ProtocolBase, so a built-in protocol is not an instance of Protocol, and a Protocol subclass registers itself in pcapkit.protocols.__proto__. - data.misc.raw.Raw: versionchanged 1.3.3. packet left its fields when the base data class took it over, so the constructor takes protocol and error only. Accuracy: - ProtocolBase.unpack: since #1769, pack() sets __header__ only on the call __post_init__ makes during construction, so the note names that call and from_schema() rather than pack() in general. - HTTP.make: Returns said bytes; it returns the versioned make()'s schema. - pcapkit.protocols.__proto__: the values are ProtocolBase subclasses, and the built-in ones are not Protocol subclasses. AST guard identical on all four files; tests/project and the pack, HTTP and docstring-contract tests pass. Refs #1103 --- pcapkit/protocols/__init__.py | 2 +- pcapkit/protocols/application/http.py | 2 +- pcapkit/protocols/data/misc/raw.py | 11 ++++++++++- pcapkit/protocols/protocol.py | 14 +++++++++++--- 4 files changed, 23 insertions(+), 6 deletions(-) diff --git a/pcapkit/protocols/__init__.py b/pcapkit/protocols/__init__.py index 8a54371f26..2327942d62 100644 --- a/pcapkit/protocols/__init__.py +++ b/pcapkit/protocols/__init__.py @@ -70,7 +70,7 @@ 'RARP', 'DRARP', ] -#: dict[str, ~typing.Type[Protocol]]: Protocol registry. +#: dict[str, ~typing.Type[~pcapkit.protocols.protocol.ProtocolBase]]: Protocol registry. __proto__ = {} # type: dict[str, Type[ProtocolBase]] for name in __all__: __proto__[name.upper()] = globals()[name] diff --git a/pcapkit/protocols/application/http.py b/pcapkit/protocols/application/http.py index 0e1725b50f..e16030a1c6 100644 --- a/pcapkit/protocols/application/http.py +++ b/pcapkit/protocols/application/http.py @@ -342,7 +342,7 @@ def make(self, **kwargs: Arbitrary keyword arguments. Returns: - bytes: Constructed packet data. + The header schema the versioned ``make`` constructs. Raises: ProtocolError: If ``version`` is unknown, or if ``preface`` is diff --git a/pcapkit/protocols/data/misc/raw.py b/pcapkit/protocols/data/misc/raw.py index f44cbe619a..98618a18c8 100644 --- a/pcapkit/protocols/data/misc/raw.py +++ b/pcapkit/protocols/data/misc/raw.py @@ -14,7 +14,16 @@ @info_final class Raw(Protocol): - """Raw packet is an unknown protocol.""" + """Raw packet is an unknown protocol. + + .. versionchanged:: 1.3.3 + + ``packet`` is not a field of this class, so its constructor takes + ``protocol`` and ``error`` only. + :class:`~pcapkit.protocols.protocol.ProtocolBase` sets ``packet`` on + the data model of every protocol it constructs. + + """ #: Original enumeration of this protocol. protocol: 'Optional[int]' diff --git a/pcapkit/protocols/protocol.py b/pcapkit/protocols/protocol.py index 5812ba4cb9..0dd44595cb 100644 --- a/pcapkit/protocols/protocol.py +++ b/pcapkit/protocols/protocol.py @@ -841,9 +841,10 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> '_PT': global packet data to underlying methods. This is useful when the packet data is not available in the current instance. - When :meth:`pack` or :meth:`from_schema` has already set - :attr:`self.__header__ `, that schema is - kept, unless it still holds raw :obj:`bytes` where parsing its + When :attr:`self.__header__ ` is already set, + by :meth:`from_schema` or by the :meth:`pack` call that + :meth:`__post_init__` makes to construct the instance, that schema + is kept, unless it still holds raw :obj:`bytes` where parsing its packed octets yields a schema -- e.g. a raw option given to ``make()`` -- which :meth:`read` cannot consume. The header is then replaced by the parsed one (:issue:`1312`). @@ -2489,6 +2490,13 @@ class Protocol(ProtocolBase, Generic[_PT, _ST]): :doc:`/ext`. The built-in protocol families do not derive from this class but from :class:`ProtocolBase`, whose metaclass is :class:`ProtocolMeta`. + .. versionchanged:: 1.3.0 + + The built-in protocol families derive from :class:`ProtocolBase`, so a + built-in protocol is not an instance of this class, where every one + was; and a subclass is registered in :data:`pcapkit.protocols.__proto__` + when it is defined. + """ def __init_subclass__(cls, /, schema: 'Optional[Type[_ST]]' = None,