From a2d8071ff5e6c7a48c6a78efca4d57e43c0ddaa5 Mon Sep 17 00:00:00 2001 From: David Foster Date: Tue, 24 May 2022 06:49:29 -0700 Subject: [PATCH 01/15] gh-91243: Document Required and NotRequired --- Doc/library/typing.rst | 57 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7ddc84ac5e4518..ec0634f2dca730 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -78,6 +78,8 @@ annotations. These include: *Introducing* :data:`TypeVarTuple` * :pep:`647`: User-Defined Type Guards *Introducing* :data:`TypeGuard` +* :pep:`655`: Marking individual TypedDict items as required or potentially-missing + *Introducing* :data:`Required` and :data:`NotRequired` * :pep:`673`: Self type *Introducing* :data:`Self` * :pep:`675`: Arbitrary Literal String Type @@ -1022,6 +1024,18 @@ These can be used as types in annotations using ``[]``, each having a unique syn .. versionadded:: 3.8 +.. data:: Required + +.. data:: NotRequired + + A special typing construct that marks individual keys of a :class:`TypedDict` + as either required or non-required respectively. + + For more information, see + :pep:`655` (Marking individual TypedDict items as required or potentially-missing). + + .. versionadded:: 3.11 + .. data:: Annotated A type, introduced in :pep:`593` (``Flexible function and variable @@ -1706,7 +1720,21 @@ These are not used in annotations. They are building blocks for declaring types. Point2D = TypedDict('Point2D', {'in': int, 'x-y': int}) By default, all keys must be present in a ``TypedDict``. It is possible to - override this by specifying totality. + mark individual keys as non-required using ``NotRequired``:: + + class Point2D(TypedDict): + x: int + y: int + label: NotRequired[str] + + # Alternative syntax + Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]}) + + This means that a ``Point2D`` ``TypedDict`` can have the ``label`` + key omitted. + + It is also possible to mark all keys as non-required by default + by specifying a totality of ``False``. Usage:: class Point2D(TypedDict, total=False): @@ -1721,6 +1749,21 @@ These are not used in annotations. They are building blocks for declaring types. ``True`` as the value of the ``total`` argument. ``True`` is the default, and makes all items defined in the class body required. + Individual keys of a ``total=False`` ``TypedDict`` can be marked as + required using ``Required``:: + + class Point2D(TypedDict, total=False): + x: Required[int] + y: Required[int] + label: str + + # Alternative syntax + Point2D = TypedDict('Point2D', { + 'x': Required[int], + 'y': Required[int], + 'label': str + }, total=False) + It is possible for a ``TypedDict`` type to inherit from one or more other ``TypedDict`` types using the class-based syntax. Usage:: @@ -1785,8 +1828,12 @@ These are not used in annotations. They are building blocks for declaring types. ``Point2D.__required_keys__`` and ``Point2D.__optional_keys__`` return :class:`frozenset` objects containing required and non-required keys, respectively. - Currently the only way to declare both required and non-required keys in the - same ``TypedDict`` is mixed inheritance, declaring a ``TypedDict`` with one value + + Keys marked with ``Required`` will always appear in ``__required_keys__`` + and keys marked with ``NotRequired`` will always appear in ``__optional_keys__``. + + It is also possible to use mixed inheritance to declare both required and + non-required keys in the same ``TypedDict`` , declaring a ``TypedDict`` with one value for the ``total`` argument and then inheriting it from another ``TypedDict`` with a different value for ``total``. Usage:: @@ -1807,6 +1854,10 @@ These are not used in annotations. They are building blocks for declaring types. .. versionadded:: 3.8 + .. versionchanged:: 3.11 + Added support for marking individual keys as ``Required`` or ``NotRequired``. + See :pep:`655`. + .. versionchanged:: 3.11 Added support for generic ``TypedDict``\ s. From 1cda51f7a6be4f4a79836f8cf815bd395ae22212 Mon Sep 17 00:00:00 2001 From: David Foster Date: Wed, 25 May 2022 06:58:53 -0700 Subject: [PATCH 02/15] Mark TypedDict inheritance trick as a 'backward-compatible' usage --- Doc/library/typing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index ec0634f2dca730..d8e63b7e5a728d 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1832,7 +1832,8 @@ These are not used in annotations. They are building blocks for declaring types. Keys marked with ``Required`` will always appear in ``__required_keys__`` and keys marked with ``NotRequired`` will always appear in ``__optional_keys__``. - It is also possible to use mixed inheritance to declare both required and + For backwards compatibility with Python 3.10 and below, + it is also possible to use mixed inheritance to declare both required and non-required keys in the same ``TypedDict`` , declaring a ``TypedDict`` with one value for the ``total`` argument and then inheriting it from another ``TypedDict`` with a different value for ``total``. From a999c2597dae4585ff27c2fb61e8b5d335f80f23 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 08:36:15 -0400 Subject: [PATCH 03/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d8e63b7e5a728d..0605d8a43ea0ef 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1028,7 +1028,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn .. data:: NotRequired - A special typing construct that marks individual keys of a :class:`TypedDict` + Special typing constructs that mark individual keys of a :class:`TypedDict` as either required or non-required respectively. For more information, see From 7bf80eb456afd48694cc2d6005c51b55267a7cae Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 08:36:29 -0400 Subject: [PATCH 04/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 0605d8a43ea0ef..206eebe6f10725 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1720,7 +1720,7 @@ These are not used in annotations. They are building blocks for declaring types. Point2D = TypedDict('Point2D', {'in': int, 'x-y': int}) By default, all keys must be present in a ``TypedDict``. It is possible to - mark individual keys as non-required using ``NotRequired``:: + mark individual keys as non-required using :data:`NotRequired`:: class Point2D(TypedDict): x: int From d46a42e5e92bf24ad16985f826145feed9b2eb89 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 08:36:38 -0400 Subject: [PATCH 05/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 206eebe6f10725..7a7a1b488e5c0f 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1750,7 +1750,7 @@ These are not used in annotations. They are building blocks for declaring types. and makes all items defined in the class body required. Individual keys of a ``total=False`` ``TypedDict`` can be marked as - required using ``Required``:: + required using :data:`Required`:: class Point2D(TypedDict, total=False): x: Required[int] From d9061dac3611436426822c608438aaed60530fba Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 08:36:45 -0400 Subject: [PATCH 06/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7a7a1b488e5c0f..4e3f60f040c37f 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1829,7 +1829,7 @@ These are not used in annotations. They are building blocks for declaring types. ``Point2D.__required_keys__`` and ``Point2D.__optional_keys__`` return :class:`frozenset` objects containing required and non-required keys, respectively. - Keys marked with ``Required`` will always appear in ``__required_keys__`` + Keys marked with :data:`Required` will always appear in ``__required_keys__`` and keys marked with ``NotRequired`` will always appear in ``__optional_keys__``. For backwards compatibility with Python 3.10 and below, From ff9aa50a1b3b43e84617878c730ea71f94d28910 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 08:37:41 -0400 Subject: [PATCH 07/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 4e3f60f040c37f..399e3d0583d8e0 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1031,7 +1031,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn Special typing constructs that mark individual keys of a :class:`TypedDict` as either required or non-required respectively. - For more information, see + For more information, see :class:`TypedDict` and :pep:`655` (Marking individual TypedDict items as required or potentially-missing). .. versionadded:: 3.11 From 5b06f2bfd36d908332bb3ea5994354aec7c8889a Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 08:37:49 -0400 Subject: [PATCH 08/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 399e3d0583d8e0..14b58a90f008a0 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1833,7 +1833,7 @@ These are not used in annotations. They are building blocks for declaring types. and keys marked with ``NotRequired`` will always appear in ``__optional_keys__``. For backwards compatibility with Python 3.10 and below, - it is also possible to use mixed inheritance to declare both required and + it is also possible to use inheritance to declare both required and non-required keys in the same ``TypedDict`` , declaring a ``TypedDict`` with one value for the ``total`` argument and then inheriting it from another ``TypedDict`` with a different value for ``total``. From e9f9fd7904dd816954e47e8e3652f3a4b318c9a8 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 05:45:52 -0700 Subject: [PATCH 09/15] Update Doc/library/typing.rst --- Doc/library/typing.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 14b58a90f008a0..f2ac81c6cb4343 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1734,8 +1734,7 @@ These are not used in annotations. They are building blocks for declaring types. key omitted. It is also possible to mark all keys as non-required by default - by specifying a totality of ``False``. - Usage:: + by specifying a totality of ``False``:: class Point2D(TypedDict, total=False): x: int From 1ac5fec826db2f8ac24699b905ed3af8bd1c3b70 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 10:21:02 -0400 Subject: [PATCH 10/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index f2ac81c6cb4343..51ef12e5d1b65e 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1032,7 +1032,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn as either required or non-required respectively. For more information, see :class:`TypedDict` and - :pep:`655` (Marking individual TypedDict items as required or potentially-missing). + :pep:`655` ("Marking individual TypedDict items as required or potentially-missing"). .. versionadded:: 3.11 From 06ae9189c26c9b260e11bb4f7a799a927ee0983f Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 10:21:25 -0400 Subject: [PATCH 11/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 51ef12e5d1b65e..6dfc1dc532c6cb 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1829,7 +1829,7 @@ These are not used in annotations. They are building blocks for declaring types. :class:`frozenset` objects containing required and non-required keys, respectively. Keys marked with :data:`Required` will always appear in ``__required_keys__`` - and keys marked with ``NotRequired`` will always appear in ``__optional_keys__``. + and keys marked with :data:`NotRequired` will always appear in ``__optional_keys__``. For backwards compatibility with Python 3.10 and below, it is also possible to use inheritance to declare both required and From d97baa7d400297dec397cdbce5d5dab00ed4d06b Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 10:21:33 -0400 Subject: [PATCH 12/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 6dfc1dc532c6cb..15958738c928af 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1855,7 +1855,7 @@ These are not used in annotations. They are building blocks for declaring types. .. versionadded:: 3.8 .. versionchanged:: 3.11 - Added support for marking individual keys as ``Required`` or ``NotRequired``. + Added support for marking individual keys as :data`Required` or :data:`NotRequired`. See :pep:`655`. .. versionchanged:: 3.11 From c503c393e9dc3b00ebe9f3c107c635ac4ab18325 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 10:23:25 -0400 Subject: [PATCH 13/15] Update Doc/library/typing.rst Co-authored-by: Alex Waygood --- Doc/library/typing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 15958738c928af..8c5bbb124758e6 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1833,10 +1833,10 @@ These are not used in annotations. They are building blocks for declaring types. For backwards compatibility with Python 3.10 and below, it is also possible to use inheritance to declare both required and - non-required keys in the same ``TypedDict`` , declaring a ``TypedDict`` with one value - for the ``total`` argument and then inheriting it from another ``TypedDict`` with - a different value for ``total``. - Usage:: + non-required keys in the same ``TypedDict`` . This is done by declaring a + ``TypedDict`` with one value for the ``total`` argument, and then + inheriting from it in another ``TypedDict`` with a different value for + ``total``:: >>> class Point2D(TypedDict, total=False): ... x: int From 182239dc3b4b9c8a9b37c9dc83a9a79d2dee1041 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 07:23:50 -0700 Subject: [PATCH 14/15] Wordsmith comma --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 8c5bbb124758e6..d185edd09f8bbf 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1834,7 +1834,7 @@ These are not used in annotations. They are building blocks for declaring types. For backwards compatibility with Python 3.10 and below, it is also possible to use inheritance to declare both required and non-required keys in the same ``TypedDict`` . This is done by declaring a - ``TypedDict`` with one value for the ``total`` argument, and then + ``TypedDict`` with one value for the ``total`` argument and then inheriting from it in another ``TypedDict`` with a different value for ``total``:: From f0f47077fabf2d77abe0e44ac743e7560ba0f889 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 26 May 2022 07:25:08 -0700 Subject: [PATCH 15/15] Fix typo --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d185edd09f8bbf..c7c5536a64fb41 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1855,7 +1855,7 @@ These are not used in annotations. They are building blocks for declaring types. .. versionadded:: 3.8 .. versionchanged:: 3.11 - Added support for marking individual keys as :data`Required` or :data:`NotRequired`. + Added support for marking individual keys as :data:`Required` or :data:`NotRequired`. See :pep:`655`. .. versionchanged:: 3.11