Skip to content

feat(engines): type the third-party engine packages with local stubs and a per-engine _expkg type #1878

Closed

Description

@JarryShaw

The engines' handle on their third-party package, _expkg, is ModuleType after #1870, so mypy sees every call through it as Any. Per the owner's request on #1870, give each engine real typing.

Current state (mypy 2.3.1, the repo's mypy.ini with ignore_missing_imports = True):

  • scapy ships py.typed.
  • dpkt and pyshark are untyped.
  • pcap (pypcap and pcap-ct) and pcapfile are untyped and are not in the test or docs environments.

Proposed:

  1. Local .pyi stubs, covering only the APIs and data types pcapkit uses, for dpkt, pyshark, pcap and pcapfile. Put them under one stub directory registered via mypy_path, and keep them out of the wheel and sdist.
  2. A per-engine type for _expkg. mypy rejects a module as a type, so use a Protocol per engine, in a TYPE_CHECKING block, describing the attributes the engine reads. The runtime stays lazy-import as it is.
  3. mypy on pcapkit/foundation/engines/ and pcapkit/toolkit/ must report no new errors, and calls through _expkg must type-check against the stubs. A test should pin that each engine's _expkg annotation is its own type and not ModuleType.

Builds on #1870, which removed the class-level engine imports.

Activity

  1. added
    featPull requests that add a new capability (feat: subject prefix)
    pendingAccepted and unstarted - nobody is on it and nothing blocks it
    on Oct 17, 2026
  2. JarryShaw commented on Oct 17, 2026

    @JarryShaw
    OwnerAuthor

    A worker is on this. It is stacked on #1870 (branch docs/1857-class-guard-annotations), which moves the engines to _expkg: ModuleType and is what this builds on.

  3. added
    wipWork in flight - a covering PR is open or an agent is actively on it
    and removed
    pendingAccepted and unstarted - nobody is on it and nothing blocks it
    on Oct 17, 2026
  4. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Oct 17, 2026
  5. added a commit that references this issue on Oct 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featPull requests that add a new capability (feat: subject prefix)

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions