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
wrote:
> 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-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/DC5JBXCFDE3B3FQ2MZVKCQG4ODWSXG32/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
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/SJEPCZOLSRZSVQENIKOVWVCJXTF4Z2WT/
Code of Conduct: http://python.org/psf/codeofconduct/
