From f0d92e249f3b255759614db91010a45d1e724432 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 12 Apr 2022 20:28:10 -0700 Subject: [PATCH 1/4] gh-91491: What's New in 3.11 section for typing PEPs Other aspects of typing aren't covered yet; I'll do that in a separate PR. --- Doc/whatsnew/3.11.rst | 130 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 2 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 6540a255a0ed82c..0da19d92a05b84d 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -74,8 +74,11 @@ New syntax features: New typing features: -* :pep:`673`: ``Self`` Type. - (Contributed by James Hilton-Balfe and Pradeep Kumar in :issue:`30924`.) +* :pep:`646`: Variadic generics. +* :pep:`655`: Marking individual TypedDict items as required or potentially-missing. +* :pep:`673`: ``Self`` type. +* :pep:`675`: Arbitrary literal string type. + New Features ============ @@ -167,6 +170,129 @@ default traceback. See :pep:`678` for more details. (Contributed by Irit Katriel in :issue:`45607`.) +.. _new-feat-related-type-hints: + +New Features Related to Type Hints +================================== + +This section covers major changes affecting :pep:`484` type hints and +the :mod:`typing` module. + +PEP 646: Variadic generics +-------------------------- + +:pep:`484` introduced ``TypeVar``, enabling creation of generics parameterised +with a single type. The new :data:`TypeVarTuple` enables parameterisation +with an *arbitrary* number of types - that is, a *variadic* type variable, +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*, enabling static type checkers +to catch shape-related bugs in code that uses these libraries. + +See :pep:`646` for more details. + +(Contributed by Matthew Rahtz in :issue:`43224`, with contributions by +Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew +Rahtz, Pradeep Kumar, and Vincent Siles.) + +PEP 655: Marking individual ``TypedDict`` items as required or non-required +--------------------------------------------------------------------------- + +:data:`typing.Required` and :data:`typing.NotRequired` provide a +straightforward way to mark whether individual items in a +:data:`TypedDict` must be present. Previously, this was only possible +using inheritance. + +As before, fields are required by default, unless the ``total=False`` +parameter is set. +For example, the following specifies a dictionary with one required and +one non-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) + +The following definition is equivalent:: + + class Movie(TypedDict, total=False): + title: Required[str] + year: int + +See :pep:`655` for more details. + +(Contributed by David Foster and Jelle Zijlstra in :issue:`47087`. PEP +written by David Foster.) + +PEP 673: ``Self`` type +---------------------- + +The new :data:`typing.Self` annotation provides a simple and intuitive +way to annotate methods that returnan 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. + +Common use cases include alternative constructors provided as classmethods +and :meth:`~object.__enter__` methods that return ``self``:: + + class MyLock: + def __enter__(self) -> Self: + self.lock() + return self + + ... + + class MyInt: + @classmethod + def fromhex(cls, s: str) -> Self: + return cls(int(s, 16)) + + ... + +See :pep:`673` for more details. + +(Contributed by James Hilton-Balfe in :issue:`46534`. PEP written by +Pradeep Kumar and James Hilton-Balfe.) + +PEP 675: Arbitrary literal string type +-------------------------------------- + +The new :data:`typing.LiteralString` annotation may be used to indicate +that a function parameter can be of any literal string type. This allows +a function to accept arbitrary literal string types, as well as strings +created from other literal strings. This allows static type checkers to +enforce that sensitive functions, such as those that execute SQL +statements or shell commands, are called only with static arguments, +which provides some protection against injection attacks. + +For example, a SQL query function could be annotated as follows:: + + def run_query(sql: LiteralString) -> ... + ... + + def caller( + arbitrary_string: str, + query_string: LiteralString, + table_name: LiteralString, + ) -> None: + run_query("SELECT * FROM students") # ok + run_query(query_string) # ok + run_query("SELECT * FROM " + table_name) # ok + run_query(arbitrary_string) # type checker error + run_query( # type checker error + f"SELECT * FROM students WHERE name = {arbitrary_string}" + ) + +See :pep:`675` for more details. + +(Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep +Kumar and Graham Bleaney.) + + Other Language Changes ====================== From b0e1c482aa3cb8e2d6b118fd048aa367909c36a8 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 19 Apr 2022 20:39:59 -0700 Subject: [PATCH 2/4] don't reuse 3.10's label --- Doc/whatsnew/3.11.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 0da19d92a05b84d..dba5e8a183ba052 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -170,7 +170,7 @@ default traceback. See :pep:`678` for more details. (Contributed by Irit Katriel in :issue:`45607`.) -.. _new-feat-related-type-hints: +.. _new-feat-related-type-hints-311: New Features Related to Type Hints ================================== From dffc0bcce21232ef97798a14a3f546a257a99783 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Wed, 20 Apr 2022 19:23:03 -0700 Subject: [PATCH 3/4] Feedback from Ken, James, Alex, David --- Doc/whatsnew/3.11.rst | 45 ++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index dba5e8a183ba052..57ccb082794f7f8 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -181,14 +181,16 @@ the :mod:`typing` module. PEP 646: Variadic generics -------------------------- -:pep:`484` introduced ``TypeVar``, enabling creation of generics parameterised -with a single type. The new :data:`TypeVarTuple` enables parameterisation -with an *arbitrary* number of types - that is, a *variadic* type variable, +:pep:`484` introduced :data:`~typing.TypeVar`, enabling creation +of generics parameterised with a single type. :pep:`646` introduces +: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. 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*, enabling static type checkers -to catch shape-related bugs in code that uses these libraries. +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. @@ -196,18 +198,18 @@ See :pep:`646` for more details. Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew Rahtz, Pradeep Kumar, and Vincent Siles.) -PEP 655: Marking individual ``TypedDict`` items as required or non-required +PEP 655: Marking individual ``TypedDict`` items as required or not-required --------------------------------------------------------------------------- -:data:`typing.Required` and :data:`typing.NotRequired` provide a +:data:`~typing.Required` and :data:`~typing.NotRequired` provide a straightforward way to mark whether individual items in a -:data:`TypedDict` must be present. Previously, this was only possible +:data:`~typing.TypedDict` must be present. Previously this was only possible using inheritance. -As before, fields are required by default, unless the ``total=False`` +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 non-required key:: +one not-required key:: class Movie(TypedDict): title: str @@ -231,9 +233,9 @@ written by David Foster.) PEP 673: ``Self`` type ---------------------- -The new :data:`typing.Self` annotation provides a simple and intuitive -way to annotate methods that returnan instance of their class. This -behaves the same as the :data:`typing.TypeVar`-based approach specified +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. Common use cases include alternative constructors provided as classmethods @@ -253,6 +255,9 @@ and :meth:`~object.__enter__` methods that return ``self``:: ... +:data:`~typing.Self` can also be used to annotate method parameters +or attributes of the same type as their enclosing class. + See :pep:`673` for more details. (Contributed by James Hilton-Balfe in :issue:`46534`. PEP written by @@ -261,13 +266,13 @@ Pradeep Kumar and James Hilton-Balfe.) PEP 675: Arbitrary literal string type -------------------------------------- -The new :data:`typing.LiteralString` annotation may be used to indicate +The new :data:`~typing.LiteralString` annotation may be used to indicate that a function parameter can be of any literal string type. This allows a function to accept arbitrary literal string types, as well as strings -created from other literal strings. This allows static type checkers to +created from other literal strings. Type checkers can then enforce that sensitive functions, such as those that execute SQL statements or shell commands, are called only with static arguments, -which provides some protection against injection attacks. +providing protection against injection attacks. For example, a SQL query function could be annotated as follows:: @@ -279,11 +284,11 @@ For example, a SQL query function could be annotated as follows:: query_string: LiteralString, table_name: LiteralString, ) -> None: - run_query("SELECT * FROM students") # ok - run_query(query_string) # ok + run_query("SELECT * FROM students") # ok + run_query(query_string) # ok run_query("SELECT * FROM " + table_name) # ok - run_query(arbitrary_string) # type checker error - run_query( # type checker error + run_query(arbitrary_string) # type checker error + run_query( # type checker error f"SELECT * FROM students WHERE name = {arbitrary_string}" ) From 46b08e66ed70a3344073c5c5603ef4e9e283de53 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sat, 23 Apr 2022 11:22:06 -0700 Subject: [PATCH 4/4] Fix Pradeep's name Co-authored-by: Pradeep Kumar --- 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 57ccb082794f7f8..a668398eca0a756 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -196,7 +196,7 @@ See :pep:`646` for more details. (Contributed by Matthew Rahtz in :issue:`43224`, with contributions by Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew -Rahtz, Pradeep Kumar, and Vincent Siles.) +Rahtz, Pradeep Kumar Srinivasan, and Vincent Siles.) PEP 655: Marking individual ``TypedDict`` items as required or not-required --------------------------------------------------------------------------- @@ -261,7 +261,7 @@ or attributes of the same type as their enclosing class. See :pep:`673` for more details. (Contributed by James Hilton-Balfe in :issue:`46534`. PEP written by -Pradeep Kumar and James Hilton-Balfe.) +Pradeep Kumar Srinivasan and James Hilton-Balfe.) PEP 675: Arbitrary literal string type -------------------------------------- @@ -295,7 +295,7 @@ For example, a SQL query function could be annotated as follows:: See :pep:`675` for more details. (Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep -Kumar and Graham Bleaney.) +Kumar Srinivasan and Graham Bleaney.) Other Language Changes