What is the expected enhancement?

Users are able to execute mypy to run a static type check in code that uses retworkx.

Python annotations are becoming more popular, and we should consider supporting them. Supporting annotations can help make retworkx more popular in codebases that have adopted mypy. Also, many popular libraries that do not support annotations yet have tickets claiming for them.

Suggested Implementation

Create .pyi stubs containing the type annotations for the existing code. See typeshed for some inspiration on how this is done. Another useful inspiration is orjson, they are another Python library that uses Rust/PyO3 and they also use the .pyi stub approach.

Challenges

• Duplication: if we use .pyi stubs, we will have to duplicate all the functions signatures in the stubs files; ideally PyO3 would generate all the stubs but Feature request: Generate stub files along during compile PyO3/pyo3#510 is far from being closed
• Packaging: making sure the stubs are installed and third-party code recognizes it when running mypy
• Testing: how do we test our stubs are correct and up to date?

Non-Goals

Use mypy internally within retworkx. The emphasis is: we want users to be able to run mypy when checking code that uses retworkx.