bpo-32769: A new take on annotations/type hinting glossary entries #6829

andresdelfino · 2018-05-14T20:22:43Z

https://bugs.python.org/issue32769

…'defined via'

…that annotations are not a runtime-only concept

andresdelfino · 2018-05-20T15:06:38Z

@ilevkivskyi I would really appreciate any input, when you have some spare time of course.

ilevkivskyi

Sorry, I lost track a bit, here are few superficial comments. I would rather ask @gvanrossum to take a look at wording here (if he has bandwidth of course).

ilevkivskyi · 2018-05-25T00:20:27Z

Doc/glossary.rst

-      A metadata value associated with a global variable, a class attribute or a
-      function or method parameter or return value, that stores a
-      :term:`type hint`.
+      A metadata value associated with a variable, a class attribute or a


I may guess "value" is what @gvanrossum didn't like, and I agree with him.

Yes, I guess this will be the most difficult part to get right 😅

ilevkivskyi · 2018-05-25T00:21:56Z

Doc/glossary.rst

+      Annotating local variables will cause the interpreter to always make them
+      locals::
+
+         def f():


I think there are too much details here, it is glossary, not a spec.

ilevkivskyi · 2018-05-25T00:22:28Z

Doc/glossary.rst

+         def broadcast_message(
+                 message: str,
+                 servers: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:
+             ...


I would also make this example shorter.

gvanrossum · 2018-05-25T04:16:00Z

Doc/glossary.rst

-      Type aliases are useful for simplifying complex
-      :term:`type hints <type hint>`.  For example ::
+      Type aliases are useful for simplifying :term:`type hints <type hint>`.
+      For example ::


Honestly this example would look better if it read "For example [bad code] could be made more readable like this [good code]" (currently it shows [good code] first).

gvanrossum · 2018-05-25T04:18:18Z

Doc/glossary.rst

      :func:`bytes.splitlines` for an additional use.

   variable annotation
      An :term:`annotation` of a variable, or a class attribute.


This should not have a comma.

gvanrossum · 2018-05-25T04:20:46Z

Doc/glossary.rst

-      A metadata value associated with a global variable, a class attribute or a
-      function or method parameter or return value, that stores a
-      :term:`type hint`.
+      A label with no defined semantics associated with a variable, a class


I think "no defined semantics" is too strong -- IMO it should say that by convention annotations are usually used for type hints (i.e. as type annotations).

Also I'm not too excited about the word "label" here but I agree it's better than "metadata value".

What about "syntactic construct"? Would that be too wordy?

gvanrossum · 2018-05-25T04:23:28Z

Doc/glossary.rst


-      Class variables can be specified as such through
+      Variables can be specified as expected to be class variables through
      :term:`type hints <type hint>`.


If you're going to be this specific I recommend calling out ClassVar by name.

I agree that this was getting too specific. I left the class variable definition, though, because I think it's useful. Let me know if you think it is not and I'll remove it.

gvanrossum · 2018-05-25T04:24:54Z

Doc/glossary.rst

-      For example, this function has its parameters annotated as taking
-      :class:`int` arguments and its return value annotated as being an
-      :class:`int` as well::
+      Function annotations can be


can be -> are usually used for

gvanrossum · 2018-05-25T04:39:36Z

Doc/glossary.rst

+      A synonym for a type, created by assigning the type to an identifier.
+
+      Type aliases are useful for simplifying :term:`type hints <type hint>`.
+      For example ::


I'd write the bad example first and the improved example next, with words such as "For example:: [bad example] can be rewritten with more clarity as:: [good example]"

gvanrossum · 2018-05-25T04:41:39Z

Doc/glossary.rst

-      A specification about the expected type for a global variable, class
-      variable, function or method parameter or return value.
+      An :term:`annotation` that specifies the expected type for a variable, class
+      attribute, function or method parameter or return value.


Rewrite as "[...] for a variable, a class attribute, or a function parameter or return value." (The repetition of "a" makes it clear that the last "or" binds more tightly than the other.)

gvanrossum · 2018-05-25T04:42:18Z

Doc/glossary.rst

      completion and refactoring.

-      Type hints are stored in :term:`annotations <annotation>`.
+      Type hints of global variables, class attributes, functions and methods


functions and methods -> function

gvanrossum · 2018-05-25T04:42:54Z

Doc/glossary.rst

+             field: 'annotation'

-      When annotating variables, assignment is optional::
+      Variable annotations can be


can be -> are usually used for

gvanrossum · 2018-05-25T04:43:24Z

Doc/glossary.rst

+      An :term:`annotation` of a variable, or a class attribute.

-      For example, this variable is annotated as taking :class:`int` values::
+      When annotating variables or class attributes, assignment is optional ::


I'd say "a variable or a class attribute"

gvanrossum

ALmost there.

gvanrossum · 2018-05-25T18:04:35Z

Doc/glossary.rst

-      Annotations can be :term:`type hints <type hint>`.
-
-      See :pep:`484` and :pep:`526`, which describe this functionality.
+      See :term:`variable annotation`, :term:`function annotation`, :pep:`484` and :pep:`526`, which describe this functionality.


Please break this long line.

gvanrossum · 2018-05-25T18:04:59Z

Doc/glossary.rst

+      :term:`type hints <type hint>`: for example this function is expected to take two
      :class:`int` arguments and is also expected to have an :class:`int`
-      return value::
+      return value ::


Why is there a space before the :: ?

I thought it was custom 😅

gvanrossum · 2018-05-25T18:05:51Z

Doc/glossary.rst

-      Type hints of global variables, class attributes, function or method
-      parameter or return value, but not local variables, can be accessed using
+      Type hints of global variables, class attributes, and functions
+      , but not local variables, can be accessed using


Move comma to preceding line.

gvanrossum · 2018-05-25T18:06:17Z

Doc/glossary.rst

-      function or method parameter or return value, with no defined semantics.
+      A label associated with a variable, a class
+      attribute or a function parameter or return value,
+      used, by convention, for :term:`type hints <type hint>`.


there's no need for commas around "by convention".

miss-islington · 2018-05-26T12:43:41Z

Thanks @andresdelfino for the PR, and @ilevkivskyi for merging it 🌮🎉.. I'm working now to backport this PR to: 3.6, 3.7.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington · 2018-05-26T12:43:49Z

Sorry, @andresdelfino and @ilevkivskyi, I could not cleanly backport this to 3.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 6e33f810c9e3a549c9379f24cf1d1752c29195f0 3.7

miss-islington · 2018-05-26T12:44:44Z

Sorry, @andresdelfino and @ilevkivskyi, I could not cleanly backport this to 3.6 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 6e33f810c9e3a549c9379f24cf1d1752c29195f0 3.6

ilevkivskyi · 2018-05-26T12:48:04Z

@andresdelfino Could you please make manual backports of these changes? (Make PRs against 3.6 and 3.7 branches).

andresdelfino · 2018-05-26T12:50:51Z

Yes, I was working on them already :)

