docs: let autodoc resolve the HTTP/2 frame and engine class annotations (#1857) (#1870)

Author: JarryShaw

pcapkit/foundation/engines/dpkt.py

@@ -29,6 +29,7 @@
 __all__ = ['DPKT', 'PCAPNGReader']
 
 if TYPE_CHECKING:
+    from types import ModuleType
     from typing import IO, Iterator, Literal, Optional, Type, Union
 
     from dpkt.dpkt import Packet as DPKTPacket
@@ -380,10 +381,8 @@ class DPKT(EngineBase['DPKTPacket']):
 
     """
     if TYPE_CHECKING:
-        import dpkt
-
-        #: Engine extraction package.
-        _expkg: 'dpkt'
+        #: Engine extraction package, i.e. :mod:`dpkt`.
+        _expkg: 'ModuleType'
         #: Engine extraction temporary storage.
         _extmp: 'Reader'
 
@@ -441,7 +440,6 @@ def run(self) -> 'None':
         from pcapkit.foundation.engines.pcapng import PCAPNG
 
         ext = self._extractor
-        dpkt = self._expkg
 
         if ext._exlyr != 'none' or ext._exptl != 'null':
             warn("'Extractor(engine=dpkt)' does not support protocol and layer threshold; "

pcapkit/foundation/engines/pcap_ct.py

@@ -24,6 +24,7 @@
 __all__ = ['PCAP_CT']
 
 if TYPE_CHECKING:
+    from types import ModuleType
     from typing import Iterator, Optional
 
     from pcap import pcap as Handle
@@ -111,10 +112,8 @@ class PCAP_CT(EngineBase['RawFrame']):
 
     """
     if TYPE_CHECKING:
-        import pcap
-
-        #: Engine extraction package.
-        _expkg: 'pcap'
+        #: Engine extraction package, i.e. :mod:`pcap`.
+        _expkg: 'ModuleType'
         #: Capture handle, kept separately from the iterator it is read through
         #: so that :meth:`close` does not depend on ``iter(handle) is handle``.
         _handle: 'Handle'

pcapkit/foundation/engines/pypcap.py

@@ -31,6 +31,7 @@
 __all__ = ['PyPCAP']
 
 if TYPE_CHECKING:
+    from types import ModuleType
     from typing import Iterator, Optional
 
     from pcap import pcap as Handle
@@ -86,10 +87,8 @@ class PyPCAP(EngineBase['RawFrame']):
 
     """
     if TYPE_CHECKING:
-        import pcap
-
-        #: Engine extraction package.
-        _expkg: 'pcap'
+        #: Engine extraction package, i.e. :mod:`pcap`.
+        _expkg: 'ModuleType'
         #: Engine extraction temporary storage.
         _extmp: 'Iterator[RawFrame]'
         #: Data link layer protocol, from the capture handle.

pcapkit/foundation/engines/pypcapfile.py

@@ -27,6 +27,7 @@
 __all__ = ['PyPCAPFile']
 
 if TYPE_CHECKING:
+    from types import ModuleType
     from typing import Any, Callable, Iterator, Optional
 
     from pcapfile.structs import __pcap_header__ as PCAPFileHeader
@@ -68,10 +69,8 @@ class PyPCAPFile(EngineBase['PCAPFilePacket']):
 
     """
     if TYPE_CHECKING:
-        import pcapfile
-
-        #: Engine extraction package.
-        _expkg: 'pcapfile'
+        #: Engine extraction package, i.e. :mod:`pcapfile`.
+        _expkg: 'ModuleType'
         #: Engine extraction temporary storage.
         _extmp: 'Iterator[PCAPFilePacket]'
         #: Data link layer protocol, from the savefile header.

pcapkit/foundation/engines/pyshark.py

@@ -22,6 +22,7 @@
 __all__ = ['PyShark']
 
 if TYPE_CHECKING:
+    from types import ModuleType
     from typing import Optional
 
     from pyshark.capture.file_capture import FileCapture
@@ -82,10 +83,8 @@ class PyShark(EngineBase['PySharkPacket']):
 
     """
     if TYPE_CHECKING:
-        import pyshark
-
-        #: Engine extraction package.
-        _expkg: 'pyshark'
+        #: Engine extraction package, i.e. :mod:`pyshark`.
+        _expkg: 'ModuleType'
         #: Engine extraction temporary storage.
         _extmp: 'FileCapture'
 

pcapkit/foundation/engines/scapy.py

@@ -51,6 +51,7 @@
 __all__ = ['Scapy']
 
 if TYPE_CHECKING:
+    from types import ModuleType
     from typing import Any, Iterator, Type
 
     from scapy.packet import Packet as ScapyPacket
@@ -282,10 +283,8 @@ class Scapy(EngineBase['ScapyPacket']):
 
     """
     if TYPE_CHECKING:
-        import scapy.all
-
-        #: Engine extraction package.
-        _expkg: 'scapy.all'
+        #: Engine extraction package, i.e. :mod:`scapy.all`.
+        _expkg: 'ModuleType'
         #: Engine extraction temporary storage.
         _extmp: 'Iterator[ScapyPacket]'
 

pcapkit/protocols/schema/application/httpv2.py

@@ -133,7 +133,10 @@ class FrameType(EnumSchema[Enum_Frame]):
     """Header schema for HTTP/2 frame payload."""
 
     if TYPE_CHECKING:
-        __flags__: 'Flags'
+        # Qualified rather than ``'Flags'``: documentation tools evaluate a class
+        # annotation against the module's globals, not the class body, so the
+        # bare nested name cannot be found there (#1857).
+        __flags__: 'FrameType.Flags'
 
     __enum__ = collections.defaultdict(lambda: UnassignedFrame)