[Python-Dev] Best way to specify docstrings for member objects

[Ivan Pozdeev]

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