On Wed, Jan 22, 2020, 7:21 PM Andrew Barnert via Python-ideas <
python-ideas@python.org> wrote:
> 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.
>
That's kind, given that the code I wrote is a syntax error. 0_o
Would have to be more like this, which is a lot less nice looking:
@dataclass
@build_docstring(style="sphinx")
class C:
"""Doc"""
x: (int, "x doc")
y: (Optional [str], "y doc") = "foo"
This is.... pretty freaking ugly.
_______________________________________________
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/IBMPGOKFTGUMRBXH6J3IY5NVS5SIYHAY/
Code of Conduct: http://python.org/psf/codeofconduct/
