Type checker error with miniupnpc import

[acul71]

Type checker error with miniupnpc import

Issue

The type checker (pyrefly) fails when importing miniupnpc in libp2p/discovery/upnp/upnp.py:

ERROR /tmp/py-libp2p/libp2p/discovery/upnp/upnp.py:4:8-17: Could not find import of `miniupnpc`, looked in these locations (from config in `/tmp/py-libp2p/pyproject.toml`):
  Import root (inferred from project layout): "/tmp/py-libp2p"
  Site package path (queried from interpreter at `/tmp/py-libp2p/venv/bin/python3.13`): ["/usr/lib/python3.13", "/usr/lib/python3.13/lib-dynload", "/tmp/py-libp2p/venv/lib/python3.13/site-packages", "__editable__.libp2p-0.3.0.finder.__path_hook__"] [import-error]

Root Cause

The miniupnpc package is a C extension without type stubs, causing the type checker to fail when trying to analyze the import.

Solution

Option 1 (Quick Fix): Add a type ignore comment to the import:

import miniupnpc  # type: ignore[import-untyped]

Option 2 (Better Long-term): Create type stubs for miniupnpc to provide proper type information. This would involve:

• Creating a miniupnpc.pyi stub file with type annotations for the methods used by libp2p
• Placing it in a location where the type checker can find it
• Maintaining the stubs as the miniupnpc API evolves

The stub approach provides better IDE support and type safety, but requires more setup and maintenance.

Files Affected

• libp2p/discovery/upnp/upnp.py (line 4)

Impact

• Prevents make pr from passing
• Blocks CI/CD pipelines
• Affects developer workflow

Priority

Low - simple one-line fix needed.

[acul71]

@pacrob @seetadev
I've merged a quick-fix in pr #1010
Do we need a better fix like adding type stubs for miniupnpc to provide proper type information ?
I don't know about C .so files and what is advisable to do with python