[Python-Dev] Best way to specify docstrings for member objects
Ivan Pozdeev
vano at mail.mipt.ru
Wed Mar 20 18:47:27 EDT 2019
On 19.03.2019 21:55, Raymond Hettinger wrote:
> I'm working on ways to make improve help() by giving docstrings to member objects.
>
> One way to do it is to wait until after the class definition and then make individual, direct assignments to __doc__ attributes.This way widely the separates docstrings from their initial __slots__ definition. Working downstream from the class definition feels awkward and doesn't look pretty.
>
> There's another way I would like to propose¹. The __slots__ definition already works with any iterable including a dictionary (the dict values are ignored), so we could use the values for the docstrings.
>
> This keeps all the relevant information in one place (much like we already do with property() objects). This way already works, we just need a few lines in pydoc to check to see if a dict if present. This way also looks pretty and doesn't feel awkward.
>
> I've included worked out examples below. What do you all think about the proposal?
>
>
> Raymond
>
>
> ¹ https://bugs.python.org/issue36326
>
>
> ====== Desired help() output ======
>
>>>> help(NormalDist)
> Help on class NormalDist in module __main__:
>
> class NormalDist(builtins.object)
> | NormalDist(mu=0.0, sigma=1.0)
> |
> | Normal distribution of a random variable
> |
> | Methods defined here:
> |
> | __init__(self, mu=0.0, sigma=1.0)
> | NormalDist where mu is the mean and sigma is the standard deviation.
> |
> | cdf(self, x)
> | Cumulative distribution function. P(X <= x)
> |
> | pdf(self, x)
> | Probability density function. P(x <= X < x+dx) / dx
> |
> | ----------------------------------------------------------------------
> | Data descriptors defined here:
> |
> | mu
> | Arithmetic mean.
> |
> | sigma
> | Standard deviation.
> |
> | variance
> | Square of the standard deviation.
>
>
>
> ====== Example of assigning docstrings after the class definition ======
>
> class NormalDist:
> 'Normal distribution of a random variable'
>
> __slots__ = ('mu', 'sigma')
>
> def __init__(self, mu=0.0, sigma=1.0):
> 'NormalDist where mu is the mean and sigma is the standard deviation.'
> self.mu = mu
> self.sigma = sigma
>
> @property
> def variance(self):
> 'Square of the standard deviation.'
> return self.sigma ** 2.
>
> def pdf(self, x):
> 'Probability density function. P(x <= X < x+dx) / dx'
> variance = self.variance
> return exp((x - self.mu)**2.0 / (-2.0*variance)) / sqrt(tau * variance)
>
> def cdf(self, x):
> 'Cumulative distribution function. P(X <= x)'
> return 0.5 * (1.0 + erf((x - self.mu) / (self.sigma * sqrt(2.0))))
>
> NormalDist.mu.__doc__ = 'Arithmetic mean'
> NormalDist.sigma.__doc__ = 'Standard deviation'
IMO this is another manifestation of the problem that things in the class definition have no access to the class object.
Logically speaking, a definition item should be able to see everything that is defined before it.
For the same reason, we have to jump through hoops to use a class name in a class attribute definition -- see e.g.
https://stackoverflow.com/questions/14513019/python-get-class-name
If that problem is resolved, you would be able to write something like:
class NormalDist:
'Normal distribution of a random variable'
__slots__ = ('mu', 'sigma')
__self__.mu.__doc__= 'Arithmetic mean'
__self__.sigma.__doc__= 'Stndard deviation'
>
>
> ====== Example of assigning docstrings with a dict =====
>
> class NormalDist:
> 'Normal distribution of a random variable'
>
> __slots__ = {'mu' : 'Arithmetic mean.', 'sigma': 'Standard deviation.'}
>
> def __init__(self, mu=0.0, sigma=1.0):
> 'NormalDist where mu is the mean and sigma is the standard deviation.'
> self.mu = mu
> self.sigma = sigma
>
> @property
> def variance(self):
> 'Square of the standard deviation.'
> return self.sigma ** 2.
>
> def pdf(self, x):
> 'Probability density function. P(x <= X < x+dx) / dx'
> variance = self.variance
> return exp((x - self.mu)**2.0 / (-2.0*variance)) / sqrt(tau * variance)
>
> def cdf(self, x):
> 'Cumulative distribution function. P(X <= x)'
> return 0.5 * (1.0 + erf((x - self.mu) / (self.sigma * sqrt(2.0))))
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: https://mail.python.org/mailman/options/python-dev/vano%40mail.mipt.ru
--
Regards,
Ivan
More information about the Python-Dev
mailing list