+1 On Thu, Nov 18, 2021 at 09:31 Michael Foord <fuzzyman@gmail.com> wrote:
On Thu, 18 Nov 2021 at 04:38, Steven D'Aprano <steve@pearwood.info> wrote:
On Wed, Nov 17, 2021 at 02:26:16PM -0000, tmkehrenberg@gmail.com wrote:
@dataclass class A: """Docstring for class A.""" x: int """Docstring for x""" y: bool = True "Docstring for y"
It is a bit awkward that the docstring is *below* the definition of the attribute, but it can't be put above because it could be confused for the class docstring.
Function and class docstrings follow *below* the function/class signature, so I don't think that's a problem.
However a real problem is that bare strings like that are already legal, although only as a no-op. People sometimes use them as multiline comments.
So we would have no real way of distinguishing between these cases:
class A: """Docstring for class A.""" x: int """Docstring for x""" y: bool = True """Just a comment."""
Making such strings syntactically meaningful would be a breaking change, although one with a very small impact. (Some strings which were previously ignored by the interpreter will now be kept in memory as docstrings.)
It wouldn't be a breaking change, there's no compatibility issue as nothing could break from this. It's a new feature so you'd have an unexpected attribute docstring that you're not using.
Michael
My proposal would be to just enshrine this syntax as the syntax for attribute docstring, and to make them available at runtime. They would be stored in a dictionary like the type annotations. For example like this:
A.__attrdoc__ == {"x": "Docstring for x", "y": "Docstring for y"}
You could get that same effect with a decorator:
@attrdoc(x="Doctring for x", y="Doctring for y") class A: """Class docstring.""" x: int y: bool = True
There's some duplication of the names, which is sad, but otherwise I don't mind it.
-- Steve _______________________________________________ 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/2F7CZR... Code of Conduct: http://python.org/psf/codeofconduct/
--
Michael Foord
Python Consultant, Contractor and Trainer
https://agileabstractions.com/
_______________________________________________ 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/OGSJU4... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido (mobile)