From 1c399dbfa5e6d7e96d5f6949d330fed16abba89e Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 25 Oct 2026 03:24:19 -0400 Subject: [PATCH] docs(foundation): document RegistryError on the method-name registrars (#2176) Problem: the registrars in pcapkit/foundation/registry/protocols.py that take a method name raise RegistryError when meth names no matching _read_* method, and none of them documents it. Fix: add a Raises: section, naming each registrar's own _read_* prefix, to register_ipv4_option, register_hip_parameter, register_hopopt_option, register_ipv6_opts_option, register_ipv6_route_routing, register_mh_message, register_mh_option, register_mh_extension, register_tcp_option, register_tcp_mp_option, register_http_frame, register_pcapng_block, register_pcapng_option, register_pcapng_record and register_pcapng_secrets. Docstring-only; the AST with docstrings stripped is unchanged. Test: tests/test_docstring_contract.py passes. --- pcapkit/foundation/registry/protocols.py | 60 ++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/pcapkit/foundation/registry/protocols.py b/pcapkit/foundation/registry/protocols.py index 10e0b337fc..3543f686f5 100644 --- a/pcapkit/foundation/registry/protocols.py +++ b/pcapkit/foundation/registry/protocols.py @@ -758,6 +758,10 @@ def register_ipv4_option(code: 'IPv4_OptionNumber', meth: 'str | tuple[IPv4_Opti schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the option. It should be a subclass of :class:`pcapkit.protocols.schema.internet.ipv4.Option`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_opt_*`` method. + """ if isinstance(meth, str) and not hasattr(IPv4, f'_read_opt_{meth}'): raise RegistryError('method must be a valid IPv4 option parser function') @@ -783,6 +787,10 @@ def register_hip_parameter(code: 'HIP_Parameter', meth: 'str | tuple[HIP_Paramet schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the parameter. It should be a subclass of :class:`pcapkit.protocols.schema.internet.hip.Parameter`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_param_*`` method. + """ if isinstance(meth, str) and not hasattr(HIP, f'_read_param_{meth}'): raise RegistryError('method must be a valid HIP parameter parser function') @@ -808,6 +816,10 @@ def register_hopopt_option(code: 'IPv6_Option', meth: 'str | tuple[HOPOPT_Option schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the option. It should be a subclass of :class:`pcapkit.protocols.schema.internet.hopopt.Option`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_opt_*`` method. + """ if isinstance(meth, str) and not hasattr(HOPOPT, f'_read_opt_{meth}'): raise RegistryError('method must be a valid HOPOPT option parser function') @@ -833,6 +845,10 @@ def register_ipv6_opts_option(code: 'IPv6_Option', meth: 'str | tuple[IPv6_Opts_ schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the option. It should be a subclass of :class:`pcapkit.protocols.schema.internet.ipv6_opts.Option`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_opt_*`` method. + """ if isinstance(meth, str) and not hasattr(IPv6_Opts, f'_read_opt_{meth}'): raise RegistryError('method must be a valid IPv6-Opts option parser function') @@ -858,6 +874,10 @@ def register_ipv6_route_routing(code: 'IPv6_Routing', meth: 'str | tuple[IPv6_Ro schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the routing data. It should be a subclass of :class:`pcapkit.protocols.schema.internet.ipv6_route.RoutingType`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_data_type_*`` method. + """ if isinstance(meth, str) and not hasattr(IPv6_Route, f'_read_data_type_{meth}'): raise RegistryError('method must be a valid IPv6-Route routing data parser function') @@ -883,6 +903,10 @@ def register_mh_message(code: 'MH_Packet', meth: 'str | tuple[MH_PacketParser, M schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the message type. It should be a subclass of :class:`pcapkit.protocols.schema.internet.mh.Packet`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_msg_*`` method. + """ if isinstance(meth, str) and not hasattr(MH, f'_read_msg_{meth}'): raise RegistryError('method must be a valid MH message type parser function') @@ -908,6 +932,10 @@ def register_mh_option(code: 'MH_Option', meth: 'str | tuple[MH_OptionParser, MH schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the option. It should be a subclass of :class:`pcapkit.protocols.schema.internet.mh.Option`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_opt_*`` method. + """ if isinstance(meth, str) and not hasattr(MH, f'_read_opt_{meth}'): raise RegistryError('method must be a valid MH option parser function') @@ -933,6 +961,10 @@ def register_mh_extension(code: 'MH_CGAExtension', meth: 'str | tuple[MH_Extensi schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the CGA extension. It should be a subclass of :class:`pcapkit.protocols.schema.internet.mh.CGAExtension`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_ext_*`` method. + .. versionchanged:: 1.5.0 ``schema`` is keyword-only, as in the other ``register_*`` functions @@ -1198,6 +1230,10 @@ def register_tcp_option(code: 'TCP_Option', meth: 'str | tuple[TCP_OptionParser, schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the option. It should be a subclass of :class:`pcapkit.protocols.schema.transport.tcp.Option`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_mode_*`` method. + """ if isinstance(meth, str) and not hasattr(TCP, f'_read_mode_{meth}'): raise RegistryError('method must be a TCP option parser function') @@ -1223,6 +1259,10 @@ def register_tcp_mp_option(code: 'TCP_MPTCPOption', meth: 'str | tuple[TCP_MPOpt schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the option. It should be a subclass of :class:`pcapkit.protocols.schema.transport.tcp.MPTCP`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_mptcp_*`` method. + """ if isinstance(meth, str) and not hasattr(TCP, f'_read_mptcp_{meth}'): raise RegistryError('method must be a MPTCP option parser function') @@ -1336,6 +1376,10 @@ def register_http_frame(code: 'HTTP_Frame', meth: 'str | tuple[HTTP_FrameParser, schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the frame. It should be a subclass of :class:`pcapkit.protocols.schema.application.httpv2.FrameType`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_http_*`` method. + """ if isinstance(meth, str) and not hasattr(HTTPv2, f'_read_http_{meth}'): raise RegistryError('method must be a frame parser function') @@ -1366,6 +1410,10 @@ def register_pcapng_block(code: 'PCAPNG_BlockType', meth: 'str | tuple[PCAPNG_Bl schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the block. It should be a subclass of :class:`pcapkit.protocols.schema.misc.pcapng.BlockType`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_block_*`` method. + """ if isinstance(meth, str) and not hasattr(PCAPNG, f'_read_block_{meth}'): raise RegistryError('method must be a block parser function') @@ -1391,6 +1439,10 @@ def register_pcapng_option(code: 'PCAPNG_OptionType', meth: 'str | tuple[PCAPNG_ schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the option. It should be a subclass of :class:`pcapkit.protocols.schema.misc.pcapng.Option`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_option_*`` method. + """ if isinstance(meth, str) and not hasattr(PCAPNG, f'_read_option_{meth}'): raise RegistryError('method must be a option parser function') @@ -1417,6 +1469,10 @@ def register_pcapng_record(code: 'PCAPNG_RecordType', meth: 'str | tuple[PCAPNG_ schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the name resolution record. It should be a subclass of :class:`pcapkit.protocols.schema.misc.pcapng.NameResolutionRecord`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_record_*`` method. + """ if isinstance(meth, str) and not hasattr(PCAPNG, f'_read_record_{meth}'): raise RegistryError('method must be a name resolution record parser function') @@ -1442,6 +1498,10 @@ def register_pcapng_secrets(code: 'PCAPNG_SecretsType', meth: 'str | tuple[PCAPN schema: :class:`~pcapkit.protocols.schema.schema.Schema` class for the decryption secrets. It should be a subclass of :class:`pcapkit.protocols.schema.misc.pcapng.DSBSecrets`. + Raises: + RegistryError: If ``meth`` is a name with no matching + ``_read_secrets_*`` method. + """ if isinstance(meth, str) and not hasattr(PCAPNG, f'_read_secrets_{meth}'): raise RegistryError('method must be a decryption secrets parser function')