From e678672ff91e2abc3d339da5d6a972b4c6bd9714 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 19 Sep 2022 08:44:01 -0500 Subject: [PATCH] gh-95913: Copyedit, link & format Typing Features section in 3.11 What's New (GH-96097) Co-authored-by: Ezio Melotti Co-authored-by: Alex Waygood (cherry picked from commit 558768ff22e47582ae95ad7c3f8955407934916e) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 73 +++++++++++++++++++++++++++++-------------- 1 file changed, 50 insertions(+), 23 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 15ca1249b1625b..277d786e35df3a 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,15 +211,20 @@ 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 -------------------------- -: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 @@ -230,26 +236,30 @@ 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 --------------------------------------------------------------------------- :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:: @@ -262,15 +272,20 @@ 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 ---------------------- 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 :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 classmethods +Common use cases include alternative constructors provided as +:func:`classmethod `\s, and :meth:`~object.__enter__` methods that return ``self``:: class MyLock: @@ -295,6 +310,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,14 +347,17 @@ 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 ------------------------------ :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:: @@ -348,26 +369,32 @@ 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. (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. +: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 put on hold indefinitely. +See `this message from the Steering Council `__ +for more information. + Windows py.exe launcher improvements ------------------------------------