docstring for dataclass fields
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'})`
On Tue, Jan 21, 2020 at 12:55 PM <contact@ehsankia.com> wrote:
My first thought is "sure, why not", but then I thought a bit more, and I"m not so sure. docstrings are VERY useful for class methods. but dataclass fields are not methods, they are attributes, and usually simple attributes. Which I do'nt hink there is any way to attach docstrings to in regular old classes. You can crate a property that looks like an attribute, an give it a docstring, but if you're going that far, maybe dataclasses aren't the right tool for the job. In fact, I'm not sure it's even possible: if a filed is a simple type, say and in integer, how would you give it a a docstring?? In [17]: i.__doc__ = "an integer's docstring" --------------------------------------------------------------------------- AttributeError Traceback (most recent call last) <ipython-input-17-94dacc7686e2> in <module> ----> 1 i.__doc__ = "an integer's docstring" AttributeError: 'int' object attribute '__doc__' is read-only -CHB -- Christopher Barker, PhD Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython
The doctrings for fields are usually inside the class object docstring (formatting of which depending on the docstring style). As CHB said, there isn't a way to add them to objects. Maybe there's a way to make this happen, though? Like: @dataclass @build_docstring(format="sphinx") class LameClass: "I'm a really awesome class, just ask me" x: int, "Xes are xes" foo: Optional[str], "Ys are ys" Then (sphinx-formatted docstring):
- Rick --- Ricky. "I've never met a Kentucky man who wasn't either thinking about going home or actually going home." - Happy Chandler On Wed, Jan 22, 2020 at 4:03 PM Christopher Barker <pythonchb@gmail.com> wrote:
The fact that i.__doc__ doesn't work is actually a strong argument. You would have to do dataclasses.fields(my_obj)[0].__doc__, which is already complex enough. At that point using metadata probably makes more sense. Thank you for your response.
On Jan 22, 2020, at 13:01, Christopher Barker <pythonchb@gmail.com> wrote:
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.
On Wed, Jan 22, 2020, 7:21 PM Andrew Barnert via Python-ideas < python-ideas@python.org> wrote:
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.
On Tue, Jan 21, 2020 at 12:55 PM <contact@ehsankia.com> wrote:
My first thought is "sure, why not", but then I thought a bit more, and I"m not so sure. docstrings are VERY useful for class methods. but dataclass fields are not methods, they are attributes, and usually simple attributes. Which I do'nt hink there is any way to attach docstrings to in regular old classes. You can crate a property that looks like an attribute, an give it a docstring, but if you're going that far, maybe dataclasses aren't the right tool for the job. In fact, I'm not sure it's even possible: if a filed is a simple type, say and in integer, how would you give it a a docstring?? In [17]: i.__doc__ = "an integer's docstring" --------------------------------------------------------------------------- AttributeError Traceback (most recent call last) <ipython-input-17-94dacc7686e2> in <module> ----> 1 i.__doc__ = "an integer's docstring" AttributeError: 'int' object attribute '__doc__' is read-only -CHB -- Christopher Barker, PhD Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython
The doctrings for fields are usually inside the class object docstring (formatting of which depending on the docstring style). As CHB said, there isn't a way to add them to objects. Maybe there's a way to make this happen, though? Like: @dataclass @build_docstring(format="sphinx") class LameClass: "I'm a really awesome class, just ask me" x: int, "Xes are xes" foo: Optional[str], "Ys are ys" Then (sphinx-formatted docstring):
- Rick --- Ricky. "I've never met a Kentucky man who wasn't either thinking about going home or actually going home." - Happy Chandler On Wed, Jan 22, 2020 at 4:03 PM Christopher Barker <pythonchb@gmail.com> wrote:
The fact that i.__doc__ doesn't work is actually a strong argument. You would have to do dataclasses.fields(my_obj)[0].__doc__, which is already complex enough. At that point using metadata probably makes more sense. Thank you for your response.
On Jan 22, 2020, at 13:01, Christopher Barker <pythonchb@gmail.com> wrote:
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.
On Wed, Jan 22, 2020, 7:21 PM Andrew Barnert via Python-ideas < python-ideas@python.org> wrote:
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.
participants (4)
-
Andrew Barnert -
Christopher Barker -
contact＠ehsankia.com -
Ricky Teachey