Skip to content

docs: retarget Protocol/ProtocolBase cross-references to match the #1103 display rule #2422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JarryShaw merged 1 commit into from
Oct 29, 2026
+75 −70
Merged

docs: retarget Protocol/ProtocolBase cross-references to match the #1103 display rule #2422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/source/ext.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,14 +241,14 @@ The following code snippet shows how to create a new protocol class:
silently wrong field. The accepted set is read from :func:`inspect.signature` -- the union of every
keyword-taking parameter of ``make``, ``read``, ``pack``, ``unpack``,
``__post_init__`` and ``__init__`` anywhere in the class's MRO -- which is
wider than ``make`` alone because :meth:`ProtocolBase.__post_init__
<pcapkit.protocols.protocol.ProtocolBase.__post_init__>` hands the same
wider than ``make`` alone because :meth:`Protocol.__post_init__
<pcapkit.protocols.protocol.Protocol.__post_init__>` hands the same
``**kwargs`` to the construction and to the parse, so a keyword only ``read``
declares still travels through ``make``.

Shapes a signature cannot express are declared on the class instead, via
:attr:`ProtocolBase.__keywords__
<pcapkit.protocols.protocol.ProtocolBase.__keywords__>`:
:attr:`Protocol.__keywords__
<pcapkit.protocols.protocol.Protocol.__keywords__>`:

.. code-block:: python

Expand All @@ -271,8 +271,8 @@ The following code snippet shows how to create a new protocol class:
subclass of a dispatcher is checked normally. Prefer a declared parameter to
either: it is also what documents the keyword to your callers.

Parsing is unaffected. :meth:`ProtocolBase.from_data
<pcapkit.protocols.protocol.ProtocolBase.from_data>` checks the keywords its
Parsing is unaffected. :meth:`Protocol.from_data
<pcapkit.protocols.protocol.Protocol.from_data>` checks the keywords its
caller passes just as strictly, raising
:exc:`~pcapkit.utilities.exceptions.UnsupportedCall`, but only warns with
:exc:`~pcapkit.utilities.warnings.UnknownFieldWarning` for a key that comes
Expand All @@ -281,8 +281,8 @@ The following code snippet shows how to create a new protocol class:

.. warning::

The check lives in :meth:`ProtocolBase.__init__
<pcapkit.protocols.protocol.ProtocolBase.__init__>`, where every producer's
The check lives in :meth:`Protocol.__init__
<pcapkit.protocols.protocol.Protocol.__init__>`, where every producer's
keywords converge, so it covers ``SomeProtocol(...)`` and the ``pack`` it
leads to -- but **not** a direct ``SomeProtocol.make(...)`` call, which still
discards an undeclared keyword in silence. ``object.__new__(cls).make(...)``
Expand Down
2 changes: 1 addition & 1 deletion docs/source/pcapkit/protocols/internet/ipv6_ext.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ This class is reached in these ways:
``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
have dedicated classes. When one of *those* raises,
:func:`~pcapkit.corekit.decorators.beholder`
(:meth:`ProtocolBase._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
(:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`)
would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
``next`` and crashes the walk as in path 1.
:meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>` catches
Expand Down
2 changes: 1 addition & 1 deletion docs/source/pcapkit/utilities/chardet.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Character Set Detection
turning the bytes of a text field into a :obj:`str`. It is shared by
:meth:`StringField.post_process
<pcapkit.corekit.fields.strings.StringField.post_process>` and
:meth:`ProtocolBase.decode <pcapkit.protocols.protocol.Protocol.decode>`,
:meth:`Protocol.decode <pcapkit.protocols.protocol.Protocol.decode>`,
which is why it lives here rather than beside either of them.

.. autofunction:: pcapkit.utilities.chardet.detect
Expand Down
8 changes: 4 additions & 4 deletions pcapkit/corekit/decorators.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@

#: contextvars.ContextVar[bool]: Whether a call :func:`beholder` wraps is under
#: way, so that an :exc:`Exception` raised inside it ends with the layer that
#: raised replaced; see :meth:`ProtocolBase._parse_next_layer
#: <pcapkit.protocols.protocol.ProtocolBase._parse_next_layer>` (:issue:`2308`).
#: raised replaced; see :meth:`Protocol._parse_next_layer
#: <pcapkit.protocols.protocol.Protocol._parse_next_layer>` (:issue:`2308`).
_beholding = contextvars.ContextVar('_beholding', default=False)


