On Mon, Dec 13, 2021 at 6:54 AM Steven D'Aprano <st...@pearwood.info> wrote:
>
> 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.
The consideration I'm making here is that any standard use of annotations
needs to be fully compatible with type hinting. That's even spelled out in
PEP 563.
"uses for annotations incompatible with the aforementioned PEPs should be
considered deprecated."
> > __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.
>
OK -- but that brings us back to how I started this sub-thread -- where are
the docstrings stored to be retrieved at runtime. If that's a new dunder,
great, then future enhancements making it easier to add them would be
compatible, and folks could hand-populate the dunder in any number of ways,
maybe including the use of typing.Annotated.
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.
yes, i read that. This trick is that that's just kicking the can down the
road. - one level up from the original state of "annotations will be
stored, and you can use them however you want". But then it was decided to
standardize the use of annotations as type hints. ANd now we are changing
how annotations work in order to better accommodate type hinting (PEP 563).
In light of the lesson there, I don't think it's a good idea to
semi-standardize one use for typing.Annotations without being more explicit
in the intent.
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.
>
but not a good idea at this point -- at least not in a way that's
incompatible with type hinting.
> 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.
>
Actually, that's not the least bit clear right now -- that exact point is
being mulled over as we speak.
Using docstrings in annotations would seem to be a good way to establish
> a strong non-typing use-case.
>
Then someone needs to do it NOW. The SC has literally asked for use-cases
for annotations for them to consider.
> 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).
>
I think it might be doable -- I'm going to give that a try soon.
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.
>
exactly -- so someone develops a tool that looks for Annotated, and tries
to extract docstrings from it. And someone else uses an Annotated with a
string in it for some completely different reason. And then a third person
runs the docstring tool on the code using Annotated for that other reason.
That just seems like asking for a mess to me.
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.
>
yes, though that is getting cleaned up, and is already a bit cleaner if you
use get_type_hints or get_annotations -- that's one reason they exist.
> 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.
>
and dataclasses are the one use-case of annotations in the stdlib. (I'm
pretty sure).
However, on thinking about it, this is actually NOT a good use case.
The dataclasse decorator uses analysis of the decorated class to set its
Fields:
If the class has a class attribute that has an annotation, it is a Field.
However, those class attributes are NOT necessarily class attributes in the
resulting class. I haven't checked the code carefully, but it looks like if
they have an immutable default, they are kept as class attributes, and
otherwise are not.
In [48]: @dataclass
...: class Test:
...: x: int
...: y: float = 1.0
...: l: list = field(default_factory=list)
...:
In [49]: Test.x
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-49-e65584dd4a8c> in <module>
----> 1 Test.x
AttributeError: type object 'Test' has no attribute 'x'
In [50]: Test.y
Out[50]: 1.0
In [51]: Test.l
---------------------------------------------------------------------------
AttributeError Traceback (most recent call last)
<ipython-input-51-2185bdd4fcc8> in <module>
----> 1 Test.l
AttributeError: type object 'Test' has no attribute 'l'
I don't know why the immutable default is kept as a class attribute -- it
gets overridden by an instance attribute when initialized anyway.
But the key point is that the class attributes used to make a dataclass are
not class attributes of teh dataclass, they are turned in to instance
attributes.
-CHB
--
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/K7RGXWPSNAN3O3JQ7BXP374RSOJ42TDS/
Code of Conduct: http://python.org/psf/codeofconduct/
