Repository navigation
Add 'annotations' to the glossary #76950
Description
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:
assignee = None
closed_at = <Date 2018-07-28.13:04:20.536>
created_at = <Date 2018-02-04.23:13:13.525>
labels = ['easy', '3.8', 'type-feature', '3.7', 'docs']
title = "Add 'annotations' to the glossary"
updated_at = <Date 2018-07-28.13:04:20.535>
user = 'https://github.com/csabella'bugs.python.org fields:
activity = <Date 2018-07-28.13:04:20.535>
actor = 'steve.dower'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-07-28.13:04:20.536>
closer = 'steve.dower'
components = ['Documentation']
creation = <Date 2018-02-04.23:13:13.525>
creator = 'cheryl.sabella'
dependencies = []
files = []
hgrepos = []
issue_num = 32769
keywords = ['patch', 'easy']
message_count = 31.0
messages = ['311796', '311900', '311904', '311905', '311907', '315953', '316121', '316143', '316146', '316147', '316553', '316557', '316558', '316559', '316562', '316564', '316566', '316568', '316618', '316646', '316648', '316650', '316674', '316705', '316714', '316739', '316751', '316752', '317741', '317746', '317749']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'r.david.murray', 'docs@python', 'lukasz.langa', 'matrixise', 'levkivskyi', 'cheryl.sabella', 'adelfino']
pr_nums = ['6657', '6821', '6829', '7127', '7128', '7131']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32769'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']
Activity
matrixise commentedon Feb 7, 2018
There is a description of the annotation in the Glossary, but with 'function annotation'
maybe we could rename 'function annotation' by 'annotation'
ilevkivskyi commentedon Feb 9, 2018
This is a rather small change, so probably it would be easier to discuss it in a PR.
bitdancer commentedon Feb 9, 2018
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.)
ilevkivskyi commentedon Feb 9, 2018
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.
gvanrossum commentedon Feb 9, 2018
I'm all for adding a bunch of terms related to type hints/annotations to the Glossary.
andresdelfino commentedon Apr 30, 2018
I just made a PR to start working on the right wording.
andresdelfino commentedon May 3, 2018
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.
gvanrossum commentedon May 3, 2018
Perhaps you can start with the more important terms from PEP-484 (and
perhaps also PEP-483, and then PEP-526 and PEP-544). E.g. start with terms
from the ToC of those PEPs.
andresdelfino commentedon May 3, 2018
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.
gvanrossum commentedon May 3, 2018
I'm okay with multiple PRs, but do beware that each PR requires a core dev
to open a browser window etc., so try to group them a bit. But no need to
wait for the perfect list!
9 remaining items
ambv commentedon May 15, 2018
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.
PEP-526 was created purely with types in mind and was inspired by PEP-484's lack of this functionality.
PEP-563 defines a future import which will become the default in a future release (currently marked as 4.0). This default stops evaluating annotations at runtime, which again was inspired by the typing use case.
Dataclasses in PEP-557 are designed to leverage types in annotations. A few quotes from that PEP:
PEP-560 added support for
__class_getitem__and__mro_entries__in core purely for the purpose of generic types.For the above reasons, PEP-563 states that non-typing usage of annotations is deprecated:
https://www.python.org/dev/peps/pep-0563/#non-typing-usage-of-annotations
ilevkivskyi commentedon May 15, 2018
What I think Guido might mean is that some type annotations are not strictly speaking type hints. For example,
dataclasses.InitVar, is not really a type, it is just a way to indicate how constructor should be constructed. I could see similar potential features in future (liketyping.Finaldiscussed recently). Eventyping.ClassVarI would say is not a type but an access qualifier.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)
annotation is a syntax to express type hints and other related metadataor similar. The current formulation seems a bit too restrictive.gvanrossum commentedon May 15, 2018
I actually intended to say that annotations continue to be usable for
non-typing purposes (beyond ClassVar/InitVar). It may be deprecated but the
usage still exists. This is a glossary, not a manifesto.
I'm fine with adding that the main use of annotations is for type hints of
course. And I was mostly reacting to the fact that the text that was just
committed seemed to imply that 'annotation' refers to something stored at
runtime in __annotations__ while 'type hint' was a syntactic form (and this
is borne out by the omission of *local* type hints from the section on
annotations).
ilevkivskyi commentedon May 15, 2018
Yes, local annotations are important and should be mentioned (maybe even with an example).
andresdelfino commentedon May 15, 2018
Hopefully I address your comments with the last PR update.
ambv commentedon May 15, 2018
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
type hintphrasing is already there, we just need to delete the word "global" that currently appears before "variable". Note that saying that annotations in class attributes and variables have no assigned meaning contradicts PEP-526.gvanrossum commentedon May 15, 2018
Your phrasing still makes it sound like an annotation is a runtime concept
-- I think of it as a syntactic construct. (Otherwise fine.)
andresdelfino commentedon May 15, 2018
Guido, could you point out what parts make it sound that way to you so I can change them?
gvanrossum commentedon May 16, 2018
(1) The word "stores" in this paragraph:
A metadata value associated with a global variable, a class attribute or a
function or method parameter or return value, that stores a type hint.
(2) The description of how annotations are stored in __annotations__ in the
following paragraph.
(3) The omission of local variables from the lists of things in those
paragraphs that can be annotated (those are the only category whose
annotation is not stored at runtime).
andresdelfino commentedon May 16, 2018
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?
#6829
ilevkivskyi commentedon May 26, 2018
New changeset 6e33f81 by Ivan Levkivskyi (Andrés Delfino) in branch 'master':
bpo-32769: A new take on annotations/type hinting glossary entries (GH-6829)
6e33f81
gvanrossum commentedon May 26, 2018
New changeset e69657d by Guido van Rossum (Andrés Delfino) in branch '3.7':
[3.7] bpo-32769: A new take on annotations/type hinting glossary entries (GH-6829) (bpo-7127)
e69657d
ilevkivskyi commentedon May 26, 2018
New changeset 717204f by Ivan Levkivskyi (Andrés Delfino) in branch '3.6':
[3.6] bpo-32769: A new take on annotations/type hinting glossary entries (GH-6829) (GH-7128)
717204f