bpo-36326: Let inspect.getdoc() find docstrings for __slots__ (GH-12498)
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 3855d36..6ab7991 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -174,6 +174,20 @@
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 b8a1422..8c398bd 100644
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -582,9 +582,12 @@
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 e5a6246..bd8a6f9 100644
--- a/Lib/statistics.py
+++ b/Lib/statistics.py
@@ -709,7 +709,8 @@
# 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 b9072e0..bc675aa 100644
--- a/Lib/test/test_inspect.py
+++ b/Lib/test/test_inspect.py
@@ -375,6 +375,11 @@
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 @@
'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 485ffe2..7f7839d 100644
--- a/Lib/test/test_statistics.py
+++ b/Lib/test/test_statistics.py
@@ -2051,7 +2051,7 @@
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 0000000..e458a70
--- /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.