diff --git a/pcapkit/protocols/internet/ah.py b/pcapkit/protocols/internet/ah.py index 11f99570b..b5d9c88d0 100644 --- a/pcapkit/protocols/internet/ah.py +++ b/pcapkit/protocols/internet/ah.py @@ -51,7 +51,7 @@ class AH(IPsec[Data_AH, Schema_AH], IPv6_Ext[Data_AH, Schema_AH], schema=Schema_AH, data=Data_AH): """This class implements Authentication Header. - Double-inherited (GitHub issue #917): ``AH`` is both a member of the + Double-inherited (GitHub issue :issue:`917`): ``AH`` is both a member of the IPsec family and an IPv6 extension header -- IANA's *IPv6 Extension Header Types* registry lists it at 51 (:rfc:`4302#section-3.1.1` has it appear after the hop-by-hop, routing and fragmentation extension @@ -86,7 +86,7 @@ def alias(self) -> 'Literal["AH"]': class-name default, because :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` now sits between this class and that default in the MRO and carries a concrete - ``'IPv6-Ext'`` of its own (GitHub issue #917). Inheriting it would + ``'IPv6-Ext'`` of its own (GitHub issue :issue:`917`). Inheriting it would rename this header in every :class:`~pcapkit.corekit.protochain.ProtoChain` string and in :meth:`IPv6._decode_next_layer diff --git a/pcapkit/protocols/internet/esp.py b/pcapkit/protocols/internet/esp.py index 7a1f50585..86fff04f0 100644 --- a/pcapkit/protocols/internet/esp.py +++ b/pcapkit/protocols/internet/esp.py @@ -459,7 +459,7 @@ class ESPStatus(EnumLookup, enum.IntEnum): """Outcome of ESP payload processing. Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub - issue #930, finishing #877's phase 2 -- pure re-parenting, since this + issue :issue:`930`, finishing :issue:`877`'s phase 2 -- pure re-parenting, since this class defines neither ``get`` nor ``_missing_`` of its own to reconcile with the base. @@ -525,7 +525,7 @@ class SecurityAssociation: Raises: ProtocolError: If the algorithms or key lengths are inconsistent, or - ``destination`` is a :obj:`bool` (c.f. #491) -- :obj:`bool` is an + ``destination`` is a :obj:`bool` (c.f. :issue:`491`) -- :obj:`bool` is an :class:`int` subclass, and :func:`ipaddress.ip_address` treats any :class:`int` below ``2**32`` as IPv4, so without this check ``destination=True`` would silently become @@ -975,7 +975,7 @@ class ESP(IPsec[Data_ESP, Schema_ESP], IPv6_Ext[Data_ESP, Schema_ESP], schema=Schema_ESP, data=Data_ESP): """This class implements Encapsulating Security Payload. - Double-inherited (GitHub issue #917), mirroring + Double-inherited (GitHub issue :issue:`917`), mirroring :class:`~pcapkit.protocols.internet.ah.AH`: IANA's *IPv6 Extension Header Types* registry lists ``ESP`` at 50 (:rfc:`4303#section-3.1.1` has it appear after the hop-by-hop, routing and fragmentation @@ -995,7 +995,7 @@ class ESP(IPsec[Data_ESP, Schema_ESP], IPv6_Ext[Data_ESP, Schema_ESP], Note: :rfc:`8200#section-4.5` says outright that ESP "is not considered an extension header". The library follows IANA's registry rather than - that sentence, on the owner's ruling for GitHub issue #895. + that sentence, on the owner's ruling for GitHub issue :issue:`895`. """ diff --git a/pcapkit/protocols/internet/hip.py b/pcapkit/protocols/internet/hip.py index a0ff409f3..eb02a2adc 100644 --- a/pcapkit/protocols/internet/hip.py +++ b/pcapkit/protocols/internet/hip.py @@ -260,7 +260,7 @@ class HIP(IPv6_Ext[Data_HIP, Schema_HIP], Internet[Data_HIP, Schema_HIP], """This class implements Host Identity Protocol. Double-inherited, per the maintainer's convention given in review of the - work for #917: a header that is *only* usable as an extension header + work for :issue:`917`: a header that is *only* usable as an extension header inherits :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` alone, while one that is also usable as a standalone protocol names :class:`~pcapkit.protocols.internet.internet.Internet` as well. HIP is @@ -3263,8 +3263,8 @@ def _make_puzzle_field_width(code: 'Enum_Parameter', version: 'int', Only case 4 can lose a leading zero octet, and it is the only case where the width is genuinely unknowable -- a from-scratch HIPv2 build with nothing declaring it. Reaching for it unconditionally is what re-serialised a - ``Length = 20`` ``SOLUTION`` as ``Length = 6`` (#653) and what built, under - HIPv1, parameters this library's own reader then rejected (#655). + ``Length = 20`` ``SOLUTION`` as ``Length = 6`` (:issue:`653`) and what built, under + HIPv1, parameters this library's own reader then rejected (:issue:`655`). Two things this deliberately does *not* reject, both of which look like oversights and are not: diff --git a/pcapkit/protocols/internet/hopopt.py b/pcapkit/protocols/internet/hopopt.py index 6f9b5a2ea..6e88b0892 100644 --- a/pcapkit/protocols/internet/hopopt.py +++ b/pcapkit/protocols/internet/hopopt.py @@ -231,7 +231,7 @@ def alias(self) -> 'Literal["HOPOPT"]': class-name default, because :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` now sits between this class and that default in the MRO and carries a concrete - ``'IPv6-Ext'`` of its own (GitHub issue #917). Inheriting it would + ``'IPv6-Ext'`` of its own (GitHub issue :issue:`917`). Inheriting it would rename this header in every :class:`~pcapkit.corekit.protochain.ProtoChain` string and in :meth:`IPv6._decode_next_layer @@ -487,8 +487,8 @@ def _hopopt_option_length(schema_len: 'int') -> 'int': Section 4.2 is the citation because it is what defines the TLV option format, and it is where the sentence quoted above actually appears. - This cited :rfc:`8200#section-4.3` until #530, which is a subtler - error than the one #517 fixed in the IPv6-Opts sibling: Section 4.3 + This cited :rfc:`8200#section-4.3` until :issue:`530`, which is a subtler + error than the one :issue:`517` fixed in the IPv6-Opts sibling: Section 4.3 is not the wrong *header* -- it is the Hop-by-Hop Options header, which is exactly what this class implements -- but it is the wrong place for this arithmetic. It defines no ``Opt Data Len`` at all, diff --git a/pcapkit/protocols/internet/ipv4.py b/pcapkit/protocols/internet/ipv4.py index dc0883aee..ae0100c60 100644 --- a/pcapkit/protocols/internet/ipv4.py +++ b/pcapkit/protocols/internet/ipv4.py @@ -1406,7 +1406,7 @@ def _make_opt_sec(self, kind: 'Enum_OptionNumber', option: 'Optional[Data_SECOpt :meth:`_read_opt_sec` encodes by looping over ``range(7)`` per octet, and the reason ``Field_Termination_Indicator`` is rejected here rather than written: the enumeration names it as structure, and - a value written there would be dropped on the way back in. See #537. + a value written there would be dropped on the way back in. See :issue:`537`. """ if option is not None: diff --git a/pcapkit/protocols/internet/ipv6.py b/pcapkit/protocols/internet/ipv6.py index 4a6a14c8e..28b8d0dae 100644 --- a/pcapkit/protocols/internet/ipv6.py +++ b/pcapkit/protocols/internet/ipv6.py @@ -71,7 +71,7 @@ class IPv6(IP[Data_IPv6, Schema_IPv6], #: :func:`~pcapkit.utilities.decorators.beholder` fall back to plain #: :class:`~pcapkit.protocols.misc.raw.Raw`, which has no ``next`` field #: and used to crash the whole packet at :meth:`_decode_next_layer`'s - #: ``proto = info.next`` (GitHub issue #891). + #: ``proto = info.next`` (GitHub issue :issue:`891`). #: #: :attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.Shim6` #: is deliberately absent, even though its wire format also conforms: @@ -101,7 +101,7 @@ class IPv6(IP[Data_IPv6, Schema_IPv6], #: * ``253`` and ``254`` have no dedicated parser at all, so they resolve #: to plain :class:`~pcapkit.protocols.misc.raw.Raw`, whose info has no #: ``next`` *attribute* -- this is what the structural check catches. - #: (``BIT-EMU``/147 used to sit here too, until GitHub issue #925 found + #: (``BIT-EMU``/147 used to sit here too, until GitHub issue :issue:`925` found #: it was never in IANA's authoritative extension-header registry to #: begin with; :class:`~pcapkit.const.ipv6.extension_header #: .ExtensionHeader` no longer carries it, so a next-header byte of 147 @@ -502,7 +502,7 @@ def _import_next_layer(self, proto: 'int', length: 'Optional[int]' = None, *, # :class:`~pcapkit.protocols.misc.raw.Raw` -- and ``Raw`` has no ``next`` field, which is what used to crash the whole packet at :meth:`_decode_next_layer`'s ``proto = info.next`` (GitHub issue - #891). Every other exception -- including one raised by + :issue:`891`). Every other exception -- including one raised by ``IPv6_Ext`` itself, or by ``ESP``'s own dedicated parser -- still reaches ``beholder`` unchanged, so *this method's own* behaviour for anything outside that closed set is diff --git a/pcapkit/protocols/internet/ipv6_ext.py b/pcapkit/protocols/internet/ipv6_ext.py index df19d1b85..894e8d6b2 100644 --- a/pcapkit/protocols/internet/ipv6_ext.py +++ b/pcapkit/protocols/internet/ipv6_ext.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.internet.ipv6_ext` contains :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` -only, which serves two roles at once (GitHub issue #917): it is the +only, which serves two roles at once (GitHub issue :issue:`917`): it is the shared **base class** of every IPv6 extension header in this package, and it implements a **generic** extractor for IPv6 extension headers, standing in for one whenever the header's own dedicated parser is @@ -64,7 +64,7 @@ This table classifies by *wire format* alone, over the eleven codes :class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader` enumerates -- matching IANA's own *IPv6 Extension Header Types* registry exactly, as of -GitHub issue #925. Before that fix this package generated the enumeration +GitHub issue :issue:`925`. Before that fix this package generated the enumeration out of the *Protocol Numbers* registry's extension-header column instead, which carried a twelfth code, ``BIT_EMU`` (147), that the authoritative registry does not; 147 was never reachable through this class either way @@ -110,14 +110,14 @@ used to default it to plain :class:`~pcapkit.protocols.misc.raw.Raw` -- which has no ``next`` field, so the walk in :meth:`IPv6._decode_next_layer ` - crashed on it (GitHub issue #891). This module registers itself for that + crashed on it (GitHub issue :issue:`891`). This module registers itself for that code instead (see the bottom of the module), so dispatch reaches a working generic parser directly. That registration is global -- shared by every :class:`~pcapkit.protocols.internet.internet.Internet` subclass -- so :meth:`__post_init__` gates on ``version == 6`` to keep it from also activating for an IPv4 payload that happens to carry protocol number 140; see its docstring for what that would otherwise do. -2. **A recognised header whose own parser raises.** This is the actual #891 +2. **A recognised header whose own parser raises.** This is the actual :issue:`891` defect: ``HOPOPT``, ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all have dedicated classes, and when one of *those* raises, :func:`~pcapkit.utilities.decorators.beholder` @@ -214,7 +214,7 @@ class IPv6_Ext(Internet[_PT, _ST], Generic[_PT, _ST], The two roles -------------- - This one class plays both, on the owner's ruling for GitHub issue #917: + This one class plays both, on the owner's ruling for GitHub issue :issue:`917`: 1. **The concrete fallback parser** for an :rfc:`6564`-conforming header this package has no dedicated class for, or whose dedicated class @@ -311,7 +311,7 @@ def protocol(self) -> 'Optional[Enum_ExtensionHeader] | Optional[str]': module's own schema -- this is **not** the base :attr:`Protocol.protocol ` meaning ("name of next layer protocol"); it is deliberately - repointed, on the owner's ruling for GitHub issue #891, at this + repointed, on the owner's ruling for GitHub issue :issue:`891`, at this instance's *own* identity -- which header's format it parsed, e.g. :attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.HOPOPT` or :attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.Shim6`. @@ -357,7 +357,7 @@ def next(self) -> 'Optional[Enum_TransType]': Shared by every subclass rather than fallback-role-only -- see :class:`_NextHeaderData` for why that is sound. Note this is an *addition* for the eight implemented headers: none of them declared a - ``next`` property of its own before GitHub issue #917, so reading one + ``next`` property of its own before GitHub issue :issue:`917`, so reading one raised :exc:`AttributeError`, and nothing could have depended on a value it never returned. diff --git a/pcapkit/protocols/internet/ipv6_opts.py b/pcapkit/protocols/internet/ipv6_opts.py index 17e8e291b..b301f2a45 100644 --- a/pcapkit/protocols/internet/ipv6_opts.py +++ b/pcapkit/protocols/internet/ipv6_opts.py @@ -482,7 +482,7 @@ def _ipv6_opts_option_length(schema_len: 'int') -> 'int': IPv6-Opts itself is the Destination Options header of :rfc:`8200#section-4.6`, which carries those TLVs but says nothing about their internal length arithmetic. This cited - :rfc:`8200#section-4.3` until #517 -- that is the Hop-by-Hop Options + :rfc:`8200#section-4.3` until :issue:`517` -- that is the Hop-by-Hop Options header, which is a different header and not the one this class implements. diff --git a/pcapkit/protocols/internet/ipv6_route.py b/pcapkit/protocols/internet/ipv6_route.py index fb41e7b8d..c86fdb0a1 100644 --- a/pcapkit/protocols/internet/ipv6_route.py +++ b/pcapkit/protocols/internet/ipv6_route.py @@ -237,8 +237,8 @@ def _make_hdr_ext_len(data_length: 'int') -> 'int': is one helper now rather than two call sites. Do NOT "simplify" the ``- 4`` / ``/ 8`` away: the units either side of it differ (octets vs. 8-octet units), and dropping the offset silently reinterprets - the field, which is exactly the defect #487 fixed (compare the - ``* 8`` unit bug behind #483 in the scapy adapter). + the field, which is exactly the defect :issue:`487` fixed (compare the + ``* 8`` unit bug behind :issue:`483` in the scapy adapter). Args: data_length: packed length, in octets, of the type-specific data diff --git a/pcapkit/protocols/internet/mh.py b/pcapkit/protocols/internet/mh.py index fd07b6a2f..657254565 100644 --- a/pcapkit/protocols/internet/mh.py +++ b/pcapkit/protocols/internet/mh.py @@ -575,13 +575,13 @@ class FastBindingAcknowledgmentStatus(EnumLookup, IntEnum): Note: Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub - issue #930, finishing #877's phase 2. :meth:`_missing_` below is + issue :issue:`930`, finishing :issue:`877`'s phase 2. :meth:`_missing_` below is untouched, since :class:`EnumLookup` does not touch that hook. This class carried its own hand-rolled ``get()`` override through - #930, and briefly again through GitHub issue #935's first attempt, + :issue:`930`, and briefly again through GitHub issue :issue:`935`'s first attempt, which widened the override to accept ``default`` rather than delete - it outright. An earlier lean on issue #935 had preferred that + it outright. An earlier lean on issue :issue:`935` had preferred that widening; a later ruling in review of the attempt went the other way: delete both ``get`` overrides in this module rather than widen them, so :class:`FastBindingAcknowledgmentStatus` and @@ -598,10 +598,10 @@ class FastBindingAcknowledgmentStatus(EnumLookup, IntEnum): :meth:`~pcapkit.corekit.enum.EnumLookup.get` already provides for every other :class:`int`-valued registry in this tree. There was nothing left to backport. ``get``/``get_all`` now come from the base - alone, the same as the five other re-parents #930 finished alongside + alone, the same as the five other re-parents :issue:`930` finished alongside this one -- including :class:`LocalizedRoutingStatus` and :class:`LMAAddressCode` below, whose own hand-rolled ``get()`` - GitHub issue #880 had already deleted outright, for the same reason: + GitHub issue :issue:`880` had already deleted outright, for the same reason: zero callers depended on anything the base does not already do. A behaviour change comes with the deletion, deliberately: the @@ -631,7 +631,7 @@ class and :class:`IPv6AddressPrefixCode` had between them, all in The enumeration is **closed**: an in-range value :rfc:`5568` leaves unassigned is not minted a placeholder member. Per the owner's ruling - on GitHub issue #877, this RFC-inline value set stays immutable, so + on GitHub issue :issue:`877`, this RFC-inline value set stays immutable, so :meth:`_missing_` raises :exc:`~pcapkit.utilities.exceptions.EnumValueError` instead of extending the class. That is not a capture-level failure -- sibling frames are unaffected -- but the cost is bigger than one @@ -646,7 +646,7 @@ class and :class:`IPv6AddressPrefixCode` had between them, all in just this one MH message. The walk defect predates this change and already fires on a malformed extension header; a well-formed packet naming merely an unassigned byte is simply a more likely way to - reach it. See GitHub issue #880. + reach it. See GitHub issue :issue:`880`. """ @@ -679,7 +679,7 @@ def _missing_(cls, value: 'int') -> 'NoReturn': Raises: EnumValueError: Always. :rfc:`5568#section-6.2.3` names this value set inline with no IANA registry behind it, and the owner's - ruling on GitHub issue #877 is that it stays immutable rather + ruling on GitHub issue :issue:`877` is that it stays immutable rather than minting an ``Unassigned_N`` placeholder member. """ @@ -695,13 +695,13 @@ class IPv6AddressPrefixCode(EnumLookup, IntEnum): Note: Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub - issue #930, finishing #877's phase 2. :meth:`_missing_` below is + issue :issue:`930`, finishing :issue:`877`'s phase 2. :meth:`_missing_` below is untouched, since :class:`EnumLookup` does not touch that hook. This class carried its own hand-rolled ``get()`` override through - #930, and briefly again through GitHub issue #935's first attempt, + :issue:`930`, and briefly again through GitHub issue :issue:`935`'s first attempt, which widened the override to accept ``default`` rather than delete - it outright. An earlier lean on issue #935 had preferred that + it outright. An earlier lean on issue :issue:`935` had preferred that widening; a later ruling in review of the attempt went the other way: delete both ``get`` overrides in this module rather than widen them, so :class:`FastBindingAcknowledgmentStatus` and @@ -718,11 +718,11 @@ class IPv6AddressPrefixCode(EnumLookup, IntEnum): :meth:`~pcapkit.corekit.enum.EnumLookup.get` already provides for every other :class:`int`-valued registry in this tree. There was nothing left to backport. ``get``/``get_all`` now come from the base - alone, the same as the five other re-parents #930 finished alongside + alone, the same as the five other re-parents :issue:`930` finished alongside this one -- including :class:`~pcapkit.protocols.internet.mh.LocalizedRoutingStatus` and :class:`~pcapkit.protocols.internet.mh.LMAAddressCode` below, whose - own hand-rolled ``get()`` GitHub issue #880 had already deleted + own hand-rolled ``get()`` GitHub issue :issue:`880` had already deleted outright, for the same reason: zero callers depended on anything the base does not already do. @@ -750,7 +750,7 @@ class and :class:`FastBindingAcknowledgmentStatus` had between The enumeration is **closed**: an in-range value :rfc:`5568` leaves unassigned is not minted a placeholder member. Per the owner's ruling - on GitHub issue #877, this RFC-inline value set stays immutable, so + on GitHub issue :issue:`877`, this RFC-inline value set stays immutable, so :meth:`_missing_` raises :exc:`~pcapkit.utilities.exceptions.EnumValueError` instead of extending the class. That is not a capture-level failure -- sibling frames are unaffected -- but the cost is bigger than one @@ -765,7 +765,7 @@ class and :class:`FastBindingAcknowledgmentStatus` had between just this one MH message. The walk defect predates this change and already fires on a malformed extension header; a well-formed packet naming merely an unassigned byte is simply a more likely way to - reach it. See GitHub issue #880. + reach it. See GitHub issue :issue:`880`. """ @@ -792,7 +792,7 @@ def _missing_(cls, value: 'int') -> 'NoReturn': Raises: EnumValueError: Always. :rfc:`5568#section-6.4.2` names this value set inline with no IANA registry behind it, and the owner's - ruling on GitHub issue #877 is that it stays immutable rather + ruling on GitHub issue :issue:`877` is that it stays immutable rather than minting an ``Unassigned_N`` placeholder member. """ @@ -808,7 +808,7 @@ class LocalizedRoutingStatus(EnumLookup, IntEnum): Note: Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub - issue #930, finishing #877's phase 2 -- pure re-parenting as far as + issue :issue:`930`, finishing :issue:`877`'s phase 2 -- pure re-parenting as far as ``get``/``get_all`` are concerned, since this class defines no ``get`` of its own to reconcile with the base; its own :meth:`_missing_` below is untouched, since :class:`EnumLookup` does @@ -823,7 +823,7 @@ class LocalizedRoutingStatus(EnumLookup, IntEnum): The enumeration is **closed**: an in-range value :rfc:`6705` leaves unassigned is not minted a placeholder member. Per the owner's ruling - on GitHub issue #877, this RFC-inline value set stays immutable, so + on GitHub issue :issue:`877`, this RFC-inline value set stays immutable, so :meth:`_missing_` raises :exc:`~pcapkit.utilities.exceptions.EnumValueError` instead of extending the class. That is not a capture-level failure -- sibling frames are unaffected -- but the cost is bigger than one @@ -838,17 +838,17 @@ class LocalizedRoutingStatus(EnumLookup, IntEnum): just this one MH message. The walk defect predates this change and already fires on a malformed extension header; a well-formed packet naming merely an unassigned byte is simply a more likely way to - reach it. See GitHub issue #880. + reach it. See GitHub issue :issue:`880`. There is no hand-rolled ``get()`` backport here -- nor, since GitHub - issue #935, on :class:`FastBindingAcknowledgmentStatus` or + issue :issue:`935`, on :class:`FastBindingAcknowledgmentStatus` or :class:`IPv6AddressPrefixCode` either: it had zero callers repo-wide - -- tests included -- so GitHub issue #880 deleted it outright rather + -- tests included -- so GitHub issue :issue:`880` deleted it outright rather than rebuilding it on the immutable contract, the same conclusion - #935 reached separately for the other two, on a ruling given in + :issue:`935` reached separately for the other two, on a ruling given in review of that work: delete those two overrides rather than widen them to match the base, which an earlier lean on the issue had - preferred. GitHub issue #930's re-parenting above gives this class + preferred. GitHub issue :issue:`930`'s re-parenting above gives this class ``get``/``get_all`` again, but as the base's own bare lookup rather than a bespoke override -- it still cannot mint, so an unassigned value raises through ``get`` exactly as it does through the bare @@ -875,7 +875,7 @@ def _missing_(cls, value: 'int') -> 'NoReturn': Raises: EnumValueError: Always. :rfc:`6705#section-10.2` names this value set inline with no IANA registry behind it, and the owner's - ruling on GitHub issue #877 is that it stays immutable rather + ruling on GitHub issue :issue:`877` is that it stays immutable rather than minting an ``Unassigned_N`` placeholder member. """ @@ -890,7 +890,7 @@ class LMAAddressCode(EnumLookup, IntEnum): Note: Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub - issue #930, finishing #877's phase 2 -- pure re-parenting as far as + issue :issue:`930`, finishing :issue:`877`'s phase 2 -- pure re-parenting as far as ``get``/``get_all`` are concerned, since this class defines no ``get`` of its own to reconcile with the base; its own :meth:`_missing_` below is untouched, since :class:`EnumLookup` does @@ -902,7 +902,7 @@ class LMAAddressCode(EnumLookup, IntEnum): The enumeration is **closed**: an in-range value :rfc:`5949` leaves unassigned is not minted a placeholder member. Per the owner's ruling - on GitHub issue #877, this RFC-inline value set stays immutable, so + on GitHub issue :issue:`877`, this RFC-inline value set stays immutable, so :meth:`_missing_` raises :exc:`~pcapkit.utilities.exceptions.EnumValueError` instead of extending the class. That is not a capture-level failure -- sibling frames are unaffected -- but the cost is bigger than one @@ -917,17 +917,17 @@ class LMAAddressCode(EnumLookup, IntEnum): just this one MH message. The walk defect predates this change and already fires on a malformed extension header; a well-formed packet naming merely an unassigned byte is simply a more likely way to - reach it. See GitHub issue #880. + reach it. See GitHub issue :issue:`880`. There is no hand-rolled ``get()`` backport here -- nor, since GitHub - issue #935, on :class:`FastBindingAcknowledgmentStatus` or + issue :issue:`935`, on :class:`FastBindingAcknowledgmentStatus` or :class:`IPv6AddressPrefixCode` either: it had zero callers repo-wide - -- tests included -- so GitHub issue #880 deleted it outright rather + -- tests included -- so GitHub issue :issue:`880` deleted it outright rather than rebuilding it on the immutable contract, the same conclusion - #935 reached separately for the other two, on a ruling given in + :issue:`935` reached separately for the other two, on a ruling given in review of that work: delete those two overrides rather than widen them to match the base, which an earlier lean on the issue had - preferred. GitHub issue #930's re-parenting above gives this class + preferred. GitHub issue :issue:`930`'s re-parenting above gives this class ``get``/``get_all`` again, but as the base's own bare lookup rather than a bespoke override -- it still cannot mint, so an unassigned value raises through ``get`` exactly as it does through the bare @@ -954,7 +954,7 @@ def _missing_(cls, value: 'int') -> 'NoReturn': Raises: EnumValueError: Always. :rfc:`5949#section-6.2.2` names this value set inline with no IANA registry behind it, and the owner's - ruling on GitHub issue #877 is that it stays immutable rather + ruling on GitHub issue :issue:`877` is that it stays immutable rather than minting an ``Unassigned_N`` placeholder member. """ @@ -1451,7 +1451,7 @@ def alias(self) -> 'Literal["MH"]': class-name default, because :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` now sits between this class and that default in the MRO and carries a concrete - ``'IPv6-Ext'`` of its own (GitHub issue #917). Inheriting it would + ``'IPv6-Ext'`` of its own (GitHub issue :issue:`917`). Inheriting it would rename this header in every :class:`~pcapkit.corekit.protochain.ProtoChain` string and in :meth:`IPv6._decode_next_layer @@ -1565,7 +1565,7 @@ def _mh_message_length(header_len: 'int') -> 'int': ``.length``, which :meth:`~pcapkit.protocols.internet.mh.MH.read` then subtracts from the outer packet length to find the next layer's length -- precisely the role ``Hdr Ext Len`` played in - #487, and the same read-side duplication :meth:`make`'s write-side + :issue:`487`, and the same read-side duplication :meth:`make`'s write-side expression (``(len(data_val) + 6) // 8 - 1``, this formula's inverse) had already been unified out of. Do NOT drop the ``+ 1``: the units either side of it differ (octets vs. 8-octet units), and @@ -2924,7 +2924,7 @@ def _mh_option_length(schema_length: 'int') -> 'int': a CGA extension's Extension Type and Extension Data Length are two octets each [:rfc:`4581#section-2`], so those readers use :meth:`_mh_extension_length` instead. Reusing this helper for them - reported every parsed CGA extension two octets short (#512). + reported every parsed CGA extension two octets short (:issue:`512`). Note that only the *stored-length* read-side call sites are collected here -- most ``_make_opt_*`` methods recompute the wire @@ -6404,7 +6404,7 @@ def _mh_extension_length(schema_length: 'int') -> 'int': the Extension in octets, not including the first 4 octets"*. Passing these lengths through :meth:`_mh_option_length` reported every - parsed CGA extension two octets short (#512): an 8-octet extension with + parsed CGA extension two octets short (:issue:`512`): an 8-octet extension with an ``Extension Data Length`` of ``4`` came back as ``6``. Note :meth:`_make_cga_extensions` has always measured ``len(schema.pack())`` instead, so the write side was already right and only the read side @@ -7979,7 +7979,7 @@ def _make_opt_mn_id(self, type: 'Enum_Option', option: 'Optional[Data_MNIDOption (RFC 4283's ``user@realm`` form) rather than a numeric identifier, so there is no non-arbitrary int-to-text mapping the way there is int-to-address or int-to-octets, and an - :obj:`int` is rejected there (c.f. #467). + :obj:`int` is rejected there (c.f. :issue:`467`). **kwargs: Arbitrary keyword arguments. Returns: @@ -7992,7 +7992,7 @@ def _make_opt_mn_id(self, type: 'Enum_Option', option: 'Optional[Data_MNIDOption ``::1`` for ``IPv6_Address`` and to a one-octet identifier for the other six, neither of which a caller passing a flag can plausibly have meant; pass ``int(...)`` to get the numeric - value (c.f. #469). If ``identifier`` is a negative :obj:`int` + value (c.f. :issue:`469`). If ``identifier`` is a negative :obj:`int` (no subtype has a wire form for one), an :obj:`int` of any value with the ``NAI`` subtype, an :obj:`int` of ``2**128`` or above with the ``IPv6_Address`` subtype (whose wire form is a @@ -8001,9 +8001,9 @@ def _make_opt_mn_id(self, type: 'Enum_Option', option: 'Optional[Data_MNIDOption type its subtype's field cannot hold at all: anything but :obj:`str` for ``NAI``, anything but :obj:`bytes`/ :obj:`bytearray`/:obj:`int` for the other six -- an :obj:`int` - is converted rather than rejected there, per #467 -- or anything + is converted rather than rejected there, per :issue:`467` -- or anything :class:`ipaddress.IPv6Address` itself does not accept for - ``IPv6_Address`` (c.f. #469). + ``IPv6_Address`` (c.f. :issue:`469`). """ if option is not None: diff --git a/pcapkit/protocols/protocol.py b/pcapkit/protocols/protocol.py index 7ae245cce..ebae0bd33 100644 --- a/pcapkit/protocols/protocol.py +++ b/pcapkit/protocols/protocol.py @@ -340,7 +340,7 @@ class ProtocolBase(Generic[_PT, _ST], metaclass=ProtocolMeta): #: Declaring the parameter is preferable where it is possible, since that is #: also what documents the keyword to the caller and to :mod:`inspect`. This #: is for the cases where it is not -- a keyword handled uniformly for a whole - #: family of names, say -- and *not* a way to reopen the silence #617 closed: + #: family of names, say -- and *not* a way to reopen the silence :issue:`617` closed: #: it is opt-in per class, so it can only ever exempt a name whose author #: wrote it down. #: @@ -352,7 +352,7 @@ class ProtocolBase(Generic[_PT, _ST], metaclass=ProtocolMeta): #: :meth:`HTTPv1.make ` or #: :meth:`HTTPv2.make ` #: depending on that value, so no set of names is right for it. Use it only - #: for that shape; a protocol that forgoes the check gets the pre-#617 + #: for that shape; a protocol that forgoes the check gets the pre-:issue:`617` #: behaviour back, and with it the silence. Unlike a set, the :obj:`None` is #: **not** inherited: a subclass of a dispatcher is checked normally unless it #: dispatches too and says so, because ``HTTPv1`` and ``HTTPv2`` declare their @@ -363,7 +363,7 @@ class ProtocolBase(Generic[_PT, _ST], metaclass=ProtocolMeta): #: Whether this instance is being rebuilt by :meth:`from_data` from a parsed #: data model, as against constructed from keywords somebody wrote. It governs #: only whether the construction keyword check of :meth:`__init__` raises or - #: warns (#617), and is set for the duration of that call alone -- the class + #: warns (:issue:`617`), and is set for the duration of that call alone -- the class #: level :data:`False` is what every other code path sees, including an #: instance built without going through ``__init__`` at all. __reconstructing__: 'bool' = False @@ -457,7 +457,7 @@ def packet(self) -> 'Data_Packet': the option list and the trailing length field -- and :meth:`ProtocolBase.__init__` injects this payload into every parsed ``_info``, so the empty value reached the dumpers and corrupted the - files they wrote. See #646. + files they wrote. See :issue:`646`. """ try: @@ -535,7 +535,7 @@ def make(self, **kwargs: 'Any') -> '_ST': parse as well as to the construction, so an implementation is not expected to declare every keyword it is called with. It is *not* a place for a caller to put a keyword no signature declares: since - #617, building a protocol *through its constructor* with such a + :issue:`617`, building a protocol *through its constructor* with such a keyword raises :exc:`~pcapkit.utilities.exceptions.UnsupportedCall` from :meth:`ProtocolBase.__init__ ` rather than @@ -553,7 +553,7 @@ def make(self, **kwargs: 'Any') -> '_ST': ` to reach its versioned implementation. Covering it would mean interposing on every ``make`` in the tree rather than on the one place their keywords converge, which - is a larger change than #617 and deliberately not made here. Construct + is a larger change than :issue:`617` and deliberately not made here. Construct through the constructor to get the check. """ @@ -752,7 +752,7 @@ def register(cls, code: 'int', protocol: 'ModuleDescriptor | Type[ProtocolBase]' fires only when the incumbent differs from the replacement, so re-registering the exact same class object under the same ``code`` is a silent no-op rather than a warning about nothing displaced. - GitHub issue #718 corrected the previous presence-only guard here, + GitHub issue :issue:`718` corrected the previous presence-only guard here, which read every repeat registration as a caller mistake even when the value was unchanged. The identity check does not reintroduce the concern that guard was written to avoid: it is a plain ``is`` @@ -880,7 +880,7 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional keyword names no parameter of this protocol's :meth:`make`, :meth:`read`, :meth:`pack`, :meth:`unpack`, :meth:`__post_init__` or :meth:`__init__`, anywhere in the MRO, - and is not listed in :attr:`__keywords__`. See #617; until then + and is not listed in :attr:`__keywords__`. See :issue:`617`; until then such a keyword was silently discarded. Parsing (``file`` is given) is unaffected. @@ -1738,11 +1738,11 @@ def _lookup_next_layer(registry: 'DefaultDict[int, ModuleDescriptor[ProtocolBase what keeps that affordable is :attr:`ModuleDescriptor.klass ` reading :data:`sys.modules` instead of re-entering - :func:`importlib.import_module` -- see #574. Memoising the resolved + :func:`importlib.import_module` -- see :issue:`574`. Memoising the resolved class here instead, whether under ``proto``, in ``registry``'s default factory, or in a cache beside the registry, would retain a - class that :func:`importlib.reload` then makes stale; #425 at - this layer and #555 at the schema layer are all that same defect. + class that :func:`importlib.reload` then makes stale; :issue:`425` at + this layer and :issue:`555` at the schema layer are all that same defect. """ protocol = ProtocolBase._lookup_registry(registry, proto)