Improve stubs (typing information)

Yury Matveevrequested to merge
improve-stubs into develop

Closes #702 (closed)

Here we considerably improve our stubs (however, there is still room for improvement :-( ) :

  1. in our generate_stubs.cmake we should not copy main __init__.pyi, but the __init__.pyi from the "_tango" subfolder. This file actually contains stubs for the extension. With this file IDE now know all function signatures and can show proper auto-completion at runtime:

Before:

old_stubs

After:

new_stubs

We still can have main __init__.pyi - but I cannot understand, what it brings. THE QUESTION: do we also need to copy all others ".pyi" files?

  1. The problem with @staticmethod was due to we wrap the method with the @green (and @_trace_client, but this does not matter for docs) decorator, which is based on functools.wraps. The pybind11-stubs uses for method analysis inspect.getfullargspec, which, as we know, does not work in this case. So it could not properly analyse function signature and marked as static. To solve it we must preserve signature in our decorators.

  2. Then, since we, actually, know the real method signatures and our extension (at least now) does not accept kwargs - we can make methods signatures real (at least some of them) - this also helps with stubs

  3. and the last - since we anyway play with signatures in @green decorator and we know that it adds three kwargs (and they must be kwargs only) - we can add them automatically to the signature. And they will be show in stubs. The main problem here is that *args, **kwargs signature cannot be updated, and, due to @green is public - we do it only if optional kwarg update_signature_and_docstring set to True

  4. and finnaly - we can also automatize docsring generation in case of @green decorator. I propose, that in docstring we just add __GREEN_KWARGS__, __GREEN_KWARGS_DESCRIPTION__ and __GREEN_RAISES__ placeholders and the @green automatically adds here preper description.

  5. I revised all bindings, and added everywhere py::arg() = now generated stubs does not look like method(arg0, arg1), but with real names. As additional benefit = we now can call all methods with kwargs

  6. I tried to minimize erorrs durin pybind11-atubgen (however, fully remove them is super-complicated due to cirlucar dependencies of classes)

So, now our stubs for DeviceProxy and AttribueProxy are almost good.

Edited by Yury Matveev

Merge request reports