Expand Down Expand Up @@ -116,8 +116,8 @@ def beholder(
:class:`~pcapkit.protocols.misc.null.NoPayload`, if the error is an
end-of-file :exc:`~pcapkit.utilities.exceptions.StructError`.

When :meth:`ProtocolBase._parse_next_layer
<pcapkit.protocols.protocol.ProtocolBase._parse_next_layer>` held the
When :meth:`Protocol._parse_next_layer
<pcapkit.protocols.protocol.Protocol._parse_next_layer>` held the
warnings of the layer that raised, they are dropped with it: they describe a
layer the result does not have, and the replacement's ``error`` reports the
failure (:issue:`2308`).
Expand Down
4 changes: 2 additions & 2 deletions pcapkit/corekit/fields/numbers.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -730,8 +730,8 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'Stdli
the registry with ``aenum.extend_enum``, for two reasons: a
capture carrying many distinct unassigned codes would otherwise grow
a process-global registry without bound, which is the growth
:meth:`ProtocolBase._lookup_registry
<pcapkit.protocols.protocol.ProtocolBase._lookup_registry>` exists
:meth:`Protocol._lookup_registry
<pcapkit.protocols.protocol.Protocol._lookup_registry>` exists
to avoid; and a stdlib :class:`enum.IntEnum` registry is then
handled exactly like an ``aenum.IntEnum`` one.

Expand Down
4 changes: 2 additions & 2 deletions pcapkit/corekit/module.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,8 @@ def klass(self) -> 'Type[_T]':
The module is read from :data:`sys.modules` first, and
:func:`importlib.import_module` is entered only when it is not
loaded yet. That matters because this property is on a *per-frame*
dispatch path: :meth:`ProtocolBase._lookup_next_layer
<pcapkit.protocols.protocol.ProtocolBase._lookup_next_layer>`
dispatch path: :meth:`Protocol._lookup_next_layer
<pcapkit.protocols.protocol.Protocol._lookup_next_layer>`
deliberately writes no resolved class back, so every next layer
lookup resolves its descriptor again -- the one registered for the
code, or the fallback for :class:`~pcapkit.protocols.misc.raw.Raw`
Expand Down
4 changes: 2 additions & 2 deletions pcapkit/corekit/sentinels.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -571,8 +571,8 @@ def __bool__(self) -> 'Literal[False]':
#: own ``__keywords__`` out of its :attr:`~object.__dict__`, where
#: :obj:`None` is itself a meaningful value -- the opt-out that says the
#: class cannot enumerate its keywords, cf.
#: :attr:`ProtocolBase.__keywords__
#: <pcapkit.protocols.protocol.ProtocolBase.__keywords__>`. Never leaves
#: :attr:`Protocol.__keywords__
#: <pcapkit.protocols.protocol.Protocol.__keywords__>`. Never leaves
#: :mod:`pcapkit.protocols.protocol`, which imports it from here for exactly
#: that one read. Private by documentation rather than by a
#: leading underscore -- see :class:`AbsentType`'s own docstring.
Expand Down
4 changes: 2 additions & 2 deletions pcapkit/foundation/engines/dpkt.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -551,8 +551,8 @@ def read_frame(self) -> 'DPKTPacket':
try:
packet = protocol(pkt) # type: DPKTPacket
except Exception as exc: # pylint: disable=broad-except
# NOTE: Caught broadly, as :meth:`ProtocolBase.analyze
# <pcapkit.protocols.protocol.ProtocolBase.analyze>` does: dpkt raises
# NOTE: Caught broadly, as :meth:`Protocol.analyze
# <pcapkit.protocols.protocol.Protocol.analyze>` does: dpkt raises
# more than its own ``UnpackError`` while parsing -- dpkt 1.9.8 reads
# ``frag_off`` from whatever header follows an IPv6 Fragment header,
# so a Fragment header followed by ESP or Destination Options raises
Expand Down
4 changes: 2 additions & 2 deletions pcapkit/protocols/application/application.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,8 @@ def from_data(cls, data: '_PT | dict[str, Any]', **kwargs: 'Any') -> 'Self':

Args:
data: Protocol data.
**kwargs: Construction keywords, as for :meth:`ProtocolBase.from_data
<pcapkit.protocols.protocol.ProtocolBase.from_data>`.
**kwargs: Construction keywords, as for :meth:`Protocol.from_data
<pcapkit.protocols.protocol.Protocol.from_data>`.

Returns:
Protocol instance, cut back to what was captured when the header
Expand Down
4 changes: 2 additions & 2 deletions pcapkit/protocols/application/http.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -404,8 +404,8 @@ def from_data(cls, data: '_PT | dict[str, Any]', **kwargs: 'Any') -> 'Self':
into the versioned data model its keys belong to -- ``receipt``
is HTTP/1.*'s and ``sid`` HTTP/2's -- since this class's own data
model carries no version.
**kwargs: As :meth:`ProtocolBase.from_data
<pcapkit.protocols.protocol.ProtocolBase.from_data>`.
**kwargs: As :meth:`Protocol.from_data
<pcapkit.protocols.protocol.Protocol.from_data>`.

Returns:
Protocol instance.
Expand Down
6 changes: 3 additions & 3 deletions pcapkit/protocols/application/httpv2.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,8 +234,8 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_HTTP'

``length`` is resolved against :func:`len` only for *this*
method's own check, and the *original* argument -- ``None``
included -- is what is forwarded to :meth:`ProtocolBase.unpack
<pcapkit.protocols.protocol.ProtocolBase.unpack>`. Collapsing
included -- is what is forwarded to :meth:`Protocol.unpack
<pcapkit.protocols.protocol.Protocol.unpack>`. Collapsing
``None`` to a concrete ``0`` would change what
:meth:`Schema.unpack <pcapkit.protocols.schema.schema.Schema.unpack>`'s own
``prepare`` decorator does with an
Expand All @@ -251,7 +251,7 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_HTTP'
if length is None:
# ``0 < ... < 9`` rather than ``... < 9``: an exhausted stream
# (``len(self) == 0``) is left alone, so ``length`` reaches
# :meth:`ProtocolBase.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`
# :meth:`Protocol.unpack <pcapkit.protocols.protocol.Protocol.unpack>`
# still ``None`` and its ``prepare`` decorator raises
# :exc:`StreamEOFError` as documented above; only a *non-empty*
# short stream is rejected as malformed here.
Expand Down
2 changes: 1 addition & 1 deletion pcapkit/protocols/internet/ah.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ def alias(self) -> 'Literal["AH"]':
"""Acronym of corresponding protocol.

Spelled out rather than left to
:attr:`ProtocolBase.alias <pcapkit.protocols.protocol.ProtocolBase.alias>`'s
:attr:`Protocol.alias <pcapkit.protocols.protocol.Protocol.alias>`'s
class-name default, because
:class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` sits between
this class and that default in the MRO and carries its own
Expand Down
2 changes: 1 addition & 1 deletion pcapkit/protocols/internet/esp.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1022,7 +1022,7 @@ def alias(self) -> 'Literal["ESP"]':
"""Acronym of corresponding protocol.

Spelled out rather than left to
:attr:`ProtocolBase.alias <pcapkit.protocols.protocol.ProtocolBase.alias>`'s
:attr:`Protocol.alias <pcapkit.protocols.protocol.Protocol.alias>`'s
class-name default, because
:class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` sits
between this class and that default in the MRO and carries a concrete
Expand Down
2 changes: 1 addition & 1 deletion pcapkit/protocols/internet/hopopt.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ def alias(self) -> 'Literal["HOPOPT"]':
"""Acronym of corresponding protocol.

Spelled out rather than left to
:attr:`ProtocolBase.alias <pcapkit.protocols.protocol.ProtocolBase.alias>`'s
:attr:`Protocol.alias <pcapkit.protocols.protocol.Protocol.alias>`'s
class-name default, because
:class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` sits between
this class and that default in the MRO and carries its own
Expand Down
12 changes: 6 additions & 6 deletions pcapkit/protocols/internet/internet.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,8 +192,8 @@ def register(cls, code: 'Enum_TransType', protocol: 'ModuleDescriptor[ProtocolBa
pcapkit.utilities.warnings.RegistryWarning: If this protocol number
is already registered, naming the displaced entry and its
replacement so a caller can tell *what* was lost. Fires only
when the incumbent differs from the replacement; see :meth:`ProtocolBase.register
<pcapkit.protocols.protocol.ProtocolBase.register>` for the
when the incumbent differs from the replacement; see :meth:`Protocol.register
<pcapkit.protocols.protocol.Protocol.register>` for the
guard this shares with ``register_protocol``, and for the
shipped descriptor a restore puts back (:issue:`1504`).

Expand All @@ -220,8 +220,8 @@ def from_data(cls, data: '_PT | dict[str, Any]', **kwargs: 'Any') -> 'Self':

Args:
data: Protocol data.
**kwargs: Construction keywords, as for :meth:`ProtocolBase.from_data
<pcapkit.protocols.protocol.ProtocolBase.from_data>`.
**kwargs: Construction keywords, as for :meth:`Protocol.from_data
<pcapkit.protocols.protocol.Protocol.from_data>`.

Returns:
Protocol instance, cut back to what was captured when the header
Expand Down Expand Up @@ -343,8 +343,8 @@ def _rebuilt_exthdr_depth(cls) -> 'int':
def _make_payload(cls, data: 'Data') -> 'ProtocolBase':
"""Create payload from ``data`` for protocol construction.

As :meth:`ProtocolBase._make_payload
<pcapkit.protocols.protocol.ProtocolBase._make_payload>`, but the payload
As :meth:`Protocol._make_payload
<pcapkit.protocols.protocol.Protocol._make_payload>`, but the payload
is built at its place in its chain of IPv6 extension headers, one past
this layer's, since it parses its own octets again. So rebuilding a frame
stops at :data:`~pcapkit.utilities.config.EXTENSION_HEADER_LIMIT` where parsing it did, rather
Expand Down
6 changes: 3 additions & 3 deletions pcapkit/protocols/internet/ipv6_ext.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ class for that code instead (see the bottom of the module), so dispatch
``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
have dedicated classes. When one of *those* raises,
:func:`~pcapkit.corekit.decorators.beholder`
(:meth:`ProtocolBase._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
(:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`)
would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
``next`` and crashes the walk as in path 1.
:meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>`
Expand Down Expand Up @@ -299,7 +299,7 @@ def protocol(self) -> 'Optional[Enum_ExtensionHeader] | Optional[str]':

In the *fallback* role (this instance parsed this module's own schema)
this is **not** the base
:attr:`ProtocolBase.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`
:attr:`Protocol.protocol <pcapkit.protocols.protocol.Protocol.protocol>`
meaning ("name of next layer protocol"). On the owner's ruling for
GitHub issue :issue:`891` it is deliberately repointed at this
instance's *own* identity, i.e. which header's format it parsed, such as
Expand Down Expand Up @@ -327,7 +327,7 @@ class sits between them and
:attr:`~pcapkit.protocols.protocol.Protocol.__data__` rather than an
:func:`isinstance` test on ``self._info``, because a ``make``-only
instance has no ``_info`` at all. Reading it would turn
:attr:`ProtocolBase.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`,
:attr:`Protocol.protocol <pcapkit.protocols.protocol.Protocol.protocol>`,
which only needs ``self._protos``, into an ``AttributeError``;
``tests/protocols/internet/test_ipv6_extension_unit.py`` constructs
exactly that instance.
Expand Down
2 changes: 1 addition & 1 deletion pcapkit/protocols/internet/mh.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1290,7 +1290,7 @@ def alias(self) -> 'Literal["MH"]':
"""Acronym of corresponding protocol.

Spelled out rather than left to
:attr:`ProtocolBase.alias <pcapkit.protocols.protocol.ProtocolBase.alias>`'s
:attr:`Protocol.alias <pcapkit.protocols.protocol.Protocol.alias>`'s
class-name default, because
:class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` sits
between this class and that default in the MRO and carries a concrete
Expand Down
6 changes: 3 additions & 3 deletions pcapkit/protocols/link/link.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,8 +149,8 @@ def register(cls, code: 'Enum_EtherType', protocol: 'ModuleDescriptor[ProtocolBa
already registered, naming the displaced entry and its
replacement so a caller can tell *what* was lost. Fires only
when the incumbent differs from the replacement -- see
:meth:`ProtocolBase.register
<pcapkit.protocols.protocol.ProtocolBase.register>` for the
:meth:`Protocol.register
<pcapkit.protocols.protocol.Protocol.register>` for the
guard this shares with ``register_protocol``, and for the
shipped descriptor that a restore puts back (:issue:`1504`).

Expand All @@ -177,7 +177,7 @@ def from_data(cls, data: '_PT | dict[str, Any]', **kwargs: 'Any') -> 'Self':

Args:
data: Protocol data.
**kwargs: Construction keywords, as for :meth:`ProtocolBase.from_data
**kwargs: Construction keywords, as for :meth:`Protocol.from_data
<pcapkit.protocols.protocol.Protocol.from_data>`.

Returns:
Expand Down
4 changes: 2 additions & 2 deletions pcapkit/protocols/misc/null.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ def protochain(self) -> 'None': # type: ignore[override]

.. versionchanged:: 1.5.0

Narrows :attr:`ProtocolBase.protochain
<pcapkit.protocols.protocol.ProtocolBase.protochain>`'s declared
Narrows :attr:`Protocol.protochain
<pcapkit.protocols.protocol.Protocol.protochain>`'s declared
type from :class:`~pcapkit.corekit.protochain.ProtoChain` to
:obj:`None`, the value ``self._protos`` already held here; the fix
is to the declaration, not the runtime value (:issue:`2317`).
Expand Down
4 changes: 2 additions & 2 deletions pcapkit/protocols/misc/pcap/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,8 +172,8 @@ def register(cls, code: 'Enum_LinkType', protocol: 'ModuleDescriptor[ProtocolBas
already registered against PCAP frames, naming the displaced
entry and its replacement so a caller can tell *what* was lost.
Fires only when the incumbent differs from the replacement --
see :meth:`ProtocolBase.register
<pcapkit.protocols.protocol.ProtocolBase.register>` for the
see :meth:`Protocol.register
<pcapkit.protocols.protocol.Protocol.register>` for the
guard this shares with ``register_protocol``, and for the
shipped descriptor a restore puts back (:issue:`1504`).

Expand Down
4 changes: 2 additions & 2 deletions pcapkit/protocols/misc/pcap/header.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,8 +287,8 @@ def from_data(cls, data: 'Data_Header | dict[str, Any]', **kwargs: 'Any') -> 'Se

Args:
data: Protocol data.
**kwargs: Construction keywords, as for :meth:`ProtocolBase.from_data
<pcapkit.protocols.protocol.ProtocolBase.from_data>`.
**kwargs: Construction keywords, as for :meth:`Protocol.from_data
<pcapkit.protocols.protocol.Protocol.from_data>`.

Returns:
Protocol instance, cut back to what was captured when the header
Expand Down
Loading
Loading