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

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

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.



> 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.

Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-leave@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