From 8c278abf8d8b63e0e0d634cc49c74ddfa2df1e06 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Tue, 6 Oct 2026 14:52:51 -0400 Subject: [PATCH] docs(protocols): Protocol docstring claims it is the base of all protocol families - Protocol: describe it as the user-facing base for third-party protocols and new protocol stacks; built-in families derive from ProtocolBase. - ProtocolBase: name the families that derive from it and its metaclass. - ProtocolMeta: it is ProtocolBase's metaclass and adds nothing over abc.ABCMeta; drop the claim that it generates attributes for Protocol. Docstrings only; AST identical to origin/main once bare-string Exprs are stripped. Closes #1101 --- pcapkit/protocols/protocol.py | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/pcapkit/protocols/protocol.py b/pcapkit/protocols/protocol.py index 54f8b83a41..73b7df3afc 100644 --- a/pcapkit/protocols/protocol.py +++ b/pcapkit/protocols/protocol.py @@ -263,21 +263,29 @@ def _check_construction_keywords(cls: 'type', kwargs: 'dict[str, Any]', class ProtocolMeta(abc.ABCMeta): - """Meta class to add dynamic support to :class:`Protocol`. + """Metaclass of :class:`ProtocolBase`, and so of every protocol class. - This meta class is used to generate necessary attributes for the - :class:`Protocol` class. It can be useful to reduce unnecessary - registry calls and simplify the customisation process. + It adds no behaviour of its own over :class:`abc.ABCMeta`. """ class ProtocolBase(Generic[_PT, _ST], metaclass=ProtocolMeta): - """Abstract base class for all protocol family. + """Abstract base class for all protocol families. + + The built-in protocol families -- the layer base classes + :class:`~pcapkit.protocols.link.link.Link`, + :class:`~pcapkit.protocols.internet.internet.Internet`, + :class:`~pcapkit.protocols.transport.transport.Transport` and + :class:`~pcapkit.protocols.application.application.Application`, and the + miscellaneous protocols in :mod:`pcapkit.protocols.misc`, PCAP and PCAP-NG + included -- derive from this class directly. Its metaclass is + :class:`ProtocolMeta`. Note: - This class is for internal use only. For customisation, please use - :class:`Protocol` instead. + This class is for internal use only. For customisation, subclass + :class:`Protocol` to create a new protocol stack, or the matching + layer base class above for a new protocol in an existing layer. """ @@ -1828,7 +1836,14 @@ def _check_term_threshold(self) -> bool: class Protocol(ProtocolBase, Generic[_PT, _ST]): - """Abstract base class for all protocol family.""" + """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. + :doc:`/ext`. The built-in protocol families do not derive from this class + but from :class:`ProtocolBase`, whose metaclass is :class:`ProtocolMeta`. + + """ def __init_subclass__(cls, /, schema: 'Optional[Type[_ST]]' = None, data: 'Optional[Type[_PT]]' = None,