mypy
mypy copied to clipboard
python
Add option to include docstrings with stubgen
Description
Closes #11965.
Add a --include-docstrings flag to stubgen. This was suggested in #11965 along with a use case. When using this flag, the .pyi files will include docstrings for Python classes and functions and for C extension functions. The flag is optional and does not change the default stubgen behaviour. When using the flag, the resulting function stubs that contain docstring will no longer be one-liners, but functions without a docstring still retain the default one-liner style.
Example input:
class A:
"""class docstring"""
def func():
"""func docstring"""
...
def nodoc():
...
output:
class A:
"""class docstring"""
def func() -> None:
"""func docstring"""
...
def nodoc() -> None: ...
Test Plan
Tests testIncludeDocstrings and testIgnoreDocstrings were added to test-data/unit/stubgen.test to ensure the code works as intended. All other tests passed as well.
C extension docstrings are tested using an updated bash script misc/test_stubgenc.sh with test data in test-data/pybind11_mypy_demo/stubgen-include-docs in same fashion as in an already existing test.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
I gave it some more thought and I will have to fix another mistake - fastparse now keeps the docstrings in memory even when nothing uses them. I think I should also add include_docstrings internal flag to mypy.options. The docstrings would be retained only when stubgen (or anything that wants it) sets the flag.
Thanks @sobolevn for you comments, I'll fix it.
I was wondering about the C extension tests as well. There is a shell script that tests stubgenc as part of the github worklow. Perhaps I should create its duplicate that would test the docstrings.
Thanks @sobolevn for the code reviews. Now I understand why this wasn't labeled as good first-time issue :-)
@hauntsaninja Can you review this PR? I would definitely welcome this feature :)
can you also consider adding variable docstring?
a_variable: int = 0
"""this is the docstring for a_variable"""
class Fields_Obj:
DefaultValue=None
"""Get/set the default value of the data field"""
https://stackoverflow.com/questions/6060813/how-to-document-fields-and-properties-in-python
@ws1088 Interesting - attribute docstrings as PEP 224 were rejected but PEP 257 kind of brings them back. I think the AST doesn't make attribute docstrings accessible, so that wouldn't be an easy change. I think I won't be able to include attribute docstrings.
@chylek Could you please resolve merge conflicts? This adds a frequently requested feature, so I would merge this (unless there are objections from other maintainers).
According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅
@chylek While a docs issue unrelated to your PR is being fixed, could you please fix a style issue I found?
According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅
According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅
