Initial import of PEP 593: Flexible function and variable annotations #1014

till-varoquaux · 2019-04-26T21:17:48Z

No description provided.

the-knights-who-say-ni · 2019-04-26T21:17:50Z

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA (this might be simply due to a missing "GitHub Name" entry in your b.p.o account settings). This is necessary for legal reasons before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for your contribution, we look forward to reviewing it!

ilevkivskyi

Thanks! This is not ready yet to be merged, I have a bunch of comments here.

ilevkivskyi · 2019-04-26T23:31:37Z

pep-0592.rst

+Content-Type: text/x-rst
+Created: 26-April-2019
+Python-Version:
+Post-History:


Please add Discussion-to: header pointing to typing-sig mailing list.

ilevkivskyi · 2019-04-26T23:35:12Z

pep-0592.rst

+effectively crowded out any other form of annotation. Some of the use
+cases for annotations described in PEP 3107 (database mapping,
+foreign languages bridge) are not currently realistic given the
+prevalence of type annotations.


This is a bit misleading, since it looks like the main motivation is enabling non-typing related uses, but in fact enabling advanced typing features supported only by some type checkers is one of the motivating use cases. I think it is worth mentioning here.

ilevkivskyi · 2019-04-26T23:37:05Z

pep-0592.rst

+``no_type_check`` functionality that current exists in the ``typing``
+module which completely disables typechecking annotations on a function
+or a class, the ``Annotated`` type allows for both static typechecking
+of ``T`` (e.g., via MyPy or Pyre, which can safely ignore ``x``)


Please use normal-word capitalization for mypy, here and everywhere below: i.e. Mypy at beginning of sentence, mypy everywhere else.

ilevkivskyi · 2019-04-26T23:39:22Z

pep-0592.rst

+~~~~~~~~~~~~~~~~~~~
+
+Reading binary data
+^^^^^^^^^^^^^^^^^^^


This is minor, but I generally don't like more than two nesting levels for sections. I would propose to make Motivating examples a top-level section.

ilevkivskyi · 2019-04-26T23:40:35Z

pep-0592.rst

+      name: Annotated[str, struct.ctype("<10s")]
+      serialnum: UnsignedShort
+      school: SignedChar
+      gradelevel: SignedChar


Please use 4 spaces indentation.

ilevkivskyi · 2019-04-27T00:08:21Z

pep-0592.rst

+    @struct.packedclass Student(NamedTuple):
+      name: Annotated[str, struct.ctype("<10s")]
+
+::


Why do you have this?

ilevkivskyi · 2019-04-27T00:09:53Z

pep-0592.rst

+    Class C:
+      def const_method(self: Const[T]) -> int:
+        ...
+


I would add a short section about rejected ideas (even if there is currently just few of them, since more can appear during the discussion).

ilevkivskyi · 2019-04-27T00:10:06Z

pep-0592.rst

+
+Writing ``typing.Annotated`` everywhere can be quite verbose;
+fortunately, the ability to alias annotations means that in practice we
+don’t expect clients to have to write lots of boilerplate code::


Suggested change

don’t expect clients to have to write lots of boilerplate code::

don't expect clients to have to write lots of boilerplate code::

ilevkivskyi · 2019-04-27T00:10:29Z

pep-0592.rst

+    Const = Annotated[T, my_annotations.CONST]
+
+    Class C:
+      def const_method(self: Const[T]) -> int:


Suggested change

def const_method(self: Const[T]) -> int:

def const_method(self: Const[List[int]]) -> int:

ilevkivskyi · 2019-04-27T00:13:30Z

pep-0592.rst

+
+    # 'unpack' only uses the metadata within the type annotations
+    Student.unpack(record)
+    # Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)


This example (and to certain extent the second example) is unnecessarily detailed. You focus too much on advocating for specific use case, instead of explaining the big picture with the example.

gvanrossum · 2019-04-27T02:32:08Z

I’ll leave the review up to Ivan.

till-varoquaux · 2019-04-29T20:12:52Z

@ilevkivskyi thanks for the suggestions. I tried to address everything you pointed out. Let me know if this version is better.

ilevkivskyi

