diff --git a/pcapkit/const/reg/apptype/apptype.py b/pcapkit/const/reg/apptype/apptype.py index d620b15d28..8a9a26bb88 100644 --- a/pcapkit/const/reg/apptype/apptype.py +++ b/pcapkit/const/reg/apptype/apptype.py @@ -55,7 +55,7 @@ class TransportProtocol(EnumLookup, IntEnum): # instead of being split. With no decoding left to protect, the owner's own # further ruling on GitHub issue #860 retired the power-of-two spacing # itself too: that spacing existed mainly for code that composed values like - # ``tcp | udp``, which the new logic no longer accepts, so sequential + # ``tcp | udp``, which the whole-value lookup does not accept, so sequential # ``auto()`` values are the expected behaviour. :meth:`AppType._dispatch` # never decodes an ``int`` -- composed by hand with ``|`` or passed bare -- # into anything narrower than the whole value it already is, on either @@ -68,8 +68,8 @@ class TransportProtocol(EnumLookup, IntEnum): # ``sctp``'s value -- resolves as ``dccp``'s, silently, with no # exception, since a real member sits at ``4`` either way. A caller holding # an integer under the old spacing (composed or not) can therefore land on a - # different real transport's registry after this change, not merely be - # refused where it previously resolved. + # different real transport's registry under the sequential numbering, not + # merely be refused where it previously resolved. #: No transport protocol. ``TransportProtocol(0) is undefined`` and #: ``bool(undefined)`` is ``False``; it is the ``proto`` sentinel default @@ -108,14 +108,12 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco ``Enum`` would raise in the circumstances, :exc:`ValueError` or :exc:`KeyError` as the case may be, and is to come from :mod:`pcapkit.utilities.exceptions` rather than being a builtin. A - stdlib ``E['nosuch']`` raises :exc:`KeyError`, and :issue:`923`'s census of the - 127 concrete :class:`~pcapkit.corekit.enum.EnumLookup` subclasses -- - taken before the phase-2 re-parenting moved this class, so it is not - among them -- found 119 already answering a name miss that way against 5 - answering with :exc:`ValueError`. Those 5 are :class:`AppType` and its - four transport registries, and they land there only because their own - ``get()`` takes an :class:`int` port and never accepts a name at all, - rather than from any name-miss policy. So there was no policy here to + stdlib ``E['nosuch']`` raises :exc:`KeyError`, and :issue:`923`'s census + found :class:`~pcapkit.corekit.enum.EnumLookup` subclasses answering a + name miss that way. The exceptions were :class:`AppType` and its + per-transport registries, and they answered with :exc:`ValueError` only + because their own ``get()`` takes an :class:`int` port and never accepts + a name at all, rather than from any name-miss policy. So there was no policy here to preserve, and a name miss reaches the caller as :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The maintainer's ruling given in review of the work for :issue:`808`, that @@ -127,25 +125,23 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco (:meth:`~pcapkit.corekit.enum.EnumLookup.get`), so this override moves from :class:`staticmethod` to :class:`classmethod` to delegate at all -- the same move GitHub issue :issue:`908` made for - :meth:`~pcapkit.const.http.method.Method.get`. Grepped every call - site in this tree for GitHub issue :issue:`877`: all call this method by - name, none take it as a bare callable or introspect ``__func__``, - so the switch is not caller-visible. + :meth:`~pcapkit.const.http.method.Method.get`. A caller invoking it by + name sees no difference between the two; only code taking it as a bare + callable or introspecting ``__func__`` could tell them apart. - ``default`` did not exist on this override before this change -- - the original had no such parameter at all, which is a genuine LSP - violation once this class' ``get`` is a :class:`classmethod` - override of one that has it: a caller holding a - :class:`~pcapkit.corekit.enum.EnumLookup`-typed reference could pass - ``default=`` and, before this, would have hit a - :exc:`TypeError` at this subclass. Forwarded verbatim to + ``default`` is accepted here because the original override had no + such parameter at all, which is a genuine LSP violation once this + class' ``get`` is a :class:`classmethod` override of one that has + it: a caller holding a :class:`~pcapkit.corekit.enum.EnumLookup`-typed + reference could pass ``default=`` and hit a :exc:`TypeError` at this + subclass. Forwarded verbatim to :meth:`~pcapkit.corekit.enum.EnumLookup.get` rather than reimplemented, so it behaves exactly as the base's own ``default`` does: a fallback to an *already-registered* value, resolved through ``_value2member_map_`` and never through the constructor, so - passing one still cannot mint. Every call site in this tree omits - it, so this is purely an added, backward-compatible capability, not - a change to anything this tree exercises today. + passing one still cannot mint. A call that omits it resolves exactly + as one made without the parameter did, so it is purely an added, + backward-compatible capability. Args: key: Key to get enum item. @@ -184,17 +180,17 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco # # NOTE: the delegation below is exception-compatible for the keys this # signature admits -- an unrecognised :class:`int` still reaches the - # caller as a :exc:`ValueError`, now the base's own + # caller as a :exc:`ValueError`, the base's own # :exc:`~pcapkit.utilities.exceptions.EnumValueError` since GitHub issue # #923 rather than ``aenum``'s bare one. It is not compatible for # keys outside it: ``None``, a :class:`float` and an unhashable key - # used to raise :exc:`AttributeError` from the ``key.lower()`` this - # branch no longer reaches, and now raise :exc:`ValueError` (or, for a + # raised :exc:`AttributeError` from ``key.lower()`` before the + # delegation, and raise :exc:`ValueError` through it (or, for a # :class:`float`, resolve -- ``get(1.0)`` answers ``tcp``, since # ``cls(key)`` accepts whatever :class:`int` equality accepts). No - # caller in this tree can reach any of those: the only live call site - # passes ``proto.lower()``, always a :class:`str`. The new shape is - # what every other ``EnumLookup`` subclass already does. + # caller inside :mod:`pcapkit` can reach any of those: the only live call + # site passes ``proto.lower()``, always a :class:`str`. Delegating is + # what every other ``EnumLookup`` subclass does. return super().get(key, default) # NOTE: ``_missing_`` used to range-check ``value`` and then defer to @@ -2472,7 +2468,7 @@ def __repr__(self) -> 'str': # the plain form GitHub issue #806 already fixed: it is appended only # when :attr:`aliases` is non-empty, so every member that does not # share its port with another service -- the vast majority -- renders - # exactly as it did before this issue. Registering a new alias through + # in the plain form unchanged. Registering a new alias through # :meth:`register_alias` changes what *every* member already on that # port renders, immediately, since :attr:`aliases` is derived fresh on # each call rather than fixed at construction. @@ -2717,8 +2713,9 @@ def get_all(cls, key: 'int', *, :meth:`get` answers with one member because that is what a port lookup means everywhere else -- :func:`socket.getservbyport` returns a single - name -- but IANA really did register all three services on TCP/80, and - discarding two of them would be inventing a registry it does not have. + name -- but IANA really does register more than one service on some + ports, TCP/80 among them, and discarding all but one would be inventing + a registry it does not have. This is how the rest are reached. Args: diff --git a/pcapkit/vendor/mh/binding_ack_flag.py b/pcapkit/vendor/mh/binding_ack_flag.py index 924ac41a76..2972d06621 100644 --- a/pcapkit/vendor/mh/binding_ack_flag.py +++ b/pcapkit/vendor/mh/binding_ack_flag.py @@ -97,7 +97,7 @@ class BindingACKFlag(Vendor): #: Link to registry. LINK = 'https://www.iana.org/assignments/mobility-parameters/mobility-parameters-12.csv' - def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # pylint: disable=arguments-differ,arguments-renamed + def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] """Process CSV data. Args: @@ -145,11 +145,11 @@ def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # enum.append(f'{sufs}\n {pres}') return enum - def context(self, data: 'list[str]') -> 'str': # pylint: disable=arguments-differ,arguments-renamed + def context(self, data: 'list[str]') -> 'str': """Generate constant context. Args: - soup: Parsed HTML source. + data: CSV data. Returns: Constant context. diff --git a/pcapkit/vendor/mh/binding_update_flag.py b/pcapkit/vendor/mh/binding_update_flag.py index 88e49a0755..5f14e4b29f 100644 --- a/pcapkit/vendor/mh/binding_update_flag.py +++ b/pcapkit/vendor/mh/binding_update_flag.py @@ -96,7 +96,7 @@ class BindingUpdateFlag(Vendor): #: Link to registry. LINK = 'https://www.iana.org/assignments/mobility-parameters/mobility-parameters-11.csv' - def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # pylint: disable=arguments-differ,arguments-renamed + def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] """Process CSV data. Args: @@ -144,11 +144,11 @@ def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # enum.append(f'{sufs}\n {pres}') return enum - def context(self, data: 'list[str]') -> 'str': # pylint: disable=arguments-differ,arguments-renamed + def context(self, data: 'list[str]') -> 'str': """Generate constant context. Args: - soup: Parsed HTML source. + data: CSV data. Returns: Constant context. diff --git a/pcapkit/vendor/mh/handover_ack_flag.py b/pcapkit/vendor/mh/handover_ack_flag.py index d2311ee496..ca3b8b790e 100644 --- a/pcapkit/vendor/mh/handover_ack_flag.py +++ b/pcapkit/vendor/mh/handover_ack_flag.py @@ -97,7 +97,7 @@ class HandoverACKFlag(Vendor): #: Link to registry. LINK = 'https://www.iana.org/assignments/mobility-parameters/handover-acknowledge-flags.csv' - def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # pylint: disable=arguments-differ,arguments-renamed + def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] """Process CSV data. Args: @@ -140,11 +140,11 @@ def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # enum.append(f'{sufs}\n {pres}') return enum - def context(self, data: 'list[str]') -> 'str': # pylint: disable=arguments-differ,arguments-renamed + def context(self, data: 'list[str]') -> 'str': """Generate constant context. Args: - soup: Parsed HTML source. + data: CSV data. Returns: Constant context. diff --git a/pcapkit/vendor/mh/handover_initiate_flag.py b/pcapkit/vendor/mh/handover_initiate_flag.py index f312a54914..874471bdf4 100644 --- a/pcapkit/vendor/mh/handover_initiate_flag.py +++ b/pcapkit/vendor/mh/handover_initiate_flag.py @@ -97,7 +97,7 @@ class HandoverInitiateFlag(Vendor): #: Link to registry. LINK = 'https://www.iana.org/assignments/mobility-parameters/handover-initiate-flags.csv' - def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # pylint: disable=arguments-differ,arguments-renamed + def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] """Process CSV data. Args: @@ -140,11 +140,11 @@ def process(self, data: 'list[str]') -> 'list[str]': # type: ignore[override] # enum.append(f'{sufs}\n {pres}') return enum - def context(self, data: 'list[str]') -> 'str': # pylint: disable=arguments-differ,arguments-renamed + def context(self, data: 'list[str]') -> 'str': """Generate constant context. Args: - soup: Parsed HTML source. + data: CSV data. Returns: Constant context. diff --git a/pcapkit/vendor/pcapng/option_type.py b/pcapkit/vendor/pcapng/option_type.py index 033fcc5581..66bd382953 100644 --- a/pcapkit/vendor/pcapng/option_type.py +++ b/pcapkit/vendor/pcapng/option_type.py @@ -472,7 +472,7 @@ def context(self, soup: 'dict[str, list[Tag]]') -> 'str': # type: ignore[overri """Generate constant context. Args: - data: CSV data. + soup: Registry data. Returns: Constant context. diff --git a/pcapkit/vendor/reg/apptype/apptype.py b/pcapkit/vendor/reg/apptype/apptype.py index 63b60645fb..f4b29ef8c5 100644 --- a/pcapkit/vendor/reg/apptype/apptype.py +++ b/pcapkit/vendor/reg/apptype/apptype.py @@ -147,7 +147,7 @@ class TransportProtocol(EnumLookup, IntEnum): # instead of being split. With no decoding left to protect, the owner's own # further ruling on GitHub issue #860 retired the power-of-two spacing # itself too: that spacing existed mainly for code that composed values like - # ``tcp | udp``, which the new logic no longer accepts, so sequential + # ``tcp | udp``, which the whole-value lookup does not accept, so sequential # ``auto()`` values are the expected behaviour. :meth:`AppType._dispatch` # never decodes an ``int`` -- composed by hand with ``|`` or passed bare -- # into anything narrower than the whole value it already is, on either @@ -160,8 +160,8 @@ class TransportProtocol(EnumLookup, IntEnum): # ``sctp``'s value -- resolves as ``dccp``'s, silently, with no # exception, since a real member sits at ``4`` either way. A caller holding # an integer under the old spacing (composed or not) can therefore land on a - # different real transport's registry after this change, not merely be - # refused where it previously resolved. + # different real transport's registry under the sequential numbering, not + # merely be refused where it previously resolved. #: No transport protocol. ``TransportProtocol(0) is undefined`` and #: ``bool(undefined)`` is ``False``; it is the ``proto`` sentinel default @@ -200,14 +200,12 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco ``Enum`` would raise in the circumstances, :exc:`ValueError` or :exc:`KeyError` as the case may be, and is to come from :mod:`pcapkit.utilities.exceptions` rather than being a builtin. A - stdlib ``E['nosuch']`` raises :exc:`KeyError`, and :issue:`923`'s census of the - 127 concrete :class:`~pcapkit.corekit.enum.EnumLookup` subclasses -- - taken before the phase-2 re-parenting moved this class, so it is not - among them -- found 119 already answering a name miss that way against 5 - answering with :exc:`ValueError`. Those 5 are :class:`AppType` and its - four transport registries, and they land there only because their own - ``get()`` takes an :class:`int` port and never accepts a name at all, - rather than from any name-miss policy. So there was no policy here to + stdlib ``E['nosuch']`` raises :exc:`KeyError`, and :issue:`923`'s census + found :class:`~pcapkit.corekit.enum.EnumLookup` subclasses answering a + name miss that way. The exceptions were :class:`AppType` and its + per-transport registries, and they answered with :exc:`ValueError` only + because their own ``get()`` takes an :class:`int` port and never accepts + a name at all, rather than from any name-miss policy. So there was no policy here to preserve, and a name miss reaches the caller as :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The maintainer's ruling given in review of the work for :issue:`808`, that @@ -219,25 +217,23 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco (:meth:`~pcapkit.corekit.enum.EnumLookup.get`), so this override moves from :class:`staticmethod` to :class:`classmethod` to delegate at all -- the same move GitHub issue :issue:`908` made for - :meth:`~pcapkit.const.http.method.Method.get`. Grepped every call - site in this tree for GitHub issue :issue:`877`: all call this method by - name, none take it as a bare callable or introspect ``__func__``, - so the switch is not caller-visible. - - ``default`` did not exist on this override before this change -- - the original had no such parameter at all, which is a genuine LSP - violation once this class' ``get`` is a :class:`classmethod` - override of one that has it: a caller holding a - :class:`~pcapkit.corekit.enum.EnumLookup`-typed reference could pass - ``default=`` and, before this, would have hit a - :exc:`TypeError` at this subclass. Forwarded verbatim to + :meth:`~pcapkit.const.http.method.Method.get`. A caller invoking it by + name sees no difference between the two; only code taking it as a bare + callable or introspecting ``__func__`` could tell them apart. + + ``default`` is accepted here because the original override had no + such parameter at all, which is a genuine LSP violation once this + class' ``get`` is a :class:`classmethod` override of one that has + it: a caller holding a :class:`~pcapkit.corekit.enum.EnumLookup`-typed + reference could pass ``default=`` and hit a :exc:`TypeError` at this + subclass. Forwarded verbatim to :meth:`~pcapkit.corekit.enum.EnumLookup.get` rather than reimplemented, so it behaves exactly as the base's own ``default`` does: a fallback to an *already-registered* value, resolved through ``_value2member_map_`` and never through the constructor, so - passing one still cannot mint. Every call site in this tree omits - it, so this is purely an added, backward-compatible capability, not - a change to anything this tree exercises today. + passing one still cannot mint. A call that omits it resolves exactly + as one made without the parameter did, so it is purely an added, + backward-compatible capability. Args: key: Key to get enum item. @@ -276,17 +272,17 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco # # NOTE: the delegation below is exception-compatible for the keys this # signature admits -- an unrecognised :class:`int` still reaches the - # caller as a :exc:`ValueError`, now the base's own + # caller as a :exc:`ValueError`, the base's own # :exc:`~pcapkit.utilities.exceptions.EnumValueError` since GitHub issue # #923 rather than ``aenum``'s bare one. It is not compatible for # keys outside it: ``None``, a :class:`float` and an unhashable key - # used to raise :exc:`AttributeError` from the ``key.lower()`` this - # branch no longer reaches, and now raise :exc:`ValueError` (or, for a + # raised :exc:`AttributeError` from ``key.lower()`` before the + # delegation, and raise :exc:`ValueError` through it (or, for a # :class:`float`, resolve -- ``get(1.0)`` answers ``tcp``, since # ``cls(key)`` accepts whatever :class:`int` equality accepts). No - # caller in this tree can reach any of those: the only live call site - # passes ``proto.lower()``, always a :class:`str`. The new shape is - # what every other ``EnumLookup`` subclass already does. + # caller inside :mod:`pcapkit` can reach any of those: the only live call + # site passes ``proto.lower()``, always a :class:`str`. Delegating is + # what every other ``EnumLookup`` subclass does. return super().get(key, default) # NOTE: ``_missing_`` used to range-check ``value`` and then defer to @@ -426,7 +422,7 @@ def __repr__(self) -> 'str': # the plain form GitHub issue #806 already fixed: it is appended only # when :attr:`aliases` is non-empty, so every member that does not # share its port with another service -- the vast majority -- renders - # exactly as it did before this issue. Registering a new alias through + # in the plain form unchanged. Registering a new alias through # :meth:`register_alias` changes what *every* member already on that # port renders, immediately, since :attr:`aliases` is derived fresh on # each call rather than fixed at construction. @@ -671,8 +667,9 @@ def get_all(cls, key: 'int', *, :meth:`get` answers with one member because that is what a port lookup means everywhere else -- :func:`socket.getservbyport` returns a single - name -- but IANA really did register all three services on TCP/80, and - discarding two of them would be inventing a registry it does not have. + name -- but IANA really does register more than one service on some + ports, TCP/80 among them, and discarding all but one would be inventing + a registry it does not have. This is how the rest are reached. Args: diff --git a/pcapkit/vendor/vlan/priority_level.py b/pcapkit/vendor/vlan/priority_level.py index cfb450a5a3..e3a7e4e7eb 100644 --- a/pcapkit/vendor/vlan/priority_level.py +++ b/pcapkit/vendor/vlan/priority_level.py @@ -54,7 +54,7 @@ def process(self, soup: 'BeautifulSoup') -> 'tuple[list[str], list[str]]': # py """Process HTML data. Args: - data: Parsed HTML source. + soup: Parsed HTML source. Returns: Enumeration fields and missing fields. diff --git a/tests/test_docstring_contract.py b/tests/test_docstring_contract.py index 58c6448f95..61a43e6e38 100644 --- a/tests/test_docstring_contract.py +++ b/tests/test_docstring_contract.py @@ -90,8 +90,8 @@ why :func:`_documented_names` normalises ``\\_`` before comparing: a plain string match drops that entry and then reports a defect that is not there. -:data:`KNOWN_DEFECTS` carries the findings this change did not fix, each with -the reason. :meth:`DocstringParameterTests.test_known_defects_are_still_defects` +:data:`KNOWN_DEFECTS` carries any finding left unfixed, each with the +reason. :meth:`DocstringParameterTests.test_known_defects_are_still_defects` asserts every one of them still reproduces, so the list cannot rot -- when the owning change lands, that test fails and the entry has to be removed rather than sitting there forever describing a bug that is gone. @@ -216,37 +216,10 @@ class Known(NamedTuple): reason: 'str' -#: Defects this change deliberately left alone, every one because the file -#: belongs to another concurrent change and editing it would silently discard -#: that work. The corrections are recorded in the issue thread; nothing here -#: is a claim that the docstring is right. -KNOWN_DEFECTS = ( - # NOTE: the ``register_extractor_engine`` entry that used to head this tuple - # is gone because the defect is fixed -- it documented 'engine' where the - # parameter is 'name', which is #546's item 2. The remaining register_* - # functions in that file were checked at the same time and none of them - # carries the same defect, so there is nothing left to record here for it. - Known(Finding('pcapkit/vendor/mh/binding_ack_flag.py', 'context', 'soup'), - "documents 'soup: Parsed HTML source.' where the parameter is 'data' " - "and holds CSV rows. Nothing was renamed here despite the " - '``# pylint: disable=arguments-renamed`` pragma -- the parameter ' - 'matches the base ``Vendor.context(self, data)`` in ' - 'pcapkit/vendor/default.py:445, which documents it as ' - "'data: CSV data.'. The line was copy-pasted from a sibling whose " - "process()/context() really does take 'soup', so both the name and " - 'the description are wrong'), - Known(Finding('pcapkit/vendor/mh/binding_update_flag.py', 'context', 'soup'), - "documents 'soup' where the parameter is 'data'"), - Known(Finding('pcapkit/vendor/mh/handover_ack_flag.py', 'context', 'soup'), - "documents 'soup' where the parameter is 'data'"), - Known(Finding('pcapkit/vendor/mh/handover_initiate_flag.py', 'context', 'soup'), - "documents 'soup' where the parameter is 'data'"), - Known(Finding('pcapkit/vendor/pcapng/option_type.py', 'context', 'data'), - "documents 'data: CSV data.' where the parameter is 'soup' and holds " - 'parsed HTML -- the name and the description are both wrong'), - Known(Finding('pcapkit/vendor/vlan/priority_level.py', 'process', 'data'), - "documents 'data' where the parameter is 'soup'"), -) +#: Defects excused from +#: :meth:`DocstringParameterTests.test_documented_parameters_exist`, each a +#: :class:`Known` carrying the reason it is left unfixed. None is excused. +KNOWN_DEFECTS = () #: Swallowed section headers excused from #: :meth:`DocstringParameterTests.test_section_headers_are_not_swallowed`, in