On Sun, Dec 12, 2021, 1:57 AM Steven D'Aprano <st...@pearwood.info> wrote:
On Sun, Dec 12, 2021 at 12:38:06AM -0500, Ricky Teachey wrote: > But Steve, since the most utilized documentation tool in the python > universe, sphinx, doesn't look at Annotated Yet. > or in the lowercase-annotation part of an expression Yet. > for this and instead looks at a bare string below the > member definition, and since I presume it had been doing this for a long > time (before Annotated was added not long ago, and probably before the > annotation too?), doesn't this mean that right now there are at least three > competing ways being used to provide attribute docstrings? And before we had PEP 484 there were multiple competing and incompatible conventions for putting type hints in docstrings. https://www.python.org/dev/peps/pep-0484/ There are: - Epytext (Javadoc style) - ReST (Sphinx) - Googledoc - Numpydoc although some of them may no longer be widely used. https://stackoverflow.com/questions/3898572/what-are-the-most-common-python-docstring-formats https://www.adrian.idv.hk/2018-02-18-docstring/ Static and runtime tools that wanted to get type hints had to guess the format and parse the docstring to get the types. Who still does that? If dataclasses, and other classes, move to using Annotated and __attrdoc__ for docstrings, the tools will follow. Runtime tools will look at the dunder, static tools will look at the annotation directly. **Which they will have to do anyway** if we add the convention that string literals following an assignment get recorded in __attrdoc__. Runtime tools will want to look in the dunder, not parse the source code. And static tools which aren't Sphinx will need to be adjusted to look at the string literals. So either way the tooling has to change. Sphinx is not the decider here. I dare say that they will want to continue supporting bare strings into the indefinite future, but new tools, and those with weaker backwards-compatibility constaints, will surely prefer to extract docstrings from __attrdoc__ than parsing the source code. > As far as using the lowercase-annotation for the docstring: in a world of > more and more type hinted python (to be clear: I don't always use type > hints but I do like this world), if you want to make you don't create a > problem later, using the annotation slot for your docstring: > > x: "spam" > > ... isn't really an option. Of course it is. Just decorate your class with @no_type_hints. > - without an official blessed agreement that the existing Annotated feature > ought to be used for docstrings, there is little reason for other 3rd party > help/documentation tools to look in that location for these docstrings All it takes is literally one stdlib class to start doing it officially, and people will pay attention. > I just think there's more to do here than add a decorator. That depends on whether you mean, what do *we* need to do get the ball rolling, or what does the entire Python ecosystem need to do to transition to the day that every tool and library is actively using attribute docstrings both statically and at runtime? Of course the second part is a bigger job. But for the first, we can either (1): * bikeshed this for another six ~~months~~ weeks; * get at least one core dev to agree to sponsor a PEP; * write a PEP; * bikeshed some more; * wait for the Steering Council to hopefully accept the PEP; * modify the interpreter; * wait for the new version to be available; or we can (2) * implement and support the feature today; to get to the point that external tools can start using it. I'm not kidding, if somebody cared enough to do this, they could probably have a patch for dataclasses to support this within a couple of hours and a plugin for Sphinx within a day. (Spoken with the supreme confidence of somebody who knows that he will absolutely not have to do either.) As far as I am concerned, this is exactly the sort of use-case that Annotated was invented for. Docstrings are metadata. Annotated is for attaching metadata to an annotation that is associated with some variable. Done and done. -- Steve I agree. I think adding something like __attrdoc__ is a very good idea. Would like to see it in all classes, personally, and then have help() look there. But starting with dataclasses seems like a logical place and might get us started on that goal. And if we start this with dataclasses and it gets expanded, none of this would slam the door on the idea of using a bare string after the definition as sugar for populating __attr_doc__. In fact if there's any hope that would ever happen, first people would need to find themselves using Annotated far more often, and get tired of having to use the longish syntax with an import and agree on such a syntax change.
_______________________________________________ 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/7OPOFROHCPW5TP552ZFSYZ6G6YT67CAQ/ Code of Conduct: http://python.org/psf/codeofconduct/
