Include py.typed in a package

[bonprosoft]

Feature request

Feature description

I use mypy, one of the most famous static type checkers in Python, to check my Python code depending on rclpy.
However, mypy won't use the type annotation of rclpy, since mypy only uses the type annotation of packages that are marked as PEP561-compatible (i.e. Packages that have py.typed inside).

• https://mypy.readthedocs.io/en/stable/installed_packages.html

Therefore, I can't check the code like:

$ cat foo.py
import rclpy

reveal_type(rclpy)
reveal_type(rclpy.init)

rclpy.foo  # should be error
rclpy.init(foo="bar")  # should be error

$ mypy foo.py 
foo.py:1: error: Cannot find implementation or library stub for module named 'rclpy'
foo.py:1: note: See https://mypy.readthedocs.io/en/latest/running_mypy.html#missing-imports
foo.py:3: note: Revealed type is 'Any'
foo.py:4: note: Revealed type is 'Any'
Found 1 error in 1 file (checked 1 source file)

Would it be possible to include py.typed in rclpy package? (I am happy to work on this task!)

Implementation considerations

• The simplest solution is to create an empty file py.typed under rclpy directory
  • rclpy uses ament_python_install_package macro, and the macro just copies the directory tree into the install directory:
    https://github.com/ament/ament_cmake/blob/b84cf9e6f2a61d8f9fc5a90c02dc2b5cb63e7f76/ament_cmake_python/cmake/ament_python_install_package.cmake#L181-L186
  • Adding this empty py.typed file is common in Python (e.g. numpy)
• Another approach is to add the following line in CMakeLists.txt:

  file(WRITE "${PYTHON_INSTALL_DIR}/${PROJECT_NAME}/py.typed" "")

  • But I don't think it's a good idea since it's a bit harder to know whether the package is PEP561-compatible or not.

[adityapande-1995]

I tried adding py..typed to the rclpy directory, but I'm still seeing the same output ;

 0% ❯ mypy foo.py
foo.py:1: error: Cannot find implementation or library stub for module named "rclpy"
foo.py:1: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
foo.py:3: note: Revealed type is "Any"
foo.py:4: note: Revealed type is "Any"
Found 1 error in 1 file (checked 1 source file)

I have a file called py.typed in ~/ros2_rolling/install/rclpy/lib/python3.8/site-packages/rclpy , where the rclpy module is located (using rclpy.__file__)

[bonprosoft]

Thank you the response!

but I'm still seeing the same output

This is because mypy uses site.getsitepackages, where PYTHONPATH doesn't affect, to look up Python stub packages.
https://github.com/python/mypy/blob/f19a711eae747e2e5525bf0b0baaa3d3ae972fbd/mypy/modulefinder.py#L759-L760
https://github.com/python/mypy/blob/f19a711eae747e2e5525bf0b0baaa3d3ae972fbd/mypy/pyinfo.py#L25-L36

Here is the document:
https://mypy.readthedocs.io/en/stable/running_mypy.html#how-imports-are-found

The easiest way to try mypy for the example is to specify PYTHONUSERBASE:

$ PYTHONUSERBASE=/opt/ros/foxy mypy foo.py
foo.py:3: note: Revealed type is "types.ModuleType"
foo.py:4: note: Revealed type is "def (*, args: Union[builtins.list[builtins.str], None] =, context: Union[rclpy.context.Context, None] =)"
foo.py:6: error: Module has no attribute "foo"
foo.py:7: error: Unexpected keyword argument "foo" for "init"
/opt/ros/foxy/lib/python3.8/site-packages/rclpy/__init__.py:62: note: "init" defined here
Found 2 errors in 1 file (checked 1 source file)

If you use python in a virtualenv, the above method may not work since site package would set ENABLE_USER_SITE=False in some environments:
https://github.com/python/cpython/blob/5b71b519f966e1017c868ea2b27c61a5eac38c1f/Lib/site.py#L533-L539

So, general solution for ROS packages might be creating a .pth file in one of the site-packages as follows:

$ echo "/opt/ros/foxy/lib/python3.8/site-packages" > $(python -c "import site; print(site.getsitepackages()[0])")/ros.pth
$ mypy foo.py

[adityapande-1995]

Thanks for the clarification @bonprosoft ! Would you be willing to open a PR to fix this in rclpy ? If you tag me as a reviewer I could take a look at it.

[bonprosoft]

Of course! I've created a PR #946. Could you please take a look?

[bonprosoft]

Also, I have a question related to the type annotations.

• What do you think about the static type checker support of ROS packages? For example, can I send a PR to add more type annotations or fix the existing wrong type annotations of rclpy in the future?
  • Maybe I can introduce some tests for type annotations itself (e.g. stubtest) if it is OK.

Just FYI: I think the following feature request is also good to have and I am ready to contribute.
I know that you are busy, but it would be appreciated if I could get any feedback:

• Python type annotation rosidl_python#157