refactor(application)!: move DRARP into its own module (#2529)

docs/source/contributing/conventions/protocol-family-grouping.rst

@@ -92,7 +92,7 @@ Only :class:`~pcapkit.protocols.application.rarp.RARP` ``('RARP', 'DRARP')`` is
 to EtherType ``0x8035``
 (:attr:`~pcapkit.const.reg.ethertype.EtherType.Reverse_Address_Resolution_Protocol`).
 A parsed RARP takes ``DRARP`` as its alias for operation 5, and
-:class:`~pcapkit.protocols.application.rarp.DRARP` ``('DRARP',)`` inherits the
+:class:`~pcapkit.protocols.application.drarp.DRARP` ``('DRARP',)`` inherits the
 ``__index__`` of RARP.
 
 A family-inclusive member is selected by any sibling's registry key (a key of

docs/source/ext.rst

@@ -108,7 +108,7 @@ The protocol classes :mod:`pcapkit` ships:
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  |                | :class:`pcapkit.protocols.application.rarp.RARP`                                    |
 +                                                                  + RARP Family    +-----------------------+-------------------------------------------------------------+
-|                                                                  |                | :class:`pcapkit.protocols.application.rarp.DRARP`                                   |
+|                                                                  |                | :class:`pcapkit.protocols.application.drarp.DRARP`                                  |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  |                | :class:`pcapkit.protocols.application.ssl.SSL`                                      |
 +                                                                  +                +-----------------------+-------------------------------------------------------------+

docs/source/pcapkit/protocols/application/drarp.rst

@@ -0,0 +1,30 @@
+DRARP - Dynamic Reverse Address Resolution Protocol
+===================================================
+
+.. module:: pcapkit.protocols.application.drarp
+
+:mod:`pcapkit.protocols.application.drarp` contains
+:class:`~pcapkit.protocols.application.drarp.DRARP` only,
+which implements an extractor for Dynamic Reverse Address
+Resolution Protocol (DRARP) [*]_, whose frame is the one
+:mod:`pcapkit.protocols.application.rarp` describes.
+
+Nothing dispatches to :class:`~pcapkit.protocols.application.drarp.DRARP`:
+under EtherType ``0x8035``, a DRARP operation parses as
+:class:`~pcapkit.protocols.application.rarp.RARP` with alias ``DRARP``.
+
+.. versionadded:: 1.6.0
+
+   Moved here from :mod:`pcapkit.protocols.application.rarp`, which keeps
+   :class:`~pcapkit.protocols.application.rarp.RARP` alone, since a module
+   holds one protocol class, named after it (:issue:`2529`).
+
+.. autoclass:: pcapkit.protocols.application.drarp.DRARP
+   :no-members:
+   :show-inheritance:
+
+   .. automethod:: id
+
+.. rubric:: Footnotes
+
+.. [*] https://datatracker.ietf.org/doc/html/rfc1931

docs/source/pcapkit/protocols/application/ftp_data.rst

@@ -13,10 +13,8 @@ Transfer Protocol (FTP) [*]_, whose octets it keeps undissected.
    Moved here from :mod:`pcapkit.protocols.application.ftp`, which keeps
    :class:`~pcapkit.protocols.application.ftp.FTP` alone. The control and data
    channels are dispatched separately -- FTP at TCP port 21, the data channel
-   at port 20 -- so each is a protocol of its own and gets its own module,
-   unlike :class:`~pcapkit.protocols.application.rarp.RARP` and
-   :class:`~pcapkit.protocols.application.rarp.DRARP`, which one dispatch
-   entry reaches (:issue:`2285`).
+   at port 20 -- so each is a protocol of its own and gets its own module
+   (:issue:`2285`).
 
 .. autoclass:: pcapkit.protocols.application.ftp_data.FTP_DATA
    :no-members:

docs/source/pcapkit/protocols/application/index.rst

@@ -22,6 +22,7 @@ function rather than encapsulation, see
    ngap
    ospf
    rarp
+   drarp
    ssl
    sslv2
    tls

docs/source/pcapkit/protocols/application/rarp.rst

@@ -1,14 +1,13 @@
-RARP/DRARP - (Dynamic) Reverse Address Resolution Protocol
-==========================================================
+RARP - Reverse Address Resolution Protocol
+==========================================
 
 .. module:: pcapkit.protocols.application.rarp
 
 :mod:`pcapkit.protocols.application.rarp` contains
-:class:`~pcapkit.protocols.application.rarp.RARP` and
-:class:`~pcapkit.protocols.application.rarp.DRARP`,
-which implement extractors for (Dynamic) Reverse
-Address Resolution Protocol (RARP/DRARP) [*]_,
-whose structure is described as below:
+:class:`~pcapkit.protocols.application.rarp.RARP` only,
+which implements an extractor for Reverse Address
+Resolution Protocol (RARP) [*]_, whose structure is
+described as below:
 
 ====== ========= ========================= =========================
 Octets      Bits        Name                    Description
@@ -28,7 +27,7 @@ Octets      Bits        Name                    Description
 
    Moved here from ``pcapkit.protocols.link.rarp``.
    :class:`~pcapkit.protocols.application.rarp.RARP` and
-   :class:`~pcapkit.protocols.application.rarp.DRARP` derive from
+   :class:`~pcapkit.protocols.application.drarp.DRARP` derive from
    :class:`~pcapkit.protocols.application.application.Application` as well as
    :class:`~pcapkit.protocols.link.arp.ARP`, so their layer is
    ``'Application'`` (:issue:`719`).
@@ -38,6 +37,12 @@ Octets      Bits        Name                    Description
    ``pcapkit.protocols.link.rarp``, and the ``RARP`` and ``DRARP`` names
    that :mod:`pcapkit.protocols.link` exported, with no alias (:issue:`719`).
 
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.application.rarp.DRARP``, with no alias. The class
+   moved to :mod:`pcapkit.protocols.application.drarp`, since a module holds
+   one protocol class, named after it (:issue:`2529`).
+
 .. autoclass:: pcapkit.protocols.application.rarp.RARP
    :no-members:
    :show-inheritance:
@@ -46,12 +51,6 @@ Octets      Bits        Name                    Description
 
    .. automethod:: __index__
 
-.. autoclass:: pcapkit.protocols.application.rarp.DRARP
-   :no-members:
-   :show-inheritance:
-
-   .. automethod:: id
-
 .. rubric:: Footnotes
 
 .. [*] http://en.wikipedia.org/wiki/Address_Resolution_Protocol

docs/source/pcapkit/protocols/index.rst

@@ -181,7 +181,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        click NGAP "application/ngap.html#pcapkit.protocols.application.ngap.NGAP"
        click OSPF "application/ospf.html#pcapkit.protocols.application.ospf.OSPF"
        click RARP "application/rarp.html#pcapkit.protocols.application.rarp.RARP"
-       click DRARP "application/rarp.html#pcapkit.protocols.application.rarp.DRARP"
+       click DRARP "application/drarp.html#pcapkit.protocols.application.drarp.DRARP"
        click SSL "application/ssl.html#pcapkit.protocols.application.ssl.SSL"
        click SSLv2 "application/sslv2.html#pcapkit.protocols.application.sslv2.SSLv2"
        click TLS "application/tls.html#pcapkit.protocols.application.tls.TLS"

docs/source/pcapkit/protocols/link/c_tag.rst

@@ -16,9 +16,10 @@ identity -- :attr:`~pcapkit.protocols.link.c_tag.C_Tag.name`,
 :meth:`~pcapkit.protocols.link.c_tag.C_Tag.id` -- and its registry index.
 
 It has a module of its own, apart from
-:class:`~pcapkit.protocols.link.s_tag.S_Tag`, because the two are reached through
-*different* registry indices, ``0x8100`` against ``0x88A8``; see
-:mod:`pcapkit.protocols.link.vlan` for the rule.
+:class:`~pcapkit.protocols.link.s_tag.S_Tag`, since a module holds one protocol
+class, named after it, with only the framework bases in
+:mod:`pcapkit.protocols.protocol` exempt (:issue:`2529`). The two tags are
+reached through different registry indices, ``0x8100`` against ``0x88A8``.
 
 .. autoclass:: pcapkit.protocols.link.c_tag.C_Tag
    :no-members:

docs/source/pcapkit/protocols/link/l2tp.rst

@@ -45,8 +45,7 @@ directly over IP as **protocol number 115**. That second route is why
 :attr:`Internet.__proto__ <pcapkit.protocols.internet.internet.Internet.__proto__>`
 leaves 115 unbound: the binding waits on an ``L2TPv3`` class. It would also be
 the first member of this family with a real
-:meth:`~pcapkit.protocols.protocol.Protocol.__index__`, and so the first that
-needs a module of its own under the project's one-module-per-index rule.
+:meth:`~pcapkit.protocols.protocol.Protocol.__index__`.
 
 **L2F** [:rfc:`2341`] is reached when the version nibble reads ``1``. It is *not*
 an earlier version of L2TP: :rfc:`2661` §3.1 requires ``Ver`` to be 2 and reserves

docs/source/pcapkit/protocols/link/s_tag.rst

@@ -15,9 +15,10 @@ identity -- :attr:`~pcapkit.protocols.link.s_tag.S_Tag.name`,
 :meth:`~pcapkit.protocols.link.s_tag.S_Tag.id` -- and its registry index.
 
 It has a module of its own, apart from
-:class:`~pcapkit.protocols.link.c_tag.C_Tag`, because the two are reached through
-*different* registry indices, ``0x88A8`` against ``0x8100``; see
-:mod:`pcapkit.protocols.link.vlan` for the rule.
+:class:`~pcapkit.protocols.link.c_tag.C_Tag`, since a module holds one protocol
+class, named after it, with only the framework bases in
+:mod:`pcapkit.protocols.protocol` exempt (:issue:`2529`). The two tags are
+reached through different registry indices, ``0x88A8`` against ``0x8100``.
 
 .. autoclass:: pcapkit.protocols.link.s_tag.S_Tag
    :no-members:

docs/source/pcapkit/protocols/link/vlan.rst

@@ -56,13 +56,11 @@ next-EtherType is ``0x8100``, which selects a customer tag in turn:
 would nest a ``c_tag`` inside a ``c_tag``, leaving nothing to say which was the
 service tag.
 
-Two EtherTypes also mean two :meth:`~pcapkit.protocols.protocol.Protocol.__index__`
-values, which is the project's rule for separate modules: siblings that *share* an
-index may share a module, as :class:`~pcapkit.protocols.link.arp.InARP` shares
-:mod:`~pcapkit.protocols.link.arp` and
-:class:`~pcapkit.protocols.application.rarp.DRARP` shares
-:mod:`~pcapkit.protocols.application.rarp`. This base is abstract, nothing
-dispatches to it, and it declares no index, so its ``__index__`` raises.
+Each tag has a module of its own because a module holds one protocol class,
+named after it, with only the framework bases in :mod:`pcapkit.protocols.protocol`
+exempt (:issue:`2529`). This base is abstract, nothing dispatches to it, and it
+declares no :meth:`~pcapkit.protocols.protocol.Protocol.__index__`, so its
+``__index__`` raises.
 
 .. autoclass:: pcapkit.protocols.link.vlan.VLAN
    :no-members:

pcapkit/protocols/application/__init__.py

@@ -27,7 +27,8 @@
 from pcapkit.protocols.application.httpv2 import HTTP as HTTPv2
 from pcapkit.protocols.application.ngap import NGAP
 from pcapkit.protocols.application.ospf import OSPF
-from pcapkit.protocols.application.rarp import RARP, DRARP
+from pcapkit.protocols.application.rarp import RARP
+from pcapkit.protocols.application.drarp import DRARP
 from pcapkit.protocols.application.sslv2 import SSLv2
 from pcapkit.protocols.application.tls import TLS, SSLv3
 from pcapkit.protocols.application.dtls import DTLS

pcapkit/protocols/application/drarp.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""DRARP - Dynamic Reverse Address Resolution Protocol
+=========================================================
+
+.. module:: pcapkit.protocols.application.drarp
+
+:mod:`pcapkit.protocols.application.drarp` contains
+:class:`~pcapkit.protocols.application.drarp.DRARP` only,
+which implements an extractor for Dynamic Reverse Address
+Resolution Protocol (DRARP) [*]_, whose frame is the one
+:mod:`pcapkit.protocols.application.rarp` describes.
+
+Nothing dispatches to :class:`~pcapkit.protocols.application.drarp.DRARP`:
+under EtherType ``0x8035``, a DRARP operation parses as
+:class:`~pcapkit.protocols.application.rarp.RARP` with alias ``DRARP``.
+
+.. [*] https://datatracker.ietf.org/doc/html/rfc1931
+
+.. versionadded:: 1.6.0
+
+   Moved here from :mod:`pcapkit.protocols.application.rarp`, which keeps
+   :class:`~pcapkit.protocols.application.rarp.RARP` alone, since a module
+   holds one protocol class, named after it (:issue:`2529`).
+
+"""
+from typing import TYPE_CHECKING
+
+from pcapkit.protocols.application.rarp import RARP
+from pcapkit.protocols.data.link.arp import ARP as Data_ARP
+from pcapkit.protocols.schema.link.arp import ARP as Schema_ARP
+
+if TYPE_CHECKING:
+    from typing_extensions import Literal
+
+__all__ = ['DRARP']
+
+
+class DRARP(RARP, schema=Schema_ARP, data=Data_ARP):
+    """This class implements Dynamic Reverse Address Resolution Protocol.
+
+    Inherits RARP's bases unchanged, so ``layer == 'Application'`` here too --
+    :rfc:`1931` makes it RARP with dynamic allocation, the same function and so
+    the same layer.
+
+    """
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    @classmethod
+    def id(cls) -> 'tuple[Literal["DRARP"]]':  # type: ignore[override]
+        """Index ID of the protocol."""
+        return ('DRARP',)

pcapkit/protocols/application/ftp_data.py

@@ -16,10 +16,8 @@
    Moved here from :mod:`pcapkit.protocols.application.ftp`, which keeps
    :class:`~pcapkit.protocols.application.ftp.FTP` alone. The control and data
    channels are dispatched separately -- FTP at TCP port 21, the data channel
-   at port 20 -- so each is a protocol of its own and gets its own module,
-   unlike :class:`~pcapkit.protocols.application.rarp.RARP` and
-   :class:`~pcapkit.protocols.application.rarp.DRARP`, which one dispatch
-   entry reaches (:issue:`2285`).
+   at port 20 -- so each is a protocol of its own and gets its own module
+   (:issue:`2285`).
 
 """
 from typing import TYPE_CHECKING

pcapkit/protocols/application/rarp.py

@@ -1,15 +1,14 @@
 # -*- coding: utf-8 -*-
-"""RARP/DRARP - (Dynamic) Reverse Address Resolution Protocol
-================================================================
+"""RARP - Reverse Address Resolution Protocol
+================================================
 
 .. module:: pcapkit.protocols.application.rarp
 
 :mod:`pcapkit.protocols.application.rarp` contains
-:class:`~pcapkit.protocols.application.rarp.RARP` and
-:class:`~pcapkit.protocols.application.rarp.DRARP`,
-which implement extractors for (Dynamic) Reverse
-Address Resolution Protocol (RARP/DRARP) [*]_,
-whose structure is described as below:
+:class:`~pcapkit.protocols.application.rarp.RARP` only,
+which implements an extractor for Reverse Address
+Resolution Protocol (RARP) [*]_, whose structure is
+described as below:
 
 ====== ========= ========================= =========================
 Octets      Bits        Name                    Description
@@ -31,7 +30,7 @@
 
    Moved here from ``pcapkit.protocols.link.rarp``.
    :class:`~pcapkit.protocols.application.rarp.RARP` and
-   :class:`~pcapkit.protocols.application.rarp.DRARP` derive from
+   :class:`~pcapkit.protocols.application.drarp.DRARP` derive from
    :class:`~pcapkit.protocols.application.application.Application` as well as
    :class:`~pcapkit.protocols.link.arp.ARP`, so their layer is
    ``'Application'`` (:issue:`719`).
@@ -41,6 +40,12 @@
    ``pcapkit.protocols.link.rarp``, and the ``RARP`` and ``DRARP`` names
    that :mod:`pcapkit.protocols.link` exported, with no alias (:issue:`719`).
 
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.application.rarp.DRARP``, with no alias. The class
+   moved to :mod:`pcapkit.protocols.application.drarp`, since a module holds
+   one protocol class, named after it (:issue:`2529`).
+
 """
 from typing import TYPE_CHECKING
 
@@ -53,7 +58,7 @@
 if TYPE_CHECKING:
     from typing_extensions import Literal
 
-__all__ = ['RARP', 'DRARP']
+__all__ = ['RARP']
 
 
 class RARP(Application, ARP, schema=Schema_ARP, data=Data_ARP):  # pylint: disable=abstract-method
@@ -106,22 +111,3 @@ def __index__(cls) -> 'Enum_EtherType':  # pylint: disable=invalid-index-returne
 
         """
         return Enum_EtherType.Reverse_Address_Resolution_Protocol  # type: ignore[return-value]
-
-
-class DRARP(RARP, schema=Schema_ARP, data=Data_ARP):
-    """This class implements Dynamic Reverse Address Resolution Protocol.
-
-    Inherits RARP's bases unchanged, so ``layer == 'Application'`` here too --
-    :rfc:`1931` makes it RARP with dynamic allocation, the same function and so
-    the same layer.
-
-    """
-
-    ##########################################################################
-    # Methods.
-    ##########################################################################
-
-    @classmethod
-    def id(cls) -> 'tuple[Literal["DRARP"]]':  # type: ignore[override]
-        """Index ID of the protocol."""
-        return ('DRARP',)

pcapkit/protocols/link/arp.py

@@ -77,7 +77,7 @@ class ARP(Link[Data_ARP, Schema_ARP],
 
     - Address Resolution Protocol (:class:`~pcapkit.protocols.link.arp.ARP`) [:rfc:`826`]
     - Reverse Address Resolution Protocol (:class:`~pcapkit.protocols.application.rarp.RARP`) [:rfc:`903`]
-    - Dynamic Reverse Address Resolution Protocol (:class:`~pcapkit.protocols.application.rarp.DRARP`) [:rfc:`1931`]
+    - Dynamic Reverse Address Resolution Protocol (:class:`~pcapkit.protocols.application.drarp.DRARP`) [:rfc:`1931`]
     - Inverse Address Resolution Protocol (:class:`~pcapkit.protocols.link.arp.InARP`) [:rfc:`2390`]
 
     .. versionchanged:: 1.5.0

pcapkit/protocols/link/c_tag.py

@@ -12,12 +12,10 @@
 identity and its registry index.
 
 It lives in a module of its own rather than beside
-:class:`~pcapkit.protocols.link.s_tag.S_Tag` because the two are reached through
-*different* registry indices -- ``0x8100`` against ``0x88A8`` -- which is the
-project's rule for when protocols share a module. Contrast
-:class:`~pcapkit.protocols.link.arp.InARP`, which shares
-:mod:`~pcapkit.protocols.link.arp` with :class:`~pcapkit.protocols.link.arp.ARP`
-precisely because it inherits its index.
+:class:`~pcapkit.protocols.link.s_tag.S_Tag`, since a module holds one protocol
+class, named after it, with only the framework bases in
+:mod:`pcapkit.protocols.protocol` exempt (:issue:`2529`). The two tags are
+reached through different registry indices, ``0x8100`` against ``0x88A8``.
 
 .. [*] https://en.wikipedia.org/wiki/IEEE_802.1Q
 

pcapkit/protocols/link/l2tp.py

@@ -176,9 +176,7 @@ def __index__(cls) -> 'NoReturn':  # pylint: disable=invalid-index-returned
 
         Note:
             An abstract base is reached by nothing, so it has no index of its
-            own. That is also the project's rule for module layout -- a distinct
-            ``__index__`` means a distinct module, and a base carrying none
-            claims no module of its own beyond holding the family together.
+            own.
 
         """
         raise UnsupportedCall(f'{cls.__name__!r} object cannot be interpreted as an integer')

pcapkit/protocols/link/s_tag.py

@@ -12,9 +12,10 @@
 identity and its registry index.
 
 It lives in a module of its own rather than beside
-:class:`~pcapkit.protocols.link.c_tag.C_Tag` because the two are reached through
-*different* registry indices -- ``0x88A8`` against ``0x8100`` -- which is the
-project's rule for when protocols share a module.
+:class:`~pcapkit.protocols.link.c_tag.C_Tag`, since a module holds one protocol
+class, named after it, with only the framework bases in
+:mod:`pcapkit.protocols.protocol` exempt (:issue:`2529`). The two tags are
+reached through different registry indices, ``0x88A8`` against ``0x8100``.
 
 .. [*] https://en.wikipedia.org/wiki/IEEE_802.1ad