[issue32769] Add 'annotations' to the glossary

[Steve Dower]

Change by Steve Dower :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Change by Andrés Delfino :


--
pull_requests: +6765

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:


New changeset 717204ffcccfe04a34b6c4a52f0e844fde3cdebe 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)
https://github.com/python/cpython/commit/717204ffcccfe04a34b6c4a52f0e844fde3cdebe


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:


New changeset e69657df244135a232117f692640e0568b04e999 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) (#7127)
https://github.com/python/cpython/commit/e69657df244135a232117f692640e0568b04e999


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Change by Andrés Delfino :


--
pull_requests: +6763

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Change by Andrés Delfino :


--
pull_requests: +6762

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:


New changeset 6e33f810c9e3a549c9379f24cf1d1752c29195f0 by Ivan Levkivskyi 
(Andrés Delfino) in branch 'master':
bpo-32769: A new take on annotations/type hinting glossary entries (GH-6829)
https://github.com/python/cpython/commit/6e33f810c9e3a549c9379f24cf1d1752c29195f0


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

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?

https://github.com/python/cpython/pull/6829

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:

(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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

Guido, could you point out what parts make it sound that way to you so I can 
change them?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:

Your phrasing still makes it sound like an annotation is a runtime concept
-- I think of it as a syntactic construct. (Otherwise fine.)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Łukasz Langa]

Łukasz Langa  added the comment:

> It may be deprecated but the usage still exists. This is a glossary, not a 
> manifesto.

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:

> A metadata value associated with a variable, a class attribute or a
> function or method parameter or return value, that has no specific
> purpouse (i.e. it's up to the user to use it as they see fit).
> (...)
> Annotations can be used to specify :term:`type hints `.

to:

> A metadata value associated with a variable, a class attribute or a
> function or method parameter or return value, that stores a
> :term:`type hint`.
> (...)
> Annotations can be used for other purposes unrelated to typing. This
> usage is deprecated, see :pep:`563` for details.


The `type hint` phrasing 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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

Hopefully I address your comments with the last PR update.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

Yes, local annotations are important and should be mentioned (maybe even with 
an example).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:

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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

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 (like `typing.Final` discussed recently). 
Even `typing.ClassVar` I 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 metadata` or similar. The current formulation seems a bit too 
restrictive.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Łukasz Langa]

Łukasz Langa  added the comment:

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.

1. PEP 526 was created purely with types in mind and was inspired by PEP 484's 
lack of this functionality.

2. 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.

3. Dataclasses in PEP 557 are designed to leverage types in annotations. A few 
quotes from that PEP:

> A class decorator is provided which inspects a class definition for variables 
> with type annotations as defined in PEP 526, "Syntax for Variable 
> Annotations".

> One main design goal of Data Classes is to support static type checkers. The 
> use of PEP 526 syntax is one example of this, but so is the design of the 
> fields() function and the @dataclass decorator.

4. PEP 560 added support for `__class_getitem__` and `__mro_entries__` in core 
purely for the purpose of generic types.

5. 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

--
nosy: +lukasz.langa

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Change by Andrés Delfino :


--
versions: +Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Change by Andrés Delfino :


--
pull_requests: +6513

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

> ... but annotations are a slightly more general concept because they may be 
> used for other purposes than to indicate the type of a variable ...

Yes, I agree.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

Yes, all this also applies to 3.6.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

Shouldn't we have this on 3.6 also?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Change by Andrés Delfino :


--
pull_requests: +6506

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

Yes, Ivan, I was thinking about that.

I think it makes sense, and I'll be glad to do it.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:


New changeset f2290fb19a9b1a5fbeef0971016f72683e8cd1ad by Ivan Levkivskyi 
(Andrés Delfino) in branch 'master':
bpo-32769: Write annotation entry for glossary (GH-6657)
https://github.com/python/cpython/commit/f2290fb19a9b1a5fbeef0971016f72683e8cd1ad


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:

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!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Andrés Delfino  added the comment:

I just made a PR to start working on the right wording.

--
nosy: +adelfino

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Andrés Delfino]

Change by Andrés Delfino :


--
keywords: +patch
pull_requests: +6353
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Cheryl Sabella]

Change by Cheryl Sabella :


--
stage:  -> needs patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Guido van Rossum]

Guido van Rossum  added the comment:

I'm all for adding a bunch of terms related to type hints/annotations to the 
Glossary.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

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.

--
nosy: +gvanrossum

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[R. David Murray]

R. David Murray  added the comment:

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.)

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

This is a rather small change, so probably it would be easier to discuss it in 
a PR.

--
nosy: +levkivskyi

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Stéphane Wirtel]

New submission from Stéphane Wirtel :

There is a description of the annotation in the Glossary, but with 'function 
annotation'

maybe we could rename 'function annotation' by 'annotation'

--
nosy: +matrixise

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32769] Add 'annotations' to the glossary

[Cheryl Sabella]

Change by Cheryl Sabella :


--
assignee: docs@python
components: Documentation
keywords: easy
nosy: csabella, docs@python
priority: normal
severity: normal
status: open
title: Add 'annotations' to the glossary
type: enhancement
versions: Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com