On Jan 22, 2020, at 13:01, Christopher Barker <python...@gmail.com> wrote:
>
>
>> On Tue, Jan 21, 2020 at 12:55 PM <cont...@ehsankia.com> wrote:
>
>> Currently, there is no way to add docstrings to fields in dataclasses.
>> PEP257 talks about attribute docstrings (a string literal following an
>> assignment), but these are visual only and not accessible at runtime. My
>> suggestion would be a simple `doc` or `docstring` parameter to
>> dataclasses.field(). Currently the best way to get anything close to this is
>> using metadata, which is much clunkier:
>> `dataclasses.field(metadata={'docstring': 'my description'})`
>
> My first thought is "sure, why not", but then I thought a bit more, and I"m
> not so sure.
Instance attributes are exactly the same issue as module contents. You can’t
apply a docstring to the constants and variables in a module either. Why?
Because you can’t attach anything to a variable, because a variable isn’t a
thing in the language. You can only attach stuff to values. So a docstring
attached to "x = 42" would change the help for the number 42 (everywhere in the
program), not the variable x, and that would be silly.
The reason it makes sense for modules’ functions (and modules’ classes, and
classes’ methods and inner classes—and descriptors) is that there aren’t any
other instances of that function value anywhere else in the program, there’s
just that one. If anyone has that value, they have that actual function, and
they want that function’s docstring. This isn’t just acceptable, it’s
necessary. Consider a method object like spam.eggs; it has no idea that you got
the function value from a variable named eggs in the spam object’s type, it
just has a reference to that same function value in a variable named __func__
in the method object (which obviously nobody has attached a docstring to). But
because docstrings are on values rather than variables, self.__func__.__doc__
is the right docstring.
I think Ricky’s answer is promising. We already have code to generate help for
a module that includes all of its attributes. That doesn’t make sense for class
instances in general, but it does make sense for dataclass instances. And
extending it to also include some string for each one makes sense. I wouldn’t
be surprised if such things already existing for Django thingies and attrs
classes.
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/YJQD4CCFYCKYBMO3AIW57KYDOLSQJOJ4/
Code of Conduct: http://python.org/psf/codeofconduct/