…ies (pythonGH-6829). (cherry picked from commit 6e33f81) Co-authored-by: Andrés Delfino <[email protected]>

bedevere-bot · 2018-05-26T12:57:07Z

GH-7127 is a backport of this pull request to the 3.7 branch.

…ies (pythonGH-6829). (cherry picked from commit 6e33f81) Co-authored-by: Andrés Delfino <[email protected]>

bedevere-bot · 2018-05-26T13:20:20Z

GH-7128 is a backport of this pull request to the 3.6 branch.

…ies (GH-6829) (#7127) (cherry picked from commit 6e33f81) Co-authored-by: Andrés Delfino <[email protected]>

…ies (GH-6829) (GH-7128) * [3.6] bpo-32769: A new take on annotations/type hinting glossary entries (GH-6829). (cherry picked from commit 6e33f81) Co-authored-by: Andrés Delfino <[email protected]> * Typo fix spotted by Guido

Initial commit

6176f8a

the-knights-who-say-ni added the CLA signed label May 14, 2018

bedevere-bot added the awaiting review label May 14, 2018

andresdelfino added 18 commits May 14, 2018 17:24

Minor fix

dd61e97

Fix term links, emphasize on the word 'expected', change 'stored' to …

70106b4

…'defined via'

Add local variable annotations comment

e5189e9

Be consistent with singular

e6c4d44

Remove 'global' from variable annotations entry

399021c

Minor change

084a08b

Fix single colons

c192e04

Fix doble colons

ec67b1e

Move local variable comment to variable annotation term

3349efe

Separate annotation syntax examples from type hinting

61fac0b

Remove 'global' from type hints

41674e3

Clarify local annotations

9b1721c

Change class variable to class attribute on type hint

6c51318

Be consistent with plurals

4a5b6be

Try to make it clear that type hints are one use of annotations, and …

8178119

…that annotations are not a runtime-only concept

Minor fix

a32ffbc

Another minor fix

a88cebb

Add type alias definition, plus minor changes

ce6d127

ilevkivskyi added the skip news label May 25, 2018

ilevkivskyi reviewed May 25, 2018

View reviewed changes

andresdelfino added 2 commits May 24, 2018 22:55

Address Ivan's comments

fcec1b2

Minor changes

3c86ab0

gvanrossum reviewed May 25, 2018

View reviewed changes

andresdelfino added 3 commits May 25, 2018 10:18

Address Guido's comments

26af7a2

Add 'for example' in variable annotations

d2a1df1

Use singular instead of plural

e8e1b36

gvanrossum reviewed May 25, 2018

View reviewed changes

Address Guido's comments

a455361

gvanrossum approved these changes May 25, 2018

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting review labels May 25, 2018

ilevkivskyi approved these changes May 26, 2018

View reviewed changes

ilevkivskyi added needs backport to 3.6 labels May 26, 2018

ilevkivskyi merged commit 6e33f81 into python:master May 26, 2018

bedevere-bot removed the awaiting merge label May 26, 2018

miss-islington assigned ilevkivskyi May 26, 2018

andresdelfino deleted the type-hints branch May 26, 2018 12:50

bedevere-bot removed the needs backport to 3.7 label May 26, 2018

bedevere-bot removed the needs backport to 3.6 label May 26, 2018

gvanrossum pushed a commit that referenced this pull request May 26, 2018

[3.7] bpo-32769: A new take on annotations/type hinting glossary entr…

e69657d

…ies (GH-6829) (#7127) (cherry picked from commit 6e33f81) Co-authored-by: Andrés Delfino <[email protected]>

andresdelfino mentioned this pull request May 26, 2018

bpo-32769: Fix typo spotted by Guido in Annotation glossary entry #7131

Merged

Uh oh!

bpo-32769: A new take on annotations/type hinting glossary entries #6829

bpo-32769: A new take on annotations/type hinting glossary entries #6829

Uh oh!

Conversation

andresdelfino commented May 14, 2018 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andresdelfino commented May 20, 2018

Uh oh!

ilevkivskyi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miss-islington commented May 26, 2018

Uh oh!

miss-islington commented May 26, 2018

Uh oh!

miss-islington commented May 26, 2018

Uh oh!

ilevkivskyi commented May 26, 2018

Uh oh!

andresdelfino commented May 26, 2018

Uh oh!

bedevere-bot commented May 26, 2018

Uh oh!

bedevere-bot commented May 26, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

andresdelfino commented May 14, 2018 •

edited by bedevere-bot

Loading