[PEP 695] Document Python 3.12 type parameter syntax by JukkaL · Pull Request #17816 · python/mypy

JukkaL · 2024-09-24T16:01:12Z

Provide examples using both syntax variants, and give both of the syntax variants similar prominence. It's likely that both syntax variants will continue to be widely used for a long time.

Also adjust terminology (e.g. use 'type parameter' / 'type argument' more consistently), since otherwise some descriptions would be unclear.

I didn't update examples outside the generics chapter. I'll do this in a follow-up PR.

Work on #17810.

JelleZijlstra

Thank you!

JelleZijlstra · 2024-09-24T16:31:43Z

docs/source/generics.rst

+
+    There are currently no plans to deprecate the legacy syntax.
+    You can freely mix code using the new and old syntax variants,
+    even within a single file.


PEP 695 does say you can't mix them within the same class (https://peps.python.org/pep-0695/#compatibility-with-traditional-typevars). The error cases are quite obscure though, so I'd be OK with not mentioning that.

docs/source/generics.rst

JelleZijlstra · 2024-09-24T16:35:09Z

docs/source/generics.rst

+.. code-block:: python
+
+   class Shape:
+       def set_scale[T: Shape](self: T, scale: float) -> T:


This is the first example using TypeVar bounds, should we introduce the syntax more explicitly?

Yeah, a good idea. I'll do this in a separate PR, since it might involve moving the upper bound section, which will generate a pretty big diff.

Here's the PR that changes the order of sections: #17827

docs/source/generics.rst

JelleZijlstra · 2024-09-24T16:36:43Z

docs/source/generics.rst

-Importantly, this is different from a union type, since combinations
-of ``str`` and ``bytes`` are not accepted:
+No matter which syntax you use, such a type variable is called a type variable
+with a value restriction. Importantly, this is different from a union type,


At runtime we call this a TypeVar with "constraints"; maybe we should also switch to this terminology in mypy?

A good idea. I'll create a follow-up PR (or a documentation issue).

Created an issue: #17828

docs/source/generics.rst

Hnasar

Nice!

Hnasar · 2024-09-24T16:24:23Z

docs/source/generics.rst

+There are two syntax variants for defining generic classes in Python.
+Python 3.12 introduced a new dedicated syntax for defining generic


It'd be nice to link to the docs — maybe this one https://docs.python.org/3/whatsnew/3.12.html#pep-695-type-parameter-syntax

docs/source/generics.rst

Hnasar · 2024-09-24T16:30:06Z

docs/source/generics.rst

+
+   class Shape:
+       def set_scale[T: Shape](self: T, scale: float) -> T:
+           self.scale = scale


Suggested change

class Shape:

def set_scale[T: Shape](self: T, scale: float) -> T:

self.scale = scale

from typing import Self

class Shape:

def set_scale(self, scale: float) -> Self:

self.scale = scale

Since Self is more explicit and concise, I think it's better to reference that here. We can even get rid of the legacy T = TypeVar("T", bound="Shape") which was necessary before Self (added in 3.11).

We discuss Self in the next section, so I'm leaving this as is. The idea is that this also explain how the Self type works behind the scenes. It would be reasonable to introduce Self first, but this can proposed in a separate PR, as it's not directly related to PEP 695 support.

Hnasar · 2024-09-24T16:32:29Z

docs/source/generics.rst

+       other: "Friend | None" = None
+
+       @classmethod
+       def make_pair[T: Friend](cls: type[T]) -> tuple[T, T]:


similarly here, we can make it more concise with

Suggested change

def make_pair[T: Friend](cls: type[T]) -> tuple[T, T]:

def make_pair(cls) -> tuple[Self, Self]:

See my comment above.

Hnasar · 2024-09-24T16:34:05Z

docs/source/generics.rst


-* :py:class:`~typing.List` is an invariant generic type. Naively, one would think
+* ``list`` is an invariant generic type. Naively, one would think
  that it is covariant, like :py:class:`~typing.Sequence` above, but consider this code:


typing.Sequence is deprecated since 3.9 in favor of https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence

docs/source/generics.rst

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>

Finish work started in #17816. Document `type` statement when discussing type aliases. Update some examples to have both old-style and new-style variants. In less common scenarios, examples only use a single syntax variant to reduce verbosity. Also update some examples to generally use more modern features. Closes #17810.

JukkaL added 10 commits September 23, 2024 14:03

Discuss 3.12 generics syntax in a few sections

d326210

Update more documentation to cover 3.12 syntax

9878381

Update TypeVar with value restriction

4829777

Update section on decorators

706c4f7

Update more docs

07d50b4

More updates

98a26e9

Minor updates

18d116c

Fixes and clarifications

3a7ef38

Minor tweaks

6b870b3

Minor tweaks

35adf86

JukkaL requested review from JelleZijlstra, hauntsaninja and ilevkivskyi September 24, 2024 16:01

JelleZijlstra reviewed Sep 24, 2024

View reviewed changes

Hnasar approved these changes Sep 24, 2024

View reviewed changes

brianschubert reviewed Sep 24, 2024

View reviewed changes

docs/source/generics.rst Outdated Show resolved Hide resolved

JukkaL and others added 3 commits September 25, 2024 11:19

Apply suggestions from code review

5992dd9

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>

Apply suggestions from review

7e3eb7d

Update more references to point to collections.abc

0032acd

JukkaL merged commit 58825f7 into master Sep 25, 2024

JukkaL deleted the generics-docs branch September 25, 2024 11:45

JukkaL mentioned this pull request Sep 25, 2024

[PEP 695] Further documentation updates #17826

Merged

JukkaL mentioned this pull request Sep 25, 2024

Replace uses of type variable "value restriction" with "constraints" #17828

Open

		There are two syntax variants for defining generic classes in Python.
		Python 3.12 introduced a new dedicated syntax for defining generic

	def make_pair[T: Friend](cls: type[T]) -> tuple[T, T]:
	def make_pair(cls) -> tuple[Self, Self]:

Uh oh!

Conversation

JukkaL commented Sep 24, 2024

Uh oh!

JelleZijlstra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Hnasar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants