[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

- Prev by Date:
**[Python-Dev] Best way to specify docstrings for member objects** - Next by Date:
**[Python-Dev] Remove tempfile.mktemp()** - Previous by thread:
**[Python-Dev] Best way to specify docstrings for member objects** - Next by thread:
**[Python-Dev] Best way to specify docstrings for member objects** - Index(es):