bpo-36326: Let inspect.getdoc() find docstrings for __slots__ (GH-12498)
This commit is contained in:
parent
713a8ae792
commit
d1e768a677
|
@ -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
|
||||
--
|
||||
|
|
|
@ -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__
|
||||
|
|
|
@ -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.'
|
||||
|
|
|
@ -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")
|
||||
|
|
|
@ -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)
|
||||
|
|
|
@ -0,0 +1,2 @@
|
|||
inspect.getdoc() can now find docstrings for member objects when __slots__
|
||||
is a dictionary.
|
Loading…
Reference in New Issue