[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: Laurie: thanks for linking that, it seems like there isn't that much enthusiasm. -- ___ Python tracker ___

[issue42414] unable to document fields of dataclass

Laurie Opperman added the comment: No new mailing list thread, but there is one from January 2020: https://mail.python.org/archives/list/python-id...@python.org/thread/RHB6XFGFVM66AZTRKNTBAKFEVVEYUDD3/ -- nosy: +Epic_Wink ___ Python tracker

[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: I was thinking about adding this to named tuple as well, but it's less useful than with dataclasses because named tuples are simpler and smaller. However if this feature is added to dataclasses and is widely used, it would make a lot of sense to expand it

[issue42414] unable to document fields of dataclass

Eric V. Smith added the comment: The more I think about this, the less I like it as a dataclasses-specific solution (if it’s accepted at all, that is). Why dataclasses and not attrs or NamedTuple? I suggest bringing it up on python-ideas for wider exposure. --

[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: I haven't modified `_finddoc` in my PR because it currently doesn't show all existing dataclass fields (only those with default set) -- therefore it would make sense to consider this addition if / when complete set of dataclass fields is added to _finddoc.

[issue42414] unable to document fields of dataclass

Change by Denis Laxalde : -- nosy: +dlax ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: I've added a new PR: https://github.com/python/cpython/pull/27279 (note it's a rough PoC draft at this point) The output of inspect.getdoc() is the same: A(total: int, num: int = 5) total: int -- number of widgets num: int [5] -- total widgets

[issue42414] unable to document fields of dataclass

Change by Andrei Kulakov : -- pull_requests: +25824 pull_request: https://github.com/python/cpython/pull/27279 ___ Python tracker ___

[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: Eric: makes sense, I'll go with that. John-Mark: I will go ahead and work on a PR along the lines Terry suggested, let us know if you have any objections or if you would prefer to work on a PR by yourself instead. P.S. I understand now what you meant by 1

[issue42414] unable to document fields of dataclass

Eric V. Smith added the comment: I think we'd be better off adding a doc parameter to dataclasses.field, and then as @terry.reedy says, modify inspect.getdoc and maybe_finddoc to look in __dataclass_fields__, if it exists. -- versions: +Python 3.11 -Python 3.10

[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: John-Mark: yep, it's just a draft patch for now. It doesn't need to be two lines; it can be updated to start with an empty dict and perhaps use a shorter special name for the doc dict and then you can do: f1:int = 1 FDOC['f1'] = 'foo' f2:str = 'a'

[issue42414] unable to document fields of dataclass

John-Mark Gurney added the comment: So, just looked at the patch, but it's missing the documentation part of it. Also, yes, you can add the doc as another line, but now that's two lines (yes, you can add semicolons to make it one line, but that might surprise some people). I do request

[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: John-Mark: each fields doc can be added to the dictionary separately though.. -- ___ Python tracker ___

[issue42414] unable to document fields of dataclass

John-Mark Gurney added the comment: Though this suggestion does work, I am not a fan of this solution. The issue is that it separates the doc from the definition. This works well if you have only a field fields in the class, But if you get 10-20+ fields, it moves away the docs and makes it

[issue42414] unable to document fields of dataclass

Andrei Kulakov added the comment: I've put up a simple PoC PR adding a __field_doc__ optional dict attr to dataclass, which would add the docs to class docstring: @dataclass class A: __field_doc__ = dict(num='number of widgets', total='total widgets') total: int num: int = 5

[issue42414] unable to document fields of dataclass

Change by Andrei Kulakov : -- keywords: +patch nosy: +andrei.avk nosy_count: 4.0 -> 5.0 pull_requests: +25809 stage: test needed -> patch review pull_request: https://github.com/python/cpython/pull/27265 ___ Python tracker

[issue42414] unable to document fields of dataclass

Terry J. Reedy added the comment: Documenting dataclass fields strikes me as a reasonable request. Since most most field values cannot have a .__doc__ attribute... > It could be stored in the dataclass-specific data attached to a class, The obvious place. > but then you'd have to use a

[issue42414] unable to document fields of dataclass

Raymond Hettinger added the comment: > There is not a way to document fields of a dataclass. I don't think there is an easy way to do this without a custom descriptor and that would add a lot of overhead. -- nosy: +rhettinger ___ Python tracker

[issue42414] unable to document fields of dataclass

Eric V. Smith added the comment: @property has a place to attach the docstring, dataclasses in general do not. I wouldn't want to add a descriptor just to have the ability to add a docstring. There are performance issues involved, and I'm sure some corner cases where functionality would

[issue42414] unable to document fields of dataclass

John-Mark Gurney added the comment: As I said, I expect it to work similar to how property works: ``` >>> class Foo: ... def getx(self): ... return 5 ... x = property(getx, doc='document the x property') ... >>> help(Foo) Help on class Foo in module __main__: class Foo(builtins.object)

[issue42414] unable to document fields of dataclass

Eric V. Smith added the comment: How would you expect to extract this docstring? I'm not sure how this would work in practice, since both of these are errors: >>> class A: ...def __init__(self): ...self.x = 3 ...self.x.__doc__ = 'foo' ... >>> A() Traceback (most recent

[issue42414] unable to document fields of dataclass

Change by Eric V. Smith : -- assignee: -> eric.smith ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue42414] unable to document fields of dataclass

Change by Karthikeyan Singaravelan : -- nosy: +eric.smith ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue42414] unable to document fields of dataclass

New submission from John-Mark Gurney : per: https://bugs.python.org/issue38401 There is not a way to document fields of a dataclass. I propose that instead of making a language change, that an additional parameter to the field be added in similar vein to property. This currently works: ```