On 2019-03-19 18: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?

[snip] Thinking ahead, could there ever be anything else that you might want also to attach to member objects? I suppose that if that's ever the case, the value could itself be expanded to be a dict, something like this: __slots__ = {'mu' : {'__doc__': 'Arithmetic mean.'}, 'sigma': {'__doc__': 'Standard deviation.'}} But that could be left to the future...

19.03.19 20:55, Raymond Hettinger пише:

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.

I think it would be nice to separate docstrings from the bytecode. This would be allow to have several translated sets of docstrings and load an appropriate set depending on user preferences. This would help in teaching Python. It is possible with docstrings of modules, classes, functions, methods and properties (created by using the decorator), because the compiler knows what string literal is a docstring. But this is impossible with namedtuple fields and any of the above ideas for slots. It would be nice to allow to specify docstrings for slots as for methods and properties. Something like in the following pseudocode: class NormalDist: slot mu: '''Arithmetic mean''' slot sigma: '''Standard deviation''' It would be also nice to annotate slots and add default values (used when the slot value was not set). class NormalDist: mu: float = 0.0 '''Arithmetic mean''' sigma: float = 1.0 '''Standard deviation'''

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