New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add 'annotations' to the glossary #76950
Comments
There is a description of the annotation in the Glossary, but with 'function annotation' maybe we could rename 'function annotation' by 'annotation' |
This is a rather small change, so probably it would be easier to discuss it in a PR. |
PRs are for discussing proposed text/code. Discussion of whether or not to do this belongs here. (I have no opinion on this issue myself.) |
I wanted to say implicitly that I like the idea, and that we should figure out details in a PR. But of course if someone is against this, then we should wait with a PR. |
I'm all for adding a bunch of terms related to type hints/annotations to the Glossary. |
I just made a PR to start working on the right wording. |
Guido, now that we are working on this, perhaps you can list what other terms related to type hints/annotations you were thinking for addition. |
Great, I'll look into them. It will take me some time to make a list of the new terms and write proper descriptions. Perhaps we could deliver the updates to the glossary by waves so people can make benefit of it? As in multiple PR being merged while retaining this issue open until all required terms are added. |
I'm okay with multiple PRs, but do beware that each PR requires a core dev |
Maybe we can consider backporting this to 3.7? Andrés, if you think it makes sense, you can cherry-pick the commit and open a PR against 3.7 branch. |
Yes, Ivan, I was thinking about that. I think it makes sense, and I'll be glad to do it. |
Shouldn't we have this on 3.6 also? |
Yes, all this also applies to 3.6. |
Before we backport this to 3.7 and 3.6, let's iterate on the wording a bit. I don't think the distinction between annotations and type hints is that annotations are materialized at runtime while type hints aren't. I think syntactically they are the same, but annotations are a slightly more general concept because they may be used for other purposes than to indicate the type of a variable (or argument, attribute etc.). So IMO in def f():
x: int 'int' is both an annotation and a type hint, OTOH in x: 'spam eggs ham' we have an annotation that is not a type hint. |
Yes, I agree. |
I see a conflict here in that annotations can be used for other purpouses, for example variable annotations, they are heavily intended for type hinting (PEP-526 says "This PEP aims at adding syntax to Python for annotating the types of variables (including class variables and instance variables), instead of expressing them through comments") I think it's correct to separate annotations from type hints, and say: annotations can be used for type hinting. I can make a new PR based on master having this in mind, and then cherry picking it for 3.7/3.6. |
Guido, do you really want to stress at this point for Python 3.8 that annotations do not have an intended purpose? That is clearly not true.
https://www.python.org/dev/peps/pep-0563/#non-typing-usage-of-annotations |
What I think Guido might mean is that some type annotations are not strictly speaking type hints. For example, Also for me the two terms: annotations and hints are a bit orthogonal, first is a syntax, while second is semantics. I think Guido is right that we should say something like (approximately) |
I actually intended to say that annotations continue to be usable for I'm fine with adding that the main use of annotations is for type hints of |
Yes, local annotations are important and should be mentioned (maybe even with an example). |
Hopefully I address your comments with the last PR update. |
Agreed. However, based on the current wording users will argue that Python documentation itself is stressing the lack of an intended purpose for annotations, equaling the typing use case with all other use cases (including future ones). This isn't our intent. I think it would be clearer to change the current wording from:
to:
The |
Your phrasing still makes it sound like an annotation is a runtime concept |
Guido, could you point out what parts make it sound that way to you so I can change them? |
(1) The word "stores" in this paragraph: A metadata value associated with a global variable, a class attribute or a (2) The description of how annotations are stored in __annotations__ in the (3) The omission of local variables from the lists of things in those |
I'm sorry, because of your comment, I believe you haven't read the last update on the PR. Could you take a look at it? |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: