[PEP 695] Document Python 3.12 type parameter syntax #17816

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

@@ -400,7 +565,7 @@ Let us illustrate this by few simple examples:
  triangle. If we give it a callable that can calculate the area of an
  arbitrary shape (not just triangles), everything still works.

-* :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

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

d326210

Update more documentation to cover 3.12 syntax

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

9878381

Update TypeVar with value restriction

4829777

Update section on decorators

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

706c4f7

Update more docs

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

07d50b4

More updates

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

98a26e9

Minor updates

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

18d116c

Fixes and clarifications

3a7ef38

Minor tweaks

6b870b3

Minor tweaks

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

Loading
Loading status checks…

35adf86

JukkaL requested review from JelleZijlstra, ilevkivskyi and hauntsaninja 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 review

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.

GPG key ID: 4AEE18F83AFDEB23
Expired

Verified
Learn about vigilant mode

Loading
Loading status checks…

7e3eb7d

Update more references to point to collections.abc

Loading
Loading status checks…

0032acd

JukkaL merged commit 58825f7 into master Sep 25, 2024
2 checks passed

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[PEP 695] Document Python 3.12 type parameter syntax #17816

[PEP 695] Document Python 3.12 type parameter syntax #17816

JukkaL commented Sep 24, 2024

JelleZijlstra left a comment

JelleZijlstra Sep 24, 2024

JelleZijlstra Sep 24, 2024

JukkaL Sep 25, 2024

JukkaL Sep 25, 2024

JelleZijlstra Sep 24, 2024

JukkaL Sep 25, 2024

JukkaL Sep 25, 2024

Hnasar left a comment

Hnasar Sep 24, 2024

Hnasar Sep 24, 2024

JukkaL Sep 25, 2024

Hnasar Sep 24, 2024

JukkaL Sep 25, 2024

Hnasar Sep 24, 2024

		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]:

[PEP 695] Document Python 3.12 type parameter syntax #17816

[PEP 695] Document Python 3.12 type parameter syntax #17816

Conversation

JukkaL commented Sep 24, 2024

JelleZijlstra 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

Hnasar 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