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 <srit...@rittau.biz> wrote: > 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-le...@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/PPXVKIH7PZCSBB73PMVSMDWGFXPBUPBA/ > 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-change-the-world/>
_______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-le...@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/IUJC2BT3LSEY3XKZFKBG7U3JUAET5M5Z/ Code of Conduct: http://python.org/psf/codeofconduct/
