diff --git a/pcapkit/const/ftp/command.py b/pcapkit/const/ftp/command.py index 06dbe7670b..0187f2850d 100644 --- a/pcapkit/const/ftp/command.py +++ b/pcapkit/const/ftp/command.py @@ -34,12 +34,12 @@ class FEATCode(EnumRegistry, StrEnum): keywords generated after them (data-driven, not hand-picked; see :meth:`~pcapkit.vendor.ftp.command.Command.process`) -- rather than minting the per-command ones at import time as an incidental side - effect of building :class:`Command`'s own rows. GitHub issue #860: - that import-time mutation was the same defect shape #775 removed + effect of building :class:`Command`'s own rows. GitHub issue :issue:`860`: + that import-time mutation was the same defect shape :issue:`775` removed from :class:`~pcapkit.const.pcapng.filter_type.FilterType`, just not previously noticed here. ``_missing_`` still unmints for a keyword that turns up on the wire but names none of these -- the extendability the - owner conditionally asked to keep on GitHub issue #860: unsure what a + owner conditionally asked to keep on GitHub issue :issue:`860`: unsure what a FEAT value absent from the RFC's list means in the CSV table, the owner said that if the expected handling is our current approach, as industry convention has it, the registry stays extendable as is, and then approved @@ -99,7 +99,7 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode': """Resolve ``key`` case-insensitively, per :rfc:`5797#section-2`. One of the few case-insensitive overrides the ruling on GitHub issue - #877 allows, and the registry's own defining document states the + :issue:`877` allows, and the registry's own defining document states the comparison rule outright rather than leaving it to be inferred -- :rfc:`5797#section-2`, on the ``FEAT Code`` column this class is generated from: *"IANA maintains uniqueness of feature names (FEAT @@ -119,7 +119,7 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode': lower case -- measured on the IANA CSV: 10 distinct all-upper-case keywords against ``base``, ``feat``, ``hist``, ``nat6`` and ``secu``, with none mixed. Without this override ``get('BASE')`` raised - :exc:`KeyError`, which is the defect GitHub issue #903's audit found. + :exc:`KeyError`, which is the defect GitHub issue :issue:`903`'s audit found. The obvious objection, answered: :rfc:`5797` uses case *presentationally* to tell a real keyword from a placeholder -- *"defined FEAT keywords @@ -127,7 +127,7 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode': listed in lowercase"* -- so folding might look like it discards that distinction. It does not. Only the inbound ``key`` is folded; every member keeps the registrar's own casing, and the fold itself is backed by - the RFC: the final ruling on GitHub issue #877 is that an enum treats its + the RFC: the final ruling on GitHub issue :issue:`877` is that an enum treats its values as case-insensitive where the RFC states they are, and as case-sensitive otherwise. So ``get('BASE').name`` is still ``'base'`` and still says placeholder. And the uniqueness rule quoted above is what makes @@ -191,7 +191,7 @@ class CommandType(EnumLookup, IntFlag): """Type of "kind" of command, based on :rfc:`959#section-4`. 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 -- this class defines no ``get`` of its own to reconcile with the base -- and its own :meth:`_missing_` range guard below is untouched, since :class:`EnumLookup` does not touch that @@ -225,7 +225,7 @@ class ConformanceRequirement(EnumLookup, IntEnum): """Expectation for support in modern FTP implementations. 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. @@ -245,7 +245,7 @@ class Command(EnumRegistry, StrEnum): .. note:: Neither ``_missing_`` nor ``get()`` mints any more. The owner ruled on - GitHub issue #860 that ``get`` should not mint: only IANA-registered + GitHub issue :issue:`860` that ``get`` should not mint: only IANA-registered values are legitimate members, a new one is properly created through :meth:`register`, and ``get`` is not given enough information to create one. Concretely true here -- a bare wire command word carries no @@ -490,7 +490,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Command': name: Bare label for the unregistered member -- here, the canonical upper-case form of ``value``, matching the name every *registered* member of this class is looked up by, - since #860's open-vocabulary registries have no manufactured + since :issue:`860`'s open-vocabulary registries have no manufactured placeholder label to fall back to. """ diff --git a/pcapkit/const/http/method.py b/pcapkit/const/http/method.py index bc89eadaab..42528114a8 100644 --- a/pcapkit/const/http/method.py +++ b/pcapkit/const/http/method.py @@ -27,7 +27,7 @@ class Method(EnumRegistry, StrEnum): .. note:: Neither ``_missing_`` nor ``get()`` mints any more. The owner ruled on - GitHub issue #860 that ``get`` should not mint: only IANA-registered + GitHub issue :issue:`860` that ``get`` should not mint: only IANA-registered values are legitimate members, a new one is properly created through :meth:`register`, and ``get`` is not given enough information to create one. Concretely true here -- a bare wire method verb carries no @@ -202,14 +202,14 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Method': identifier, not the value -- is canonicalised. A *registered* member of this class used to carry something - different here: GitHub issue #870 found that + different here: GitHub issue :issue:`870` found that :meth:`__new__` called ``str.__new__(cls)`` with no argument at all, so every one of the 40 declared members' own :class:`str` payload was permanently empty regardless of ``value`` (``str(Method.GET) == ''``, and ``Method.GET == 'GET'`` was :obj:`False`) -- true on ``main`` at ``60b85e3a4`` as well as when this docstring - was first written. #870 fixed :meth:`__new__` to + was first written. :issue:`870` fixed :meth:`__new__` to ``str.__new__(cls, value)``, mirroring :class:`~pcapkit.const.ftp.command.Command`'s own ``__new__``, so a registered member's payload now agrees @@ -219,7 +219,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Method': name: Bare label for the unregistered member -- here, the canonical upper-case form of ``value``, matching the name every *registered* member of this class is looked up by, - since #860's open-vocabulary registries have no manufactured + since :issue:`860`'s open-vocabulary registries have no manufactured placeholder label to fall back to. """ @@ -233,7 +233,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method': """Backport support for original codes. Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for the - lookup itself, per GitHub issue #908: the previous override checked + lookup itself, per GitHub issue :issue:`908`: the previous override checked only ``_member_map_`` (names), never ``_value2member_map_`` (values), so the two IANA methods whose member *name* differs from their *value* -- ``BASELINE_CONTROL`` / ``'BASELINE-CONTROL'`` and @@ -246,7 +246,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method': (:meth:`~pcapkit.corekit.enum.EnumLookup.get`), and a zero-argument ``super()`` needs a first argument to bind, so this override had to move from :class:`staticmethod` to :class:`classmethod` to delegate - at all -- see GitHub issue #908's own correction of the fix it + at all -- see GitHub issue :issue:`908`'s own correction of the fix it originally proposed. Callers are unaffected by the switch itself: ``Method.get('X')`` binds identically either way. @@ -270,11 +270,11 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method': and values, via the base's own precedence -- name before value -- so a value-only match such as ``'BASELINE-CONTROL'`` now resolves too, closing GitHub - issue #908. + issue :issue:`908`. default: Value for the unregistered member built when ``key`` matches neither a name nor a value. ``None``, the default, uses ``key`` itself -- unchanged from before - GitHub issue #908. + GitHub issue :issue:`908`. Raises: ValueError: If ``key`` is not a :class:`str`. This reaches the @@ -282,7 +282,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method': ``cls(key)`` and so ``_missing_``, and is **not** caught by the ``except KeyError`` fallback below -- only a failed *name* lookup is. The non-``str`` surface therefore moved - with GitHub issue #908: ``get(42)`` and ``get(None)`` used + with GitHub issue :issue:`908`: ``get(42)`` and ``get(None)`` used to raise :exc:`AttributeError` from ``key.upper()``, and ``get(b'GET')`` used to *return* a member whose name and value were both the :class:`bytes` object. Raising is the @@ -317,7 +317,7 @@ def _missing_(cls, value: 'str') -> 'Method': the canonical upper-case member names -- deliberately unlike :meth:`get`, which is case-**sensitive** per :rfc:`9110#section-9.1`. The split was ruled deliberate on - GitHub issue #896; GitHub issue #908 is the pointer between + GitHub issue :issue:`896`; GitHub issue :issue:`908` is the pointer between the two, so a reader of this one file is not left with two contradictory rationales and nothing tying them together. diff --git a/pcapkit/const/ngap/__init__.py b/pcapkit/const/ngap/__init__.py index aad35818cd..2dc14d3725 100644 --- a/pcapkit/const/ngap/__init__.py +++ b/pcapkit/const/ngap/__init__.py @@ -20,7 +20,7 @@ :mod:`pcapkit.vendor.ngap.procedure_code` and :mod:`pcapkit.vendor.ngap.protocol_ie`, which source the assignment from |pycrate|_'s compiled NGAP specification rather than a network registry -- -see that module's docstring for why, and GitHub issue #880 for the ruling. +see that module's docstring for why, and GitHub issue :issue:`880` for the ruling. .. [*] 3GPP TS 38.413 .. [*] 3GPP TS 38.413 diff --git a/pcapkit/const/reg/apptype/apptype.py b/pcapkit/const/reg/apptype/apptype.py index e78451dd9e..e515e587d5 100644 --- a/pcapkit/const/reg/apptype/apptype.py +++ b/pcapkit/const/reg/apptype/apptype.py @@ -89,7 +89,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco """Backport support for original codes. Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for GitHub - issue #877's re-parenting, but keeps this override rather than dropping + issue :issue:`877`'s re-parenting, but keeps this override rather than dropping it, for one behaviour the base does not reproduce on its own: **case folding**. This class has always matched a name case-insensitively (``key.lower()``); the base's own ``str`` branch is case-sensitive. @@ -100,12 +100,12 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco Case folding is now the *only* thing this override adds. It used to convert the base's name-miss exception as well -- this class raised :exc:`ValueError` where the base raised :exc:`KeyError` -- and the - ruling given in review of the work for #877, implemented in GitHub issue - #923, retired that conversion: the exception is to follow what stdlib's + ruling given in review of the work for :issue:`877`, implemented in GitHub issue + :issue:`923`, retired that conversion: the exception is to follow what stdlib's ``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 #923's census of the + 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 @@ -115,7 +115,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco rather than from any name-miss policy. So there was no policy here to preserve, and a name miss now reaches the caller as :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The - maintainer's ruling given in review of the work for #808, that + maintainer's ruling given in review of the work for :issue:`808`, that :class:`TransportProtocol` is not to be extended at all, is untouched by that: the refusal is still a refusal and still mints nothing, only its exception class moved. @@ -123,9 +123,9 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco The base is a :class:`classmethod` (: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 #908 made for + 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 #877: all call this method by + 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. @@ -154,7 +154,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco Raises: EnumKeyError: If ``key`` names no member and there is no usable ``default``. A :exc:`KeyError`, from the base, since GitHub - issue #923 -- it used to be a plain :exc:`ValueError` raised + issue :issue:`923` -- it used to be a plain :exc:`ValueError` raised here. EnumValueError: If ``key`` is a value no member carries and there is no usable ``default``. A :exc:`ValueError`, from the base. @@ -2430,7 +2430,7 @@ def __new__(cls, value: 'int', name: 'str' = '', def aliases(self) -> 'tuple[AppType, ...]': """Other services sharing :attr:`port` in this member's own registry. - GitHub issue #807. No storage of its own: IANA already keeps every + GitHub issue :issue:`807`. No storage of its own: IANA already keeps every colliding service as its own member of :data:`__registry__`, keyed on the shared port -- :meth:`get_all` already walks that same bucket to answer with the aliases after the canonical member, so this is exactly @@ -2518,16 +2518,16 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ every entry point rejects a non-port identically. proto: Transport protocol, as a member, its name, or a bare :class:`int`. That last shape is not merely defensive: GitHub - issue #808 dropped ``TransportProtocol``'s ``IntFlag`` base, so + issue :issue:`808` dropped ``TransportProtocol``'s ``IntFlag`` base, so ``TransportProtocol.a | TransportProtocol.b`` -- built by hand, the same as any caller passing a literal port-transport bitmask -- falls through to ``int.__or__`` and returns a bare :class:`int` rather than a member. Never split back into the transports its bits would each name -- a ruling given in review - of the work for #808 -- so it is looked up as the one whole + of the work for :issue:`808` -- so it is looked up as the one whole value it already is, exactly like any other bare int: refused when that whole value names no registry, resolved when it - happens to equal one instead. Since GitHub issue #860 moved + happens to equal one instead. Since GitHub issue :issue:`860` moved this class off power-of-two spacing, a hand-built composite is no longer guaranteed to be the former -- see :meth:`_dispatch`'s own body for a value that resolves. @@ -2755,7 +2755,7 @@ def register(cls, port: 'int', name: 'str') -> 'AppType': # pylint: disable=arg ``port`` to already carry a member and adds a further name for it; this requires the opposite -- ``port`` unclaimed in this registry -- and mints the first. :meth:`get` can no longer do this itself as of - GitHub issue #860 (the owner's ruling there: only IANA-registered values + GitHub issue :issue:`860` (the owner's ruling there: only IANA-registered values are legitimate, a new entry is properly created through :meth:`register`, and ``get`` lacks the information to create one), so this is now the only way to add a service this registry does not already carry. @@ -2812,7 +2812,7 @@ def register(cls, port: 'int', name: 'str') -> 'AppType': # pylint: disable=arg def register_alias(cls, port: 'int', name: 'str') -> 'AppType': # pylint: disable=arguments-renamed """Register ``name`` as a new alias on ``port``, in this registry alone. - GitHub issue #807's third ask, deliberately scoped to **this** + GitHub issue :issue:`807`'s third ask, deliberately scoped to **this** per-transport registry: ``TCP.register_alias(...)`` never touches :class:`UDP`'s members, which is what keeps an alias registered on one transport from leaking onto a transport IANA never assigned it -- e.g. diff --git a/pcapkit/vendor/__main__.py b/pcapkit/vendor/__main__.py index 87beac897c..fb0cd9eae9 100644 --- a/pcapkit/vendor/__main__.py +++ b/pcapkit/vendor/__main__.py @@ -51,7 +51,7 @@ def get_parser() -> 'ArgumentParser': def _snapshot_and_restore(vendor: 'Type[Vendor]') -> 'Iterator[None]': """Copy a target's const file aside before it runs; restore it if it raises. - A ruling given in review of the work for #872 settled how a failed target + A ruling given in review of the work for :issue:`872` settled how a failed target is undone: keep a copy of its const file before running the sub-vendor and revert if anything failed, rather than making the write itself atomic. This is that -- at the per-target boundary :func:`run` already owns, which @@ -100,7 +100,7 @@ def _snapshot_and_restore(vendor: 'Type[Vendor]') -> 'Iterator[None]': not backed up stops the target before it starts. Both leave the previous file exactly as it was, for different reasons. - A symlinked destination has a related divergence from the pre-#872 + A symlinked destination has a related divergence from the pre-:issue:`872` behaviour -- documented against the write path by rounds 4-8 (deleted along with ``_write_atomic``, though the underlying behaviour persists here instead): ``open(const_file, 'w')`` writes *through* a symlink, diff --git a/pcapkit/vendor/default.py b/pcapkit/vendor/default.py index e38495000e..df01a3ac44 100644 --- a/pcapkit/vendor/default.py +++ b/pcapkit/vendor/default.py @@ -436,7 +436,7 @@ def _dest_path(cls) -> 'str': :attr:`~Vendor.__module__` sits somewhere under the :mod:`pcapkit.vendor` package -- today always exactly one level down, e.g. - :mod:`pcapkit.vendor.reg.apptype`, but #732 needs deeper nesting such as + :mod:`pcapkit.vendor.reg.apptype`, but :issue:`732` needs deeper nesting such as :mod:`pcapkit.vendor.reg.apptype.tcp`. The output file mirrors that same position, whatever its depth, under :mod:`pcapkit.const` instead. @@ -484,7 +484,7 @@ def _dest_path(cls) -> 'str': *without* instantiating it, and so without triggering :meth:`Vendor.__init__`'s network fetch, render and write -- :func:`pcapkit.vendor.__main__.run`'s pre-run snapshot (GitHub issue - #872) is exactly such a caller. Every crawler defined in this + :issue:`872`) is exactly such a caller. Every crawler defined in this codebase inherits this implementation unchanged; none overrides ``_dest_path``, so the classmethod is authoritative for all of them. @@ -539,7 +539,7 @@ def _request(self) -> 'list[str]': :func:`stdin_is_interactive` finds a terminal. A non-interactive run -- under a pipe, in a container, from a scheduled job -- is failed with the fetch error instead, the same way :envvar:`PCAPKIT_CI_MODE` fails it, - rather than printing instructions nobody will read. See #522. + rather than printing instructions nobody will read. See :issue:`522`. Returns: CSV data. diff --git a/pcapkit/vendor/ftp/command.py b/pcapkit/vendor/ftp/command.py index 2ec01a699f..acd436898c 100644 --- a/pcapkit/vendor/ftp/command.py +++ b/pcapkit/vendor/ftp/command.py @@ -74,12 +74,12 @@ class FEATCode(EnumRegistry, StrEnum): keywords generated after them (data-driven, not hand-picked; see :meth:`~pcapkit.vendor.ftp.command.Command.process`) -- rather than minting the per-command ones at import time as an incidental side - effect of building :class:`Command`'s own rows. GitHub issue #860: - that import-time mutation was the same defect shape #775 removed + effect of building :class:`Command`'s own rows. GitHub issue :issue:`860`: + that import-time mutation was the same defect shape :issue:`775` removed from :class:`~pcapkit.const.pcapng.filter_type.FilterType`, just not previously noticed here. ``_missing_`` still unmints for a keyword that turns up on the wire but names none of these -- the extendability the - owner conditionally asked to keep on GitHub issue #860: unsure what a + owner conditionally asked to keep on GitHub issue :issue:`860`: unsure what a FEAT value absent from the RFC's list means in the CSV table, the owner said that if the expected handling is our current approach, as industry convention has it, the registry stays extendable as is, and then approved @@ -111,7 +111,7 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode': """Resolve ``key`` case-insensitively, per :rfc:`5797#section-2`. One of the few case-insensitive overrides the ruling on GitHub issue - #877 allows, and the registry's own defining document states the + :issue:`877` allows, and the registry's own defining document states the comparison rule outright rather than leaving it to be inferred -- :rfc:`5797#section-2`, on the ``FEAT Code`` column this class is generated from: *"IANA maintains uniqueness of feature names (FEAT @@ -131,7 +131,7 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode': lower case -- measured on the IANA CSV: 10 distinct all-upper-case keywords against ``base``, ``feat``, ``hist``, ``nat6`` and ``secu``, with none mixed. Without this override ``get('BASE')`` raised - :exc:`KeyError`, which is the defect GitHub issue #903's audit found. + :exc:`KeyError`, which is the defect GitHub issue :issue:`903`'s audit found. The obvious objection, answered: :rfc:`5797` uses case *presentationally* to tell a real keyword from a placeholder -- *"defined FEAT keywords @@ -139,7 +139,7 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode': listed in lowercase"* -- so folding might look like it discards that distinction. It does not. Only the inbound ``key`` is folded; every member keeps the registrar's own casing, and the fold itself is backed by - the RFC: the final ruling on GitHub issue #877 is that an enum treats its + the RFC: the final ruling on GitHub issue :issue:`877` is that an enum treats its values as case-insensitive where the RFC states they are, and as case-sensitive otherwise. So ``get('BASE').name`` is still ``'base'`` and still says placeholder. And the uniqueness rule quoted above is what makes @@ -203,7 +203,7 @@ class CommandType(EnumLookup, IntFlag): """Type of "kind" of command, based on :rfc:`959#section-4`. 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 -- this class defines no ``get`` of its own to reconcile with the base -- and its own :meth:`_missing_` range guard below is untouched, since :class:`EnumLookup` does not touch that @@ -237,7 +237,7 @@ class ConformanceRequirement(EnumLookup, IntEnum): """Expectation for support in modern FTP implementations. 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. @@ -257,7 +257,7 @@ class {NAME}(EnumRegistry, StrEnum): .. note:: Neither ``_missing_`` nor ``get()`` mints any more. The owner ruled on - GitHub issue #860 that ``get`` should not mint: only IANA-registered + GitHub issue :issue:`860` that ``get`` should not mint: only IANA-registered values are legitimate members, a new one is properly created through :meth:`register`, and ``get`` is not given enough information to create one. Concretely true here -- a bare wire command word carries no @@ -324,7 +324,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> '{NAME}': name: Bare label for the unregistered member -- here, the canonical upper-case form of ``value``, matching the name every *registered* member of this class is looked up by, - since #860's open-vocabulary registries have no manufactured + since :issue:`860`'s open-vocabulary registries have no manufactured placeholder label to fall back to. """ @@ -397,7 +397,7 @@ def process(self, data: 'list[str]') -> 'tuple[list[str], list[str]]': :class:`Command`'s enumeration fields, and every distinct per-command keyword the ``FEAT code`` column names -- :class:`FEATCode` must declare these as real members (GitHub - issue #860), rather than the old approach of minting one as an + issue :issue:`860`), rather than the old approach of minting one as an incidental side effect the first time a :class:`Command` row referencing it was evaluated at import time. diff --git a/pcapkit/vendor/http/method.py b/pcapkit/vendor/http/method.py index 2c8357f13d..a12fc0aea7 100644 --- a/pcapkit/vendor/http/method.py +++ b/pcapkit/vendor/http/method.py @@ -51,7 +51,7 @@ class {NAME}(EnumRegistry, StrEnum): .. note:: Neither ``_missing_`` nor ``get()`` mints any more. The owner ruled on - GitHub issue #860 that ``get`` should not mint: only IANA-registered + GitHub issue :issue:`860` that ``get`` should not mint: only IANA-registered values are legitimate members, a new one is properly created through :meth:`register`, and ``get`` is not given enough information to create one. Concretely true here -- a bare wire method verb carries no @@ -107,14 +107,14 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> '{NAME}': identifier, not the value -- is canonicalised. A *registered* member of this class used to carry something - different here: GitHub issue #870 found that + different here: GitHub issue :issue:`870` found that :meth:`__new__` called ``str.__new__(cls)`` with no argument at all, so every one of the 40 declared members' own :class:`str` payload was permanently empty regardless of ``value`` (``str(Method.GET) == ''``, and ``Method.GET == 'GET'`` was :obj:`False`) -- true on ``main`` at ``60b85e3a4`` as well as when this docstring - was first written. #870 fixed :meth:`__new__` to + was first written. :issue:`870` fixed :meth:`__new__` to ``str.__new__(cls, value)``, mirroring :class:`~pcapkit.const.ftp.command.Command`'s own ``__new__``, so a registered member's payload now agrees @@ -124,7 +124,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> '{NAME}': name: Bare label for the unregistered member -- here, the canonical upper-case form of ``value``, matching the name every *registered* member of this class is looked up by, - since #860's open-vocabulary registries have no manufactured + since :issue:`860`'s open-vocabulary registries have no manufactured placeholder label to fall back to. """ @@ -138,7 +138,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}': """Backport support for original codes. Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for the - lookup itself, per GitHub issue #908: the previous override checked + lookup itself, per GitHub issue :issue:`908`: the previous override checked only ``_member_map_`` (names), never ``_value2member_map_`` (values), so the two IANA methods whose member *name* differs from their *value* -- ``BASELINE_CONTROL`` / ``'BASELINE-CONTROL'`` and @@ -151,7 +151,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}': (:meth:`~pcapkit.corekit.enum.EnumLookup.get`), and a zero-argument ``super()`` needs a first argument to bind, so this override had to move from :class:`staticmethod` to :class:`classmethod` to delegate - at all -- see GitHub issue #908's own correction of the fix it + at all -- see GitHub issue :issue:`908`'s own correction of the fix it originally proposed. Callers are unaffected by the switch itself: ``{NAME}.get('X')`` binds identically either way. @@ -175,11 +175,11 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}': and values, via the base's own precedence -- name before value -- so a value-only match such as ``'BASELINE-CONTROL'`` now resolves too, closing GitHub - issue #908. + issue :issue:`908`. default: Value for the unregistered member built when ``key`` matches neither a name nor a value. ``None``, the default, uses ``key`` itself -- unchanged from before - GitHub issue #908. + GitHub issue :issue:`908`. Raises: ValueError: If ``key`` is not a :class:`str`. This reaches the @@ -187,7 +187,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}': ``cls(key)`` and so ``_missing_``, and is **not** caught by the ``except KeyError`` fallback below -- only a failed *name* lookup is. The non-``str`` surface therefore moved - with GitHub issue #908: ``get(42)`` and ``get(None)`` used + with GitHub issue :issue:`908`: ``get(42)`` and ``get(None)`` used to raise :exc:`AttributeError` from ``key.upper()``, and ``get(b'GET')`` used to *return* a member whose name and value were both the :class:`bytes` object. Raising is the @@ -222,7 +222,7 @@ def _missing_(cls, value: 'str') -> '{NAME}': the canonical upper-case member names -- deliberately unlike :meth:`get`, which is case-**sensitive** per :rfc:`9110#section-9.1`. The split was ruled deliberate on - GitHub issue #896; GitHub issue #908 is the pointer between + GitHub issue :issue:`896`; GitHub issue :issue:`908` is the pointer between the two, so a reader of this one file is not left with two contradictory rationales and nothing tying them together. diff --git a/pcapkit/vendor/ipv6/extension_header.py b/pcapkit/vendor/ipv6/extension_header.py index 0fc5bb202d..2b99841f4f 100644 --- a/pcapkit/vendor/ipv6/extension_header.py +++ b/pcapkit/vendor/ipv6/extension_header.py @@ -56,7 +56,7 @@ class ExtensionHeader(Vendor): #: Keyword-style names carried over from this crawler's *previous* data #: source, keyed by protocol number. The Protocol Numbers registry #: (``protocol-numbers-1.csv``, this crawler's :attr:`LINK` before GitHub - #: issue #925) paired each of these headers with a short ``Keyword`` + #: issue :issue:`925`) paired each of these headers with a short ``Keyword`` #: column value, e.g. ``IPv6-Route`` for header 43. The registry #: :attr:`LINK` now points at -- IANA's authoritative *IPv6 Extension #: Header Types* registry -- has no such column, only a verbose @@ -81,7 +81,7 @@ class ExtensionHeader(Vendor): #: #: .. note:: #: - #: Until GitHub issue #925, this pointed at the *Protocol Numbers* + #: Until GitHub issue :issue:`925`, this pointed at the *Protocol Numbers* #: registry (``protocol-numbers/protocol-numbers-1.csv``), filtered on #: its ``IPv6 Extension Header`` column -- a derived signal, not the #: registry :rfc:`8200#section-4` names as authoritative for this diff --git a/pcapkit/vendor/ipx/socket.py b/pcapkit/vendor/ipx/socket.py index cf1b329644..f48fb03cf1 100644 --- a/pcapkit/vendor/ipx/socket.py +++ b/pcapkit/vendor/ipx/socket.py @@ -253,10 +253,10 @@ #: Range names from :data:`RANGES` above that name an allocation *policy* for #: the pool (who may claim a code, or that nobody has) rather than a specific #: assigned protocol. The maintainer's test, set in review of the branch-order -#: fix for #841, is whether a label is the final concrete assigned name or only -#: a notation for readers; the ruling on #775 kept ``Registered by Xerox`` out +#: fix for :issue:`841`, is whether a label is the final concrete assigned name or only +#: a notation for readers; the ruling on :issue:`775` kept ``Registered by Xerox`` out #: of this set on that test, because a proprietary protocol may expose no name -#: of its own, so the company name serves as its name. #775's final round +#: of its own, so the company name serves as its name. :issue:`775`'s final round #: converts it too, so this set no longer decides *whether* a range registers -- #: only *how its name is spelled*: these four keep the bare label with no hex #: suffix, since the label itself already says nothing was assigned, while diff --git a/pcapkit/vendor/ngap/__init__.py b/pcapkit/vendor/ngap/__init__.py index 768d94c375..1ded1323c4 100644 --- a/pcapkit/vendor/ngap/__init__.py +++ b/pcapkit/vendor/ngap/__init__.py @@ -18,7 +18,7 @@ Both are sourced from |pycrate|_'s compiled NGAP specification rather than a network registry -- see :mod:`pcapkit.vendor.ngap.procedure_code`'s module -docstring for why, and GitHub issue #880 for the ruling. +docstring for why, and GitHub issue :issue:`880` for the ruling. .. [*] 3GPP TS 38.413 .. [*] 3GPP TS 38.413 diff --git a/pcapkit/vendor/ngap/procedure_code.py b/pcapkit/vendor/ngap/procedure_code.py index cdbbd787f4..5d73a0d93b 100644 --- a/pcapkit/vendor/ngap/procedure_code.py +++ b/pcapkit/vendor/ngap/procedure_code.py @@ -8,7 +8,7 @@ Codes**, which is automatically generating :class:`pcapkit.const.ngap.procedure_code.ProcedureCode`. -GitHub issue #880's owner ruling: unlike every other crawler in this package, +GitHub issue :issue:`880`'s owner ruling: unlike every other crawler in this package, the source of truth here is not a network registry :mod:`requests` can fetch -- 3GPP publishes TS 38.413 as a PDF, with no CSV or HTML IANA-style registry kept in step with it. |pycrate|_ already carries the up-to-date assignment as @@ -25,13 +25,13 @@ :class:`~pcapkit.const.ngap.procedure_code.ProcedureCode` is a genuinely open registry -- 3GPP keeps assigning new elementary procedures to TS 38.413 -- so, -unlike the closed :mod:`pcapkit.protocols.internet.mh` enums GitHub issue #877 +unlike the closed :mod:`pcapkit.protocols.internet.mh` enums GitHub issue :issue:`877` ruled on, an in-range value this crawler has not (yet) seen is not a bug to raise on: :meth:`~pcapkit.const.ngap.procedure_code.ProcedureCode._missing_` answers it with a throwaway, non-registering member instead (see :meth:`pcapkit.corekit.enum.EnumRegistry._unregistered_member`), which is what stops two different unrecognised keys from aliasing onto the same member -- -the defect GitHub issue #880 exists to fix. +the defect GitHub issue :issue:`880` exists to fix. .. |pycrate| replace:: ``pycrate`` .. _pycrate: https://github.com/pycrate-org/pycrate diff --git a/pcapkit/vendor/ngap/protocol_ie.py b/pcapkit/vendor/ngap/protocol_ie.py index 07313d797b..7db2792b3a 100644 --- a/pcapkit/vendor/ngap/protocol_ie.py +++ b/pcapkit/vendor/ngap/protocol_ie.py @@ -13,7 +13,7 @@ specification rather than a network registry, and why an in-range value it has not seen answers through :meth:`~pcapkit.corekit.enum.EnumRegistry. _unregistered_member` rather than raising or minting a permanent, shared-value -member -- the same GitHub issue #880 ruling, applied to the sibling registry. +member -- the same GitHub issue :issue:`880` ruling, applied to the sibling registry. .. |pycrate| replace:: ``pycrate`` .. _pycrate: https://github.com/pycrate-org/pycrate diff --git a/pcapkit/vendor/pcapng/option_type.py b/pcapkit/vendor/pcapng/option_type.py index fbb7165279..4dcdde18cf 100644 --- a/pcapkit/vendor/pcapng/option_type.py +++ b/pcapkit/vendor/pcapng/option_type.py @@ -203,7 +203,7 @@ class OptionType(Vendor): #: Value limit checker. FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' #: Link to registry. See :mod:`pcapkit.vendor.pcapng.block_type` for why this - #: is the ``-03`` revision in the immutable I-D archive; see #518. + #: is the ``-03`` revision in the immutable I-D archive; see :issue:`518`. LINK = 'https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html' def count(self, data: 'list[str]') -> 'Counter[str]': diff --git a/pcapkit/vendor/pcapng/record_type.py b/pcapkit/vendor/pcapng/record_type.py index 6142f5f23d..c4b9aa1951 100644 --- a/pcapkit/vendor/pcapng/record_type.py +++ b/pcapkit/vendor/pcapng/record_type.py @@ -31,7 +31,7 @@ class RecordType(Vendor): #: Value limit checker. FLAG = 'isinstance(value, int) and 0 <= value <= 0xFFFF' #: Link to registry. See :mod:`pcapkit.vendor.pcapng.block_type` for why this - #: is the ``-03`` revision in the immutable I-D archive; see #518. + #: is the ``-03`` revision in the immutable I-D archive; see :issue:`518`. LINK = 'https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html' def count(self, data: 'list[str]') -> 'Counter[str]': diff --git a/pcapkit/vendor/pcapng/tls_key_label.py b/pcapkit/vendor/pcapng/tls_key_label.py index 4e4655b9ca..8e51771bcc 100644 --- a/pcapkit/vendor/pcapng/tls_key_label.py +++ b/pcapkit/vendor/pcapng/tls_key_label.py @@ -24,11 +24,11 @@ __all__ = ['TLSKeyLabel'] #: Hand-carried comment for the ``RSA`` member, copied verbatim from the text -#: GitHub issue #882 gave it in +#: GitHub issue :issue:`882` gave it in #: :class:`pcapkit.protocols.misc.pcapng.TLSKeyLabel` -- ``RSA`` has no row in #: :attr:`TLSKeyLabel.LINK`'s registry to generate a comment from (``grep -c #: RSA`` on the fetched CSV is 0), so it is carried across rather than -#: derived, per GitHub issue #886's first constraint. The embedded +#: derived, per GitHub issue :issue:`886`'s first constraint. The embedded #: ``\n #: `` continuations match every other multi-line member comment #: this crawler (and its siblings) emit, so the rendered class body indents #: correctly once :meth:`TLSKeyLabel.context` joins it in. diff --git a/pcapkit/vendor/reg/apptype/apptype.py b/pcapkit/vendor/reg/apptype/apptype.py index 2cf6da00b3..6f4180bac0 100644 --- a/pcapkit/vendor/reg/apptype/apptype.py +++ b/pcapkit/vendor/reg/apptype/apptype.py @@ -182,7 +182,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco """Backport support for original codes. Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for GitHub - issue #877's re-parenting, but keeps this override rather than dropping + issue :issue:`877`'s re-parenting, but keeps this override rather than dropping it, for one behaviour the base does not reproduce on its own: **case folding**. This class has always matched a name case-insensitively (``key.lower()``); the base's own ``str`` branch is case-sensitive. @@ -193,12 +193,12 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco Case folding is now the *only* thing this override adds. It used to convert the base's name-miss exception as well -- this class raised :exc:`ValueError` where the base raised :exc:`KeyError` -- and the - ruling given in review of the work for #877, implemented in GitHub issue - #923, retired that conversion: the exception is to follow what stdlib's + ruling given in review of the work for :issue:`877`, implemented in GitHub issue + :issue:`923`, retired that conversion: the exception is to follow what stdlib's ``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 #923's census of the + 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 @@ -208,7 +208,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco rather than from any name-miss policy. So there was no policy here to preserve, and a name miss now reaches the caller as :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The - maintainer's ruling given in review of the work for #808, that + maintainer's ruling given in review of the work for :issue:`808`, that :class:`TransportProtocol` is not to be extended at all, is untouched by that: the refusal is still a refusal and still mints nothing, only its exception class moved. @@ -216,9 +216,9 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco The base is a :class:`classmethod` (: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 #908 made for + 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 #877: all call this method by + 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. @@ -247,7 +247,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco Raises: EnumKeyError: If ``key`` names no member and there is no usable ``default``. A :exc:`KeyError`, from the base, since GitHub - issue #923 -- it used to be a plain :exc:`ValueError` raised + issue :issue:`923` -- it used to be a plain :exc:`ValueError` raised here. EnumValueError: If ``key`` is a value no member carries and there is no usable ``default``. A :exc:`ValueError`, from the base. @@ -385,7 +385,7 @@ def __new__(cls, value: 'int', name: 'str' = '', def aliases(self) -> 'tuple[{NAME}, ...]': """Other services sharing :attr:`port` in this member's own registry. - GitHub issue #807. No storage of its own: IANA already keeps every + GitHub issue :issue:`807`. No storage of its own: IANA already keeps every colliding service as its own member of :data:`__registry__`, keyed on the shared port -- :meth:`get_all` already walks that same bucket to answer with the aliases after the canonical member, so this is exactly @@ -473,16 +473,16 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ every entry point rejects a non-port identically. proto: Transport protocol, as a member, its name, or a bare :class:`int`. That last shape is not merely defensive: GitHub - issue #808 dropped ``TransportProtocol``'s ``IntFlag`` base, so + issue :issue:`808` dropped ``TransportProtocol``'s ``IntFlag`` base, so ``TransportProtocol.a | TransportProtocol.b`` -- built by hand, the same as any caller passing a literal port-transport bitmask -- falls through to ``int.__or__`` and returns a bare :class:`int` rather than a member. Never split back into the transports its bits would each name -- a ruling given in review - of the work for #808 -- so it is looked up as the one whole + of the work for :issue:`808` -- so it is looked up as the one whole value it already is, exactly like any other bare int: refused when that whole value names no registry, resolved when it - happens to equal one instead. Since GitHub issue #860 moved + happens to equal one instead. Since GitHub issue :issue:`860` moved this class off power-of-two spacing, a hand-built composite is no longer guaranteed to be the former -- see :meth:`_dispatch`'s own body for a value that resolves. @@ -710,7 +710,7 @@ def register(cls, port: 'int', name: 'str') -> '{NAME}': # pylint: disable=argu ``port`` to already carry a member and adds a further name for it; this requires the opposite -- ``port`` unclaimed in this registry -- and mints the first. :meth:`get` can no longer do this itself as of - GitHub issue #860 (the owner's ruling there: only IANA-registered values + GitHub issue :issue:`860` (the owner's ruling there: only IANA-registered values are legitimate, a new entry is properly created through :meth:`register`, and ``get`` lacks the information to create one), so this is now the only way to add a service this registry does not already carry. @@ -767,7 +767,7 @@ def register(cls, port: 'int', name: 'str') -> '{NAME}': # pylint: disable=argu def register_alias(cls, port: 'int', name: 'str') -> '{NAME}': # pylint: disable=arguments-renamed """Register ``name`` as a new alias on ``port``, in this registry alone. - GitHub issue #807's third ask, deliberately scoped to **this** + GitHub issue :issue:`807`'s third ask, deliberately scoped to **this** per-transport registry: ``TCP.register_alias(...)`` never touches :class:`UDP`'s members, which is what keeps an alias registered on one transport from leaking onto a transport IANA never assigned it -- e.g. diff --git a/pcapkit/vendor/reg/ethertype.py b/pcapkit/vendor/reg/ethertype.py index de08a19136..35470ebae8 100644 --- a/pcapkit/vendor/reg/ethertype.py +++ b/pcapkit/vendor/reg/ethertype.py @@ -36,10 +36,10 @@ class EtherType(Vendor): #: carrying no real assignment -- a company holding the block but naming #: nothing (``DEC Unassigned``), or a range the list says is dead/invalid #: outright -- rather than a proprietary protocol's real name. The owner's - #: original ruling on #775/#841 held these two out as the only rows to + #: original ruling on :issue:`775`/:issue:`841` held these two out as the only rows to #: convert to :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_ #: member`, on the theory that a proprietary protocol's company name IS - #: the final concrete name for every other row. #775's final round + #: the final concrete name for every other row. :issue:`775`'s final round #: converts every row alike, so this set no longer decides *whether* a #: row registers -- only *how its name is spelled*: these two keep the #: bare label with no hex suffix, since the label itself already says @@ -90,7 +90,7 @@ def _insert_range(ranges: 'list[tuple[int, int, list[str]]]', entry: 'tuple[int, The generated :meth:`~EtherType._missing_` tests these ``if`` blocks in list order and returns on the first match, so a range that is fully contained within an earlier, wider one would never be reached -- see - GitHub issue #862, where the source table lists ``0x0101-0x01FF`` + GitHub issue :issue:`862`, where the source table lists ``0x0101-0x01FF`` after the ``0x0000-0x05DC`` range that wholly contains it. The IANA CSV is not otherwise sorted by range, so this only reorders diff --git a/tests/const/test_const_method_value_lookup_908_unit.py b/tests/const/test_const_method_value_lookup_908_unit.py index e947858f26..1b0d4dfd33 100644 --- a/tests/const/test_const_method_value_lookup_908_unit.py +++ b/tests/const/test_const_method_value_lookup_908_unit.py @@ -323,7 +323,7 @@ def test_the_crawler_template_carries_the_same_get(self) -> None: rendered = LINE('Method', 'HTTP Method', '', 'pcapkit.vendor.http.method') source = inspect.getsource(Method.get.__func__) # type: ignore[attr-defined] - self.assertIn('GitHub issue #908', source) + self.assertRegex(source, r'GitHub issue (?:#|:issue:`)908') self.assertIn('return super().get(key)', source) self.assertIn(source.rstrip('\n'), rendered) @@ -338,7 +338,7 @@ def test_the_crawler_template_carries_the_missing_cross_reference_too(self) -> N rendered = LINE('Method', 'HTTP Method', '', 'pcapkit.vendor.http.method') source = inspect.getsource(Method._missing_.__func__) # type: ignore[attr-defined] - self.assertIn('GitHub issue #908', source) + self.assertRegex(source, r'GitHub issue (?:#|:issue:`)908') self.assertIn(source.rstrip('\n'), rendered)