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@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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
