fix(protocols): parser registrars warn only when the entry really changes (#1362)

pcapkit/protocols/application/httpv2.py

@@ -471,8 +471,18 @@ def register_frame(cls, code: 'Enum_Frame', meth: 'str | tuple[FrameParser, Fram
             code: HTTP frame type code.
             meth: Method name or callable to parse and/or construct the frame.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__frame__:
+        incumbent = cls.__frame__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'HTTP/2: [Type {code}] frame already registered', RegistryWarning)
         cls.__frame__[code] = meth
 

pcapkit/protocols/internet/hip.py

@@ -694,8 +694,18 @@ def register_parameter(cls, code: 'Enum_Parameter', meth: 'str | tuple[Parameter
             code: HIP parameter code.
             meth: Method name or callable to parse and/or construct the parameter.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__parameter__:
+        incumbent = cls.__parameter__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'parameter {code} already registered, overwriting', RegistryWarning)
         cls.__parameter__[code] = meth
 

pcapkit/protocols/internet/hopopt.py

@@ -383,8 +383,18 @@ def register_option(cls, code: 'Enum_Option', meth: 'str | tuple[OptionParser, O
             code: HOPOPT option code.
             meth: Method name or callable to parse and/or construct the option.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__option__:
+        incumbent = cls.__option__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'option {code} already registered, overwriting', RegistryWarning)
         cls.__option__[code] = meth
 

pcapkit/protocols/internet/ipv4.py

@@ -510,8 +510,18 @@ def register_option(cls, code: 'Enum_OptionNumber', meth: 'str | tuple[OptionPar
             code: IPv4 option code.
             meth: Method name or callable to parse and/or construct the option.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__option__:
+        incumbent = cls.__option__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'option {code} already registered, overwriting', RegistryWarning)
         cls.__option__[code] = meth
 

pcapkit/protocols/internet/ipv6_opts.py

@@ -375,8 +375,18 @@ def register_option(cls, code: 'Enum_Option', meth: 'str | tuple[OptionParser, O
             code: IPv6-Opts option code.
             meth: Method name or callable to parse and/or construct the option.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__option__:
+        incumbent = cls.__option__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'option {code} already registered, overwriting', RegistryWarning)
         cls.__option__[code] = meth
 

pcapkit/protocols/internet/ipv6_route.py

@@ -353,8 +353,18 @@ def register_routing(cls, code: 'Enum_Routing', meth: 'str | tuple[TypeParser, T
             code: IPv6-Route data type code.
             meth: Method name or callable to parse and/or construct the data.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__routing__:
+        incumbent = cls.__routing__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'routing {code} already registered, overwriting', RegistryWarning)
         cls.__routing__[code] = meth
 

pcapkit/protocols/internet/mh.py

@@ -1520,8 +1520,18 @@ def register_message(cls, code: 'Enum_Packet', meth: 'str | tuple[PacketParser,
             code: MH message type code.
             meth: Method name or callable to parse and/or construct the message.
 
-        """
-        if code in cls.__message__:
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
+        """
+        incumbent = cls.__message__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'message type {code} already registered, overwriting', RegistryWarning)
         cls.__message__[code] = meth
 
@@ -1533,8 +1543,18 @@ def register_option(cls, code: 'Enum_Option', meth: 'str | tuple[OptionParser, O
             code: MH option code.
             meth: Method name or callable to parse and/or construct the option.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__option__:
+        incumbent = cls.__option__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'option {code} already registered, overwriting', RegistryWarning)
         cls.__option__[code] = meth
 
@@ -1546,8 +1566,18 @@ def register_extension(cls, code: 'Enum_CGAExtension', meth: 'str | tuple[Extens
             code: CGA extension code.
             meth: Method name or callable to parse and/or construct the extension.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__extension__:
+        incumbent = cls.__extension__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'extension {code} already registered, overwriting', RegistryWarning)
         cls.__extension__[code] = meth
 

pcapkit/protocols/transport/sctp.py

@@ -641,8 +641,18 @@ def register_chunk(cls, code: 'Enum_Chunk', meth: 'str | tuple[ChunkParser, Chun
             code: SCTP chunk type.
             meth: Method name or callable to parse and/or construct the chunk.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__chunk__:
+        incumbent = cls.__chunk__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'chunk {code} already registered, overwriting', RegistryWarning)
         cls.__chunk__[code] = meth
 
@@ -654,8 +664,18 @@ def register_parameter(cls, code: 'Enum_Parameter', meth: 'str | tuple[Parameter
             code: SCTP chunk parameter type.
             meth: Method name or callable to parse and/or construct the parameter.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__parameter__:
+        incumbent = cls.__parameter__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'parameter {code} already registered, overwriting', RegistryWarning)
         cls.__parameter__[code] = meth
 
@@ -667,8 +687,18 @@ def register_cause(cls, code: 'Enum_CauseCode', meth: 'str | tuple[CauseParser,
             code: SCTP error cause code.
             meth: Method name or callable to parse and/or construct the cause.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__cause__:
+        incumbent = cls.__cause__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'error cause {code} already registered, overwriting', RegistryWarning)
         cls.__cause__[code] = meth
 

pcapkit/protocols/transport/tcp.py

@@ -646,8 +646,18 @@ def register_option(cls, code: 'Enum_Option', meth: 'str | tuple[OptionParser, O
             code: TCP option code.
             meth: Method name or callable to parse and/or construct the option.
 
-        """
-        if code in cls.__option__:
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
+        """
+        incumbent = cls.__option__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'option {code} already registered, overwriting', RegistryWarning)
         cls.__option__[code] = meth
 
@@ -659,8 +669,18 @@ def register_mp_option(cls, code: 'Enum_MPTCPOption', meth: 'str | tuple[MPOptio
             code: MPTCP option code.
             meth: Method name or callable to parse and/or construct the option.
 
+        Warns:
+            RegistryWarning: If a different entry is already registered for
+                ``code``; it is overwritten. Handing back the entry already
+                stored, or one equal to it, is a silent no-op. The entry
+                ``code`` shipped with is accepted like any other, so an
+                override can be undone (:issue:`1362`, :issue:`1363`).
+
         """
-        if code in cls.__mp_option__:
+        incumbent = cls.__mp_option__.get(code)
+        if incumbent is not None and incumbent == meth:
+            return
+        if incumbent is not None:
             warn(f'option {code} already registered, overwriting', RegistryWarning)
         cls.__mp_option__[code] = meth
 

tests/protocols/application/test_http_unit.py

@@ -1839,7 +1839,7 @@ def test_httpv2_id_length_make_bytes_and_register_frame_warning(self) -> None:
         try:
             schema = proto.make(type=Frame.DATA, flags=0x01, sid=3, frame=b'data')
             with mock.patch('pcapkit.protocols.application.httpv2.warn') as warn:
-                HTTPv2.register_frame(Frame.DATA, 'data')
+                HTTPv2.register_frame(Frame.DATA, 'headers')
 
             self.assertEqual(HTTPv2.id(), ('HTTP', 'HTTPv2'))
             self.assertEqual(proto.alias, 'HTTP/2')

tests/protocols/internet/test_hip_unit.py

@@ -239,9 +239,9 @@ def test_hip_register_parameter_warns_on_overwrite(self) -> None:
         original = registry[Parameter.ESP_INFO]
         try:
             with mock.patch('pcapkit.protocols.internet.hip.warn') as warn:
-                HIP.register_parameter(Parameter.ESP_INFO, 'esp_info')
+                HIP.register_parameter(Parameter.ESP_INFO, 'unassigned')
             warn.assert_called_once()
-            self.assertEqual(registry[Parameter.ESP_INFO], 'esp_info')
+            self.assertEqual(registry[Parameter.ESP_INFO], 'unassigned')
         finally:
             registry[Parameter.ESP_INFO] = original
 
@@ -257,8 +257,13 @@ def test_hip_register_parameter_warns_on_overwrite(self) -> None:
             warn.assert_not_called()
             self.assertEqual(registry[custom], 'unassigned')
 
+            # Handing back the entry just stored is no overwrite either (#1362).
             with mock.patch('pcapkit.protocols.internet.hip.warn') as warn:
                 HIP.register_parameter(custom, 'unassigned')
+            warn.assert_not_called()
+
+            with mock.patch('pcapkit.protocols.internet.hip.warn') as warn:
+                HIP.register_parameter(custom, 'esp_info')
             warn.assert_called_once()
         finally:
             registry.pop(custom, None)

tests/protocols/internet/test_ipv4_unit.py

@@ -1102,9 +1102,9 @@ def test_ipv4_register_option_warns_on_overwrite(self) -> None:
         original = registry[OptionNumber.EOOL]
         try:
             with mock.patch('pcapkit.protocols.internet.ipv4.warn') as warn:
-                IPv4.register_option(OptionNumber.EOOL, 'eool')
+                IPv4.register_option(OptionNumber.EOOL, 'nop')
             warn.assert_called_once()
-            self.assertEqual(registry[OptionNumber.EOOL], 'eool')
+            self.assertEqual(registry[OptionNumber.EOOL], 'nop')
         finally:
             registry[OptionNumber.EOOL] = original
 
@@ -1120,8 +1120,13 @@ def test_ipv4_register_option_warns_on_overwrite(self) -> None:
             warn.assert_not_called()
             self.assertEqual(registry[custom], 'unassigned')
 
+            # Handing back the entry just stored is no overwrite either (#1362).
             with mock.patch('pcapkit.protocols.internet.ipv4.warn') as warn:
                 IPv4.register_option(custom, 'unassigned')
+            warn.assert_not_called()
+
+            with mock.patch('pcapkit.protocols.internet.ipv4.warn') as warn:
+                IPv4.register_option(custom, 'nop')
             warn.assert_called_once()
         finally:
             registry.pop(custom, None)

tests/protocols/internet/test_ipv6_extension_unit.py

@@ -63,9 +63,9 @@ def test_hopopt_register_option_warns_on_overwrite(self) -> None:
         original = HOPOPT.__dict__['__option__'][Option.Pad1]
         try:
             with mock.patch('pcapkit.protocols.internet.hopopt.warn') as warn:
-                HOPOPT.register_option(Option.Pad1, 'pad')
+                HOPOPT.register_option(Option.Pad1, 'tun')
             warn.assert_called_once()
-            self.assertEqual(HOPOPT.__dict__['__option__'][Option.Pad1], 'pad')
+            self.assertEqual(HOPOPT.__dict__['__option__'][Option.Pad1], 'tun')
         finally:
             HOPOPT.__dict__['__option__'][Option.Pad1] = original
 
@@ -76,9 +76,9 @@ def test_ipv6_opts_register_option_warns_on_overwrite(self) -> None:
         original = IPv6_Opts.__dict__['__option__'][Option.Pad1]
         try:
             with mock.patch('pcapkit.protocols.internet.ipv6_opts.warn') as warn:
-                IPv6_Opts.register_option(Option.Pad1, 'pad')
+                IPv6_Opts.register_option(Option.Pad1, 'tun')
             warn.assert_called_once()
-            self.assertEqual(IPv6_Opts.__dict__['__option__'][Option.Pad1], 'pad')
+            self.assertEqual(IPv6_Opts.__dict__['__option__'][Option.Pad1], 'tun')
         finally:
             IPv6_Opts.__dict__['__option__'][Option.Pad1] = original
 
@@ -89,9 +89,9 @@ def test_ipv6_route_register_routing_warns_on_overwrite(self) -> None:
         original = IPv6_Route.__dict__['__routing__'][Routing.Source_Route]
         try:
             with mock.patch('pcapkit.protocols.internet.ipv6_route.warn') as warn:
-                IPv6_Route.register_routing(Routing.Source_Route, 'src')
+                IPv6_Route.register_routing(Routing.Source_Route, 'rpl')
             warn.assert_called_once()
-            self.assertEqual(IPv6_Route.__dict__['__routing__'][Routing.Source_Route], 'src')
+            self.assertEqual(IPv6_Route.__dict__['__routing__'][Routing.Source_Route], 'rpl')
         finally:
             IPv6_Route.__dict__['__routing__'][Routing.Source_Route] = original