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 3855d3604e1cdbb4c824492ba714ccdedf04c961..6ab7991d8d4c65b9da270dec73871d39e72fae0e 100644 (file)
--- 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 b8a142232b88a0fb35d966dc9e58a2a501fabe98..8c398bd3534cb6a7fb949ad1c66d890a4bcd305c 100644 (file)
--- 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 e5a62463f0154e701266f2001b0e72e3f7da8b0b..bd8a6f96381a72e9d401445131903cb9728e4dcb 100644 (file)
--- 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 b9072e0137eb087f7b1718e931e2bbd14373ce1e..bc675aa5df21dd38c4c4f93eb2423637ed837deb 100644 (file)
--- 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 485ffe24036d13cc970560f3603ce6abcf39abda..7f7839de460039bbf150a473ba87ba811ac5170b 100644 (file)
--- 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 (file)
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.