[Python-checkins] bpo-46066: Deprecate kwargs syntax for TypedDict definitions (GH-31126)
JelleZijlstra
webhook-mailer at python.org
Wed Feb 16 22:26:18 EST 2022
https://github.com/python/cpython/commit/de6043e596492201cc1a1eb28038970bb69f3107
commit: de6043e596492201cc1a1eb28038970bb69f3107
branch: main
author: 97littleleaf11 <11172084+97littleleaf11 at users.noreply.github.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-02-16T19:26:07-08:00
summary:
bpo-46066: Deprecate kwargs syntax for TypedDict definitions (GH-31126)
Closes python/typing#981
https://bugs.python.org/issue46066
files:
A Misc/NEWS.d/next/Library/2022-02-08-16-42-20.bpo-46066.m32Hl0.rst
M Doc/library/typing.rst
M Lib/test/test_typing.py
M Lib/typing.py
M Misc/ACKS
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 94a46b01a1a8c..8240c912c6497 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1470,11 +1470,20 @@ These are not used in annotations. They are building blocks for declaring types.
``Point2D.__optional_keys__``.
To allow using this feature with older versions of Python that do not
support :pep:`526`, ``TypedDict`` supports two additional equivalent
- syntactic forms::
+ syntactic forms:
+
+ * Using a literal :class:`dict` as the second argument::
- Point2D = TypedDict('Point2D', x=int, y=int, label=str)
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
+ * Using keyword arguments::
+
+ Point2D = TypedDict('Point2D', x=int, y=int, label=str)
+
+ .. deprecated-removed:: 3.11 3.13
+ The keyword-argument syntax is deprecated in 3.11 and will be removed
+ in 3.13. It may also be unsupported by static type checkers.
+
By default, all keys must be present in a ``TypedDict``. It is possible to
override this by specifying totality.
Usage::
@@ -1483,6 +1492,9 @@ These are not used in annotations. They are building blocks for declaring types.
x: int
y: int
+ # Alternative syntax
+ Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)
+
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,
diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py
index 2bb5d61068a78..9548a0cab1d1e 100644
--- a/Lib/test/test_typing.py
+++ b/Lib/test/test_typing.py
@@ -4380,7 +4380,8 @@ def test_basics_functional_syntax(self):
self.assertEqual(Emp.__total__, True)
def test_basics_keywords_syntax(self):
- Emp = TypedDict('Emp', name=str, id=int)
+ with self.assertWarns(DeprecationWarning):
+ Emp = TypedDict('Emp', name=str, id=int)
self.assertIsSubclass(Emp, dict)
self.assertIsSubclass(Emp, typing.MutableMapping)
self.assertNotIsSubclass(Emp, collections.abc.Sequence)
@@ -4395,7 +4396,8 @@ def test_basics_keywords_syntax(self):
self.assertEqual(Emp.__total__, True)
def test_typeddict_special_keyword_names(self):
- TD = TypedDict("TD", cls=type, self=object, typename=str, _typename=int, fields=list, _fields=dict)
+ with self.assertWarns(DeprecationWarning):
+ TD = TypedDict("TD", cls=type, self=object, typename=str, _typename=int, fields=list, _fields=dict)
self.assertEqual(TD.__name__, 'TD')
self.assertEqual(TD.__annotations__, {'cls': type, 'self': object, 'typename': str, '_typename': int, 'fields': list, '_fields': dict})
a = TD(cls=str, self=42, typename='foo', _typename=53, fields=[('bar', tuple)], _fields={'baz', set})
@@ -4451,7 +4453,7 @@ def test_py36_class_syntax_usage(self):
def test_pickle(self):
global EmpD # pickle wants to reference the class by name
- EmpD = TypedDict('EmpD', name=str, id=int)
+ EmpD = TypedDict('EmpD', {'name': str, 'id': int})
jane = EmpD({'name': 'jane', 'id': 37})
for proto in range(pickle.HIGHEST_PROTOCOL + 1):
z = pickle.dumps(jane, proto)
@@ -4463,7 +4465,7 @@ def test_pickle(self):
self.assertEqual(EmpDnew({'name': 'jane', 'id': 37}), jane)
def test_optional(self):
- EmpD = TypedDict('EmpD', name=str, id=int)
+ EmpD = TypedDict('EmpD', {'name': str, 'id': int})
self.assertEqual(typing.Optional[EmpD], typing.Union[None, EmpD])
self.assertNotEqual(typing.List[EmpD], typing.Tuple[EmpD])
diff --git a/Lib/typing.py b/Lib/typing.py
index 4a8bdf8132861..3233827d816d1 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -2569,9 +2569,8 @@ class Point2D(TypedDict):
The type info can be accessed via the Point2D.__annotations__ dict, and
the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
- TypedDict supports two additional equivalent forms::
+ TypedDict supports an additional equivalent form::
- 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
@@ -2587,14 +2586,22 @@ class point2D(TypedDict, total=False):
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+
+ The class syntax is only supported in Python 3.6+, while the other
+ syntax form works for Python 2.7 and 3.2+
"""
if fields is None:
fields = kwargs
elif kwargs:
raise TypeError("TypedDict takes either a dict or keyword arguments,"
" but not both")
+ if kwargs:
+ warnings.warn(
+ "The kwargs-based syntax for TypedDict definitions is deprecated "
+ "in Python 3.11, will be removed in Python 3.13, and may not be "
+ "understood by third-party type checkers.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
ns = {'__annotations__': dict(fields)}
module = _caller()
diff --git a/Misc/ACKS b/Misc/ACKS
index 64bd91d7d6905..244d7579b25eb 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1974,6 +1974,7 @@ Arnon Yaari
Alakshendra Yadav
Hirokazu Yamamoto
Masayuki Yamamoto
+Jingchen Ye
Ka-Ping Yee
Chi Hsuan Yen
Jason Yeo
diff --git a/Misc/NEWS.d/next/Library/2022-02-08-16-42-20.bpo-46066.m32Hl0.rst b/Misc/NEWS.d/next/Library/2022-02-08-16-42-20.bpo-46066.m32Hl0.rst
new file mode 100644
index 0000000000000..d13d9421e748b
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-02-08-16-42-20.bpo-46066.m32Hl0.rst
@@ -0,0 +1,3 @@
+Deprecate kwargs-based syntax for :class:`typing.TypedDict` definitions.
+It had confusing semantics when specifying totality, and was largely unused.
+Patch by Jingchen Ye.
More information about the Python-checkins
mailing list