From d1e768a67707bf7bb426c1537e1a764e89eaff78 Mon Sep 17 00:00:00 2001
From: Raymond Hettinger <rhettinger@users.noreply.github.com>
Date: Mon, 25 Mar 2019 13:01:13 -0700
Subject: bpo-36326: Let inspect.getdoc() find docstrings for __slots__
 (GH-12498)

---
 Doc/whatsnew/3.8.rst                                       | 14 ++++++++++++++
 Lib/inspect.py                                             |  5 ++++-
 Lib/statistics.py                                          |  3 ++-
 Lib/test/test_inspect.py                                   |  9 +++++++++
 Lib/test/test_statistics.py                                |  2 +-
 .../next/Library/2019-03-22-13-47-52.bpo-36326.WCnEI5.rst  |  2 ++
 6 files changed, 32 insertions(+), 3 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2019-03-22-13-47-52.bpo-36326.WCnEI5.rst

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 @@ 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 b8a1422..8c398bd 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 e5a6246..bd8a6f9 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 b9072e0..bc675aa 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 485ffe2..7f7839d 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 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.
-- 
cgit v0.12