bpo-36326: Let inspect.getdoc() find docstrings for __slots__ (GH-12498)

This commit is contained in:
Raymond Hettinger 2019-03-25 13:01:13 -07:00 committed by GitHub
parent 713a8ae792
commit d1e768a677
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 32 additions and 3 deletions

View File

@ -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
--

View File

@ -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__

View File

@ -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.'

View File

@ -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")

View File

@ -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)

View File

@ -0,0 +1,2 @@
inspect.getdoc() can now find docstrings for member objects when __slots__
is a dictionary.