From 5a327347e0d99ccade6074381a80d6271b43165c Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 18 Aug 2022 20:40:09 -0500 Subject: [PATCH 1/8] Ensure consistant headings, ref target labels & line breaks --- Doc/whatsnew/3.11.rst | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 2159a3175b91f1..32750ce7346211 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -203,6 +203,7 @@ Irit Katriel in :issue:`45607`.) .. _new-feat-related-type-hints-311: +.. _whatsnew311-typing-features: New Features Related to Type Hints ================================== @@ -210,6 +211,9 @@ New Features Related to Type Hints This section covers major changes affecting :pep:`484` type hints and the :mod:`typing` module. + +.. _whatsnew311-pep646: + PEP 646: Variadic generics -------------------------- @@ -230,6 +234,9 @@ See :pep:`646` for more details. Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew Rahtz, Pradeep Kumar Srinivasan, and Vincent Siles.) + +.. _whatsnew311-pep655: + PEP 655: Marking individual ``TypedDict`` items as required or not-required --------------------------------------------------------------------------- @@ -262,6 +269,9 @@ See :pep:`655` for more details. (Contributed by David Foster and Jelle Zijlstra in :issue:`47087`. PEP written by David Foster.) + +.. _whatsnew311-pep673: + PEP 673: ``Self`` type ---------------------- @@ -295,6 +305,9 @@ See :pep:`673` for more details. (Contributed by James Hilton-Balfe in :issue:`46534`. PEP written by Pradeep Kumar Srinivasan and James Hilton-Balfe.) + +.. _whatsnew311-pep675: + PEP 675: Arbitrary literal string type -------------------------------------- @@ -329,6 +342,9 @@ See :pep:`675` for more details. (Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep Kumar Srinivasan and Graham Bleaney.) + +.. _whatsnew311-pep681: + PEP 681: Data Class Transforms ------------------------------ @@ -362,13 +378,17 @@ See :pep:`681` for more details. (Contributed by Jelle Zijlstra in :gh:`91860`. PEP written by Erik De Bonte and Eric Traut.) -PEP 563 May Not Be the Future + +.. _whatsnew311-pep563-deferred: + +PEP 563 may not be the future ----------------------------- * :pep:`563` Postponed Evaluation of Annotations, ``__future__.annotations`` that was planned for this release has been indefinitely postponed. See `this message `_ for more information. + Other Language Changes ====================== From 412671d5c25c0af3c1312773f0854b160fdb0ab4 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 18 Aug 2022 21:04:16 -0500 Subject: [PATCH 2/8] PEP 646: Copyedit & split description into two shorter paragraphs --- Doc/whatsnew/3.11.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 32750ce7346211..f0d027274293aa 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -217,15 +217,17 @@ the :mod:`typing` module. PEP 646: Variadic generics -------------------------- -:pep:`484` introduced :data:`~typing.TypeVar`, enabling creation -of generics parameterised with a single type. :pep:`646` introduces +:pep:`484` previously introduced :data:`~typing.TypeVar`, enabling creation +of generics parameterised with a single type. :pep:`646` adds :data:`~typing.TypeVarTuple`, enabling parameterisation with an *arbitrary* number of types. In other words, a :data:`~typing.TypeVarTuple` is a *variadic* type variable, -enabling *variadic* generics. This enables a wide variety of use cases. +enabling *variadic* generics. + +This enables a wide variety of use cases. In particular, it allows the type of array-like structures in numerical computing libraries such as NumPy and TensorFlow to be -parameterised with the array *shape*. Static type checkers will now +parameterised with the array *shape*, and static type checkers will now be able to catch shape-related bugs in code that uses these libraries. See :pep:`646` for more details. From f36b3438fffb21c290ed2109424749c92a838a31 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 18 Aug 2022 21:05:46 -0500 Subject: [PATCH 3/8] PEP 655: Describe interaction with total more clearly & copyedit --- Doc/whatsnew/3.11.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index f0d027274293aa..589e86778b73b9 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -244,21 +244,22 @@ PEP 655: Marking individual ``TypedDict`` items as required or not-required :data:`~typing.Required` and :data:`~typing.NotRequired` provide a straightforward way to mark whether individual items in a -:data:`~typing.TypedDict` must be present. Previously this was only possible +:class:`~typing.TypedDict` must be present. Previously, this was only possible using inheritance. -Fields are still required by default, unless the ``total=False`` -parameter is set. -For example, the following specifies a dictionary with one required and -one not-required key:: +All fields are still required by default, +unless the *total* parameter is set to ``False``, +in which case all fields are still not-required by default. +For example, the following specifies a :class:`!TypedDict` +with one required and one not-required key:: class Movie(TypedDict): title: str year: NotRequired[int] - m1: Movie = {"title": "Black Panther", "year": 2018} # ok - m2: Movie = {"title": "Star Wars"} # ok (year is not required) - m3: Movie = {"year": 2022} # error (missing required field title) + m1: Movie = {"title": "Black Panther", "year": 2018} # OK + m2: Movie = {"title": "Star Wars"} # OK (year is not required) + m3: Movie = {"year": 2022} # ERROR (missing required field title) The following definition is equivalent:: From e13edd036e3a572ab13a1e26966491c34e0f07b1 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 18 Aug 2022 21:06:50 -0500 Subject: [PATCH 4/8] PEP 673: Link referred to PEP section directly & classmethod func --- Doc/whatsnew/3.11.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 589e86778b73b9..9a9a984d3862a7 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -280,10 +280,12 @@ PEP 673: ``Self`` type The new :data:`~typing.Self` annotation provides a simple and intuitive way to annotate methods that return an instance of their class. This -behaves the same as the :data:`~typing.TypeVar`-based approach specified -in :pep:`484` but is more concise and easier to follow. +behaves the same as the :data:`~typing.TypeVar`-based approach +:pep:`specified in PEP 484<484#annotating-instance-and-class-methods>`, +but is more concise and easier to follow. -Common use cases include alternative constructors provided as classmethods +Common use cases include alternative constructors provided as +:func:`classmethod `\s, and :meth:`~object.__enter__` methods that return ``self``:: class MyLock: From 814dbab8f76a0ad99b58e04ced393ac8cc750072 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 18 Aug 2022 21:08:47 -0500 Subject: [PATCH 5/8] PEP 681: Copyedit for minor formatting/textual issues --- Doc/whatsnew/3.11.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 9a9a984d3862a7..b2d23660169655 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -356,8 +356,8 @@ PEP 681: Data Class Transforms :data:`~typing.dataclass_transform` may be used to decorate a class, metaclass, or a function that is itself a decorator. The presence of ``@dataclass_transform()`` tells a static type checker that the -decorated object performs runtime "magic" that -transforms a class, giving it :func:`dataclasses.dataclass`-like behaviors. +decorated object performs runtime "magic" that transforms a class, +giving it :func:`dataclass `-like behaviors. For example:: @@ -369,14 +369,13 @@ For example:: cls.__ne__ = ... return cls - # The create_model decorator can now be used to create new model - # classes, like this: + # The create_model decorator can now be used to create new model classes: @create_model class CustomerModel: id: int name: str - c = CustomerModel(id=327, name="John Smith") + c = CustomerModel(id=327, name="Eric Idle") See :pep:`681` for more details. From dc75401b339075bd9891be76d5a5bb21c25e753f Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 18 Aug 2022 21:20:19 -0500 Subject: [PATCH 6/8] PEP 563: Clarify wording, links/references and structure --- Doc/whatsnew/3.11.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index b2d23660169655..72f8a78fc15df4 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -388,9 +388,11 @@ Erik De Bonte and Eric Traut.) PEP 563 may not be the future ----------------------------- -* :pep:`563` Postponed Evaluation of Annotations, ``__future__.annotations`` - that was planned for this release has been indefinitely postponed. - See `this message `_ for more information. +:pep:`563` Postponed Evaluation of Annotations +(the ``from __future__ import annotations`` :ref:`future statement `) +that was originally planned for release in Python 3.10 has been deferred again. +See `this message from the Steering Council `__ +for more information. Other Language Changes From 8bff5eb6277823803b7420587c2af6229a4bea5e Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 18 Aug 2022 23:32:25 -0500 Subject: [PATCH 7/8] Implement minor changes from review feedback --- Doc/whatsnew/3.11.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 72f8a78fc15df4..ebb2b5a53c1019 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -227,7 +227,7 @@ enabling *variadic* generics. This enables a wide variety of use cases. In particular, it allows the type of array-like structures in numerical computing libraries such as NumPy and TensorFlow to be -parameterised with the array *shape*, and static type checkers will now +parameterised with the array *shape*. Static type checkers will now be able to catch shape-related bugs in code that uses these libraries. See :pep:`646` for more details. @@ -390,7 +390,8 @@ PEP 563 may not be the future :pep:`563` Postponed Evaluation of Annotations (the ``from __future__ import annotations`` :ref:`future statement `) -that was originally planned for release in Python 3.10 has been deferred again. +that was originally planned for release in Python 3.10 +has been deferred indefinitely. See `this message from the Steering Council `__ for more information. From 346a23f0fa7b2ddd15511b9a5eb3becc2573deb8 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 20 Aug 2022 02:49:26 -0500 Subject: [PATCH 8/8] Apply further reviewer textual suggestions Co-authored-by: Ezio Melotti Co-authored-by: Alex Waygood --- Doc/whatsnew/3.11.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index ebb2b5a53c1019..62f2072d59f512 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -280,8 +280,8 @@ PEP 673: ``Self`` type The new :data:`~typing.Self` annotation provides a simple and intuitive way to annotate methods that return an instance of their class. This -behaves the same as the :data:`~typing.TypeVar`-based approach -:pep:`specified in PEP 484<484#annotating-instance-and-class-methods>`, +behaves the same as the :class:`~typing.TypeVar`-based approach +:pep:`specified in PEP 484 <484#annotating-instance-and-class-methods>`, but is more concise and easier to follow. Common use cases include alternative constructors provided as @@ -391,7 +391,7 @@ PEP 563 may not be the future :pep:`563` Postponed Evaluation of Annotations (the ``from __future__ import annotations`` :ref:`future statement `) that was originally planned for release in Python 3.10 -has been deferred indefinitely. +has been put on hold indefinitely. See `this message from the Steering Council `__ for more information.