On Sat, Dec 11, 2021 at 3:03 PM Steven D'Aprano <st...@pearwood.info> wrote:
> On Sat, Dec 11, 2021 at 10:07:50AM -0800, Christopher Barker wrote:
> > Where/how should class attribute doc strings be stored?
> >
> > Tacked on to the class __doc__ ?
> > Another dict?
> > __attr_doc__
> > Added to __annotaions__ ?
> > Something else?
>
> Didn't we decide there was an existing feature for this, no need for
> new syntax?
>
> >>> from typing import Annotated
> >>> class C:
> ... x: Annotated[int, "Doc string"] = 123
> ...
> >>> C.x
> 123
> >>> C.__annotations__
> {'x': typing.Annotated[int, 'Doc string']}
>
Well, no. In fact, you could always put anything you wanted into an
annotation:
In [10]: class C2:
...: x: "a docstring" = 123
...:
In [11]: inspect.get_annotations(C2)
Out[11]: {'x': 'a docstring'}
So the typing module contains a nifty thing they've called "Annotatated",
and, I imagine type checkers (like MyPy) do something sensible with them,
but there's nothing else going on here. Actually yes, there is, the
typing,get_type_hints function strips out the annotation:
In [13]: class C:
...: x: Annotated[int, "Doc string"] = 123
...:
In [14]: typing.get_type_hints(C)
Out[14]: {'x': int}
Anyway, take a look at the docs for Annotated:
https://docs.python.org/3/library/typing.html#typing.Annotated
It has a number of possible unspecified uses, but fundamentally, it's about
the adding information to the type, not to the attribute -- e.g. not really
intended for docstrings.
Sure, typing.Annotated *could* be used that way, but I don't think we can
say that the problem is solved.
Heck you could just as easily provide a tuple for the annotation:
In [17]: class C:
...: x: ("Doc string", int) = 123
...:
In [18]: inspect.get_annotations(C)
Out[18]: {'x': ('Doc string', int)}
The use cases for annotations are a bit up in the air at the moment -- see
the ongoing discussion on python-dev. But I don't think there's any doubt
that any future endorsed use of them will be compatible with static typing
(if not restricted to it), so extending the use of annotations for
docstrings would take a bit of work to define and accept that use.
Perhaps a better way to do that than to use Annotated would be to introduce
new "thing", maybe in teh typoing module, like "Documented":
class C:
x: Documented(doc_string="this is the doc string", type=int) = 123
and then inspect.get_annotations and typing,get_type_hints could be taught
to extract the type from the Documented object, and we could add an
inspect.get_docstrings() function, so that:
typing.get_type_hints(C)
{'x': int}
inspect.get_docstrings(C)
{'x': 'this is the doc string'}
And, of course, future syntax could automatically create a Documented()
object if there was a docstring in the appropriate place.
Or just have a new dunder for it, e.g. __attr_doc__
Anyway, what I'm getting at is that it needs to be determined whare to put
the docstrings before we can get very far with this idea.
-CHB
>
> --
> 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/UQV3GZLVHDCHXKN4L2QCIHYLFTWBFEW3/
> 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
_______________________________________________
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/LEFJD7BVN43E4EUNZOKTT2M7YOYU262R/
Code of Conduct: http://python.org/psf/codeofconduct/
