This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Mechanism for inheriting docstrings and signatures
Type: enhancement Stage: resolved
Components: Library (Lib) Versions: Python 3.5
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: Nosy List: Arfrever, asvetlov, bignose, cvrebert, eric.snow, ncoghlan, serhiy.storchaka, yselivanov
Priority: normal Keywords: patch

Created on 2012-08-20 04:37 by ncoghlan, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Messages (5)
msg168618 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-08-20 04:37
While working on #8810, I was reminded of the problem of wanting to inherit docstrings while replacing a method implementation.

The abstract base class method docstrings for tzinfo.utcoffset and tzinfo.dst are also correct for the concrete subclasses in the pure Python and the C versions. However, the docstrings currently need to be duplicated in all 3 places manually.

functools.wraps already plays in this space, but arguably asserts *too much* about the relationship between components

A couple of descriptors on bound and unbound methods (for __doc__ and __signature__) could have dealt with this fairly easily, but we don't have unbound methods any more :(
msg168619 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-08-20 04:40
Slight correction: turns out this docstring appears in a lot of other places, too.
msg209706 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-01-30 06:20
Perhaps, something like @functools.inherit decorator could help: (just a quick illustration).
msg259796 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-02-07 18:20
After issue15582, is it still actual?
msg259813 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2016-02-08 04:28
Agreed, making it easy to follow the inheritance chains at docstring lookup time means it would be redundant to duplicate them at class definition time.

Code that interrogates __doc__ directly rather than using inspect.getdoc won't benefit from the new behaviour, but that's a quality of implementation question in the code handling the introspection.
Date User Action Args
2022-04-11 14:57:34adminsetgithub: 59936
2016-02-08 04:28:11ncoghlansetstatus: open -> closed
resolution: out of date
messages: + msg259813

stage: resolved
2016-02-07 18:20:32serhiy.storchakasetmessages: + msg259796
2014-01-30 06:20:02yselivanovsetmessages: + msg209706
2014-01-30 05:55:10yselivanovsetnosy: + yselivanov

versions: + Python 3.5, - Python 3.4
2013-01-26 15:20:39serhiy.storchakasetnosy: + serhiy.storchaka
2012-08-26 20:13:06Arfreversetnosy: + Arfrever
2012-08-25 02:01:00cvrebertsetnosy: + cvrebert
2012-08-20 11:17:49ncoghlansetfiles: - issue8810_reconcile_docs.patch
2012-08-20 11:17:09ncoghlansetmessages: - msg168622
2012-08-20 11:17:04ncoghlansetmessages: - msg168621
2012-08-20 10:41:25asvetlovsetnosy: + asvetlov
2012-08-20 06:42:39bignosesetmessages: + msg168622
2012-08-20 06:25:34bignosesetfiles: + issue8810_reconcile_docs.patch

nosy: + bignose
messages: + msg168621

keywords: + patch
2012-08-20 04:40:40ncoghlansetmessages: + msg168619
2012-08-20 04:37:11ncoghlancreate