From abed2fb0f95d423282ecebb1f04633adfbbaecc7 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Sat, 25 May 2019 20:36:58 +0100 Subject: [PATCH 1/6] Add TypedDict to typing --- Lib/test/test_typing.py | 109 +++++++++++++++++++++++++++++++++++++++- Lib/typing.py | 84 +++++++++++++++++++++++++++++++ 2 files changed, 192 insertions(+), 1 deletion(-) diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index c9bfd0c7ed720de..abeb2ae05752a0a 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -18,7 +18,7 @@ from typing import no_type_check, no_type_check_decorator from typing import Type from typing import NewType -from typing import NamedTuple +from typing import NamedTuple, TypedDict from typing import IO, TextIO, BinaryIO from typing import Pattern, Match import abc @@ -1774,6 +1774,18 @@ def __str__(self): def __add__(self, other): return 0 +Label = TypedDict('Label', [('label', str)]) + +class Point2D(TypedDict): + x: int + y: int + +class LabelPoint2D(Point2D, Label): ... + +class Options(TypedDict, total=False): + log_level: int + log_path: str + class HasForeignBaseClass(mod_generics_cache.A): some_xrepr: 'XRepr' other_a: 'mod_generics_cache.A' @@ -2549,6 +2561,101 @@ def test_pickle(self): self.assertEqual(jane2, jane) +class TypedDictTests(BaseTestCase): + def test_basics_iterable_syntax(self): + Emp = TypedDict('Emp', {'name': str, 'id': int}) + self.assertIsSubclass(Emp, dict) + self.assertIsSubclass(Emp, typing.MutableMapping) + if sys.version_info[0] >= 3: + import collections.abc + self.assertNotIsSubclass(Emp, collections.abc.Sequence) + jim = Emp(name='Jim', id=1) + self.assertIs(type(jim), dict) + self.assertEqual(jim['name'], 'Jim') + self.assertEqual(jim['id'], 1) + self.assertEqual(Emp.__name__, 'Emp') + self.assertEqual(Emp.__module__, __name__) + self.assertEqual(Emp.__bases__, (dict,)) + self.assertEqual(Emp.__annotations__, {'name': str, 'id': int}) + self.assertEqual(Emp.__total__, True) + + def test_basics_keywords_syntax(self): + Emp = TypedDict('Emp', name=str, id=int) + self.assertIsSubclass(Emp, dict) + self.assertIsSubclass(Emp, typing.MutableMapping) + if sys.version_info[0] >= 3: + import collections.abc + self.assertNotIsSubclass(Emp, collections.abc.Sequence) + jim = Emp(name='Jim', id=1) + self.assertIs(type(jim), dict) + self.assertEqual(jim['name'], 'Jim') + self.assertEqual(jim['id'], 1) + self.assertEqual(Emp.__name__, 'Emp') + self.assertEqual(Emp.__module__, __name__) + self.assertEqual(Emp.__bases__, (dict,)) + self.assertEqual(Emp.__annotations__, {'name': str, 'id': int}) + self.assertEqual(Emp.__total__, True) + + def test_typeddict_errors(self): + Emp = TypedDict('Emp', {'name': str, 'id': int}) + self.assertEqual(TypedDict.__module__, 'typing_extensions') + jim = Emp(name='Jim', id=1) + with self.assertRaises(TypeError): + isinstance({}, Emp) + with self.assertRaises(TypeError): + isinstance(jim, Emp) + with self.assertRaises(TypeError): + issubclass(dict, Emp) + with self.assertRaises(TypeError): + TypedDict('Hi', x=1) + with self.assertRaises(TypeError): + TypedDict('Hi', [('x', int), ('y', 1)]) + with self.assertRaises(TypeError): + TypedDict('Hi', [('x', int)], y=int) + + def test_py36_class_syntax_usage(self): + self.assertEqual(LabelPoint2D.__name__, 'LabelPoint2D') + self.assertEqual(LabelPoint2D.__module__, __name__) + self.assertEqual(LabelPoint2D.__annotations__, {'x': int, 'y': int, 'label': str}) + self.assertEqual(LabelPoint2D.__bases__, (dict,)) + self.assertEqual(LabelPoint2D.__total__, True) + self.assertNotIsSubclass(LabelPoint2D, typing.Sequence) + not_origin = Point2D(x=0, y=1) + self.assertEqual(not_origin['x'], 0) + self.assertEqual(not_origin['y'], 1) + other = LabelPoint2D(x=0, y=1, label='hi') + self.assertEqual(other['label'], 'hi') + + def test_pickle(self): + global EmpD # pickle wants to reference the class by name + 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) + jane2 = pickle.loads(z) + self.assertEqual(jane2, jane) + self.assertEqual(jane2, {'name': 'jane', 'id': 37}) + ZZ = pickle.dumps(EmpD, proto) + EmpDnew = pickle.loads(ZZ) + self.assertEqual(EmpDnew({'name': 'jane', 'id': 37}), jane) + + def test_optional(self): + EmpD = TypedDict('EmpD', name=str, id=int) + + self.assertEqual(typing.Optional[EmpD], typing.Union[None, EmpD]) + self.assertNotEqual(typing.List[EmpD], typing.Tuple[EmpD]) + + def test_total(self): + D = TypedDict('D', {'x': int}, total=False) + self.assertEqual(D(), {}) + self.assertEqual(D(x=1), {'x': 1}) + self.assertEqual(D.__total__, False) + + self.assertEqual(Options(), {}) + self.assertEqual(Options(log_level=2), {'log_level': 2}) + self.assertEqual(Options.__total__, False) + + class IOTests(BaseTestCase): def test_io(self): diff --git a/Lib/typing.py b/Lib/typing.py index 7aab1628a3192b9..f2365165f2b47a6 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -87,6 +87,7 @@ 'Set', 'FrozenSet', 'NamedTuple', # Not really a type. + 'TypedDict', 'Generator', # One-off things. @@ -1417,6 +1418,89 @@ def __new__(self, typename, fields=None, **kwargs): return _make_nmtuple(typename, fields) +def _dict_new(cls, *args, **kwargs): + return dict(*args, **kwargs) + + +def _typeddict_new(cls, _typename, _fields=None, **kwargs): + total = kwargs.pop('total', True) + if _fields is None: + _fields = kwargs + elif kwargs: + raise TypeError("TypedDict takes either a dict or keyword arguments," + " but not both") + + ns = {'__annotations__': dict(_fields), '__total__': total} + try: + # Setting correct module is necessary to make typed dict classes pickleable. + ns['__module__'] = sys._getframe(1).f_globals.get('__name__', '__main__') + except (AttributeError, ValueError): + pass + + return _TypedDictMeta(_typename, (), ns) + + +def _check_fails(cls, other): + # Typed dicts are only for static structural subtyping. + raise TypeError('TypedDict does not support instance and class checks') + + +class _TypedDictMeta(type): + def __new__(cls, name, bases, ns, total=True): + """Create new typed dict class object. + + This method is called directly when TypedDict is subclassed, + or via _typeddict_new when TypedDict is instantiated. This way + TypedDict supports all three syntax forms described in its docstring. + Subclasses and instances of TypedDict return actual dictionaries + via _dict_new. + """ + ns['__new__'] = _typeddict_new if name == 'TypedDict' else _dict_new + tp_dict = super(_TypedDictMeta, cls).__new__(cls, name, (dict,), ns) + + anns = ns.get('__annotations__', {}) + msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type" + anns = {n: _type_check(tp, msg) for n, tp in anns.items()} + for base in bases: + anns.update(base.__dict__.get('__annotations__', {})) + tp_dict.__annotations__ = anns + if not hasattr(tp_dict, '__total__'): + tp_dict.__total__ = total + return tp_dict + + __instancecheck__ = __subclasscheck__ = _check_fails + + +class TypedDict(dict, metaclass=_TypedDictMeta): + """A simple typed name space. At runtime it is equivalent to a plain dict. + + TypedDict creates a dictionary type that expects all of its + instances to have a certain set of keys, with each key + associated with a value of a consistent type. This expectation + is not checked at runtime but is only enforced by type checkers. + Usage:: + + class Point2D(TypedDict): + x: int + y: int + label: str + + a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK + b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check + + assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') + + The type info could be accessed via Point2D.__annotations__. TypedDict + supports two additional equivalent forms:: + + Point2D = TypedDict('Point2D', x=int, y=int, label=str) + Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) + + The class syntax is only supported in Python 3.6+, while two other + syntax forms work for Python 2.7 and 3.2+ + """ + + def NewType(name, tp): """NewType creates simple unique types with almost zero runtime overhead. NewType(name, tp) is considered a subtype of tp From 2f2f069b4de29e21b4dace4ef87e15ed4ef0c4f6 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Sat, 25 May 2019 20:37:53 +0100 Subject: [PATCH 2/6] Fix(update) repr test --- Lib/test/test_typing.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index abeb2ae05752a0a..f55ebd02422d782 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -2598,7 +2598,7 @@ def test_basics_keywords_syntax(self): def test_typeddict_errors(self): Emp = TypedDict('Emp', {'name': str, 'id': int}) - self.assertEqual(TypedDict.__module__, 'typing_extensions') + self.assertEqual(TypedDict.__module__, 'typing') jim = Emp(name='Jim', id=1) with self.assertRaises(TypeError): isinstance({}, Emp) From b1843491381713cfc059ff48e24826f45d95c4bb Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Sat, 25 May 2019 20:46:59 +0100 Subject: [PATCH 3/6] Add docs --- Doc/library/typing.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 86a3db8467ec742..3cf8611689fcc76 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -878,6 +878,34 @@ The module defines the following classes, functions and decorators: The ``_field_types`` and ``__annotations__`` attributes are now regular dictionaries instead of instances of ``OrderedDict``. +.. class:: TypedDict(dict) + + A simple typed name space. At runtime it is equivalent to + a plain :class:`dict`. + + ``TypedDict`` creates a dictionary type that expects all of its + instances to have a certain set of keys, with each key + associated with a value of a consistent type. This expectation + is not checked at runtime but is only enforced by type checkers. + Usage:: + + class Point2D(TypedDict): + x: int + y: int + label: str + + a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK + b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check + + assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') + + The type info for introspection could be accessed via ``Point2D.__annotations__`` + and ``Point2D.__total__``. Backward-compatible usage:: + + Point2D = TypedDict('Point2D', x=int, y=int, label=str) + Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) + + .. versionadded:: 3.8 .. function:: NewType(typ) From 41fa983082e183d47fc9f53e3d37d7a814a86f08 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" Date: Sat, 25 May 2019 19:48:44 +0000 Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../NEWS.d/next/Library/2019-05-25-19-48-42.bpo-37049.an2LXJ.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Library/2019-05-25-19-48-42.bpo-37049.an2LXJ.rst diff --git a/Misc/NEWS.d/next/Library/2019-05-25-19-48-42.bpo-37049.an2LXJ.rst b/Misc/NEWS.d/next/Library/2019-05-25-19-48-42.bpo-37049.an2LXJ.rst new file mode 100644 index 000000000000000..e0ce4a708d9eb74 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2019-05-25-19-48-42.bpo-37049.an2LXJ.rst @@ -0,0 +1 @@ +PEP 589: Add ``TypedDict`` to the ``typing`` module. \ No newline at end of file From c9b868404b06f796feaacfdc662fb68ccc40cf78 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Sun, 26 May 2019 00:03:14 +0100 Subject: [PATCH 5/6] Address CR --- Doc/library/typing.rst | 13 +++++++++---- Lib/test/test_typing.py | 10 +++------- Lib/typing.py | 6 +++--- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 3cf8611689fcc76..9c8399610c9a0cf 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -880,11 +880,11 @@ The module defines the following classes, functions and decorators: .. class:: TypedDict(dict) - A simple typed name space. At runtime it is equivalent to + A simple typed namespace. At runtime it is equivalent to a plain :class:`dict`. ``TypedDict`` creates a dictionary type that expects all of its - instances to have a certain set of keys, with each key + instances to have a certain set of keys, where each key is associated with a value of a consistent type. This expectation is not checked at runtime but is only enforced by type checkers. Usage:: @@ -899,12 +899,17 @@ The module defines the following classes, functions and decorators: assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') - The type info for introspection could be accessed via ``Point2D.__annotations__`` - and ``Point2D.__total__``. Backward-compatible usage:: + The type info for introspection can be accessed via ``Point2D.__annotations__`` + and ``Point2D.__total__``. To allow using this feature with older versions + of Python that do not support :pep:`526`, ``TypedDict`` supports two additional + equivalent syntactic forms:: 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. + .. versionadded:: 3.8 .. function:: NewType(typ) diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index f55ebd02422d782..ae1b9c8cd5fcaf2 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -2562,13 +2562,11 @@ def test_pickle(self): class TypedDictTests(BaseTestCase): - def test_basics_iterable_syntax(self): + def test_basics_functional_syntax(self): Emp = TypedDict('Emp', {'name': str, 'id': int}) self.assertIsSubclass(Emp, dict) self.assertIsSubclass(Emp, typing.MutableMapping) - if sys.version_info[0] >= 3: - import collections.abc - self.assertNotIsSubclass(Emp, collections.abc.Sequence) + self.assertNotIsSubclass(Emp, collections.abc.Sequence) jim = Emp(name='Jim', id=1) self.assertIs(type(jim), dict) self.assertEqual(jim['name'], 'Jim') @@ -2583,9 +2581,7 @@ def test_basics_keywords_syntax(self): Emp = TypedDict('Emp', name=str, id=int) self.assertIsSubclass(Emp, dict) self.assertIsSubclass(Emp, typing.MutableMapping) - if sys.version_info[0] >= 3: - import collections.abc - self.assertNotIsSubclass(Emp, collections.abc.Sequence) + self.assertNotIsSubclass(Emp, collections.abc.Sequence) jim = Emp(name='Jim', id=1) self.assertIs(type(jim), dict) self.assertEqual(jim['name'], 'Jim') diff --git a/Lib/typing.py b/Lib/typing.py index f2365165f2b47a6..d6ba4d1b8788d5d 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -87,7 +87,7 @@ 'Set', 'FrozenSet', 'NamedTuple', # Not really a type. - 'TypedDict', + 'TypedDict', # Not really a type. 'Generator', # One-off things. @@ -1472,10 +1472,10 @@ def __new__(cls, name, bases, ns, total=True): class TypedDict(dict, metaclass=_TypedDictMeta): - """A simple typed name space. At runtime it is equivalent to a plain dict. + """A simple typed namespace. At runtime it is equivalent to a plain dict. TypedDict creates a dictionary type that expects all of its - instances to have a certain set of keys, with each key + instances to have a certain set of keys, where each key is associated with a value of a consistent type. This expectation is not checked at runtime but is only enforced by type checkers. Usage:: From 2c0c8dacb305b7213acb400ff19659d330ba855a Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Sun, 26 May 2019 00:05:57 +0100 Subject: [PATCH 6/6] can --- Lib/typing.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/typing.py b/Lib/typing.py index d6ba4d1b8788d5d..790f397aedb0239 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -1490,7 +1490,7 @@ class Point2D(TypedDict): assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') - The type info could be accessed via Point2D.__annotations__. TypedDict + The type info can be accessed via Point2D.__annotations__. TypedDict supports two additional equivalent forms:: Point2D = TypedDict('Point2D', x=int, y=int, label=str)