diff --git a/pcapkit/dumpkit/common.py b/pcapkit/dumpkit/common.py index c930c4bb4a..e3de857781 100644 --- a/pcapkit/dumpkit/common.py +++ b/pcapkit/dumpkit/common.py @@ -189,7 +189,7 @@ def render_enum(o: 'enum.Enum | aenum.Enum') -> 'str': so interpolating it unguarded put the literal four characters ``None`` into the name half and rendered :class:`~pcapkit.const.tcp.flags.Flags` ``(0)`` as ``'Flags::None [0]'`` - (GitHub issue #648). + (GitHub issue :issue:`648`). Two things make that worth a guard rather than a shrug. ``'None'`` is a plausible member name, so a consumer splitting the rendering on ``::`` diff --git a/pcapkit/foundation/extraction.py b/pcapkit/foundation/extraction.py index e45ace797b..a5d0847fc3 100644 --- a/pcapkit/foundation/extraction.py +++ b/pcapkit/foundation/extraction.py @@ -142,7 +142,7 @@ class Extractor(Generic[_P]): #: stopping. It retries only while the input is still producing, though -- #: see :meth:`~pcapkit.foundation.extraction.Extractor._note_eof_progress` #: for the rule and for what it narrows, without which an exhausted stream - #: spins forever (#620). + #: spins forever (:issue:`620`). _flag_n: 'bool' #: Input filename flag. It indicates if the input file is a file #: name or a binary IO object. For the latter, we should not close @@ -192,7 +192,7 @@ class Extractor(Generic[_P]): #: :data:`None` before the first one. Comparing it against the position #: at the next end of stream is what tells a live capture that has paused #: -- retry, more may arrive -- from one that is finished, which is the - #: termination condition ``no_eof`` was missing (#620). + #: termination condition ``no_eof`` was missing (:issue:`620`). _eof_mark: 'Optional[int]' #: Magic number. @@ -376,8 +376,8 @@ def register_dumper(cls, format: 'str', dumper: 'ModuleDescriptor[Dumper] | Type The overwrite guard fires only when the incumbent dumper differs from the replacement, so re-registering the exact same object is a silent no-op rather than a warning about nothing displaced -- - the identity guard GitHub issue #718 gave the code-keyed - registrars, extended here by GitHub issue #739. ``__output__`` + the identity guard GitHub issue :issue:`718` gave the code-keyed + registrars, extended here by GitHub issue :issue:`739`. ``__output__`` maps each format to a ``(dumper, ext)`` pair, so the identity check compares the incumbent *dumper* (index ``0``), not the pair -- a re-registration that only changes ``ext`` is still @@ -416,8 +416,8 @@ def register_engine(cls, name: 'str', engine: 'ModuleDescriptor[Engine] | Type[E The overwrite guard fires only when the incumbent differs from the replacement, so re-registering the exact same object is a silent no-op rather than a warning about nothing displaced -- - the identity guard GitHub issue #718 gave the code-keyed - registrars, extended here by GitHub issue #739. + the identity guard GitHub issue :issue:`718` gave the code-keyed + registrars, extended here by GitHub issue :issue:`739`. Arguments: name: engine name @@ -451,8 +451,8 @@ def register_reassembly(cls, protocol: 'str', reassembly: 'ModuleDescriptor[Reas The overwrite guard fires only when the incumbent differs from the replacement, so re-registering the exact same object is a silent no-op rather than a warning about nothing displaced -- - the identity guard GitHub issue #718 gave the code-keyed - registrars, extended here by GitHub issue #739. + the identity guard GitHub issue :issue:`718` gave the code-keyed + registrars, extended here by GitHub issue :issue:`739`. Arguments: protocol: protocol name @@ -482,8 +482,8 @@ def register_traceflow(cls, protocol: 'str', traceflow: 'ModuleDescriptor[TraceF The overwrite guard fires only when the incumbent differs from the replacement, so re-registering the exact same object is a silent no-op rather than a warning about nothing displaced -- - the identity guard GitHub issue #718 gave the code-keyed - registrars, extended here by GitHub issue #739. + the identity guard GitHub issue :issue:`718` gave the code-keyed + registrars, extended here by GitHub issue :issue:`739`. Arguments: protocol: protocol name @@ -1145,7 +1145,7 @@ def __del__(self) -> 'None': stops before end of file never reaches :meth:`_cleanup` at all, so the ownership rule there never gets to run. The handle then survives until the interpreter collects it, and CPython announces that with the - ``ResourceWarning`` #606 was tripping over -- from an unrelated test, in an + ``ResourceWarning`` :issue:`606` was tripping over -- from an unrelated test, in an unrelated file, which is what made that flake so hard to place. This is a backstop and not the recommended route: collection is not @@ -1183,7 +1183,7 @@ def __del__(self) -> 'None': def _owns_input(self) -> 'bool': """Whether the input stream is this class's to close. - The one place the ownership rule of #610 is written down, so that + The one place the ownership rule of :issue:`610` is written down, so that :meth:`_cleanup` and :meth:`__del__` cannot drift apart on it. Returns: @@ -1229,7 +1229,7 @@ def _note_eof_progress(self) -> 'bool': ``fin='-'`` -- so the extraction retries rather than stopping. What it had no way to decide was when the stream is *genuinely* finished, and for an exhausted one every retry raises end of stream again immediately, which is - the spin #620 reported. + the spin :issue:`620` reported. The signal is the input's own position. End of stream is raised by :func:`~pcapkit.utilities.decorators.prepare` when the bytes remaining in @@ -1255,7 +1255,7 @@ def _note_eof_progress(self) -> 'bool': following the writer. That is a deliberate narrowing of what ``no_eof`` used to do, and it is measured: on ``6c3d1b0d9`` a file gaining its last record 0.6s in yielded all six frames, and here it yields five. The - previous behaviour was unbounded by construction -- it is the defect #620 + previous behaviour was unbounded by construction -- it is the defect :issue:`620` reports -- so *some* stopping rule had to be chosen, and a timed grace period would only make the cut-off intermittent rather than absent. Following a growing file wants a deliberate policy of its own; see the diff --git a/pcapkit/foundation/reassembly/data/data.py b/pcapkit/foundation/reassembly/data/data.py index c52561ecec..f8fdd5d1f0 100644 --- a/pcapkit/foundation/reassembly/data/data.py +++ b/pcapkit/foundation/reassembly/data/data.py @@ -22,7 +22,7 @@ class Completion(EnumLookup, StrEnum): """How completely a datagram was reassembled, and why it stopped. Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub - issue #877's ruling that every non-registry enumeration shares that + issue :issue:`877`'s ruling that every non-registry enumeration shares that lookup contract -- pure re-parenting, since this class defines neither ``get`` nor ``_missing_`` of its own to reconcile with the base. @@ -52,7 +52,7 @@ class Completion(EnumLookup, StrEnum): new state can be tested for without importing this class. :class:`~pcapkit.protocols.misc.pcapng.TLSKeyLabel` used to be a third precedent for the same :class:`~pcapkit.utilities.compat.StrEnum` base, but - GitHub issue #886 moved its canonical definition to + GitHub issue :issue:`886` moved its canonical definition to :class:`pcapkit.const.pcapng.tls_key_label.TLSKeyLabel`, generated like its :mod:`pcapkit.const.pcapng` siblings: it now derives from :class:`aenum`'s own ``StrEnum`` (via :class:`~pcapkit.corekit.enum.EnumRegistry`) rather than diff --git a/pcapkit/foundation/registry/protocols.py b/pcapkit/foundation/registry/protocols.py index 1106dc4c47..014450ffea 100644 --- a/pcapkit/foundation/registry/protocols.py +++ b/pcapkit/foundation/registry/protocols.py @@ -162,7 +162,7 @@ def register_protocol(protocol: 'Type[ProtocolBase]') -> 'None': `, which resolves a bare protocol name through it. - Per #675 the overwrite is now reported rather than silent, matching + Per :issue:`675` the overwrite is now reported rather than silent, matching :meth:`ProtocolBase.register ` and the other overwrite-warning registries. @@ -181,7 +181,7 @@ class under two codes, a supported and documented thing to do, reaches that filter is what would then hide the ``HTTP`` collision this warning exists to surface. The sibling ``register`` methods across the package -- each keyed on a caller-supplied ``code`` rather than a name derived from - the class -- apply the same identity criterion as of GitHub issue #718; + the class -- apply the same identity criterion as of GitHub issue :issue:`718`; before that they warned on presence alone, and none of them does now. Making the key itself unique would resolve the collision rather than @@ -195,7 +195,7 @@ class under two codes, a supported and documented thing to do, reaches :class:`~pcapkit.foundation.reassembly.reassembly.ReassemblyMeta` and :class:`~pcapkit.foundation.traceflow.traceflow.TraceFlowMeta` fall back to :class:`~pcapkit.protocols.misc.raw.Raw`. Re-keying is therefore part of the - registry redesign in #514, and reporting the collision here is the step that + registry redesign in :issue:`514`, and reporting the collision here is the step that redesign is sequenced behind. Args: @@ -241,7 +241,7 @@ class under two codes, a supported and documented thing to do, reaches #: Enum type -> the class(es) owning the :attr:`ProtocolBase.__proto__ #: ` dispatch registry #: keyed by that enum type -- the "registry-of-registries" that lets -#: ``code=`` infer a destination from a key's own type, per #514. This is +#: ``code=`` infer a destination from a key's own type, per :issue:`514`. This is #: not an invention: it is exactly the targeting #: :func:`register_ethertype`, :func:`register_transtype`, #: :func:`register_linktype` and :func:`register_sctp` already hard-code by @@ -350,7 +350,7 @@ def register_protocol_code(protocol: 'Type[ProtocolBase]', code: 'Any') -> 'None 1701. :class:`L2TPv2 ` answers on port 1701 only, and registering *it* at ``TransType.L2TP`` would point the :rfc:`2661` parser at a v3-over-IP header -- see - :class:`~pcapkit.protocols.link.l2tp.L2TP` and GitHub issue #548 for + :class:`~pcapkit.protocols.link.l2tp.L2TP` and GitHub issue :issue:`548` for what that produced when measured. Args: @@ -849,8 +849,8 @@ def register_apptype(code: 'int | Enum_AppType', module: 'str | ModuleDescriptor when ``module`` is a :class:`str` and either ``class_`` names no attribute of it, or ``class_`` was never given at all -- the latter distinguished from the former rather than reported as a - missing attribute named ``'(null)'``. See GitHub issues #832 and - #833. + missing attribute named ``'(null)'``. See GitHub issues :issue:`832` and + :issue:`833`. Important: :class:`~pcapkit.protocols.transport.sctp.SCTP` is deliberately **not** diff --git a/pcapkit/foundation/traceflow/traceflow.py b/pcapkit/foundation/traceflow/traceflow.py index b45bf42baf..86423403b2 100644 --- a/pcapkit/foundation/traceflow/traceflow.py +++ b/pcapkit/foundation/traceflow/traceflow.py @@ -213,8 +213,8 @@ def register_dumper(cls, format: 'str', dumper: 'ModuleDescriptor[Dumper] | Type The overwrite guard fires only when the incumbent dumper differs from the replacement, so re-registering the exact same object is a silent no-op rather than a warning about nothing displaced -- - the identity guard GitHub issue #718 gave the code-keyed - registrars, extended here by GitHub issue #739. ``__output__`` + the identity guard GitHub issue :issue:`718` gave the code-keyed + registrars, extended here by GitHub issue :issue:`739`. ``__output__`` maps each format to a ``(dumper, ext)`` pair, so the identity check compares the incumbent *dumper* (index ``0``), not the pair -- a re-registration that only changes ``ext`` is still diff --git a/pcapkit/toolkit/pyshark.py b/pcapkit/toolkit/pyshark.py index a7a1ba37d0..61922a97bd 100644 --- a/pcapkit/toolkit/pyshark.py +++ b/pcapkit/toolkit/pyshark.py @@ -237,7 +237,7 @@ #: rewrite. Names are listed even where they already spell their :class:`LinkType` member #: (``docsis``, ``fddi``, ``pflog``, ...): there is deliberately **no** fallback onto a like-named #: member, because upper-casing the name is exactly what answered 101 for a ``rawip6`` capture and -#: 0 for a ``DLT_LOOP`` one -- valid DLTs, wrong ones, and silent (#843). +#: 0 for a ``DLT_LOOP`` one -- valid DLTs, wrong ones, and silent (:issue:`843`). #: #: Three classes of name are absent, all three measured rather than assumed: #: diff --git a/pcapkit/toolkit/scapy.py b/pcapkit/toolkit/scapy.py index 09df946fc2..cd39648e91 100644 --- a/pcapkit/toolkit/scapy.py +++ b/pcapkit/toolkit/scapy.py @@ -25,7 +25,7 @@ a side effect, because by the time any of these functions runs the engine has already called ``sniff`` and every frame has already been dissected -- or not. - That distinction is what made #406 hard to see. Reaching + That distinction is what made :issue:`406` hard to see. Reaching :func:`ipv6_reassembly` repaired ``conf.l2types`` mid-run, one call too late to affect the frames being reassembled, so whether a process dissected correctly depended on what had imported `Scapy`_ earlier. Populating the registries before diff --git a/pcapkit/utilities/decorators.py b/pcapkit/utilities/decorators.py index 19999cb785..9764bfe8f8 100644 --- a/pcapkit/utilities/decorators.py +++ b/pcapkit/utilities/decorators.py @@ -208,8 +208,7 @@ def prepare(func: 'Callable[Concatenate[Type[R_prepare], bytes | IO[bytes], Opti and nothing calls it with more; an earlier revision of this note nonetheless promised implementors a trailing ``*args, **kwargs``, which the wrapper below never populated. A caller relying on that promise - got extras silently discarded instead of forwarded -- see `#454 - `__ -- so the + got extras silently discarded instead of forwarded -- see :issue:`454` -- so the wrapper now raises :exc:`TypeError` for a fifth positional argument or an unconsumed keyword, the same as an ordinary call with too many arguments would. diff --git a/pcapkit/utilities/exceptions.py b/pcapkit/utilities/exceptions.py index d91d8a3fda..8af4dcacba 100644 --- a/pcapkit/utilities/exceptions.py +++ b/pcapkit/utilities/exceptions.py @@ -203,7 +203,7 @@ class BaseError(Exception): * The two hooks still do not cover *every* path an exception can take. A traceback a caller formats itself with :mod:`traceback` -- rather than letting it reach the top level uncaught -- passes through - neither. See GitHub issue #719. + neither. See GitHub issue :issue:`719`. * The ``stacklevel`` of the log record is the relative level :func:`stacklevel` computes, so the record is attributed to the caller whose operation failed rather than to this module. It used to be @@ -716,14 +716,14 @@ class EnumKeyError(BaseError, KeyError): taste: ``E['nosuch']`` raises :exc:`KeyError` and ``E(999)`` raises :exc:`ValueError`, so a lookup that misses by *name* is :exc:`KeyError`-derived and one that misses by *value* is - :exc:`ValueError`-derived. That is a ruling given in review of #877's - phase-2 re-parenting, carried out by GitHub issue #923: raise + :exc:`ValueError`-derived. That is a ruling given in review of :issue:`877`'s + phase-2 re-parenting, carried out by GitHub issue :issue:`923`: raise whichever of the two stdlib :class:`~enum.Enum` would raise in the same circumstances, and raise it from this module rather than as a builtin. Deriving from :exc:`KeyError` is what makes that ruling cheap to carry out: :meth:`~pcapkit.corekit.enum.EnumLookup.get` raised a bare builtin - :exc:`KeyError` on a name miss until #923, and six in-library call sites + :exc:`KeyError` on a name miss until :issue:`923`, and six in-library call sites catch it -- :meth:`~pcapkit.const.http.method.Method.get` catches it in order to *mint*, so for that one a failed name lookup is part of a successful call. Every one of them keeps catching, unchanged.