From 525dc73509e1439e3bb99d4d74d684207e60e066 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 25 Oct 2026 10:27:26 -0400 Subject: [PATCH] docs(tests): state const tests' behaviour without change-relative narrative (#1103) Rewrites comments and docstrings under tests/const/ so they describe behaviour and the defect each test guards against, not the change that introduced it. Prose only; AST-identical once docstrings are stripped. --- .../test_const_apptype_lazy_1538_unit.py | 2 +- ..._const_apptype_register_range_1792_unit.py | 19 +- tests/const/test_const_apptype_split_unit.py | 527 ++++++------ tests/const/test_const_enum_builtin_parity.py | 321 ++++---- tests/const/test_const_enum_get.py | 304 +++---- tests/const/test_const_enum_lookup.py | 32 +- tests/const/test_const_enum_no_mint.py | 764 ++++++++---------- tests/const/test_const_ethertype_862_unit.py | 22 +- ...onst_ftp_command_get_key_type_1824_unit.py | 2 +- .../test_const_ftp_featcode_case_903_unit.py | 6 +- ...st_const_ipv6_extension_header_925_unit.py | 68 +- tests/const/test_const_linktype_209_unit.py | 44 +- ...st_const_method_case_sensitive_896_unit.py | 24 +- ...test_const_method_value_lookup_908_unit.py | 16 +- ...ster_validates_every_registry_1816_unit.py | 2 +- tests/const/test_const_registry_protocol.py | 488 +++++------ .../const/test_const_str_payload_870_unit.py | 29 +- 17 files changed, 1213 insertions(+), 1457 deletions(-) diff --git a/tests/const/test_const_apptype_lazy_1538_unit.py b/tests/const/test_const_apptype_lazy_1538_unit.py index 2b40365caf..12b08e2607 100644 --- a/tests/const/test_const_apptype_lazy_1538_unit.py +++ b/tests/const/test_const_apptype_lazy_1538_unit.py @@ -5,7 +5,7 @@ :mod:`~pcapkit.const.reg.apptype.udp` are generated from IANA's registry and hold about 49,700 lines of members between them; ``python -X importtime -c 'import pcapkit'`` put them at 104 ms and 102 ms of a 700 ms import. Nothing on -any import path needs them, so :mod:`pcapkit.const.reg.apptype` now imports them +any import path needs them, so :mod:`pcapkit.const.reg.apptype` imports them from a :pep:`562` ``__getattr__`` and from :attr:`AppType.__registries__ ` the first time either is read. diff --git a/tests/const/test_const_apptype_register_range_1792_unit.py b/tests/const/test_const_apptype_register_range_1792_unit.py index d75a3ab8de..c8b9df3bd0 100644 --- a/tests/const/test_const_apptype_register_range_1792_unit.py +++ b/tests/const/test_const_apptype_register_range_1792_unit.py @@ -1,15 +1,16 @@ # -*- coding: utf-8 -*- """``AppType.register`` refuses a port that ``get`` refuses. -GitHub issue #1792. :meth:`~pcapkit.const.reg.apptype.apptype.AppType.register` -neither called nor overrode -:meth:`~pcapkit.corekit.enum.EnumLookup._validate_value`, so ``TCP.register(70000, -'x')`` minted a member, and ``AppType.get(70000, proto='tcp')`` then returned it -although ``get`` raises :exc:`ValueError` for a port outside ``0``-``65535`` -(#758). ``AppType`` now overrides the hook with :meth:`_missing_`'s own check and -``register`` calls it after its duplicate check, as the base ``register`` does. -The override raises :exc:`~pcapkit.utilities.exceptions.EnumValueError`, as the -registry-protocol convention asks of one, with the message ``get`` raises. +GitHub issue #1792. Without the fix, +:meth:`~pcapkit.const.reg.apptype.apptype.AppType.register` neither calls nor +overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value`, so +``TCP.register(70000, 'x')`` mints a member, and ``AppType.get(70000, +proto='tcp')`` then returns it although ``get`` raises :exc:`ValueError` for a +port outside ``0``-``65535`` (#758). ``AppType`` overrides the hook with +:meth:`_missing_`'s own check and ``register`` calls it after its duplicate +check, as the base ``register`` does. The override raises +:exc:`~pcapkit.utilities.exceptions.EnumValueError`, as the registry-protocol +convention asks of one, with the message ``get`` raises. Each test imports the registries after :func:`~tests._support.reimport_once_per_class`, whose ``restore`` puts the diff --git a/tests/const/test_const_apptype_split_unit.py b/tests/const/test_const_apptype_split_unit.py index 10117d2dc7..ac8f35bc4f 100644 --- a/tests/const/test_const_apptype_split_unit.py +++ b/tests/const/test_const_apptype_split_unit.py @@ -1,18 +1,18 @@ # -*- coding: utf-8 -*- """The application layer registry as a per-transport package. -GitHub issue #732. :file:`pcapkit/const/reg/apptype.py` was one -:class:`~aenum.StrEnum` holding the members of every transport protocol, -with a ``__members_proto__`` mapping that kept **one** member per -``(transport, port)`` pair -- so of the three services IANA assigns to port 80, -two were reachable only by attribute name and none of that was visible from a -lookup. It is now :mod:`pcapkit.const.reg.apptype`: a memberless +GitHub issue #732. :mod:`pcapkit.const.reg.apptype` is a memberless :class:`~pcapkit.const.reg.apptype.apptype.AppType` base and one registry per transport protocol, each keyed on port by a -:class:`~pcapkit.corekit.multidict.MultiDict` that keeps every assignment. - -These properties carry the design and none of them held before, so each is -asserted directly rather than left to the generic sweeps in +:class:`~pcapkit.corekit.multidict.MultiDict` that keeps every assignment. The +defect #732 reported was a single :class:`~aenum.StrEnum` holding the members +of every transport protocol, with a ``__members_proto__`` mapping that kept +**one** member per ``(transport, port)`` pair -- so of the three services IANA +assigns to port 80, two were reachable only by attribute name and none of that +was visible from a lookup. + +These properties carry the design, so each is asserted directly rather than +left to the generic sweeps in :mod:`tests.const.test_const_enum_builtin_parity`: #. the base holds **no** members, which is not a tidiness preference -- @@ -23,7 +23,7 @@ #. a colliding port keeps **every** service IANA assigned it, answering with one canonical member and keeping the rest reachable as named aliases; #. :func:`~aenum.extend_enum` on an occupied port *appends* rather than - displacing what was there, which is the silent data loss the old + displacing what was there, which is the silent data loss #732's ``__members_proto__`` assignment performed. """ @@ -86,9 +86,9 @@ def _declarations(path: 'str', name: 'str') -> 'tuple[tuple[str, int], ...]': def _declared(registry: 'type') -> 'list[tuple[str, int]]': """Every member ``registry``'s generated module declares, in source order. - GitHub issue #1820. The population checks in this file used to pin IANA's - per-registry member counts, so a vendor update that added or removed a port - turned them red with nothing wrong. They compare against this instead: the + GitHub issue #1820. The population checks in this file compare against + this rather than pin IANA's per-registry member counts, which a vendor + update that adds or removes a port turns red with nothing wrong: the ``(name, port)`` rows the generated class body declares, read with :mod:`ast` rather than off the live class, so the oracle does not depend on what the registry holds at run time. A vendor update moves both sides alike, @@ -464,7 +464,7 @@ def test_register_alias_refuses_a_name_already_on_the_port(self) -> None: self.assertEqual(len(TCP.__registry__.getlist(80)), before) def test_extend_enum_appends_to_an_occupied_port(self) -> None: - """The old ``__members_proto__[proto][port] = obj`` displaced it silently.""" + """Guards against #732's ``__members_proto__[proto][port] = obj`` displacing a member.""" import aenum from pcapkit.const.reg.apptype import UDP, TransportProtocol @@ -478,9 +478,9 @@ def test_extend_enum_appends_to_an_occupied_port(self) -> None: after = [member.svc for member in UDP.__registry__.getlist(80)] self.assertEqual(after, ['http', 'www', 'www-http', 'unit-test-80']) - # Appending must not displace the answer either: the old code overwrote - # the bucket, so a third-party registration silently became what every - # lookup of that port returned. + # Appending must not displace the answer either: #732's assignment + # overwrites the bucket, so a third-party registration silently becomes + # what every lookup of that port returns. self.assertEqual(UDP.get(80).svc, 'http') self.assertIn('unit-test-80', [member.svc for member in UDP.get_all(80)]) @@ -504,14 +504,13 @@ def test_every_registry_rejects_a_negative_value(self) -> None: def test_a_port_lookup_on_the_base_dispatches_by_transport(self) -> None: """Which is what keeps every ``AppType.get(port, proto=...)`` caller working. - 9899 -- this test's own port before GitHub issue #860 step 2 PR 2 -- - is not one SCTP declares, so ``SCTP.get(9899)`` now mints an - *unregistered* member on every call: equal, but no longer identical, - so ``assertIs`` against a second, independent call would be + A port SCTP does not declare, such as 9899, mints an *unregistered* + member on every call (GitHub issue #860 step 2 PR 2): equal, but not + identical, so ``assertIs`` against a second, independent call would be comparing two different objects that merely resolved the same way. - 9 (``discard``) is a real, declared SCTP member, so identity is - still the right check there -- exactly as it remains for 80 on TCP - and UDP, both real declared members too. + 9 (``discard``) is a real, declared SCTP member, so identity is the + right check there -- exactly as it is for 80 on TCP and UDP, both real + declared members too. """ from pcapkit.const.reg.apptype import SCTP, TCP, UDP, AppType, TransportProtocol @@ -528,11 +527,11 @@ def test_a_port_lookup_on_the_base_dispatches_by_transport(self) -> None: def test_a_service_name_is_not_a_port_lookup(self) -> None: """GitHub issue #734's junk-minting path is gone rather than fixed. - The old string branch tested ``key in __members_proto__``, which is keyed + The string branch #734 reported tested ``key in __members_proto__``, which is keyed by transport protocol, so a name never matched and ``AppType.get('ssh')`` returned a **new** member with port ``-1`` instead of the one at 22. Nothing in :mod:`pcapkit` resolves a service by name, so - it now raises; #734 was closed on that, with the name lookup removed + it raises; #734 was closed on that, with the name lookup removed rather than repaired. """ from pcapkit.const.reg.apptype import TCP @@ -563,16 +562,16 @@ def test_unassigned_rows_are_documented_rather_than_declared(self) -> None: self.assertNotIn(-1, [member.port for member in cls]) def test_a_real_port_with_no_transport_no_longer_resolves(self) -> None: - """The one deliberate behaviour change, pinned so it cannot happen twice. + """The one deliberate behaviour difference from #732's lookup, pinned. Some registry entries carry a real port with an **empty** transport - protocol column, and the old ``_missing_`` consulted them as a fallback - tier after the transport-specific lookup missed -- so ``get(51, - proto=tcp)`` answered ``reserved``, claiming a TCP assignment IANA never + protocol column. A ``_missing_`` that consults them as a fallback tier + after the transport-specific lookup misses answers ``get(51, + proto=tcp)`` with ``reserved``, claiming a TCP assignment IANA never made. They are documented on the base class instead, and the lookup - answers an unknown port, which is the honest answer -- since GitHub issue - #860 step 2 PR 2, an unregistered one rather than a permanent mint, so - there is nothing left for :meth:`_purge_member` to undo (it no-ops when + answers an unknown port, which is the honest answer -- an unregistered + one rather than a permanent mint (GitHub issue #860 step 2 PR 2), so + there is nothing for :meth:`_purge_member` to undo (it no-ops when the name it is asked to remove was never added, which is exactly what happens here; kept anyway as a harmless guard against a regression that reintroduced minting). @@ -672,9 +671,9 @@ def test_every_transport_named_span_is_claimed_by_one_registry(self) -> None: spans that happen to collide: a branch minting a member for a named transport protocol is claimed by that registry, and one answering with ``cls.__transport__`` claims nothing, since IANA's unassigned and reserved - markers belong to whichever registry was asked. Such a branch answered - ``undefined`` until GitHub issue #2048, which made it answer with the - asking registry's own transport, so none answers ``undefined``. + markers belong to whichever registry was asked. Such a branch answers + with the asking registry's own transport, not ``undefined`` (GitHub + issue #2048). "Every branch" is checked against the same source parsed with :mod:`ast`: the pattern has to find one branch per ``_unregistered_member`` call in @@ -688,16 +687,15 @@ def test_every_transport_named_span_is_claimed_by_one_registry(self) -> None: from pcapkit.const.reg.apptype import AppType source = inspect.getsource(AppType._missing_.__func__) # type: ignore[attr-defined] - # NOTE: GitHub issue #768 changed the emitted form from - # ``TransportProtocol.get('tcp')`` to the attribute access - # ``TransportProtocol.tcp``, so the capture is a bare identifier now - # rather than a quoted literal. GitHub issue #860 step 2 PR 2 changed - # the call itself from ``extend_enum(cls, f'_{value}', value, - # '