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

Gregory P. Smith greg at krypto.org
Wed Mar 20 18:30:14 EDT 2019

(answers above and below the quoting)

I like the idea of documenting attributes, but we shouldn't force the user to use slots as that has significant side effects and is rarely something people should bother to use. There are multiple types of attributes. class and instance. but regardless of where they are initialized, they all define the API shape of a class (or instance).

Q: Where at runtime regardless of syntax chosen would such docstrings live? One (of many) common conventions today is to just put them into an Attributes: or similar section of the class docstring. We could actually do that automatically by appending a section to the class docstring, but that unstructures the data enshrining one format and could break existing code for the users of the few but existing APIs that treat docstrings as structured runtime data instead of documentation if someone were to try and use attribute docstrings on subclasses of those library types. (ply does this, I believe some database abstraction APIs do as well).

On Wed, Mar 20, 2019 at 12:41 AM Serhiy Storchaka <storchaka at gmail.com> wrote:

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'''

I don't think adding a 'slot' keyword even if limited in scope to class body definition level is a good idea (very painful anytime we reserve a new word that is already used in code and APIs).

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''' Something along these lines is more interesting to me. And could be applied to variables in any scope. though there wouldn't be a point in using a string in context where the name isn't bound to a class or module.

The best practice today remains "just use the class docstring to document your public class and instance attributes". FWIW other languages tend to generate their documentation from code via comments rather than requiring a special in language runtime accessible syntax to declare it as documentation.

It feels like Python is diverging from the norm if we were encourage more of this doc carried around at runtime implicit assignment than we already have. I'm not convinced that is a good thing.

-gps -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20190320/dfce7afd/attachment.html>

More information about the Python-Dev mailing list