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

[Gregory P. Smith]

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