https://github.com/python/cpython/commit/ab6423fe2de0ed5f8a0dc86a9c707022932... commit: ab6423fe2de0ed5f8a0dc86a9c7070229326b0f0 branch: master author: ananthan-123 <ananthakrishnan15.2001@gmail.com> committer: GitHub <noreply@github.com> date: 2020-02-18T20:33:05-08:00 summary: bpo-39572: Document ’total’ flag of TypedDict (GH-18554) files: A Misc/NEWS.d/next/Documentation/2020-02-18-18-37-07.bpo-39572.CCtzy1.rst M Doc/library/typing.rst M Lib/typing.py diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d3bab94c6dd40..eac75ee8654f5 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 6da145fcdb83a..0a685d304bd96 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -13,7 +13,7 @@ * 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 Point2D(TypedDict): 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 0000000000000..d47bb455e71d1 --- /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.