Type annotations for Python API

[PeterJCLaw]

I'm not sure how the Python API is built, however I was wondering whether it would be possible to create type annotations for it. This would help document the APIs as well as allow users to check that their code is using the API correctly (just as, for example, the Java compiler is able to do for users of the Java API).

At the moment I've got a set of local stubs in my project which I've manually created based on the documented API, with the types captured from a mixture of observed data types and the docs for other languages (mostly Java).

It feels like type annotations could usefully be added to the signature snippets in the docs as well as potentially being published as a stubs package on PyPI for use in type checking and as editor completions.

I'm definitely hoping that the signatures would be generated from the true source, however I'd be happy to contribute the stubs I've created as a starting point if they need to be manually defined.

[omichel]

We use swig to generate the Python API from the C++ API and there is no easy way to introduce type annotations there, see swig/swig#735 for a discussion on this topic. So, you local stubs approach may be a better way. I guess we shall it to the Python library build process somewhere here: https://github.com/cyberbotics/webots/tree/master/resources/languages/python
Feel free to propose a solution by submitting a new pull request in this repository. We will be happy to review it.

Alternatively, it shouldn't be that difficult to get rid of SWIG for the Python wrapper and maintain it, based on the C libController library (instead of the C++ one). But that's probably a bit more of work, but could be also very nice and fix other problems caused by SWIG.

[Justin-Fisher]

