On Sun, 2021-12-12 at 12:23 -0800, Christopher Barker wrote: > 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.
Confirmed. I have tooling today using exactly that to dynamically generate API documentation. > 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. But what's being annotated, the type or the attribute? > 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). 1. Docstrings today are attached to the things they're documenting by way of an included `__doc__` attrbute. `Annotated` is arguably "attached" to the type, to the extent that the type is embedded in the annotation itself. Illustration: SomeType = Annotated[str, "some type"] class A: x: SomeType y: SomeType Clearly, above we documented the type, not the attribute. We could solve this by allowing it to be re-annotated, which seems perfectly valid: SomeType = Annotated[str, "some type"] class A: x: Annotated[SomeType, "x docstring"] y: Annotated[SomeType, "y docstring"] The last bare string could "win" as the prevaling docstring: >>> SomeType = Annotated[str, "some type"] >>> U = Annotated[SomeType, "new docstring"] >>> U typing.Annotated[str, 'some type', 'new docstring'] Or, doc tools could even include them both to provide a more meaningful context. You could argue that since the type annotation of an attribute can be extended in this manner, `Annotated` is an acceptable way of documenting an attribute. 2. Adding a typing.Documented would definitely increase verbosity. I think we may already be pushing the envelope with `Annotated[...]`; `Annotated[..., Documented(...)] may be an annotation too far. Since there is not yet a convention for a bare string in `Annotated`, I suggest we reserve it the purpose of documenting the type or attribute. > 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 think as long as strings are considered documentation—regardless of where they appear in the annotation—we'd still be on solid ground. > 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. > > [*] 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? I don't think dataclasses have to do anything with them. I'm literally embedding strings in Annotated today, for this exact purpose, with no impact on dataclasses. I think the work would be in documentation tools to interpret the annotations and produce something usable to the developer.
_______________________________________________ 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/AAYG4NR4O3L7HIPTO4JOVJ2I2HKKA2H4/ Code of Conduct: http://python.org/psf/codeofconduct/
