Experiment towards an auto-geneated type stubs package

[PeterJCLaw]

Description

This creates a PEP 561 type stubs package which can be published to PyPI, perhaps for use in type-checking in CI without needing to install the whole of Webots.

A core limitation of this approach is that since this is a stubs-only package consumers are still unable to import the Webots classes, meaning that this doesn't provide a solution for writing unit-tests of controller code which imports (but does not use in tests) Webots controllers. This stubs package does not preclude (nor would it interfere with) adding a more complete runtime package on PyPI later. Doing so would likely render this package redundant however.

This is very much a first pas and not at all ready for merge yet. Instead this is intended as a contribution to the conversation around Python type stubs for Webots.

Currently this package produces type checking failures in the test project I have (https://github.com/srobo/competition-simulator/tree/webots-published-stubs) which are not found by the local stubs from the project (removed on the linked branch). I'm not sure if that's a result of the project-local stubs being incorrect, whether the API in Webots has moved on since the last release, whether there are bugs in the type annotations in Webots, or something else.

Included here is a CI job which builds the package and saves it as an artefact. This is mostly so there's an easily available copy of the output.

I did notice that the Python API in Webots doesn't have full type coverage, nor is it itself checked by mypy. While those aren't things I'd want this PR to introduce, it would probably be better to have at least the checking by mypy in place before publishing the stubs package so that the stubs don't themselves contain inconsistencies.

Related Issues

Follows from discussion #2385 (comment)

Documentation

This would likely need documentation.

Questions

• Is this a useful thing to have?

If so:

• Is this the right place for it in the code?
• Where/how should the code to publish it go?

[omichel]

My feeling is that use cases for this are pretty limited (type checking in CI), and it adds some complexity to our CI actions (which we will have to maintain on the long run). So, I am not sure this is worth the effort.
I believe that if we would add the libController binaries, it would allow for more use cases, e.g., starting an extern controller on one machine that connects to a Webots instance running on a different machine.
But even for this one, I am not aware of anyone needing this.

[omichel]

Note: we are currently working on a new repository that holds only the libController and which you could use in your CI: https://github.com/cyberbotics/webots-libcontroller/tree/R2023a
This repo is kept in sync with the Webots repository every night.
Alternatively we are also exploring having branch on the webots repo that contains only the libController files (including Python files, C/C++ headers, Java files, etc.). This could also be a good solution for your use case. It is here for testing purposes: https://github.com/cyberbotics/webots/tree/libcontroller. This one is also synchronized every night on the master and develop branches.

[PeterJCLaw]

Yeah, purely type checking is fairly limited. In my actual use-case we also use our "stubs" to allow our controller code to be imported by unit tests (though we don't touch the webots interface during testing), which your libController package approach would also solve for (if I'm understanding correctly). If you're planning to/interested in publishing that as a standalone typed package (on PyPI?) then that definitely feels like it would make this stubs-only package redundant.

I'll have a play with one or both of those alternatives at some point and let you know if they work for us.