Thanks for updates! This is almost ready to be merged, I have few more comments. Also please don't rebase and/or force push, because it is harder to follow the reviews and GitHub doesn't send notifications when you do this. Just add new commits and merge when necessary.

ilevkivskyi · 2019-04-29T23:29:18Z

pep-0592.rst

@@ -0,0 +1,295 @@
+PEP: 592
+Title: External annotations in the typing module


Now I am thinking about a possible better title for this PEP. What do you think about "Flexible function and variable annotations"?

"Mixing typing and non-typing annotations"? "Extra [meta]data in type hints"? "Non-typing information in type hints?" Just spitballing here.

ilevkivskyi · 2019-04-29T23:31:17Z

pep-0592.rst

+analysis or at runtime. If a library (or tool) encounters a typehint
+``Annotated[T, x]`` and has no special logic for metadata ``x``, it
+should ignore it and simply treat the type as ``T``. Unlike the
+``no_type_check`` functionality that current exists in the ``typing``


Suggested change

``no_type_check`` functionality that current exists in the ``typing``

``no_type_check`` functionality that currently exists in the ``typing``

ilevkivskyi · 2019-04-29T23:32:45Z

pep-0592.rst

+runtime (e.g.: dataclasses); having the ability to extend the typing annotations
+with external data would be a great boon for those libraries.
+
+Example::


Make it clear that this example is about hypothetic functionality in cstruct module.

ilevkivskyi · 2019-04-29T23:33:38Z

pep-0592.rst

+        name: Annotated[str, cstruct.ctype("<10s")]
+        serialnum: UnsignedShort
+        school: SignedChar
+        gradelevel: SignedChar


Maybe we can keep only one SignedChar field for brevity?

ilevkivskyi · 2019-04-29T23:34:26Z

pep-0592.rst

+typing module and change mypy, PyCharm [pycharm]_, Pyre,
+pytype [pytype]_, etc...
+This is particularly important when working on open-source code that
+makes use of our new types, seeing as the code would not be immediately


Suggested change

makes use of our new types, seeing as the code would not be immediately

makes use of our these types, seeing as the code would not be immediately

ilevkivskyi · 2019-04-29T23:37:15Z

pep-0592.rst

+
+This is a somewhat cumbersome syntax but it allows us to iterate on this
+proof-of-concept and have people with type checkers (or other tools) that don't
+yet support this feature work in a codebase with tagged unions. We could easily


You often use "we" while it is not always totally clear whom do you mean.

ilevkivskyi · 2019-04-29T23:40:23Z

pep-0592.rst

+        int, ValueRange(3, 10), ValueRange(3, 10)
+    ]
+
+* ``Annotated`` can be used as a higher order aliases::


Suggested change

* ``Annotated`` can be used as a higher order aliases::

* ``Annotated`` can be used with nested and generic aliases::

ilevkivskyi · 2019-04-29T23:41:26Z

pep-0592.rst

+and treat annotated type as the underlying type. For example, if we were
+to add an annotation that is not an instance of ``new_struct.ctype`` to the
+annotation for name (e.g.,
+``Annotated[str, 'foo', new_struct.ctype("<10s")]``), the unpack method


Use same name for the hypothetic module here and in the first motivating example.

ilevkivskyi · 2019-04-29T23:42:36Z

pep-0592.rst

+out of the returned value. Otherwise, the annotations will be returned
+unchanged::
+
+    @struct.packedclass Student(NamedTuple):


Something is still wrong with the formatting here, this is a syntax error.

ilevkivskyi · 2019-04-29T23:45:39Z

pep-0592.rst

+Ideally, we should be able to introduce new types in a manner that allows for
+graceful degradation when clients do not have a custom mypy plugin
+[mypy-plugin]_, which would lower the barrier to development and ensure some
+degree of backward compatibility.


TBH, this sentence is still not very clear. In particular, it is not clear what is special about mypy here. Maybe add "for example" somewhere?

jstasiak · 2019-05-14T09:09:10Z

There's a conflict with another PEP introduced in #1032 now.

pfalcon · 2019-05-14T10:10:23Z

Conflict in the PEP number (592), it should be added.

ilevkivskyi · 2019-05-14T12:59:37Z

@till-varoquaux You can grab the next number 593, also please let me know when this is ready for another review.

