On Sun, Dec 12, 2021 at 12:23:54PM -0800, Christopher Barker wrote: > > the tools will follow. Runtime tools will > > look at the dunder, static tools will look at the annotation directly. > > > > I hope not. *maybe* inspect.get_annotations() though.
Sorry, I don't understand your position here. Putting aside *how* we write attribute docstrings, isn't the point of them that they are available to runtime inspection? Say, by help(). So why do you hope that runtime tools don't inspect the dunder storing the attribute docstrings? And that static tools *don't* look at the annotation? (Or whatever mechanism we use.) They can't use the dunder because it doesn't exist yet, you haven't run the code. So I'm confused... we go to the trouble of deciding on a mechanism to write attribute docstrings, we write them in the code, and you hope that nobody uses them??? Have I misunderstood? > > > x: "spam" > > > > > > ... isn't really an option. > > > > Of course it is. Just decorate your class with @no_type_hints. > > > > and then your class attribute isn't type hinted. Of course you can do it, > but it can't be the standard way to add documentation to class attributes > — see above. Okay, I'm sorry, I understand the statement to be referring to people who had no intention of using type-hints. For those people, no_type_hints is the right solution. But for those who want type hints as well as docstrings, it is not. Sorry for the confusion. > > All it takes is literally one stdlib class to start doing it officially, > > and people will pay attention. > > > > Sure -- but where do the docstrings extracted from a typing.Annoated object > go? > > __attrdoc__ has been suggested -- but THAT requires some level of approval > from the SC. I don't think that needs a PEP or SC approval, I think that's a small enough change that any core developer who cares can just add that dunder to their class and start collecting docstrings in there. But at some point somebody will need to ask on the Python-Dev list and see if anyone objects and says yes, you need a PEP. > > As far as I am concerned, this is exactly the sort of use-case that > > Annotated was invented for. > > > and yet the docs for typing.Annotated don't seem to say that. So what > concerns me is that this may break other uses of Annotated, which are > expecting types to be stored there. Have you read the PEP? Particularly this section: https://www.python.org/dev/peps/pep-0593/#consuming-annotations Quote: Ultimately, the responsibility of how to interpret the annotations (if at all) is the responsibility of the tool or library encountering the Annotated type. A tool or library encountering an Annotated type can scan through the annotations to determine if they are of interest (e.g., using isinstance()). Unknown annotations: When a tool or a library does not support annotations or encounters an unknown annotation it should just ignore it and treat annotated type as the underlying type. Similarly in the docs: https://docs.python.org/3/library/typing.html#typing.Annotated Until such time that the Steering Council announce that type-hints are no longer merely the preferred use for annotations, but the *only* use for annotations, and any other usage is banned, using annotations to capture variable docstrings is perfectly legitimate. The current SC has made it quite clear that they are happy with the status quo, that typing is the primary but not only use for annotations. Using docstrings in annotations would seem to be a good way to establish a strong non-typing use-case. > One problem with a docstrings is that > they are "just a string". isinstance checks, as mentioned in the docs, > are not so helpful. So we'd be establishing a new standard: “a bare string > in an Annotated type is a docstring” -- adding a typing,Documented wouldn't > be a much bigger lift ( I wonder if making it a subclass of Annotated would > help). No, we can't be that gung-ho to say that bare strings have to be docstrings. Since typing is the primary use-case for annotations, including the metadata in Annotated, it would have to be opt-in. Any type-hint can be a string: either due to PEP 563, due to forward references, or just because the developer on a whim choses to stringify their type-hints. Opting-in would mean documenting your class' requirements and assumptions about the format of annotations, and then using something like a decorator or metaclass to extract the docstrings. > And I note that Annotated flattens nested Annotated types, so having both a > docstring and other use of Annotated could be a bit tricky. class MyClass: """Blah blah blah. Variable annotations of the form Annotated[T, 'string', *args] always interpret the string in the second position as a docstring. If you want to use Annotated but without a docstring, put None in the second position. """ spam: Annotated[int, 'Yummy meat-like product'] eggs: Annotated[float, 'Goes well with spam', Domain[0, 1]] cheese: Sequence[str] # No docstring. The metadata is *always* interpreted by the tool, this is no different. > I'm not a type hints user -- but I think this should be run by the MyPy and > other folks Naturally. I could be wrong. In theory. *wink* > As for using dataclasses as a way to introduce a convention: that could be > a good route — but I doubt Eric would go for it[*] and in any case, it > would in fact be introducing a new convention, so getting some consensus on > what that convention should be would be helpful. I only mention dataclasses because that seemed to be the primary use-case mentioned from the start of this thread. I don't speak for Eric, and I haven't verified for myself that dataclasses would benefit from attribute docstrings. -- 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/TBOER3HFSUHCOWHNDYUQ22WFBFXUD5CR/ Code of Conduct: http://python.org/psf/codeofconduct/
