Why Docstring for Python stub is necessary #881

Cirn09 · 2023-03-26T07:41:02Z

Cirn09
Mar 26, 2023

Yes, LIEF has Python port API. We can see all API easliy in any Python interpreter:

>>> import lief
>>> dir(lief)
['ARCHITECTURES',
 'ART',
 'Android',
 'Binary',
 'DEX',
 'ELF',
...
]

But lief is a pyd module. Our IDE don't know pyd's API, so we create stubs, let it tell IDE what API does LIEF has. Just as we discussed in #650

Yes, Python module LIEF has docstring. We can see it easliy in any Python interpreter.

>>> import lief
>>> help(lief.PE.parse)
Help on built-in function parse in module lief._lief.PE:

parse(...) method of builtins.PyCapsule instance
   parse(*args, **kwargs)
   Overloaded function.

   1. parse(filename: str) -> LIEF::PE::Binary
...

But lief is a pyd module. Our IDE don't know pyd's API and the Docstring of API, so we also need create stubs with Docstring, let it tell IDE what Docstring is for this API. Just as tttapa said:

I think this would be most useful for external C or C++ modules, because some IDEs don't look for signatures or docstrings in compiled modules.
Using stubgen at least fixes autocomplete for compiled modules, but if the stub files don't include docstrings, IDEs might not show any documentation when hovering over the function/class/variable in the editor (unlike with plain Python modules).
For example, Pylance in VSCode doesn't show documentation for functions in compiled modules, even with stub files generated by stubgen.

romainthomas · 2023-03-26T07:48:48Z

romainthomas
Mar 26, 2023
Maintainer

Our IDE don't know pyd's API

This is an IDE issue, not a LIEF issue:

vim supports well this
sphinx supports as well: https://lief-project.github.io/doc/latest/api/python/pe.html#parser
the python interpreter/ipython recognize the doc.

I don't plan to address this request as it would mean duplicating the documentation in two places:

the native module
the pyi files

You should ask VSCode to address this limitation

2 replies

Cirn09 Mar 26, 2023
Author

I see. Since Vim already supports this, that makes discussion easier. (Before starting this discussion, I investigated VSCode and PyCharm, which do not support reading API and docstrings from pyd files. And indeed, some modules add docstrings directly to the pyi file.)
I will initiate a new discussion on the VSCode side.
Thank you very much for your patient and prompt response.

LecrisUT May 3, 2025

This can be supported with nanobind_add_stub()

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Why Docstring for Python stub is necessary #881

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Why Docstring for Python stub is necessary #881

Uh oh!

Cirn09 Mar 26, 2023

Replies: 1 comment · 2 replies

Uh oh!

romainthomas Mar 26, 2023 Maintainer

Uh oh!

Cirn09 Mar 26, 2023 Author

Uh oh!

LecrisUT May 3, 2025

Cirn09
Mar 26, 2023

Replies: 1 comment 2 replies

romainthomas
Mar 26, 2023
Maintainer

Cirn09 Mar 26, 2023
Author