docs(foundation): convert bare citations to the issue role in docstrings

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 ``::``

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

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

pcapkit/foundation/registry/protocols.py

@@ -162,7 +162,7 @@ def register_protocol(protocol: 'Type[ProtocolBase]') -> 'None':
     <pcapkit.protocols.protocol.ProtocolBase.expand_comp>`, 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
     <pcapkit.protocols.protocol.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__
 #: <pcapkit.protocols.protocol.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 <pcapkit.protocols.link.l2tpv2.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**

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

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:
 #:

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

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
-        <https://github.com/JarryShaw/PyPCAPKit/issues/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.

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.