How do we avoid having the docstrings in two places? Large communities
(e.g. Jupyter notebook and IPython users) rely on docstrings available at
runtime. There should be a tool to update the docstrings in stubs before I
could recommend duplicating them there.
Even for stubs corresponding to extension modules we would need such a
tool, since those also typically expose docstrings (defined in the C code)
at runtime.
On Fri, Jan 1, 2021 at 7:11 AM
Alexey Volobuev wrote:
Sometimes you have to put docstrings in stub files e.g. when using code generation. In that case, stubs are the only place you can locate "objects" to add docstrings to. Thus it is frustrating to find that docstring-related software generally tends to ignore the presence of docstrings in stubs or to work incorrectly with those. I think we need a PEP to clarify the interaction between stubs and docstrings. This PEP might also encourage developers of docstring-related software to mind docstrings provided with stub files.
Not having docstrings in type stubs is one of the small frustrations I have when working with Python. When working with combined Python/Typescript projects in PyCharm, I often find myself hitting Ctrl-B to jump to the definition of third-party JavaScript functions. This takes me to the appropriate *.d.ts file, which is JavaScript's equivalent of Python stubs files. But they also include JSDoc comments. I often wish I could do the same in Python.
In my ideal world, every Python package (as well as the stdlib) would ship with stubs files that describe the package's public API, both for machine and human consumption. This could be automatically generated on build time from the sources, or it could be hand-crafted. This means, including types and docstrings. I also thing that providing the actual default, like Eric Traut suggested, would be a good idea. _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/PPXVKI... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido) *Pronouns: he/him **(why is my pronoun here?)* http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-c...