diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 3855d3604e1..6ab7991d8d4 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -174,6 +174,20 @@ gettext Added :func:`~gettext.pgettext` and its variants. (Contributed by Franz Glasner, Éric Araujo, and Cheryl Sabella in :issue:`2504`.) +inspect +------- + +The :func:`inspect.getdoc` function can now find docstrings for ``__slots__`` +if that attribute is a :class:`dict` where the values are docstrings. +This provides documentation options similar to what we already have +for :func:`property`, :func:`classmethod`, and :func:`staticmethod`:: + + class AudioClip: + __slots__ = {'bit_rate': 'expressed in kilohertz to one decimal place', + 'duration': 'in seconds, rounded up to an integer'} + def __init__(self, bit_rate, duration): + self.bit_rate = round(bit_rate / 1000.0, 1) + self.duration = ceil(duration) gc -- diff --git a/Lib/inspect.py b/Lib/inspect.py index b8a142232b8..8c398bd3534 100644 --- a/Lib/inspect.py +++ b/Lib/inspect.py @@ -582,9 +582,12 @@ def _finddoc(obj): cls = obj.__objclass__ if getattr(cls, name) is not obj: return None + if ismemberdescriptor(obj): + slots = getattr(cls, '__slots__', None) + if isinstance(slots, dict) and name in slots: + return slots[name] else: return None - for base in cls.__mro__: try: doc = getattr(base, name).__doc__ diff --git a/Lib/statistics.py b/Lib/statistics.py index e5a62463f01..bd8a6f96381 100644 --- a/Lib/statistics.py +++ b/Lib/statistics.py @@ -709,7 +709,8 @@ class NormalDist: # https://en.wikipedia.org/wiki/Normal_distribution # https://en.wikipedia.org/wiki/Variance#Properties - __slots__ = ('mu', 'sigma') + __slots__ = {'mu': 'Arithmetic mean of a normal distribution', + 'sigma': 'Standard deviation of a normal distribution'} def __init__(self, mu=0.0, sigma=1.0): 'NormalDist where mu is the mean and sigma is the standard deviation.' diff --git a/Lib/test/test_inspect.py b/Lib/test/test_inspect.py index b9072e0137e..bc675aa5df2 100644 --- a/Lib/test/test_inspect.py +++ b/Lib/test/test_inspect.py @@ -375,6 +375,11 @@ class GetSourceBase(unittest.TestCase): self.assertEqual(inspect.getsource(obj), self.sourcerange(top, bottom)) +class SlotUser: + 'Docstrings for __slots__' + __slots__ = {'power': 'measured in kilowatts', + 'distance': 'measured in kilometers'} + class TestRetrievingSourceCode(GetSourceBase): fodderModule = mod @@ -429,6 +434,10 @@ class TestRetrievingSourceCode(GetSourceBase): 'A longer,\n\nindented\n\ndocstring.') self.assertEqual(inspect.getdoc(git.abuse), 'Another\n\ndocstring\n\ncontaining\n\ntabs') + self.assertEqual(inspect.getdoc(SlotUser.power), + 'measured in kilowatts') + self.assertEqual(inspect.getdoc(SlotUser.distance), + 'measured in kilometers') @unittest.skipIf(sys.flags.optimize >= 2, "Docstrings are omitted with -O2 and above") diff --git a/Lib/test/test_statistics.py b/Lib/test/test_statistics.py index 485ffe24036..7f7839de460 100644 --- a/Lib/test/test_statistics.py +++ b/Lib/test/test_statistics.py @@ -2051,7 +2051,7 @@ class TestNormalDist(unittest.TestCase): nd = statistics.NormalDist(300, 23) with self.assertRaises(TypeError): vars(nd) - self.assertEqual(nd.__slots__, ('mu', 'sigma')) + self.assertEqual(tuple(nd.__slots__), ('mu', 'sigma')) def test_instantiation_and_attributes(self): nd = statistics.NormalDist(500, 17) diff --git a/Misc/NEWS.d/next/Library/2019-03-22-13-47-52.bpo-36326.WCnEI5.rst b/Misc/NEWS.d/next/Library/2019-03-22-13-47-52.bpo-36326.WCnEI5.rst new file mode 100644 index 00000000000..e458a7024da --- /dev/null +++ b/Misc/NEWS.d/next/Library/2019-03-22-13-47-52.bpo-36326.WCnEI5.rst @@ -0,0 +1,2 @@ +inspect.getdoc() can now find docstrings for member objects when __slots__ +is a dictionary.