On Thu, 18 Nov 2021 at 04:38, Steven D'Aprano <st...@pearwood.info> wrote:
> On Wed, Nov 17, 2021 at 02:26:16PM -0000, tmkehrenb...@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-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/2F7CZRNSEEWRIBUFTTR3CBTLWO6APKJW/ > 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-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/OGSJU4YK6WX6FNK3C5BWCOPYCZMHRJ4P/ Code of Conduct: http://python.org/psf/codeofconduct/