Skip to content

refactor(internet): name IGMP member classes after their modules (#2529) #2542

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 2 commits into from
Nov 1, 2026
+312 −252
Merged

refactor(internet): name IGMP member classes after their modules (#2529) #2542

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92fd4ca
refactor(internet): name IGMP member classes after their modules (#2529)
JarryShaw Nov 1, 2026
00b11ad
fix(internet): clear IGMP reachability gaps and per-version output ke…
JarryShaw Nov 1, 2026
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
10 changes: 10 additions & 0 deletions docs/source/contributing/conventions/documentation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,16 @@ deprecation note where a user could have depended on the thing, and deleted outr
where it never shipped. The ``rarp`` entry above needed no note for that second reason.
Asked and ruled on :issue:`719`.

Version Directives
~~~~~~~~~~~~~~~~~~

**One** ``versionadded`` **per version in a docstring or prose block.** Directives of
the same version there merge into one. **A body that only names the thing added and
cites its issue or pull request is dropped**, leaving the bare tag: the summary above
already names the thing, so the body adds nothing. A body with content of its own
stays, such as a move (*Moved here from* ...), a rename or a takeover. Ruled on
:issue:`2530`.

Format and Mechanics
~~~~~~~~~~~~~~~~~~~~

Expand Down
3 changes: 2 additions & 1 deletion docs/source/contributing/conventions/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ House Conventions
* :ref:`registry-protocol` -- :mod:`pcapkit.const` again;
* :ref:`extension-header-subclassing` -- a protocol class hierarchy;
* :ref:`protocol-family-grouping` -- how a protocol family's base and members
spell :meth:`~pcapkit.protocols.protocol.Protocol.id`;
spell :meth:`~pcapkit.protocols.protocol.Protocol.id`, and how a protocol class
is named after its module;
* :ref:`protocol-member-order` -- the order of members in a protocol class body;
* :ref:`protocol-layer-placement` -- which subpackage a dissector belongs in;
* :ref:`process` -- the repository rather than any of its code;
Expand Down
38 changes: 30 additions & 8 deletions docs/source/contributing/conventions/protocol-family-grouping.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,9 @@ Member Shapes
- the member's own name only
- :class:`~pcapkit.protocols.internet.ah.AH` ``('AH',)``,
:class:`~pcapkit.protocols.internet.esp.ESP` ``('ESP',)``;
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` ``('IGMPv2',)`` and
:class:`IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMP>` ``('IGMPv3',)`` --
:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>` narrows the same way,
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMPv2>` ``('IGMPv2',)`` and
:class:`IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMPv3>` ``('IGMPv3',)`` --
:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMPv1>` narrows the same way,
but to the RFC canonical name rather than a versioned one
(:ref:`protocol-family-canonical-names`)
* - Family-inclusive
Expand Down Expand Up @@ -121,10 +121,10 @@ and its ``name`` carries no "version 4". ``ICMPv6`` keeps its own version, since

**IGMPv1 follows the same shape, by the same reasoning** (:issue:`2439`, :pr:`2506`).
:rfc:`1112` names IGMPv1's protocol plain ``IGMP``, so
:meth:`IGMPv1.id() <pcapkit.protocols.internet.igmpv1.IGMP.id>` is ``('IGMP',)`` and
:meth:`IGMPv1.id() <pcapkit.protocols.internet.igmpv1.IGMPv1.id>` is ``('IGMP',)`` and
its ``alias`` is ``'IGMP'``, while
:meth:`IGMPv2.id() <pcapkit.protocols.internet.igmpv2.IGMP.id>` and
:meth:`IGMPv3.id() <pcapkit.protocols.internet.igmpv3.IGMP.id>` keep their own
:meth:`IGMPv2.id() <pcapkit.protocols.internet.igmpv2.IGMPv2.id>` and
:meth:`IGMPv3.id() <pcapkit.protocols.internet.igmpv3.IGMPv3.id>` keep their own
versions, ``('IGMPv2',)`` and ``('IGMPv3',)``, since :rfc:`2236` and :rfc:`3376` name
them with one. The family base's ``id()`` follows:
:meth:`IGMP.id() <pcapkit.protocols.internet.igmp.IGMP.id>` is
Expand Down Expand Up @@ -175,5 +175,27 @@ No Invented Suffixes
:class:`~pcapkit.protocols.application.http.HTTP`,
:class:`~pcapkit.protocols.link.vlan.VLAN` and
:class:`~pcapkit.protocols.link.l2tp.L2TP` are the precedent. No ``_Family`` suffix is
added (:pr:`2446`). A member may take a versioned class name, as
:ref:`above <protocol-family-canonical-names>` describes.
added (:pr:`2446`).

**A protocol class takes its module's name**, whatever its canonical name and
``id()``. The family base takes the family's name and a member its module's versioned
name: :mod:`~pcapkit.protocols.internet.igmpv1` holds
:class:`~pcapkit.protocols.internet.igmpv1.IGMPv1`, though its ``id()`` is ``('IGMP',)``
(:ref:`above <protocol-family-canonical-names>`). **A module holds one protocol
class.** :mod:`~pcapkit.protocols.protocol` is exempt: its
:class:`~pcapkit.protocols.protocol.ProtocolBase` and
:class:`~pcapkit.protocols.protocol.Protocol` are framework bases rather than
dissectors. Both ruled on :issue:`2529`.

The name match ignores case and underscores: :mod:`~pcapkit.protocols.link.c_tag` holds
:class:`~pcapkit.protocols.link.c_tag.C_Tag` and :mod:`~pcapkit.protocols.link.linux_sll1`
holds :class:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1`. **The** ``schema/`` **and**
``data/`` **modules follow the same layout**: the top-level class takes the module's
name, and sub-structure classes such as
:class:`~pcapkit.protocols.schema.internet.igmpv3.Query` share its module. Ruled on
:issue:`2529`, where the classes that do not match yet are pending:
:class:`httpv1.HTTP <pcapkit.protocols.application.httpv1.HTTP>`,
:class:`httpv2.HTTP <pcapkit.protocols.application.httpv2.HTTP>`,
:class:`arp.InARP <pcapkit.protocols.link.arp.InARP>`,
:class:`tls.SSLv3 <pcapkit.protocols.application.tls.SSLv3>` and
:class:`null.NoPayload <pcapkit.protocols.misc.null.NoPayload>`.
6 changes: 3 additions & 3 deletions docs/source/contributing/pep.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1101,9 +1101,9 @@ checksums (ICMPv6 does; ICMPv4 does not) and parse without checksum computation
(:issue:`2470`).

**IGMP — done within wave 2** (:issue:`2439`, :issue:`2448`).
The three concrete classes :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>`,
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` and
:class:`IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMP>` share one read path on
The three concrete classes :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMPv1>`,
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMPv2>` and
:class:`IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMPv3>` share one read path on
the abstract :class:`~pcapkit.protocols.internet.igmp.IGMP` base, which
:meth:`~pcapkit.protocols.internet.igmp.IGMP._classify` dispatches to the right
one. IGMPv1/v2 share one 8-octet message shape; IGMPv3 (:rfc:`3376`) adds the
Expand Down
6 changes: 3 additions & 3 deletions docs/source/ext.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,11 +80,11 @@ The protocol classes :mod:`pcapkit` ships:
+ +----------------+-----------------------+-------------------------------------------------------------+
| | | :class:`pcapkit.protocols.internet.igmp.IGMP` |
+ + +-----------------------+-------------------------------------------------------------+
| | | :class:`pcapkit.protocols.internet.igmpv1.IGMP` |
| | | :class:`pcapkit.protocols.internet.igmpv1.IGMPv1` |
+ + IGMP Family +-----------------------+-------------------------------------------------------------+
| | | :class:`pcapkit.protocols.internet.igmpv2.IGMP` |
| | | :class:`pcapkit.protocols.internet.igmpv2.IGMPv2` |
+ + +-----------------------+-------------------------------------------------------------+
| | | :class:`pcapkit.protocols.internet.igmpv3.IGMP` |
| | | :class:`pcapkit.protocols.internet.igmpv3.IGMPv3` |
+------------------------------------------------------------------+----------------+-----------------------+-------------------------------------------------------------+
| Transport Layer | :class:`pcapkit.protocols.transport.tcp.TCP` |
+ (:class:`~pcapkit.protocols.transport.transport.Transport` +----------------+-----------------------+-------------------------------------------------------------+
Expand Down
6 changes: 3 additions & 3 deletions docs/source/pcapkit/protocols/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,9 +148,9 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
click ESP "internet/esp.html#pcapkit.protocols.internet.esp.ESP"
click HIP "internet/hip.html#pcapkit.protocols.internet.hip.HIP"
click IGMP "internet/igmp.html#pcapkit.protocols.internet.igmp.IGMP"
click IGMPv1 "internet/igmpv1.html#pcapkit.protocols.internet.igmpv1.IGMP"
click IGMPv2 "internet/igmpv2.html#pcapkit.protocols.internet.igmpv2.IGMP"
click IGMPv3 "internet/igmpv3.html#pcapkit.protocols.internet.igmpv3.IGMP"
click IGMPv1 "internet/igmpv1.html#pcapkit.protocols.internet.igmpv1.IGMPv1"
click IGMPv2 "internet/igmpv2.html#pcapkit.protocols.internet.igmpv2.IGMPv2"
click IGMPv3 "internet/igmpv3.html#pcapkit.protocols.internet.igmpv3.IGMPv3"
click HOPOPT "internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT"
click ICMP "internet/icmp.html#pcapkit.protocols.internet.icmp.ICMP"
click ICMPv4 "internet/icmpv4.html#pcapkit.protocols.internet.icmpv4.ICMPv4"
Expand Down
17 changes: 10 additions & 7 deletions docs/source/pcapkit/protocols/internet/igmp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,26 @@ IGMP - Internet Group Management Protocol
:class:`~pcapkit.protocols.internet.igmp.IGMP`, the abstract base of the
Internet Group Management Protocol (IGMP) [*]_ versions 1, 2 and 3. IGMPv1
and IGMPv2 share the 8-octet structure below.
:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>` and
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` set
:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMPv1>` and
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMPv2>` set
:attr:`~pcapkit.protocols.internet.igmp.IGMP.version` and reuse this schema and
data model as-is; IGMPv3's wire format differs materially by message, so
:class:`IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMP>` carries its own
:class:`IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMPv3>` carries its own
instead -- see :doc:`igmpv3`.
:attr:`~pcapkit.protocols.internet.igmp.IGMP.alias` names the protocol each
message is read as: ``'IGMP'`` for IGMPv1, the name :rfc:`1112` gives it, and
``'IGMPv2'`` or ``'IGMPv3'`` for the others.

The structure is keyed as for IGMPv1; an IGMPv2 message's keys start ``igmpv2``
instead:

======= ========= ========================= ===================================
Octets Bits Name Description
======= ========= ========================= ===================================
0 0 ``igmp.type`` Type
1 8 ``igmp.max_resp_time`` Max Response Time
2 16 ``igmp.checksum`` Checksum
4 32 ``igmp.group`` Group Address
0 0 ``igmpv1.type`` Type
1 8 ``igmpv1.max_resp_time`` Max Response Time
2 16 ``igmpv1.checksum`` Checksum
4 32 ``igmpv1.group`` Group Address
======= ========= ========================= ===================================

.. autoclass:: pcapkit.protocols.internet.igmp.IGMP
Expand Down
6 changes: 3 additions & 3 deletions docs/source/pcapkit/protocols/internet/igmpv1.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ IGMPv1 - Internet Group Management Protocol version 1
.. module:: pcapkit.protocols.internet.igmpv1

:mod:`pcapkit.protocols.internet.igmpv1` contains
:class:`~pcapkit.protocols.internet.igmpv1.IGMP`, which implements an
:class:`~pcapkit.protocols.internet.igmpv1.IGMPv1`, which implements an
extractor for Internet Group Management Protocol version 1 (IGMPv1)
[:rfc:`1112`]. It shares its header schema and data model with
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` -- see
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMPv2>` -- see
:mod:`~pcapkit.protocols.internet.igmp` for both.

.. autoclass:: pcapkit.protocols.internet.igmpv1.IGMP
.. autoclass:: pcapkit.protocols.internet.igmpv1.IGMPv1
:no-members:
:show-inheritance:

Expand Down
6 changes: 3 additions & 3 deletions docs/source/pcapkit/protocols/internet/igmpv2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ IGMPv2 - Internet Group Management Protocol version 2
.. module:: pcapkit.protocols.internet.igmpv2

:mod:`pcapkit.protocols.internet.igmpv2` contains
:class:`~pcapkit.protocols.internet.igmpv2.IGMP`, which implements an
:class:`~pcapkit.protocols.internet.igmpv2.IGMPv2`, which implements an
extractor for Internet Group Management Protocol version 2 (IGMPv2)
[:rfc:`2236`]. It shares its header schema and data model with
:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>` -- see
:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMPv1>` -- see
:mod:`~pcapkit.protocols.internet.igmp` for both.

.. autoclass:: pcapkit.protocols.internet.igmpv2.IGMP
.. autoclass:: pcapkit.protocols.internet.igmpv2.IGMPv2
:no-members:
:show-inheritance:

Expand Down
42 changes: 22 additions & 20 deletions docs/source/pcapkit/protocols/internet/igmpv3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ IGMPv3 - Internet Group Management Protocol version 3
.. module:: pcapkit.protocols.internet.igmpv3

:mod:`pcapkit.protocols.internet.igmpv3` contains
:class:`~pcapkit.protocols.internet.igmpv3.IGMP`, which implements an
:class:`~pcapkit.protocols.internet.igmpv3.IGMPv3`, which implements an
extractor for Internet Group Management Protocol version 3 (IGMPv3)
[:rfc:`3376`]. Unlike :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>`
and :class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>`, which reuse the
[:rfc:`3376`]. Unlike :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMPv1>`
and :class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMPv2>`, which reuse the
abstract base's own 8-octet schema and data model (see
:mod:`~pcapkit.protocols.internet.igmp`), IGMPv3 defines two message shapes
of its own:
Expand All @@ -19,14 +19,16 @@ appends a source-list extension:
======= ========= ================================== ===================================
Octets Bits Name Description
======= ========= ================================== ===================================
0 0 ``igmp.type`` Type
1 8 ``igmp.body.max_resp_code`` Max Response Code
2 16 ``igmp.body.checksum`` Checksum
4 32 ``igmp.body.group`` Group Address
8 64 ``igmp.body.ext.flags`` Resv / S Flag / QRV
9 72 ``igmp.body.ext.qqic`` Querier's Query Interval Code
10 80 ``igmp.body.ext.num_sources`` Number of Sources (N)
12 96 ``igmp.body.ext.sources`` Source Address [1..N]
0 0 ``igmpv3.type`` Type
1 8 ``igmpv3.max_resp_code`` Max Response Code
2 16 ``igmpv3.checksum`` Checksum
4 32 ``igmpv3.group`` Group Address
8 64 ``igmpv3.resv`` Reserved (Resv)
8 68 ``igmpv3.s_flag`` Suppress Router-Side Processing (S)
8 69 ``igmpv3.qrv`` Querier's Robustness Variable (QRV)
9 72 ``igmpv3.qqic`` Querier's Query Interval Code
10 80 Number of Sources (N)
12 96 ``igmpv3.sources`` Source Address [1..N]
======= ========= ================================== ===================================

An IGMPv3 Membership Report (type ``0x22``) has an unrelated, materially
Expand All @@ -35,15 +37,15 @@ different shape of its own:
======= ========= ================================== ===================================
Octets Bits Name Description
======= ========= ================================== ===================================
0 0 ``igmp.type`` Type
1 8 ``igmp.body.reserved_1`` Reserved
2 16 ``igmp.body.checksum`` Checksum
4 32 ``igmp.body.reserved_2`` Reserved
6 48 ``igmp.body.num_group_records`` Number of Group Records (M)
8 64 ``igmp.body.records`` Group Record [1..M]
0 0 ``igmpv3.type`` Type
1 8 ``igmpv3.reserved_1`` Reserved
2 16 ``igmpv3.checksum`` Checksum
4 32 ``igmpv3.reserved_2`` Reserved
6 48 ``igmpv3.num_group_records`` Number of Group Records (M)
8 64 ``igmpv3.records`` Group Record [1..M]
======= ========= ================================== ===================================

.. autoclass:: pcapkit.protocols.internet.igmpv3.IGMP
.. autoclass:: pcapkit.protocols.internet.igmpv3.IGMPv3
:no-members:
:show-inheritance:

Expand All @@ -63,7 +65,7 @@ Header Schemas

.. module:: pcapkit.protocols.schema.internet.igmpv3

.. autoclass:: pcapkit.protocols.schema.internet.igmpv3.IGMP
.. autoclass:: pcapkit.protocols.schema.internet.igmpv3.IGMPv3
:members:
:show-inheritance:

Expand All @@ -88,7 +90,7 @@ Data Models

.. module:: pcapkit.protocols.data.internet.igmpv3

.. autoclass:: pcapkit.protocols.data.internet.igmpv3.IGMP
.. autoclass:: pcapkit.protocols.data.internet.igmpv3.IGMPv3
:members:
:show-inheritance:

Expand Down
4 changes: 2 additions & 2 deletions examples/generators/dispatch.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -399,12 +399,12 @@ def _internet_payload(code: 'int') -> 'bytes':
payload=_tcp(9999)))
if code == TransType.IGMP:
from pcapkit.const.igmp.type import Type
from pcapkit.protocols.internet.igmpv2 import IGMP
from pcapkit.protocols.internet.igmpv2 import IGMPv2

# A General Query: an IGMPv1/v2 message is the 8-octet header and
# nothing else, so there is no further payload to wrap. A nonzero
# max_resp_time makes it IGMPv2, the class IGMP dispatches it to.
return bytes(IGMP(type=Type.IGMP_Membership_Query, max_resp_time=100, group='0.0.0.0'))
return bytes(IGMPv2(type=Type.IGMP_Membership_Query, max_resp_time=100, group='0.0.0.0'))
if code == TransType.IPv6_NoNxt:
# The registered target for this code *is* Raw -- there is no
# dissector to hand it, "no next header" is the whole point -- so any
Expand Down
2 changes: 1 addition & 1 deletion pcapkit/protocols/data/internet/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@
# Internet Group Management Protocol
from pcapkit.protocols.data.internet.igmp import IGMP
from pcapkit.protocols.data.internet.igmpv3 import GroupRecord as IGMPv3_GroupRecord
from pcapkit.protocols.data.internet.igmpv3 import IGMP as IGMPv3
from pcapkit.protocols.data.internet.igmpv3 import IGMPv3
from pcapkit.protocols.data.internet.igmpv3 import Query as IGMPv3_Query
from pcapkit.protocols.data.internet.igmpv3 import Report as IGMPv3_Report

Expand Down
Loading
Loading