Endorsing putting docstrings in stub files is an intriguing idea, but I can see some potential issues with the approach:
>From pep 484, the use-cases listed for stub files are: - Extension modules - Third-party modules whose authors have not yet added type hints - Standard library modules for which type hints have not yet been written - Modules that must be compatible with Python 2 and 3 - Modules that use annotations for other purposes Additionally, the pep mentions that stub files are "only for use by the type checker, not at runtime" -- Obviously these things could change, or be changed, but taking the current wording, I can see a few issues with trying to promote docstrings in stub files: 1. Arguably(?), The official way to get a docstring from an object is to call `inspect.getdoc()`, so if we want official support for docstrings in stubs, inspect.getdoc() would have to be able to load and query stub files for docstrings at "runtime". 2. At the very least we'd need a standard library way to extract docstrings from objects that includes doing so from stub files, ending up with many different implementations of stub loading/docstring extracting withing different projects would not be ideal. 3. The use-cases listed above (from pep 484) suggest that stubs are really a workaround for cases where type information can't be provided directly in the source code. It's not super obvious that these use cases apply to docstrings. Extension modules already can provide docstrings directly, and documenting third-party modules seems a little unlikely (happy to be wrong about this!) 4. Promoting stub files from technical 'workaround', to being recommended in non-workaround situations seems like a So, I think the above would need to be discussed/have some consensus as part of the debate. Personally, this isn't a change I'd directly support, but have no major opinions either way. Steve On Thu, Dec 24, 2020 at 10:57 AM Alexey Volobuev <alex.volob...@gmail.com> wrote: > Actually, I am talking about both. It is not stated anywhere in PEPs or > Python documentation that it is OK to put docstrings in .pyi files. > > So we have 2 problems: > * Developers (of general purpose software) don't know should they put > docstrings in .pyi files > * Some other developers of docstring tools (like pydoc or help()) don't > know if they should consider docstrings in .pyi files > > I think right now it is possible for any software dealing with docstrings > to find those in corresponding .pyi files given .pyi matches corresponding > .py. > _______________________________________________ > 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/6NGRCJOXAFTOZF4FMX5425ZS62GY4A6I/ > Code of Conduct: http://python.org/psf/codeofconduct/ >
_______________________________________________ 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/2CTSUCKJJKQHNFOTZNDYR5KC7Y43ZU7K/ Code of Conduct: http://python.org/psf/codeofconduct/