If we can't figure out a way to (1) make swig automatically generate appropriate python type hints (and my sense from reading threads like the one @omichel linked is that this isn't really feasible yet), I suppose another option would be (2) to write a script that automatically adds appropriate type hints to the swig output. Writing Python code to alter Python code is quite straightforward, using Python Abstract Syntax Trees (AST's). The main challenge would just be to figure out which types to assign to which arguments and outputs. This mapping could be constructed manually, and would likely require little maintenance afterwards, or there may be a way to get swig to generate its auto-documentation (which apparently will be wrong in various ways, like using C++ names for the types rather than python names) and then convert that into the appropriate python type hints.

On the bright side, Python type hints and documentation are optional, so this needn't be perfect or complete in order to be useful. So, e.g., a partial solution that adds type hints to commonly used things would be very useful, and it wouldn't really matter very much if newly added Webots features don't immediately get their own type hints.

A related useful feature, which might be good to fold in with this, would be to include (either a hyperlink to or a copy of) Webots documentation in the Python docstrings for functions in controller.py, so that this documentation could be immediately available within a Python IDE like PyCharm, rather than requiring flipping over to a browser and searching there.

[omichel]

All what you propose should be easy to implement if we totally get rid of swig for generating the Python API.
I believe more and more that a totally new Python API could be created without swig and maintained manually, which should be easy because it will be very straightforward. This API could rely on the C API (instead of the C++ one) thus, removing the dependency on libCppController and other C++ dependencies. It would call the C API function directly from python.
Such a library could easily include python hints and documentation with hyperlinks as described above.
In addition to all these benefits, such a library should be designed to be more "pythonic" with python .value getters and setters instead of .getValue()/.setValue() methods inherited from C++.

If someone would volunteer to go ahead with such an implementation, I would suggest to start with a minimal proof of concept implementation supporting only one type of sensor and one type of actuator. I would be happy to review it in a PR and if it looks good we could generalize it to the complete API. Ultimately, we could drop the current Python API and replace it with this new one.

[Justin-Fisher]

My current way of using supervisor controllers in Python works much like you suggest with getters and setters to let me use simple .attribute notation to get/set the fields of scene tree nodes, and also to retrieve descendant nodes. E.g., grabbing a quick example, I use the following one-liner to do something that in vanilla webots would take half a dozen lines to find the the node with DEF-name PUDDLE, and then delve down through fields to find the relevant subfield and set it to a new value:

    ROOT.PUDDLE.appearance.textureTransform.translation = newpos

My "proxy scene tree" currently implements this using container objects (called proxy nodes and proxy fields) that wrap around Webots own python versions of nodes and fields, and for the most part simply redirect attempted references and method calls to the corresponding Webots fields and methods. I've tested this quite a lot in the labs for my class, and it works smoothly, and is a tremendous quality-of-life improvement over vanilla Webots supervisor control.

Two alternative approaches (even more like what you're suggesting) would have been (2) to subclass the Webots python objects themselves to produce objects that simultaneously are instances of the Webots classes and have this sort of "pythonic" functionality, or (3) to not even bother with subclassing and rewrite controller.py to make the only version of the Webots python objects be ones with this sort of pythonic functionality. It would be fairly straightforward to adapt what I already have to produce either of these approaches.

Three of the main advantages of (1) my current container-based approach are (a) that it automatically adapts to swig-produced Webots updates typically with no need for manual maintenance, (b) it minimizes the risk of there being some name-collision between the few attributes and methods I use for handling the proxies and any attributes or methods that Webots might someday give to its objects, and (c) it is entirely optional whether to use it (which is sort of good, sort of bad).

Some drawbacks of (1) this generic-containers approach are (d) since I dynamically redirect references to fields and methods, those aren't known in advance so don't currently serve the linting goals that were the original topic of this thread, and (e) this runs a bit slower than an approach that cuts out my proxy middlemen could be. Approaches (2) or (3) could help with each of these, though at the cost of (a-c) above, especially increased maintenance costs for future Webots versions (or upfront costs getting swig or a post-swig script to automatically make these changes).

So, anyway, you had suggested doing a "minimal proof of concept" with a single sensor and actuator. The proof of concept that I have currently instead is far from minimal, being a generic one-size-fits-all wrapper for all scene tree nodes and fields, but it does demonstrate that these can indeed be made to work in a much more "pythonic" fashion than they do in vanilla webots, and I can attest that this was a tremendous improvement in my quality of life writing supervisor controllers. (It may also be worth emphasizing that this works just with the various node and field objects that supervisor controllers use, not with the device objects that ordinary controllers use, though similar moves could be made with them.)

[omichel]

That's a very nice contribution, but it looks like a helper for the supervisor API, not a replacement of the python controller library. My idea was to replace the swig-generated python controller library by a native python controller library in order to have more flexibility to introduce type annotations and provide a more "pythonic" interface. Your contribution would actually fit very well into this new python library.

[Justin-Fisher]

Making controller.py be manually maintained would indeed open the door to a number of useful things, including (1) type-hinting for python linters, (2) adding helpful python doc-strings, and (3) providing more "pythonic" access to some attributes and methods. (I've developed a handful of other useful "pythonic" changes I'd probably suggest including under (3) too, if we do this.)

In my eyes, the biggest drawback of making controller.py be manually updated is that it would add to the workflow of changing core Webots features that require corresponding changes to controller.py. E.g., last year there were changes to how a supervisor gets contact points that led to corresponding changes in controller.py, which I think were probably done automatically by swig? There must be some advantages to having swig automatically percolate such changes to Python without requiring that the person who figured out how to make these changes in C need to know how to do this in Python, and remember to do it.

It's above my paygrade to determine whether the long-term advantages of switching to manual maintenance of controller.py are worth the costs.

Another option I would probably consider in your position is creating a python script that would take the swig auto-generated version of controller.py and automatically rewrite it to include things like (1-3) above (or perhaps there is a way to force swig to do everything we'd want, not sure). If this script is added to Webots' automated build process, then this would automatically percolate many Webots changes to controller.py via swig and this script, rather than requiring any sort of manual maintenance. Depending on what the Webots changes are, there might be some sorts of manual maintenance that would be good to do, e.g., adding any type-hinting or documentation that the script can't figure out on its own. But, since type-hinting and documentation are optional in Python, if no one remembers to make those changes, that would just be a minor inconvenience and wouldn't stop new Webots features from working in Python. Of course there are probably greater set-up costs to get this script going in the first place, though once you know what you're doing it's not all that much harder to script a sequence of find-and-replace steps than it is to perform them manually once. And there could be some future changes to Webots that this script wouldn't be prepared for that might require some sort of manual response, but those would likely be rare, much more rare than all the Webots changes that would require manual revisions to controller.py if we followed your proposal to stop using swig entirely.

[omichel]

I believe the maintenance overhead for a new python library without swig (let's call it native) is very small. We do not add API functions everyday and whenever we add one, we need to test it in python to ensure the swig generated interface works which is not always the case and sometimes needs to be adapted in the controller.i file. This file, as you can see, requires anyhow some maintenance and is pretty complex to maintain (you need some good swig expertise and you may need to update it when swig gets an update, etc.).

So my feeling is that the maintenance overhead is a little price to pay to have a better and simpler Python API and I am happy to move into this direction.

[Justin-Fisher]

I think there is a swig option to have it generate auto-documentation, which is often flawed (e.g., using C++ names for types rather than their Python names) but still could be a helpful starting point for manually setting up type-hinting. So I guess a useful first step would be for someone to use swig to generate a version of controller.py with that auto-documentation included. I haven't figured out how to use swig, so I'm not ideally situated to do that.

It may also be useful to look at the stubs that @PeterJCLaw created that included some Python type-hinting already -- slightly out of date now, but probably straightforward to merge.

Adding the type-hinting would probably be quite straightforward, if a bit tedious. I think mironix expressed some willingness to take that on.

I'll also look through controller.py and think about what I would recommend regarding making things more "pythonic", including figuring out a good way to incorporate my proxy scene tree stuff. I think I will probably recommend the option I had labeled as (3) above: directly building this stuff into the controller.py, rather than adding extra subclasses or container classes.

[Justin-Fisher]

Ironically enough, last year I pointed out that specific flavors of getDevice functions like getMotor weren't really needed, when there was already a one-size-fits-all getDevice function that yielded exactly the same effects. In response, you deprecated the specific flavors and encouraged folks to switch to getDevice. However... now that we're thinking about trying to facilitate type-hinting, one-size-fits-all constructors like getDevice actually aren't very friendly for type-hinting, since it's unpredictable which flavor of device will be returned, so linters won't have any way of knowing that getDevice("left motor") will return a motor device rather than some other device, and won't automatically be able to recommend methods or documentation that are specific to Motors.

This may weigh somewhat in the direction of un-deprecating the specific flavors like getMotor, now that they actually can serve a useful type-hinting purpose separate from the generic getDevice. Alternatively, we could just make the sample Python code include explicit type hints that would accomplish the same linting purposes. This alternative is attractive because it allows novices to get away with remembering a single getDevice command rather than needing to learn a bunch of specific flavors, while still giving folks who want type hinting an option that isn't much harder than looking up a specific flavor of getFoo command.

m = getMotor("left motor") # currently deprecated, but could easily be made to type-hint that the returned item will be a Motor
m = getDevice("left motor") # currently equivalent to the preceding, but can't automatically type hint Motor
m = getDevice("left motor") # type: Motor   # Serves the same type-hinting purposes as the first would have

Relatedly, though, I very often end up pairing getDevice with device.enable commands, so, if we're thinking of making things more "pythonic", I would probably suggest letting getFoo commands accept an optional argument to simultaneously enable them with a specified time interval.

ls = getDevice("light sensor", interval = robot.timestep ) # type: LightSensor  # finds and enables this light sensor

I can't remember, off the top of my head, how much variety there is in device.enable calls for different Webots sensors, but the more diversity there is, the more this might weigh in favor of going back to having specific flavors of getFoo calls with their own enable options, rather than trying to do everything with a generic getDevice.

[omichel]

Your type hinting suggestion sounds very good to me.
About adding the interval optional argument, this is also a very good idea. However, it may be a problem with some devices, such as Emitter, Pen, Skin or LED, which don't have a enable method, but I guess in this case, the library should simply issue a warning in the console.