This might be a weird idea but I think it looks nice, is backward compatible, and flexible. It could be a convention to have the type hint syntax location (ie, the syntax location after the colon that usually contains type hints only today) do double duty. It could be used for documentation as long as it is provided FIRST. Then, optionally provide the type hint information on a later line: @dataclass class A: """Docstring for class A.""" x: "Docstring for x" x: int y: "Docstring for y" y: bool = True In this way one could provide the docstrings in all together in a separate section of code, as long as the docstrings came before the final type hint and any default values: @dataclass class A: """Docstring for class A.""" x: "Docstring for x" y: "Docstring for y" x: int y: bool = True People that have no interest in type hinting their code and don't intend for it to run through a type checker can use the same convention without any issues: class A: """Docstring for class A.""" x: "Docstring for x" y: "Docstring for y" If desired and if it became a popular idea, language support could later be provided to make use of these docstrings- saving them in a useful place- and bring them into help() output in a proper looking way. I am unsure if this would be backwards compatible with mypy. __________ WARNING: half baked idea ahead! ahoy there be dragons here probably, etc etc ___________ Expanding on that idea: if language support for making use of this documentation convention is indeed later wanted but it were deemed too problematic, and potentially backwards incompatible, to differentiate docstrings from regular typing information, there could be a docstring literal d"", similar to f string literal: @dataclass class A: """Docstring for class A.""" x: d"Docstring for x" y: d"Docstring for y" x: int y: bool = True To be clear there is nothing magical about the d"" string itself. It's just a regular string. The d"" moniker merely causes the string contents to be stored away for safe keeping in a class or module dunder, storing all the info for the created docstrings in a dictionary:
print(A.__member_docstrings__) {'x': 'Docstring for x', 'y': 'Docstring for y'}
Using only convention, you could do all sorts of fancy shenanigans with these docstrings. You could provide format fields in the docstring.... such as using a convention for identifying the variable name on the LHS inside the docstring, or its type hint (type hint maybe defaulting to Any if there isn't a type hint?): class A: """Docstring for class A.""" x: d"{var} is of type {hint}" y: d"{var} is of type {hint}" Documentation tools line help() could know about __member_docstrings__ and these conventions, properly parse them using the format() method:
help(A.x) x is of type Any
In this way the help function or other documentation tools wouldn't require type hint information, and a type hint could even be defined/changed later (such as in a child class). class B(A): """Docstring for class B.""" x: int
help(A.x) x is of type int
I'm unsure how the help() function, or other similar documentation tools,
could know where to look (ie, in the parent class) for the docstring
information. Seems like this could be solved in some way, though.
On Fri, Nov 19, 2021, 6:23 PM Angelo Kontaxis
I feel like we could possible use the slots being a dict here, this is already a supported feature and is able to document attributes indivually, and dataclasses does have a slots argument now in 3.10
class Foo: """docstring for Foo""" __slots__ = {"bar": "docstring for bar"} def __init__(self, bar): self.bar = bar _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@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/DC5JBX... Code of Conduct: http://python.org/psf/codeofconduct/