Hi All, # Too long didn't read:
In 3.9 inspect.getdoc(instance) behavior was changed and does not return the documentation of type(instance) or it's superclass(es) – I think this is a problematic change of for some project and interactive use to get info on objects that get rarely directly constructed by users. For example pandas dataframe obtained via `pandas.read_csv(filepath)`. I'd like to ask for reconsideration, and that change of behavior are better suited in a new function; potentially deprecating the old one. # Longer version In https://bugs.python.org/issue40257 attempts are made to improve the output of `pydoc`, it particular it is difficult to have fine grained logic depending on where the documentation comes from (instance, class , superclass, etc..). Which sometime can lead to nonsensical help. The following are given as examples: > inspect.getdoc(1) returns the same as inspect.getdoc(int) or >>> import wave >>> help(wave.Error) Help on class Error in module wave: class Error(builtins.Exception) | Common base class for all non-exit exceptions. | | Method resolution order: ... In 3.9 the behavior of `inspect.getdoc()` has been changed to be way more restrictive in what it returns, often returning None where it used to return docstrings. I agree with the end goal of having more controllable way of finding where the documentation/docstrings is coming from and avoiding incorrect docs in pydoc and help, though I find that change of behavior of `getdocs()` might not be the right approach. I'm quite worried many project rely on current behavior of `getdocs()` – at least IPython/Jupyter does to provide user with help/superhelp accessible via obj? and obj??. I would also argue that inaccurate help is also often better than no help. With current state on Python 3.9, a few things like asking for help on a pandas dataframe instance will currently loose informations. >>> import pandas as pd >>> from inspect import getdoc >>> df = pd.read_csv('mydata.csv') >>> print(getdoc(df)) None I'm taking the example of pandas as this is typically the kind of objects you don't construct directly, and get via for example `read_csv()`, or that another API/Package return to you. I haven't been able to confirm yet exactly how this affects sphinx rendering of docs, and how other IDEs provide help (Spyder, Pycharm...), or other projects that use `getdocs()`. I've found mentions of `getdocs()` in numpy, scipy, jedi, matplotlib ... as well (sphinx extension and various dynamic docs), and working on building them on 3.9 to check the effect. In general though the effect of `getdoc()` rarely seem to be tested as they will directly be user facing is my feeling – I was lucky to catch it in IPython/Jupyter as the failing test was unrelated and indirectly relying on the exact output of a subprocess. From the IPython/Jupyter perspective I would prefer to keep current behavior of `inspect.getdocs()` potentially deprecating it if you wish to, and provide an alternative that have a behavior of your choosing. Dealing with functions with slightly chaging behavior across Python version is not the best experience, and this would let the ecosystem get some chance to adapt. Updated project get rarely released in synchrony with new Python versions. Your thoughts on this issue are welcome, thanks for all your work on core python, and I'll support any decision that get made. -- Matthias _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/6QO2XI5B7RVZDW3YZV24LYD75VGRITFU/ Code of Conduct: http://python.org/psf/codeofconduct/
