search

jim-easterbrook / python-gphoto2

Python interface to libgphoto2
GNU Lesser General Public License v3.0
357 stars 59 forks source link

Generate Stub-File (.pyi) for public interface #125

Closed raverank closed 1 year ago

raverank commented 2 years ago

I would love to have a better autocompletion/doc-support while coding. Right now, my editor (VS-Code with Pylance) has no idea about the implemented methods and classes in your package as it does not get information from the binaries. Do you know, if SWIG is able to generate .pyi-files with stubs for all methods and classes? This would greatly improve the workflow with the package.

Or is there another way (editor?) to get the same info as with pydoc while programming?

jim-easterbrook commented 2 years ago

I've never looked into this before. I'll do a bit of reading and see what's possible.

jim-easterbrook commented 2 years ago

I've just been experimenting with Python's idle IDE (as that's the only one I use). Once gphoto2 has been imported (using idle's Python shell) you get tab-completion of function names, but instead of listing parameters it just says "see source or doc" which is not very helpful.

SWIG doesn't generate stub files itself, although this has been suggested. http://swig.10945.n7.nabble.com/Python-type-hinting-stubs-generator-td14751.html

I'm already using doxygen and doxy2swig to extract documentation from the C sources (not the header files needed to build python-gphoto2 on a user's machine) so might be able to tweak this if needed. One problem is that the C documentation includes the "output" parameters that become return values in Python.

jim-easterbrook commented 2 years ago

More discussion of SWIG and PEP-484 here: https://github.com/swig/swig/issues/735

Note that I'm not using SWIG's doxygen parsing as SWIG runs on the header files only, but gphoto2's doxygen comments are mostly in the C source.

jim-easterbrook commented 2 years ago

I've done a bit of experimenting. It won't be possible to generate stub files with SWIG unless someone (not me) modifies SWIG. I tried using stubgen from mypy (https://mypy.readthedocs.io/en/stable/stubgen.html) on my installed python-gphoto2. This appears to work, but I don't know if the generated stubs are useful as idle doesn't seem to use them.

raverank commented 2 years ago

Thank you so much for your time and efforts! As soon as I find the time, I will try out if stubgen can improve my workflow and share my experience here.