classification
Title: Simplify per-instance control of help() output
Type: enhancement Stage:
Components: Library (Lib) Versions: Python 3.4
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: ncoghlan, python-dev, yselivanov
Priority: normal Keywords:

Created on 2013-10-26 07:22 by ncoghlan, last changed 2015-07-21 08:07 by ethan.furman.

Messages (5)
msg201322 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 07:22
While working on issue 19330, I also took a look at whether or not I could fix the @contextmanager decorator to also provide useful help information on the resulting objects. This turned out to be difficult, since calling decorated functions produces instances of contextlib._GeneratorContextManager, and help() insists on showing the docs for that rather than a __doc__ attribute set on the context manager instance itself.

This behaviour appears to be ultimately due to "pydoc.render_doc()", which has a hardcoded list of conditions it checks to decide whether to document the instance directly or to provide the class documentation instead:
http://hg.python.org/cpython/file/2b904290b3b9/Lib/pydoc.py#l1544

This first idea that comes to mind is to simply add the additional condition that if "obj.__doc__ != type(obj).__doc__", then help() shouldn't replace the object with it's type. The simple trick that I originally explored was simply setting the __doc__ attribute on the _GeneratorContextManager instance based on the docstring of the decorated function, and I believe that approach might work for property instances, too (rather than needing to hardcode the isinstance check into render_doc()). It may even handle some of the other currently hardcoded conditions in that list.
msg201326 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-26 08:08
New changeset 09153a9a3bb9 by Nick Coghlan in branch 'default':
Close #19330 by using public classes in contextlib
http://hg.python.org/cpython/rev/09153a9a3bb9
msg201365 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 14:49
Issue 19031 is a report indicating that this is a problem for Enum instances as well.
msg201388 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2013-10-26 18:11
Would it make sense to have the presence of a non-None __doc__ be a deciding factor?  How often does an instance have a docstring where one would want the class info instead?
msg201404 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-27 01:32
As far as I am aware, never. But "instance.__doc__" falls back to the
class, hence the != check rather than "is not None".
History
Date User Action Args
2015-07-21 08:07:37ethan.furmansetnosy: - ethan.furman
2014-11-01 14:54:07ethan.furmanlinkissue19031 superseder
2014-02-01 00:11:48yselivanovsetnosy: + yselivanov
2013-10-27 01:32:26ncoghlansetmessages: + msg201404
2013-10-26 18:11:09ethan.furmansetmessages: + msg201388
2013-10-26 14:49:59ncoghlansetmessages: + msg201365
2013-10-26 08:08:29python-devsetnosy: + python-dev
messages: + msg201326
2013-10-26 07:22:18ncoghlancreate