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/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-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/OGSJU4YK6WX6FNK3C5BWCOPYCZMHRJ4P/
Code of Conduct: http://python.org/psf/codeofconduct/