From 6d273b2cef03ab1784d5ec4d913ae42031f363cb Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 25 Oct 2026 03:33:58 -0400 Subject: [PATCH] docs(corekit): say which generated registries bound their width (#2178) The Notes of EnumField.post_process, and a docstring in tests/corekit/test_fields_numbers_unassigned_enum.py, said only the bit-flag registries bound themselves to a width and that none of those backs a plain EnumField. Most generated _missing_ guards range-check the value, plain registries such as ipv4 OptionNumber included, and those are plain EnumField namespaces. Say so, and that it is harmless because the out-of-width rejection is the bare ValueError the method falls back on. Docstrings only: the docstring-stripped AST of both files is unchanged. --- pcapkit/corekit/fields/numbers.py | 19 +++++++++++-------- .../test_fields_numbers_unassigned_enum.py | 11 +++++++---- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/pcapkit/corekit/fields/numbers.py b/pcapkit/corekit/fields/numbers.py index 52389c527d..d63c4f3264 100644 --- a/pcapkit/corekit/fields/numbers.py +++ b/pcapkit/corekit/fields/numbers.py @@ -741,14 +741,17 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'Stdli bare, unlogged :exc:`ValueError` precisely because the ``except ValueError`` fallback of :meth:`~pcapkit.corekit.enum.EnumLookup.get` has to keep catching it (GitHub issues :issue:`584` and - :issue:`647`). The registries that - *do* bound themselves to a width and reject outside it are the - bit-flag ones -- :class:`pcapkit.const.tcp.flags.Flags` among them -- - and none of those is named as the namespace of a plain - :class:`EnumField` anywhere in the package, so no in-library guard - loses its force through this method. The distinction is therefore for - a registry registered from outside :mod:`pcapkit.const`, which has no - such obligation to stay quiet. + :issue:`647`). That bare :exc:`ValueError` is also how a generated + guard bounds its registry to a width, rejecting a value outside + ``0 <= value <= N``. Bit-flag registries such as + :class:`pcapkit.const.tcp.flags.Flags` do so, and so do plain ones + such as :class:`pcapkit.const.ipv4.option_number.OptionNumber`, which + is the namespace of a plain :class:`EnumField`. That is harmless: + the out-of-width rejection is the bare :exc:`ValueError` this method + falls back on, so no in-library guard loses its force through this + method. The distinction is therefore for a registry registered from + outside :mod:`pcapkit.const`, which has no such obligation to stay + quiet. Octets carrying bits outside :attr:`~NumberField.bit_length` that :meth:`NumberField.post_process` recorded resolve to a member that diff --git a/tests/corekit/test_fields_numbers_unassigned_enum.py b/tests/corekit/test_fields_numbers_unassigned_enum.py index d83b09d033..a99e1c4059 100644 --- a/tests/corekit/test_fields_numbers_unassigned_enum.py +++ b/tests/corekit/test_fields_numbers_unassigned_enum.py @@ -239,10 +239,13 @@ def test_an_in_library_rejection_is_not_absorbed(self) -> None: :exc:`ValueError` on purpose -- ``tests/const/test_const_enum_builtin_parity.py`` pins exactly that, because each generated ``get()``'s ``except ValueError`` fallback depends on it -- so no registry under - :mod:`pcapkit.const` exercises this branch, and none needs to: the - bit-flag registries that do bound themselves to a width, including - :class:`pcapkit.const.tcp.flags.Flags`, are reached through neither a - plain :class:`~pcapkit.corekit.fields.numbers.EnumField` nor this method. + :mod:`pcapkit.const` exercises this branch, and none needs to: a + generated guard that bounds its registry to a width rejects with that + same bare :exc:`ValueError`, whether the registry is a bit-flag one such + as :class:`pcapkit.const.tcp.flags.Flags` or a plain one such as + :class:`pcapkit.const.ipv4.option_number.OptionNumber` behind a plain + :class:`~pcapkit.corekit.fields.numbers.EnumField`, so the field falls + back on it like any other miss. Asserted for both enumeration libraries, because the registries under :mod:`pcapkit.const` are a mixture of the two and ``_missing_`` is