[Python-Dev] Best way to specify docstrings for member objects (original) (raw)

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.0variance)) / 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.0variance)) / 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