Author ncoghlan
Recipients ethan.furman, ncoghlan
Date 2013-10-26.07:22:17
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1382772138.17.0.267743568288.issue19404@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2013-10-26 07:22:18ncoghlansetrecipients: + ncoghlan, ethan.furman
2013-10-26 07:22:18ncoghlansetmessageid: <1382772138.17.0.267743568288.issue19404@psf.upfronthosting.co.za>
2013-10-26 07:22:18ncoghlanlinkissue19404 messages
2013-10-26 07:22:17ncoghlancreate