till-varoquaux · 2019-05-16T04:38:28Z

@ilevkivskyi sorry for the incredible amount of procrastinating I've been doing. I owe you a box of chocolates for your patience...

ilevkivskyi

OK, I think this is ready.

@gvanrossum Should I just merge this, or the PEP number should be officially assigned by a PEP-editor?

gvanrossum · 2019-05-19T21:05:35Z

As a core dev you can merge it yourself.

ilevkivskyi · 2019-05-19T21:12:11Z

@till-varoquaux Please start a discussion on typing-sig to gather some more feedback.

ilevkivskyi · 2019-05-19T21:17:28Z

Btw @gvanrossum is there a chance this can get into Python 3.8? Technically there is still almost two weeks before beta1 :-)

gvanrossum · 2019-05-19T22:10:26Z

Btw @gvanrossum is there a chance this can get into Python 3.8? Technically there is still almost two weeks before beta1 :-)

Not very likely then. That hardly sounds like enough to even have the PEP properly discussed on typing-sig. I haven't read it yet. How much code needs to be added to typing.py? Probably better to aim at typing_extensions.

ilevkivskyi · 2019-05-19T22:12:42Z

How much code needs to be added to typing.py?

I think around hundred lines. But I can see how this is very tight.

Probably better to aim at typing_extensions.

OK, makes sense. We can add it there first and then move to typing in 3.9.

jstasiak · 2019-05-20T08:54:10Z

If this lands in typing_extensions would typing_extensions also get an extended get_type_hints() implementation? I assume typing.get_type_hints() would continue to return the extra information until 3.9 by default.

the-knights-who-say-ni added CLA not signed CLA signed and removed CLA not signed labels Apr 26, 2019

till-varoquaux mentioned this pull request Apr 26, 2019

Add support for external annotations in the typing module python/typing#600

Closed

brettcannon requested review from ilevkivskyi and gvanrossum April 26, 2019 21:44

ilevkivskyi requested changes Apr 27, 2019

View reviewed changes

Initial import of PEP 592

2756e19

ilevkivskyi reviewed Apr 29, 2019

View reviewed changes

renamed to pep-593, clarified a lot of "we"s and addressed comments...

9eb4698

till-varoquaux changed the title ~~Initial import of PEP 592: External annotations in the typing module~~ Initial import of PEP 593: Flexible function and variable annotations May 16, 2019

Typo

4cb1502

ilevkivskyi approved these changes May 19, 2019

View reviewed changes

ilevkivskyi merged commit c100af6 into python:master May 19, 2019

hugovk mentioned this pull request Jun 9, 2022

PEP 593: Fix citation references #2640

Merged

	don’t expect clients to have to write lots of boilerplate code::
	don't expect clients to have to write lots of boilerplate code::

	def const_method(self: Const[T]) -> int:
	def const_method(self: Const[List[int]]) -> int:

		@@ -0,0 +1,295 @@
		PEP: 592
		Title: External annotations in the typing module

	``no_type_check`` functionality that current exists in the ``typing``
	``no_type_check`` functionality that currently exists in the ``typing``

	makes use of our new types, seeing as the code would not be immediately
	makes use of our these types, seeing as the code would not be immediately

	* ``Annotated`` can be used as a higher order aliases::
	* ``Annotated`` can be used with nested and generic aliases::

Initial import of PEP 593: Flexible function and variable annotations #1014

Initial import of PEP 593: Flexible function and variable annotations #1014

Conversation

till-varoquaux commented Apr 26, 2019

the-knights-who-say-ni commented Apr 26, 2019

ilevkivskyi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gvanrossum commented Apr 27, 2019

till-varoquaux commented Apr 29, 2019

ilevkivskyi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jstasiak commented May 14, 2019

pfalcon commented May 14, 2019

ilevkivskyi commented May 14, 2019

till-varoquaux commented May 16, 2019

ilevkivskyi left a comment

Choose a reason for hiding this comment

gvanrossum commented May 19, 2019

ilevkivskyi commented May 19, 2019

ilevkivskyi commented May 19, 2019

gvanrossum commented May 19, 2019

ilevkivskyi commented May 19, 2019

jstasiak commented May 20, 2019