From ab6423fe2de0ed5f8a0dc86a9c7070229326b0f0 Mon Sep 17 00:00:00 2001
From: ananthan-123 <ananthakrishnan15.2001@gmail.com>
Date: Wed, 19 Feb 2020 10:03:05 +0530
Subject: [PATCH] =?UTF-8?q?bpo-39572:=20Document=20=E2=80=99total=E2=80=99?=
 =?UTF-8?q?=20flag=20of=20TypedDict=20(GH-18554)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Doc/library/typing.rst                           | 16 ++++++++++++++--
 Lib/typing.py                                    | 15 ++++++++++++++-
 .../2020-02-18-18-37-07.bpo-39572.CCtzy1.rst     |  1 +
 3 files changed, 29 insertions(+), 3 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2020-02-18-18-37-07.bpo-39572.CCtzy1.rst

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index d3bab94c6dd..eac75ee8654 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -996,8 +996,20 @@ The module defines the following classes, functions and decorators:
       Point2D = TypedDict('Point2D', x=int, y=int, label=str)
       Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
 
-   See :pep:`589` for more examples and detailed rules of using ``TypedDict``
-   with type checkers.
+   By default, all keys must be present in a TypedDict. It is possible
+   to override this by specifying totality.
+   Usage::
+
+      class point2D(TypedDict, total=False):
+          x: int
+          y: int
+
+   This means that a point2D TypedDict can have any of the keys omitted.A type
+   checker is only expected to support a literal False or True as the value of
+   the total argument. True is the default, and makes all items defined in the
+   class body be required.
+
+   See :pep:`589` for more examples and detailed rules of using ``TypedDict``.
 
    .. versionadded:: 3.8
 
diff --git a/Lib/typing.py b/Lib/typing.py
index 6da145fcdb8..0a685d304bd 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -13,7 +13,7 @@ At large scale, the structure of the module is following:
 * Public helper functions: get_type_hints, overload, cast, no_type_check,
   no_type_check_decorator.
 * Generic aliases for collections.abc ABCs and few additional protocols.
-* Special types: NewType, NamedTuple, TypedDict (may be added soon).
+* Special types: NewType, NamedTuple, TypedDict.
 * Wrapper submodules for re and io related types.
 """
 
@@ -1885,6 +1885,19 @@ class TypedDict(dict, metaclass=_TypedDictMeta):
         Point2D = TypedDict('Point2D', x=int, y=int, label=str)
         Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
 
+    By default, all keys must be present in a TypedDict. It is possible
+    to override this by specifying totality.
+    Usage::
+
+        class point2D(TypedDict, total=False):
+            x: int
+            y: int
+
+    This means that a point2D TypedDict can have any of the keys omitted.A type
+    checker is only expected to support a literal False or True as the value of
+    the total argument. True is the default, and makes all items defined in the
+    class body be required.
+
     The class syntax is only supported in Python 3.6+, while two other
     syntax forms work for Python 2.7 and 3.2+
     """
diff --git a/Misc/NEWS.d/next/Documentation/2020-02-18-18-37-07.bpo-39572.CCtzy1.rst b/Misc/NEWS.d/next/Documentation/2020-02-18-18-37-07.bpo-39572.CCtzy1.rst
new file mode 100644
index 00000000000..d47bb455e71
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2020-02-18-18-37-07.bpo-39572.CCtzy1.rst
@@ -0,0 +1 @@
+Updated documentation of ``total`` flag of TypeDict.