On Sat, Dec 11, 2021 at 10:55 PM Steven D'Aprano <st...@pearwood.info> wrote:
> If dataclasses, and other classes, move to using Annotated and > __attrdoc__ for docstrings, OK -- THAT is the point I brought up earlier, and you responded with "this is settled" -- it's the __attrdoc__ part that needs to be standardized. As for Typing.Annotated: it has one advantage in that typing tools currently (presumably) already accommodate extracting the type information from it -- see what typing.get_type_hints() does. > > 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. > **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. > but they do that anyway, for all other docstrings. > As far as using the lowercase-annotation for the docstring: in a world of > > more and more type hinted python yes, it's very clear that any standardized use of annotations needs to be compatible with type hints and type checkers, static and dynamic. Which i think is Steve's point -- typing.Annotated is indeed compatible with those uses. > > 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. 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. 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. 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). And I note that Annotated flattens nested Annotated types, so having both a docstring and other use of Annotated could be a bit tricky. I'm not a type hints user -- but I think this should be run by the MyPy and other folks to see if I’m right in my skepticism. Docstrings are metadata. Annotated is for > attaching metadata to an annotation that is associated with some > variable. Done and done. It’s not Done unless the community accepts it as standard practice. This is why we have all the Typing PEPs — annotations have been there a long time, but if various tools use them differently, they really aren’t that useful. 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. -CHB [*] Eric, of course, can speak for himself, but so far, dataclasses deliberately don’t do anything with annotations other than pass them on, and there is active debate about whether they should do more, and if so, what? > > > > -- > 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/4SMDBNO2FUQCJECDD6ILYK6RAQZ25TNP/ > Code of Conduct: http://python.org/psf/codeofconduct/ > -- Christopher Barker, PhD (Chris) Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython -- Christopher Barker, PhD (Chris) Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython
_______________________________________________ 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/MMGWIW2MMS4ZNER4ZDUD2UBLUIE7VEXU/ Code of Conduct: http://python.org/psf/codeofconduct/
