On Thu, Nov 18, 2021 at 7:44 PM Stephen J. Turnbull wrote:

Steven D'Aprano writes:

...

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"

...

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.

I agree it's a real problem. But I don't think it's a show-stopper. That is, the proposal as written also seems to be a near no-op from the point of view of backwards compatibility (I guess if you list the attributes of the class you would discover the new dunder).

...

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

True, but why would one want to, except to save the space? And for that, there's -OO.

Possible wrinkle: What if a string literal immediately follows something that isn't an attribute declaration? class A: "Class docstring" x: int "x docstring" y: bool; True "y docstring?" print("Hello, world?") "print docstring??" def spam(self): ... "spam docstring???" I presume it would have to be permitted and ignored, as per current behaviour (otherwise it'd create bizarre errors in currently-legal code). But that may make for some hard-to-track-down bugs when there's an error in a declaration, or when something technically breaks the declaration from the docstring (like the presumably-unintended semicolon in the y line). I'm personally -0 on this - I don't declare class level type annotations enough to want to use this, but if it existed, I'd probably find a way to use it for a DSL or something. It's of minimal value, but it should also be of minimal disruption. ChrisA

Could this be a use case for typing.Annotated? In [6]: from dataclasses import dataclass In [7]: from typing import Annotated In [8]: class A: ...: """Docstring for class A.""" ...: x: Annotated[int, "Docstring for x"] ...: y: Annotated[bool, "Docstring for y"] = True In [9]: A.__annotations__ Out[9]: {'x': typing.Annotated[int, 'Docstring for x'], 'y': typing.Annotated[bool, 'Docstring for y']} The syntax is a bit arduous; I'd be in favor of thinking through ways to make it easier to write. But the basic functionality already exists; there's no reason to duplicate it with another language feature. Rick. --- Ricky. "I've never met a Kentucky man who wasn't either thinking about going home or actually going home." - Happy Chandler On Thu, Nov 18, 2021 at 5:50 AM wrote:

Stephen J. Turnbull wrote:

...

@standard_class_docstring_parser class A: """ Class docstring. x: Docstring for x y: Docstring for y """ x: int y: bool = True

Oh, this is actually a nice idea. You could have a decorator that parses reST and then according to some conventions extracts the attribute docstrings. I think I will try to write something like that.

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

I've seen this proposed before, but it is, as you said, a bit arduous. For dataclasses specifically, there is also another possibility: add a `doc` argument to dataclasses.field. Like this: from dataclasses import dataclass, field @dataclass class A: x: int = field(doc="Docstring for x.") y: bool = field(default=False, doc="Docstring for y.") And then it would be retrievable with dataclasses.fields(A). Thomas

On Thu, Nov 18, 2021 at 1:39 PM Thomas Grainger wrote:

Ricky Teachey wrote:

...

Could this be a use case for typing.Annotated? In [6]: from dataclasses import dataclass In [7]: from typing import Annotated In [8]: class A: ...: """Docstring for class A.""" ...: x: Annotated[int, "Docstring for x"] ...: y: Annotated[bool, "Docstring for y"] = True In [9]: A.__annotations__ Out[9]: {'x': typing.Annotated[int, 'Docstring for x'], 'y': typing.Annotated[bool, 'Docstring for y']} The syntax is a bit arduous; I'd be in favor of thinking through ways to make it easier to write. But the basic functionality already exists; there's no reason to duplicate it with another language feature. Rick. --- Ricky. "I've never met a Kentucky man who wasn't either thinking about going home or actually going home." - Happy Chandler On Thu, Nov 18, 2021 at 5:50 AM tmkehrenberg@gmail.com wrote:

...

Stephen J. Turnbull wrote: @standard_class_docstring_parser class A: """ Class docstring. x: Docstring for x y: Docstring for y """ x: int y: bool = True Oh, this is actually a nice idea. You could have a decorator that parses reST and then according to some conventions extracts the attribute docstrings. I think I will try to write something like that. Thomas _______________________________________________ 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/F2QJ3Q. ..

...

Code of Conduct: http://python.org/psf/codeofconduct/

I think you need to use another type rather than a plain string here eg:

``` @dataclasses.dataclass(frozen=True) class Doc: v: str

@dataclasses.dataclass class A: """docstring for class A.""" x: typing.Annotated[int, Doc("docstring for x")] ```

I don't know why you would? It seems to work just fine with a plain string? One thing that is bad about it: the class member "docstrings" (actually the annotations) are repeated all over the place (look like 4 times total?) in the help() output-- example is below:

...

...

help(A) Help on class A in module __main__:

class A(builtins.object) | A(x: *typing.Annotated[int, 'docstring for x']*) -> None | | docstring for class A. | | Methods defined here: | | __eq__(self, other) | | __init__(self, x: *typing.Annotated[int, 'docstring for x']*) -> None | | __repr__(self) | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined) | | ---------------------------------------------------------------------- | Data and other attributes defined here: | | __annotations__ = {'x': *typing.Annotated[int, 'docstring for x']*} | | __dataclass_fields__ = {'x': Field(name='x',type= *typing.Annotated[int,..*. | | __dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,or... | | __hash__ = None --- Ricky. "I've never met a Kentucky man who wasn't either thinking about going home or actually going home." - Happy Chandler

On Thu, 18 Nov 2021 at 04:38, Steven D'Aprano 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/

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