Debian Codegraph @

Lib/test/test_annotationlib.py

raw
1 """Tests for the annotations module."""
2
3 import textwrap
4 import annotationlib
5 import builtins
6 import collections
7 import functools
8 import itertools
9 import pickle
10 from string.templatelib import Template, Interpolation
11 import types
12 import typing
13 import sys
14 import unittest
15 from annotationlib import (
16 Format,
17 ForwardRef,
18 get_annotations,
19 annotations_to_string,
20 type_repr,
21 )
22 from typing import Unpack, get_type_hints, List, Union
23
24 from test import support
25 from test.support import import_helper
26 from test.test_inspect import inspect_stock_annotations
27 from test.test_inspect import inspect_stringized_annotations
28 from test.test_inspect import inspect_stringized_annotations_2
29 from test.test_inspect import inspect_stringized_annotations_pep695
30
31
32 def times_three(fn):
33 @functools.wraps(fn)
34 def wrapper(a, b):
35 return fn(a * 3, b * 3)
36
37 return wrapper
38
39
40 class MyClass:
41 def __repr__(self):
42 return "my repr"
43
44
45 class TestFormat(unittest.TestCase):
46 def test_enum(self):
47 self.assertEqual(Format.VALUE.value, 1)
48 self.assertEqual(Format.VALUE, 1)
49
50 self.assertEqual(Format.VALUE_WITH_FAKE_GLOBALS.value, 2)
51 self.assertEqual(Format.VALUE_WITH_FAKE_GLOBALS, 2)
52
53 self.assertEqual(Format.FORWARDREF.value, 3)
54 self.assertEqual(Format.FORWARDREF, 3)
55
56 self.assertEqual(Format.STRING.value, 4)
57 self.assertEqual(Format.STRING, 4)
58
59
60 class TestForwardRefFormat(unittest.TestCase):
61 def test_closure(self):
62 def inner(arg: x):
63 pass
64
65 anno = get_annotations(inner, format=Format.FORWARDREF)
66 fwdref = anno["arg"]
67 self.assertIsInstance(fwdref, ForwardRef)
68 self.assertEqual(fwdref.__forward_arg__, "x")
69 with self.assertRaises(NameError):
70 fwdref.evaluate()
71
72 x = 1
73 self.assertEqual(fwdref.evaluate(), x)
74
75 anno = get_annotations(inner, format=Format.FORWARDREF)
76 self.assertEqual(anno["arg"], x)
77
78 def test_multiple_closure(self):
79 def inner(arg: x[y]):
80 pass
81
82 fwdref = get_annotations(inner, format=Format.FORWARDREF)["arg"]
83 self.assertIsInstance(fwdref, ForwardRef)
84 self.assertEqual(fwdref.__forward_arg__, "x[y]")
85 with self.assertRaises(NameError):
86 fwdref.evaluate()
87
88 y = str
89 fwdref = get_annotations(inner, format=Format.FORWARDREF)["arg"]
90 self.assertIsInstance(fwdref, ForwardRef)
91 extra_name, extra_val = next(iter(fwdref.__extra_names__.items()))
92 self.assertEqual(fwdref.__forward_arg__.replace(extra_name, extra_val.__name__), "x[str]")
93 with self.assertRaises(NameError):
94 fwdref.evaluate()
95
96 x = list
97 self.assertEqual(fwdref.evaluate(), x[y])
98
99 fwdref = get_annotations(inner, format=Format.FORWARDREF)["arg"]
100 self.assertEqual(fwdref, x[y])
101
102 def test_function(self):
103 def f(x: int, y: doesntexist):
104 pass
105
106 anno = get_annotations(f, format=Format.FORWARDREF)
107 self.assertIs(anno["x"], int)
108 fwdref = anno["y"]
109 self.assertIsInstance(fwdref, ForwardRef)
110 self.assertEqual(fwdref.__forward_arg__, "doesntexist")
111 with self.assertRaises(NameError):
112 fwdref.evaluate()
113 self.assertEqual(fwdref.evaluate(globals={"doesntexist": 1}), 1)
114
115 def test_nonexistent_attribute(self):
116 def f(
117 x: some.module,
118 y: some[module],
119 z: some(module),
120 alpha: some | obj,
121 beta: +some,
122 gamma: some < obj,
123 delta: some | {obj: module},
124 epsilon: some | {obj},
125 zeta: some | [obj, module],
126 eta: some | (),
127 ):
128 pass
129
130 anno = get_annotations(f, format=Format.FORWARDREF)
131 x_anno = anno["x"]
132 self.assertIsInstance(x_anno, ForwardRef)
133 self.assertEqual(x_anno, support.EqualToForwardRef("some.module", owner=f))
134
135 y_anno = anno["y"]
136 self.assertIsInstance(y_anno, ForwardRef)
137 self.assertEqual(y_anno, support.EqualToForwardRef("some[module]", owner=f))
138
139 z_anno = anno["z"]
140 self.assertIsInstance(z_anno, ForwardRef)
141 self.assertEqual(z_anno, support.EqualToForwardRef("some(module)", owner=f))
142
143 alpha_anno = anno["alpha"]
144 self.assertIsInstance(alpha_anno, ForwardRef)
145 self.assertEqual(alpha_anno, support.EqualToForwardRef("some | obj", owner=f))
146
147 beta_anno = anno["beta"]
148 self.assertIsInstance(beta_anno, ForwardRef)
149 self.assertEqual(beta_anno, support.EqualToForwardRef("+some", owner=f))
150
151 gamma_anno = anno["gamma"]
152 self.assertIsInstance(gamma_anno, ForwardRef)
153 self.assertEqual(gamma_anno, support.EqualToForwardRef("some < obj", owner=f))
154
155 delta_anno = anno["delta"]
156 self.assertIsInstance(delta_anno, ForwardRef)
157 self.assertEqual(delta_anno, support.EqualToForwardRef("some | {obj: module}", owner=f))
158
159 epsilon_anno = anno["epsilon"]
160 self.assertIsInstance(epsilon_anno, ForwardRef)
161 self.assertEqual(epsilon_anno, support.EqualToForwardRef("some | {obj}", owner=f))
162
163 zeta_anno = anno["zeta"]
164 self.assertIsInstance(zeta_anno, ForwardRef)
165 self.assertEqual(zeta_anno, support.EqualToForwardRef("some | [obj, module]", owner=f))
166
167 eta_anno = anno["eta"]
168 self.assertIsInstance(eta_anno, ForwardRef)
169 self.assertEqual(eta_anno, support.EqualToForwardRef("some | ()", owner=f))
170
171 def test_partially_nonexistent(self):
172 # These annotations start with a non-existent variable and then use
173 # global types with defined values. This partially evaluates by putting
174 # those globals into `fwdref.__extra_names__`.
175 def f(
176 x: obj | int,
177 y: container[int:obj, int],
178 z: dict_val | {str: int},
179 alpha: set_val | {str, int},
180 beta: obj | bool | int,
181 gamma: obj | call_func(int, kwd=bool),
182 ):
183 pass
184
185 def func(*args, **kwargs):
186 return Union[*args, *(kwargs.values())]
187
188 anno = get_annotations(f, format=Format.FORWARDREF)
189 globals_ = {
190 "obj": str, "container": list, "dict_val": {1: 2}, "set_val": {1, 2},
191 "call_func": func
192 }
193
194 x_anno = anno["x"]
195 self.assertIsInstance(x_anno, ForwardRef)
196 self.assertEqual(x_anno.evaluate(globals=globals_), str | int)
197
198 y_anno = anno["y"]
199 self.assertIsInstance(y_anno, ForwardRef)
200 self.assertEqual(y_anno.evaluate(globals=globals_), list[int:str, int])
201
202 z_anno = anno["z"]
203 self.assertIsInstance(z_anno, ForwardRef)
204 self.assertEqual(z_anno.evaluate(globals=globals_), {1: 2} | {str: int})
205
206 alpha_anno = anno["alpha"]
207 self.assertIsInstance(alpha_anno, ForwardRef)
208 self.assertEqual(alpha_anno.evaluate(globals=globals_), {1, 2} | {str, int})
209
210 beta_anno = anno["beta"]
211 self.assertIsInstance(beta_anno, ForwardRef)
212 self.assertEqual(beta_anno.evaluate(globals=globals_), str | bool | int)
213
214 gamma_anno = anno["gamma"]
215 self.assertIsInstance(gamma_anno, ForwardRef)
216 self.assertEqual(gamma_anno.evaluate(globals=globals_), str | func(int, kwd=bool))
217
218 def test_partially_nonexistent_union(self):
219 # Test unions with '|' syntax equal unions with typing.Union[] with some forwardrefs
220 class UnionForwardrefs:
221 pipe: str | undefined
222 union: Union[str, undefined]
223
224 annos = get_annotations(UnionForwardrefs, format=Format.FORWARDREF)
225
226 pipe = annos["pipe"]
227 self.assertIsInstance(pipe, ForwardRef)
228 self.assertEqual(
229 pipe.evaluate(globals={"undefined": int}),
230 str | int,
231 )
232 union = annos["union"]
233 self.assertIsInstance(union, Union)
234 arg1, arg2 = typing.get_args(union)
235 self.assertIs(arg1, str)
236 self.assertEqual(
237 arg2, support.EqualToForwardRef("undefined", is_class=True, owner=UnionForwardrefs)
238 )
239
240
241 class TestStringFormat(unittest.TestCase):
242 def test_closure(self):
243 x = 0
244
245 def inner(arg: x):
246 pass
247
248 anno = get_annotations(inner, format=Format.STRING)
249 self.assertEqual(anno, {"arg": "x"})
250
251 def test_closure_undefined(self):
252 if False:
253 x = 0
254
255 def inner(arg: x):
256 pass
257
258 anno = get_annotations(inner, format=Format.STRING)
259 self.assertEqual(anno, {"arg": "x"})
260
261 def test_function(self):
262 def f(x: int, y: doesntexist):
263 pass
264
265 anno = get_annotations(f, format=Format.STRING)
266 self.assertEqual(anno, {"x": "int", "y": "doesntexist"})
267
268 def test_expressions(self):
269 def f(
270 add: a + b,
271 sub: a - b,
272 mul: a * b,
273 matmul: a @ b,
274 truediv: a / b,
275 mod: a % b,
276 lshift: a << b,
277 rshift: a >> b,
278 or_: a | b,
279 xor: a ^ b,
280 and_: a & b,
281 floordiv: a // b,
282 pow_: a**b,
283 lt: a < b,
284 le: a <= b,
285 eq: a == b,
286 ne: a != b,
287 gt: a > b,
288 ge: a >= b,
289 invert: ~a,
290 neg: -a,
291 pos: +a,
292 getitem: a[b],
293 getattr: a.b,
294 call: a(b, *c, d=e), # **kwargs are not supported
295 *args: *a,
296 ):
297 pass
298
299 anno = get_annotations(f, format=Format.STRING)
300 self.assertEqual(
301 anno,
302 {
303 "add": "a + b",
304 "sub": "a - b",
305 "mul": "a * b",
306 "matmul": "a @ b",
307 "truediv": "a / b",
308 "mod": "a % b",
309 "lshift": "a << b",
310 "rshift": "a >> b",
311 "or_": "a | b",
312 "xor": "a ^ b",
313 "and_": "a & b",
314 "floordiv": "a // b",
315 "pow_": "a ** b",
316 "lt": "a < b",
317 "le": "a <= b",
318 "eq": "a == b",
319 "ne": "a != b",
320 "gt": "a > b",
321 "ge": "a >= b",
322 "invert": "~a",
323 "neg": "-a",
324 "pos": "+a",
325 "getitem": "a[b]",
326 "getattr": "a.b",
327 "call": "a(b, *c, d=e)",
328 "args": "*a",
329 },
330 )
331
332 def test_reverse_ops(self):
333 def f(
334 radd: 1 + a,
335 rsub: 1 - a,
336 rmul: 1 * a,
337 rmatmul: 1 @ a,
338 rtruediv: 1 / a,
339 rmod: 1 % a,
340 rlshift: 1 << a,
341 rrshift: 1 >> a,
342 ror: 1 | a,
343 rxor: 1 ^ a,
344 rand: 1 & a,
345 rfloordiv: 1 // a,
346 rpow: 1**a,
347 ):
348 pass
349
350 anno = get_annotations(f, format=Format.STRING)
351 self.assertEqual(
352 anno,
353 {
354 "radd": "1 + a",
355 "rsub": "1 - a",
356 "rmul": "1 * a",
357 "rmatmul": "1 @ a",
358 "rtruediv": "1 / a",
359 "rmod": "1 % a",
360 "rlshift": "1 << a",
361 "rrshift": "1 >> a",
362 "ror": "1 | a",
363 "rxor": "1 ^ a",
364 "rand": "1 & a",
365 "rfloordiv": "1 // a",
366 "rpow": "1 ** a",
367 },
368 )
369
370 def test_template_str(self):
371 def f(
372 x: t"{a}",
373 y: list[t"{a}"],
374 z: t"{a:b} {c!r} {d!s:t}",
375 a: t"a{b}c{d}e{f}g",
376 b: t"{a:{1}}",
377 c: t"{a | b * c}",
378 gh138558: t"{ 0}",
379 ): pass
380
381 annos = get_annotations(f, format=Format.STRING)
382 self.assertEqual(annos, {
383 "x": "t'{a}'",
384 "y": "list[t'{a}']",
385 "z": "t'{a:b} {c!r} {d!s:t}'",
386 "a": "t'a{b}c{d}e{f}g'",
387 # interpolations in the format spec are eagerly evaluated so we can't recover the source
388 "b": "t'{a:1}'",
389 "c": "t'{a | b * c}'",
390 "gh138558": "t'{ 0}'",
391 })
392
393 def g(
394 x: t"{a}",
395 ): ...
396
397 annos = get_annotations(g, format=Format.FORWARDREF)
398 templ = annos["x"]
399 # Template and Interpolation don't have __eq__ so we have to compare manually
400 self.assertIsInstance(templ, Template)
401 self.assertEqual(templ.strings, ("", ""))
402 self.assertEqual(len(templ.interpolations), 1)
403 interp = templ.interpolations[0]
404 self.assertEqual(interp.value, support.EqualToForwardRef("a", owner=g))
405 self.assertEqual(interp.expression, "a")
406 self.assertIsNone(interp.conversion)
407 self.assertEqual(interp.format_spec, "")
408
409 def test_getitem(self):
410 def f(x: undef1[str, undef2]):
411 pass
412 anno = get_annotations(f, format=Format.STRING)
413 self.assertEqual(anno, {"x": "undef1[str, undef2]"})
414
415 anno = get_annotations(f, format=Format.FORWARDREF)
416 fwdref = anno["x"]
417 self.assertIsInstance(fwdref, ForwardRef)
418 self.assertEqual(
419 fwdref.evaluate(globals={"undef1": dict, "undef2": float}), dict[str, float]
420 )
421
422 def test_slice(self):
423 def f(x: a[b:c]):
424 pass
425 anno = get_annotations(f, format=Format.STRING)
426 self.assertEqual(anno, {"x": "a[b:c]"})
427
428 def f(x: a[b:c, d:e]):
429 pass
430 anno = get_annotations(f, format=Format.STRING)
431 self.assertEqual(anno, {"x": "a[b:c, d:e]"})
432
433 obj = slice(1, 1, 1)
434 def f(x: obj):
435 pass
436 anno = get_annotations(f, format=Format.STRING)
437 self.assertEqual(anno, {"x": "obj"})
438
439 def test_literals(self):
440 def f(
441 a: 1,
442 b: 1.0,
443 c: "hello",
444 d: b"hello",
445 e: True,
446 f: None,
447 g: ...,
448 h: 1j,
449 ):
450 pass
451
452 anno = get_annotations(f, format=Format.STRING)
453 self.assertEqual(
454 anno,
455 {
456 "a": "1",
457 "b": "1.0",
458 "c": 'hello',
459 "d": "b'hello'",
460 "e": "True",
461 "f": "None",
462 "g": "...",
463 "h": "1j",
464 },
465 )
466
467 def test_displays(self):
468 # Simple case first
469 def f(x: a[[int, str], float]):
470 pass
471 anno = get_annotations(f, format=Format.STRING)
472 self.assertEqual(anno, {"x": "a[[int, str], float]"})
473
474 def g(
475 w: a[[int, str], float],
476 x: a[{int}, 3],
477 y: a[{int: str}, 4],
478 z: a[(int, str), 5],
479 ):
480 pass
481 anno = get_annotations(g, format=Format.STRING)
482 self.assertEqual(
483 anno,
484 {
485 "w": "a[[int, str], float]",
486 "x": "a[{int}, 3]",
487 "y": "a[{int: str}, 4]",
488 "z": "a[(int, str), 5]",
489 },
490 )
491
492 def test_nested_expressions(self):
493 def f(
494 nested: list[Annotated[set[int], "set of ints", 4j]],
495 set: {a + b}, # single element because order is not guaranteed
496 dict: {a + b: c + d, "key": e + g},
497 list: [a, b, c],
498 tuple: (a, b, c),
499 slice: (a[b:c], a[b:c:d], a[:c], a[b:], a[:], a[::d], a[b::d]),
500 extended_slice: a[:, :, c:d],
501 unpack1: [*a],
502 unpack2: [*a, b, c],
503 ):
504 pass
505
506 anno = get_annotations(f, format=Format.STRING)
507 self.assertEqual(
508 anno,
509 {
510 "nested": "list[Annotated[set[int], 'set of ints', 4j]]",
511 "set": "{a + b}",
512 "dict": "{a + b: c + d, 'key': e + g}",
513 "list": "[a, b, c]",
514 "tuple": "(a, b, c)",
515 "slice": "(a[b:c], a[b:c:d], a[:c], a[b:], a[:], a[::d], a[b::d])",
516 "extended_slice": "a[:, :, c:d]",
517 "unpack1": "[*a]",
518 "unpack2": "[*a, b, c]",
519 },
520 )
521
522 def test_unsupported_operations(self):
523 format_msg = "Cannot stringify annotation containing string formatting"
524
525 def f(fstring: f"{a}"):
526 pass
527
528 with self.assertRaisesRegex(TypeError, format_msg):
529 get_annotations(f, format=Format.STRING)
530
531 def f(fstring_format: f"{a:02d}"):
532 pass
533
534 with self.assertRaisesRegex(TypeError, format_msg):
535 get_annotations(f, format=Format.STRING)
536
537 def test_shenanigans(self):
538 # In cases like this we can't reconstruct the source; test that we do something
539 # halfway reasonable.
540 def f(x: x | (1).__class__, y: (1).__class__):
541 pass
542
543 self.assertEqual(
544 get_annotations(f, format=Format.STRING),
545 {"x": "x | <class 'int'>", "y": "<class 'int'>"},
546 )
547
548
549 class TestGetAnnotations(unittest.TestCase):
550 def test_builtin_type(self):
551 self.assertEqual(get_annotations(int), {})
552 self.assertEqual(get_annotations(object), {})
553
554 def test_custom_metaclass(self):
555 class Meta(type):
556 pass
557
558 class C(metaclass=Meta):
559 x: int
560
561 self.assertEqual(get_annotations(C), {"x": int})
562
563 def test_missing_dunder_dict(self):
564 class NoDict(type):
565 @property
566 def __dict__(cls):
567 raise AttributeError
568
569 b: str
570
571 class C1(metaclass=NoDict):
572 a: int
573
574 self.assertEqual(get_annotations(C1), {"a": int})
575 self.assertEqual(
576 get_annotations(C1, format=Format.FORWARDREF),
577 {"a": int},
578 )
579 self.assertEqual(
580 get_annotations(C1, format=Format.STRING),
581 {"a": "int"},
582 )
583 self.assertEqual(get_annotations(NoDict), {"b": str})
584 self.assertEqual(
585 get_annotations(NoDict, format=Format.FORWARDREF),
586 {"b": str},
587 )
588 self.assertEqual(
589 get_annotations(NoDict, format=Format.STRING),
590 {"b": "str"},
591 )
592
593 def test_format(self):
594 def f1(a: int):
595 pass
596
597 def f2(a: undefined):
598 pass
599
600 self.assertEqual(
601 get_annotations(f1, format=Format.VALUE),
602 {"a": int},
603 )
604 self.assertEqual(get_annotations(f1, format=1), {"a": int})
605
606 fwd = support.EqualToForwardRef("undefined", owner=f2)
607 self.assertEqual(
608 get_annotations(f2, format=Format.FORWARDREF),
609 {"a": fwd},
610 )
611 self.assertEqual(get_annotations(f2, format=3), {"a": fwd})
612
613 self.assertEqual(
614 get_annotations(f1, format=Format.STRING),
615 {"a": "int"},
616 )
617 self.assertEqual(get_annotations(f1, format=4), {"a": "int"})
618
619 with self.assertRaises(ValueError):
620 get_annotations(f1, format=42)
621
622 with self.assertRaisesRegex(
623 ValueError,
624 r"The VALUE_WITH_FAKE_GLOBALS format is for internal use only",
625 ):
626 get_annotations(f1, format=Format.VALUE_WITH_FAKE_GLOBALS)
627
628 with self.assertRaisesRegex(
629 ValueError,
630 r"The VALUE_WITH_FAKE_GLOBALS format is for internal use only",
631 ):
632 get_annotations(f1, format=2)
633
634 def test_custom_object_with_annotations(self):
635 class C:
636 def __init__(self):
637 self.__annotations__ = {"x": int, "y": str}
638
639 self.assertEqual(get_annotations(C()), {"x": int, "y": str})
640
641 def test_custom_format_eval_str(self):
642 def foo():
643 pass
644
645 with self.assertRaises(ValueError):
646 get_annotations(foo, format=Format.FORWARDREF, eval_str=True)
647 get_annotations(foo, format=Format.STRING, eval_str=True)
648
649 def test_eval_str_wrapped_cycle_self(self):
650 # gh-146556: self-referential __wrapped__ cycle must not hang.
651 def f(x: 'int') -> 'str': ...
652 f.__wrapped__ = f
653 # Cycle is detected and broken; globals from f itself are used.
654 result = get_annotations(f, eval_str=True)
655 self.assertEqual(result, {'x': int, 'return': str})
656
657 def test_eval_str_wrapped_cycle_mutual(self):
658 # gh-146556: mutual __wrapped__ cycle (a -> b -> a) must not hang.
659 def a(x: 'int'): ...
660 def b(): ...
661 a.__wrapped__ = b
662 b.__wrapped__ = a
663 result = get_annotations(a, eval_str=True)
664 self.assertEqual(result, {'x': int})
665
666 def test_eval_str_wrapped_chain_no_cycle(self):
667 # gh-146556: a valid (non-cyclic) __wrapped__ chain must still work.
668 def inner(x: 'int'): ...
669 def outer(x: 'int'): ...
670 outer.__wrapped__ = inner
671 result = get_annotations(outer, eval_str=True)
672 self.assertEqual(result, {'x': int})
673
674 def test_stock_annotations(self):
675 def foo(a: int, b: str):
676 pass
677
678 for format in (Format.VALUE, Format.FORWARDREF):
679 with self.subTest(format=format):
680 self.assertEqual(
681 get_annotations(foo, format=format),
682 {"a": int, "b": str},
683 )
684 self.assertEqual(
685 get_annotations(foo, format=Format.STRING),
686 {"a": "int", "b": "str"},
687 )
688
689 foo.__annotations__ = {"a": "foo", "b": "str"}
690 for format in Format:
691 if format == Format.VALUE_WITH_FAKE_GLOBALS:
692 continue
693 with self.subTest(format=format):
694 self.assertEqual(
695 get_annotations(foo, format=format),
696 {"a": "foo", "b": "str"},
697 )
698
699 self.assertEqual(
700 get_annotations(foo, eval_str=True, locals=locals()),
701 {"a": foo, "b": str},
702 )
703 self.assertEqual(
704 get_annotations(foo, eval_str=True, globals=locals()),
705 {"a": foo, "b": str},
706 )
707
708 def test_stock_annotations_in_module(self):
709 isa = inspect_stock_annotations
710
711 for kwargs in [
712 {},
713 {"eval_str": False},
714 {"format": Format.VALUE},
715 {"format": Format.FORWARDREF},
716 {"format": Format.VALUE, "eval_str": False},
717 {"format": Format.FORWARDREF, "eval_str": False},
718 ]:
719 with self.subTest(**kwargs):
720 self.assertEqual(get_annotations(isa, **kwargs), {"a": int, "b": str})
721 self.assertEqual(
722 get_annotations(isa.MyClass, **kwargs),
723 {"a": int, "b": str},
724 )
725 self.assertEqual(
726 get_annotations(isa.function, **kwargs),
727 {"a": int, "b": str, "return": isa.MyClass},
728 )
729 self.assertEqual(
730 get_annotations(isa.function2, **kwargs),
731 {"a": int, "b": "str", "c": isa.MyClass, "return": isa.MyClass},
732 )
733 self.assertEqual(
734 get_annotations(isa.function3, **kwargs),
735 {"a": "int", "b": "str", "c": "MyClass"},
736 )
737 self.assertEqual(
738 get_annotations(annotationlib, **kwargs), {}
739 ) # annotations module has no annotations
740 self.assertEqual(get_annotations(isa.UnannotatedClass, **kwargs), {})
741 self.assertEqual(
742 get_annotations(isa.unannotated_function, **kwargs),
743 {},
744 )
745
746 for kwargs in [
747 {"eval_str": True},
748 {"format": Format.VALUE, "eval_str": True},
749 ]:
750 with self.subTest(**kwargs):
751 self.assertEqual(get_annotations(isa, **kwargs), {"a": int, "b": str})
752 self.assertEqual(
753 get_annotations(isa.MyClass, **kwargs),
754 {"a": int, "b": str},
755 )
756 self.assertEqual(
757 get_annotations(isa.function, **kwargs),
758 {"a": int, "b": str, "return": isa.MyClass},
759 )
760 self.assertEqual(
761 get_annotations(isa.function2, **kwargs),
762 {"a": int, "b": str, "c": isa.MyClass, "return": isa.MyClass},
763 )
764 self.assertEqual(
765 get_annotations(isa.function3, **kwargs),
766 {"a": int, "b": str, "c": isa.MyClass},
767 )
768 self.assertEqual(get_annotations(annotationlib, **kwargs), {})
769 self.assertEqual(get_annotations(isa.UnannotatedClass, **kwargs), {})
770 self.assertEqual(
771 get_annotations(isa.unannotated_function, **kwargs),
772 {},
773 )
774
775 self.assertEqual(
776 get_annotations(isa, format=Format.STRING),
777 {"a": "int", "b": "str"},
778 )
779 self.assertEqual(
780 get_annotations(isa.MyClass, format=Format.STRING),
781 {"a": "int", "b": "str"},
782 )
783 self.assertEqual(
784 get_annotations(isa.function, format=Format.STRING),
785 {"a": "int", "b": "str", "return": "MyClass"},
786 )
787 self.assertEqual(
788 get_annotations(isa.function2, format=Format.STRING),
789 {"a": "int", "b": "str", "c": "MyClass", "return": "MyClass"},
790 )
791 self.assertEqual(
792 get_annotations(isa.function3, format=Format.STRING),
793 {"a": "int", "b": "str", "c": "MyClass"},
794 )
795 self.assertEqual(
796 get_annotations(annotationlib, format=Format.STRING),
797 {},
798 )
799 self.assertEqual(
800 get_annotations(isa.UnannotatedClass, format=Format.STRING),
801 {},
802 )
803 self.assertEqual(
804 get_annotations(isa.unannotated_function, format=Format.STRING),
805 {},
806 )
807
808 def test_stock_annotations_on_wrapper(self):
809 isa = inspect_stock_annotations
810
811 wrapped = times_three(isa.function)
812 self.assertEqual(wrapped(1, "x"), isa.MyClass(3, "xxx"))
813 self.assertIsNot(wrapped.__globals__, isa.function.__globals__)
814 self.assertEqual(
815 get_annotations(wrapped),
816 {"a": int, "b": str, "return": isa.MyClass},
817 )
818 self.assertEqual(
819 get_annotations(wrapped, format=Format.FORWARDREF),
820 {"a": int, "b": str, "return": isa.MyClass},
821 )
822 self.assertEqual(
823 get_annotations(wrapped, format=Format.STRING),
824 {"a": "int", "b": "str", "return": "MyClass"},
825 )
826 self.assertEqual(
827 get_annotations(wrapped, eval_str=True),
828 {"a": int, "b": str, "return": isa.MyClass},
829 )
830 self.assertEqual(
831 get_annotations(wrapped, eval_str=False),
832 {"a": int, "b": str, "return": isa.MyClass},
833 )
834
835 def test_stringized_annotations_in_module(self):
836 isa = inspect_stringized_annotations
837 for kwargs in [
838 {},
839 {"eval_str": False},
840 {"format": Format.VALUE},
841 {"format": Format.FORWARDREF},
842 {"format": Format.STRING},
843 {"format": Format.VALUE, "eval_str": False},
844 {"format": Format.FORWARDREF, "eval_str": False},
845 {"format": Format.STRING, "eval_str": False},
846 ]:
847 with self.subTest(**kwargs):
848 self.assertEqual(
849 get_annotations(isa, **kwargs),
850 {"a": "int", "b": "str"},
851 )
852 self.assertEqual(
853 get_annotations(isa.MyClass, **kwargs),
854 {"a": "int", "b": "str"},
855 )
856 self.assertEqual(
857 get_annotations(isa.function, **kwargs),
858 {"a": "int", "b": "str", "return": "MyClass"},
859 )
860 self.assertEqual(
861 get_annotations(isa.function2, **kwargs),
862 {"a": "int", "b": "'str'", "c": "MyClass", "return": "MyClass"},
863 )
864 self.assertEqual(
865 get_annotations(isa.function3, **kwargs),
866 {"a": "'int'", "b": "'str'", "c": "'MyClass'"},
867 )
868 self.assertEqual(get_annotations(isa.UnannotatedClass, **kwargs), {})
869 self.assertEqual(
870 get_annotations(isa.unannotated_function, **kwargs),
871 {},
872 )
873
874 for kwargs in [
875 {"eval_str": True},
876 {"eval_str": True, "globals": isa.__dict__, "locals": {}},
877 {"eval_str": True, "globals": {}, "locals": isa.__dict__},
878 {"format": Format.VALUE, "eval_str": True},
879 ]:
880 with self.subTest(**kwargs):
881 self.assertEqual(get_annotations(isa, **kwargs), {"a": int, "b": str})
882 self.assertEqual(
883 get_annotations(isa.MyClass, **kwargs),
884 {"a": int, "b": str},
885 )
886 self.assertEqual(
887 get_annotations(isa.function, **kwargs),
888 {"a": int, "b": str, "return": isa.MyClass},
889 )
890 self.assertEqual(
891 get_annotations(isa.function2, **kwargs),
892 {"a": int, "b": "str", "c": isa.MyClass, "return": isa.MyClass},
893 )
894 self.assertEqual(
895 get_annotations(isa.function3, **kwargs),
896 {"a": "int", "b": "str", "c": "MyClass"},
897 )
898 self.assertEqual(get_annotations(isa.UnannotatedClass, **kwargs), {})
899 self.assertEqual(
900 get_annotations(isa.unannotated_function, **kwargs),
901 {},
902 )
903
904 def test_stringized_annotations_in_empty_module(self):
905 isa2 = inspect_stringized_annotations_2
906 self.assertEqual(get_annotations(isa2), {})
907 self.assertEqual(get_annotations(isa2, eval_str=True), {})
908 self.assertEqual(get_annotations(isa2, eval_str=False), {})
909
910 def test_stringized_annotations_with_star_unpack(self):
911 def f(*args: "*tuple[int, ...]"): ...
912 self.assertEqual(get_annotations(f, eval_str=True),
913 {'args': (*tuple[int, ...],)[0]})
914 def f(*args: " *tuple[int, ...]"): ...
915 self.assertEqual(get_annotations(f, eval_str=True),
916 {'args': (*tuple[int, ...],)[0]})
917
918
919 def test_stringized_annotations_on_wrapper(self):
920 isa = inspect_stringized_annotations
921 wrapped = times_three(isa.function)
922 self.assertEqual(wrapped(1, "x"), isa.MyClass(3, "xxx"))
923 self.assertIsNot(wrapped.__globals__, isa.function.__globals__)
924 self.assertEqual(
925 get_annotations(wrapped),
926 {"a": "int", "b": "str", "return": "MyClass"},
927 )
928 self.assertEqual(
929 get_annotations(wrapped, eval_str=True),
930 {"a": int, "b": str, "return": isa.MyClass},
931 )
932 self.assertEqual(
933 get_annotations(wrapped, eval_str=False),
934 {"a": "int", "b": "str", "return": "MyClass"},
935 )
936
937 def test_stringized_annotations_on_partial_wrapper(self):
938 isa = inspect_stringized_annotations
939
940 def times_three_str(fn: typing.Callable[[str], isa.MyClass]):
941 @functools.wraps(fn)
942 def wrapper(b: "str") -> "MyClass":
943 return fn(b * 3)
944
945 return wrapper
946
947 wrapped = times_three_str(functools.partial(isa.function, 1))
948 self.assertEqual(wrapped("x"), isa.MyClass(1, "xxx"))
949 self.assertIsNot(wrapped.__globals__, isa.function.__globals__)
950 self.assertEqual(
951 get_annotations(wrapped, eval_str=True),
952 {"b": str, "return": isa.MyClass},
953 )
954 self.assertEqual(
955 get_annotations(wrapped, eval_str=False),
956 {"b": "str", "return": "MyClass"},
957 )
958
959 # If functools is not loaded, names will be evaluated in the current
960 # module instead of being unwrapped to the original.
961 functools_mod = sys.modules["functools"]
962 del sys.modules["functools"]
963
964 self.assertEqual(
965 get_annotations(wrapped, eval_str=True),
966 {"b": str, "return": MyClass},
967 )
968 self.assertEqual(
969 get_annotations(wrapped, eval_str=False),
970 {"b": "str", "return": "MyClass"},
971 )
972
973 sys.modules["functools"] = functools_mod
974
975 def test_stringized_annotations_on_class(self):
976 isa = inspect_stringized_annotations
977 # test that local namespace lookups work
978 self.assertEqual(
979 get_annotations(isa.MyClassWithLocalAnnotations),
980 {"x": "mytype"},
981 )
982 self.assertEqual(
983 get_annotations(isa.MyClassWithLocalAnnotations, eval_str=True),
984 {"x": int},
985 )
986
987 def test_stringized_annotations_on_custom_object(self):
988 class HasAnnotations:
989 @property
990 def __annotations__(self):
991 return {"x": "int"}
992
993 ha = HasAnnotations()
994 self.assertEqual(get_annotations(ha), {"x": "int"})
995 self.assertEqual(get_annotations(ha, eval_str=True), {"x": int})
996
997 def test_stringized_annotation_permutations(self):
998 def define_class(name, has_future, has_annos, base_text, extra_names=None):
999 lines = []
1000 if has_future:
1001 lines.append("from __future__ import annotations")
1002 lines.append(f"class {name}({base_text}):")
1003 if has_annos:
1004 lines.append(f" {name}_attr: int")
1005 else:
1006 lines.append(" pass")
1007 code = "\n".join(lines)
1008 ns = support.run_code(code, extra_names=extra_names)
1009 return ns[name]
1010
1011 def check_annotations(cls, has_future, has_annos):
1012 if has_annos:
1013 if has_future:
1014 anno = "int"
1015 else:
1016 anno = int
1017 self.assertEqual(get_annotations(cls), {f"{cls.__name__}_attr": anno})
1018 else:
1019 self.assertEqual(get_annotations(cls), {})
1020
1021 for meta_future, base_future, child_future, meta_has_annos, base_has_annos, child_has_annos in itertools.product(
1022 (False, True),
1023 (False, True),
1024 (False, True),
1025 (False, True),
1026 (False, True),
1027 (False, True),
1028 ):
1029 with self.subTest(
1030 meta_future=meta_future,
1031 base_future=base_future,
1032 child_future=child_future,
1033 meta_has_annos=meta_has_annos,
1034 base_has_annos=base_has_annos,
1035 child_has_annos=child_has_annos,
1036 ):
1037 meta = define_class(
1038 "Meta",
1039 has_future=meta_future,
1040 has_annos=meta_has_annos,
1041 base_text="type",
1042 )
1043 base = define_class(
1044 "Base",
1045 has_future=base_future,
1046 has_annos=base_has_annos,
1047 base_text="metaclass=Meta",
1048 extra_names={"Meta": meta},
1049 )
1050 child = define_class(
1051 "Child",
1052 has_future=child_future,
1053 has_annos=child_has_annos,
1054 base_text="Base",
1055 extra_names={"Base": base},
1056 )
1057 check_annotations(meta, meta_future, meta_has_annos)
1058 check_annotations(base, base_future, base_has_annos)
1059 check_annotations(child, child_future, child_has_annos)
1060
1061 def test_modify_annotations(self):
1062 def f(x: int):
1063 pass
1064
1065 self.assertEqual(get_annotations(f), {"x": int})
1066 self.assertEqual(
1067 get_annotations(f, format=Format.FORWARDREF),
1068 {"x": int},
1069 )
1070
1071 f.__annotations__["x"] = str
1072 # The modification is reflected in VALUE (the default)
1073 self.assertEqual(get_annotations(f), {"x": str})
1074 # ... and also in FORWARDREF, which tries __annotations__ if available
1075 self.assertEqual(
1076 get_annotations(f, format=Format.FORWARDREF),
1077 {"x": str},
1078 )
1079 # ... but not in STRING which always uses __annotate__
1080 self.assertEqual(
1081 get_annotations(f, format=Format.STRING),
1082 {"x": "int"},
1083 )
1084
1085 def test_non_dict_annotations(self):
1086 class WeirdAnnotations:
1087 @property
1088 def __annotations__(self):
1089 return "not a dict"
1090
1091 wa = WeirdAnnotations()
1092 for format in Format:
1093 if format == Format.VALUE_WITH_FAKE_GLOBALS:
1094 continue
1095 with (
1096 self.subTest(format=format),
1097 self.assertRaisesRegex(
1098 ValueError, r".*__annotations__ is neither a dict nor None"
1099 ),
1100 ):
1101 get_annotations(wa, format=format)
1102
1103 def test_annotations_on_custom_object(self):
1104 class HasAnnotations:
1105 @property
1106 def __annotations__(self):
1107 return {"x": int}
1108
1109 ha = HasAnnotations()
1110 self.assertEqual(get_annotations(ha, format=Format.VALUE), {"x": int})
1111 self.assertEqual(get_annotations(ha, format=Format.FORWARDREF), {"x": int})
1112
1113 self.assertEqual(get_annotations(ha, format=Format.STRING), {"x": "int"})
1114
1115 def test_raising_annotations_on_custom_object(self):
1116 class HasRaisingAnnotations:
1117 @property
1118 def __annotations__(self):
1119 return {"x": undefined}
1120
1121 hra = HasRaisingAnnotations()
1122
1123 with self.assertRaises(NameError):
1124 get_annotations(hra, format=Format.VALUE)
1125
1126 with self.assertRaises(NameError):
1127 get_annotations(hra, format=Format.FORWARDREF)
1128
1129 undefined = float
1130 self.assertEqual(get_annotations(hra, format=Format.VALUE), {"x": float})
1131
1132 def test_forwardref_prefers_annotations(self):
1133 class HasBoth:
1134 @property
1135 def __annotations__(self):
1136 return {"x": int}
1137
1138 @property
1139 def __annotate__(self):
1140 return lambda format: {"x": str}
1141
1142 hb = HasBoth()
1143 self.assertEqual(get_annotations(hb, format=Format.VALUE), {"x": int})
1144 self.assertEqual(get_annotations(hb, format=Format.FORWARDREF), {"x": int})
1145 self.assertEqual(get_annotations(hb, format=Format.STRING), {"x": str})
1146
1147 def test_only_annotate(self):
1148 def f(x: int):
1149 pass
1150
1151 class OnlyAnnotate:
1152 @property
1153 def __annotate__(self):
1154 return f.__annotate__
1155
1156 oa = OnlyAnnotate()
1157 self.assertEqual(get_annotations(oa, format=Format.VALUE), {"x": int})
1158 self.assertEqual(get_annotations(oa, format=Format.FORWARDREF), {"x": int})
1159 self.assertEqual(
1160 get_annotations(oa, format=Format.STRING),
1161 {"x": "int"},
1162 )
1163
1164 def test_non_dict_annotate(self):
1165 class WeirdAnnotate:
1166 def __annotate__(self, *args, **kwargs):
1167 return "not a dict"
1168
1169 wa = WeirdAnnotate()
1170 for format in Format:
1171 if format == Format.VALUE_WITH_FAKE_GLOBALS:
1172 continue
1173 with (
1174 self.subTest(format=format),
1175 self.assertRaisesRegex(
1176 ValueError, r".*__annotate__ returned a non-dict"
1177 ),
1178 ):
1179 get_annotations(wa, format=format)
1180
1181 def test_no_annotations(self):
1182 class CustomClass:
1183 pass
1184
1185 class MyCallable:
1186 def __call__(self):
1187 pass
1188
1189 for format in Format:
1190 if format == Format.VALUE_WITH_FAKE_GLOBALS:
1191 continue
1192 for obj in (None, 1, object(), CustomClass()):
1193 with self.subTest(format=format, obj=obj):
1194 with self.assertRaises(TypeError):
1195 get_annotations(obj, format=format)
1196
1197 # Callables and types with no annotations return an empty dict
1198 for obj in (int, len, MyCallable()):
1199 with self.subTest(format=format, obj=obj):
1200 self.assertEqual(get_annotations(obj, format=format), {})
1201
1202 def test_pep695_generic_class_with_future_annotations(self):
1203 ann_module695 = inspect_stringized_annotations_pep695
1204 A_annotations = get_annotations(ann_module695.A, eval_str=True)
1205 A_type_params = ann_module695.A.__type_params__
1206 self.assertIs(A_annotations["x"], A_type_params[0])
1207 self.assertEqual(A_annotations["y"].__args__[0], Unpack[A_type_params[1]])
1208 self.assertIs(A_annotations["z"].__args__[0], A_type_params[2])
1209
1210 def test_pep695_generic_class_with_future_annotations_and_local_shadowing(self):
1211 B_annotations = get_annotations(
1212 inspect_stringized_annotations_pep695.B, eval_str=True
1213 )
1214 self.assertEqual(B_annotations, {"x": int, "y": str, "z": bytes})
1215
1216 def test_pep695_generic_class_with_future_annotations_name_clash_with_global_vars(
1217 self,
1218 ):
1219 ann_module695 = inspect_stringized_annotations_pep695
1220 C_annotations = get_annotations(ann_module695.C, eval_str=True)
1221 self.assertEqual(
1222 set(C_annotations.values()), set(ann_module695.C.__type_params__)
1223 )
1224
1225 def test_pep_695_generic_function_with_future_annotations(self):
1226 ann_module695 = inspect_stringized_annotations_pep695
1227 generic_func_annotations = get_annotations(
1228 ann_module695.generic_function, eval_str=True
1229 )
1230 func_t_params = ann_module695.generic_function.__type_params__
1231 self.assertEqual(
1232 generic_func_annotations.keys(), {"x", "y", "z", "zz", "return"}
1233 )
1234 self.assertIs(generic_func_annotations["x"], func_t_params[0])
1235 self.assertEqual(generic_func_annotations["y"], Unpack[func_t_params[1]])
1236 self.assertIs(generic_func_annotations["z"].__origin__, func_t_params[2])
1237 self.assertIs(generic_func_annotations["zz"].__origin__, func_t_params[2])
1238
1239 def test_pep_695_generic_function_with_future_annotations_name_clash_with_global_vars(
1240 self,
1241 ):
1242 self.assertEqual(
1243 set(
1244 get_annotations(
1245 inspect_stringized_annotations_pep695.generic_function_2,
1246 eval_str=True,
1247 ).values()
1248 ),
1249 set(
1250 inspect_stringized_annotations_pep695.generic_function_2.__type_params__
1251 ),
1252 )
1253
1254 def test_pep_695_generic_method_with_future_annotations(self):
1255 ann_module695 = inspect_stringized_annotations_pep695
1256 generic_method_annotations = get_annotations(
1257 ann_module695.D.generic_method, eval_str=True
1258 )
1259 params = {
1260 param.__name__: param
1261 for param in ann_module695.D.generic_method.__type_params__
1262 }
1263 self.assertEqual(
1264 generic_method_annotations,
1265 {"x": params["Foo"], "y": params["Bar"], "return": None},
1266 )
1267
1268 def test_pep_695_generic_method_with_future_annotations_name_clash_with_global_vars(
1269 self,
1270 ):
1271 self.assertEqual(
1272 set(
1273 get_annotations(
1274 inspect_stringized_annotations_pep695.D.generic_method_2,
1275 eval_str=True,
1276 ).values()
1277 ),
1278 set(
1279 inspect_stringized_annotations_pep695.D.generic_method_2.__type_params__
1280 ),
1281 )
1282
1283 def test_pep_695_generic_method_with_future_annotations_name_clash_with_global_and_local_vars(
1284 self,
1285 ):
1286 self.assertEqual(
1287 get_annotations(inspect_stringized_annotations_pep695.E, eval_str=True),
1288 {"x": str},
1289 )
1290
1291 def test_pep_695_generics_with_future_annotations_nested_in_function(self):
1292 results = inspect_stringized_annotations_pep695.nested()
1293
1294 self.assertEqual(
1295 set(results.F_annotations.values()), set(results.F.__type_params__)
1296 )
1297 self.assertEqual(
1298 set(results.F_meth_annotations.values()),
1299 set(results.F.generic_method.__type_params__),
1300 )
1301 self.assertNotEqual(
1302 set(results.F_meth_annotations.values()), set(results.F.__type_params__)
1303 )
1304 self.assertEqual(
1305 set(results.F_meth_annotations.values()).intersection(
1306 results.F.__type_params__
1307 ),
1308 set(),
1309 )
1310
1311 self.assertEqual(results.G_annotations, {"x": str})
1312
1313 self.assertEqual(
1314 set(results.generic_func_annotations.values()),
1315 set(results.generic_func.__type_params__),
1316 )
1317
1318 def test_partial_evaluation(self):
1319 def f(
1320 x: builtins.undef,
1321 y: list[int],
1322 z: 1 + int,
1323 a: builtins.int,
1324 b: [builtins.undef, builtins.int],
1325 ):
1326 pass
1327
1328 self.assertEqual(
1329 get_annotations(f, format=Format.FORWARDREF),
1330 {
1331 "x": support.EqualToForwardRef("builtins.undef", owner=f),
1332 "y": list[int],
1333 "z": support.EqualToForwardRef("1 + int", owner=f),
1334 "a": int,
1335 "b": [
1336 support.EqualToForwardRef("builtins.undef", owner=f),
1337 # We can't resolve this because we have to evaluate the whole annotation
1338 support.EqualToForwardRef("builtins.int", owner=f),
1339 ],
1340 },
1341 )
1342
1343 self.assertEqual(
1344 get_annotations(f, format=Format.STRING),
1345 {
1346 "x": "builtins.undef",
1347 "y": "list[int]",
1348 "z": "1 + int",
1349 "a": "builtins.int",
1350 "b": "[builtins.undef, builtins.int]",
1351 },
1352 )
1353
1354 def test_partial_evaluation_error(self):
1355 def f(x: range[1]):
1356 pass
1357 with self.assertRaisesRegex(
1358 TypeError, "type 'range' is not subscriptable"
1359 ):
1360 f.__annotations__
1361
1362 self.assertEqual(
1363 get_annotations(f, format=Format.FORWARDREF),
1364 {
1365 "x": support.EqualToForwardRef("range[1]", owner=f),
1366 },
1367 )
1368
1369 def test_partial_evaluation_cell(self):
1370 obj = object()
1371
1372 class RaisesAttributeError:
1373 attriberr: obj.missing
1374
1375 anno = get_annotations(RaisesAttributeError, format=Format.FORWARDREF)
1376 self.assertEqual(
1377 anno,
1378 {
1379 "attriberr": support.EqualToForwardRef(
1380 "obj.missing", is_class=True, owner=RaisesAttributeError
1381 )
1382 },
1383 )
1384
1385 def test_nonlocal_in_annotation_scope(self):
1386 class Demo:
1387 nonlocal sequence_b
1388 x: sequence_b
1389 y: sequence_b[int]
1390
1391 fwdrefs = get_annotations(Demo, format=Format.FORWARDREF)
1392
1393 self.assertIsInstance(fwdrefs["x"], ForwardRef)
1394 self.assertIsInstance(fwdrefs["y"], ForwardRef)
1395
1396 sequence_b = list
1397 self.assertIs(fwdrefs["x"].evaluate(), list)
1398 self.assertEqual(fwdrefs["y"].evaluate(), list[int])
1399
1400 def test_raises_error_from_value(self):
1401 # test that if VALUE is the only supported format, but raises an error
1402 # that error is propagated from get_annotations
1403 class DemoException(Exception): ...
1404
1405 def annotate(format, /):
1406 if format == Format.VALUE:
1407 raise DemoException()
1408 else:
1409 raise NotImplementedError(format)
1410
1411 def f(): ...
1412
1413 f.__annotate__ = annotate
1414
1415 for fmt in [Format.VALUE, Format.FORWARDREF, Format.STRING]:
1416 with self.assertRaises(DemoException):
1417 get_annotations(f, format=fmt)
1418
1419
1420 class TestCallEvaluateFunction(unittest.TestCase):
1421 def test_evaluation(self):
1422 def evaluate(format, exc=NotImplementedError):
1423 if format > 2:
1424 raise exc
1425 return undefined
1426
1427 with self.assertRaises(NameError):
1428 annotationlib.call_evaluate_function(evaluate, Format.VALUE)
1429 self.assertEqual(
1430 annotationlib.call_evaluate_function(evaluate, Format.FORWARDREF),
1431 support.EqualToForwardRef("undefined"),
1432 )
1433 self.assertEqual(
1434 annotationlib.call_evaluate_function(evaluate, Format.STRING),
1435 "undefined",
1436 )
1437
1438 def test_fake_global_evaluation(self):
1439 # This will raise an AttributeError
1440 def evaluate_union(format, exc=NotImplementedError):
1441 if format == Format.VALUE_WITH_FAKE_GLOBALS:
1442 # Return a ForwardRef
1443 return builtins.undefined | list[int]
1444 raise exc
1445
1446 self.assertEqual(
1447 annotationlib.call_evaluate_function(evaluate_union, Format.FORWARDREF),
1448 support.EqualToForwardRef("builtins.undefined | list[int]"),
1449 )
1450
1451 # This will raise an AttributeError
1452 def evaluate_intermediate(format, exc=NotImplementedError):
1453 if format == Format.VALUE_WITH_FAKE_GLOBALS:
1454 intermediate = builtins.undefined
1455 # Return a literal
1456 return intermediate is None
1457 raise exc
1458
1459 self.assertIs(
1460 annotationlib.call_evaluate_function(evaluate_intermediate, Format.FORWARDREF),
1461 False,
1462 )
1463
1464
1465 class TestCallAnnotateFunction(unittest.TestCase):
1466 # Tests for user defined annotate functions.
1467
1468 # Format and NotImplementedError are provided as arguments so they exist in
1469 # the fake globals namespace.
1470 # This avoids non-matching conditions passing by being converted to stringifiers.
1471 # See: https://github.com/python/cpython/issues/138764
1472
1473 def test_user_annotate_value(self):
1474 def annotate(format, /):
1475 if format == Format.VALUE:
1476 return {"x": str}
1477 else:
1478 raise NotImplementedError(format)
1479
1480 annotations = annotationlib.call_annotate_function(
1481 annotate,
1482 Format.VALUE,
1483 )
1484
1485 self.assertEqual(annotations, {"x": str})
1486
1487 def test_user_annotate_forwardref_supported(self):
1488 # If Format.FORWARDREF is supported prefer it over Format.VALUE
1489 def annotate(format, /, __Format=Format, __NotImplementedError=NotImplementedError):
1490 if format == __Format.VALUE:
1491 return {'x': str}
1492 elif format == __Format.VALUE_WITH_FAKE_GLOBALS:
1493 return {'x': int}
1494 elif format == __Format.FORWARDREF:
1495 return {'x': float}
1496 else:
1497 raise __NotImplementedError(format)
1498
1499 annotations = annotationlib.call_annotate_function(
1500 annotate,
1501 Format.FORWARDREF
1502 )
1503
1504 self.assertEqual(annotations, {"x": float})
1505
1506 def test_user_annotate_forwardref_fakeglobals(self):
1507 # If Format.FORWARDREF is not supported, use Format.VALUE_WITH_FAKE_GLOBALS
1508 # before falling back to Format.VALUE
1509 def annotate(format, /, __Format=Format, __NotImplementedError=NotImplementedError):
1510 if format == __Format.VALUE:
1511 return {'x': str}
1512 elif format == __Format.VALUE_WITH_FAKE_GLOBALS:
1513 return {'x': int}
1514 else:
1515 raise __NotImplementedError(format)
1516
1517 annotations = annotationlib.call_annotate_function(
1518 annotate,
1519 Format.FORWARDREF
1520 )
1521
1522 self.assertEqual(annotations, {"x": int})
1523
1524 def test_user_annotate_forwardref_value_fallback(self):
1525 # If Format.FORWARDREF and Format.VALUE_WITH_FAKE_GLOBALS are not supported
1526 # use Format.VALUE
1527 def annotate(format, /, __Format=Format, __NotImplementedError=NotImplementedError):
1528 if format == __Format.VALUE:
1529 return {"x": str}
1530 else:
1531 raise __NotImplementedError(format)
1532
1533 annotations = annotationlib.call_annotate_function(
1534 annotate,
1535 Format.FORWARDREF,
1536 )
1537
1538 self.assertEqual(annotations, {"x": str})
1539
1540 def test_user_annotate_string_supported(self):
1541 # If Format.STRING is supported prefer it over Format.VALUE
1542 def annotate(format, /, __Format=Format, __NotImplementedError=NotImplementedError):
1543 if format == __Format.VALUE:
1544 return {'x': str}
1545 elif format == __Format.VALUE_WITH_FAKE_GLOBALS:
1546 return {'x': int}
1547 elif format == __Format.STRING:
1548 return {'x': "float"}
1549 else:
1550 raise __NotImplementedError(format)
1551
1552 annotations = annotationlib.call_annotate_function(
1553 annotate,
1554 Format.STRING,
1555 )
1556
1557 self.assertEqual(annotations, {"x": "float"})
1558
1559 def test_user_annotate_string_fakeglobals(self):
1560 # If Format.STRING is not supported but Format.VALUE_WITH_FAKE_GLOBALS is
1561 # prefer that over Format.VALUE
1562 def annotate(format, /, __Format=Format, __NotImplementedError=NotImplementedError):
1563 if format == __Format.VALUE:
1564 return {'x': str}
1565 elif format == __Format.VALUE_WITH_FAKE_GLOBALS:
1566 return {'x': int}
1567 else:
1568 raise __NotImplementedError(format)
1569
1570 annotations = annotationlib.call_annotate_function(
1571 annotate,
1572 Format.STRING,
1573 )
1574
1575 self.assertEqual(annotations, {"x": "int"})
1576
1577 def test_user_annotate_string_value_fallback(self):
1578 # If Format.STRING and Format.VALUE_WITH_FAKE_GLOBALS are not
1579 # supported fall back to Format.VALUE and convert to strings
1580 def annotate(format, /, __Format=Format, __NotImplementedError=NotImplementedError):
1581 if format == __Format.VALUE:
1582 return {"x": str}
1583 else:
1584 raise __NotImplementedError(format)
1585
1586 annotations = annotationlib.call_annotate_function(
1587 annotate,
1588 Format.STRING,
1589 )
1590
1591 self.assertEqual(annotations, {"x": "str"})
1592
1593 def test_condition_not_stringified(self):
1594 # Make sure the first condition isn't evaluated as True by being converted
1595 # to a _Stringifier
1596 def annotate(format, /):
1597 if format == Format.FORWARDREF:
1598 return {"x": str}
1599 else:
1600 raise NotImplementedError(format)
1601
1602 with self.assertRaises(NotImplementedError):
1603 annotationlib.call_annotate_function(annotate, Format.STRING)
1604
1605 def test_unsupported_formats(self):
1606 def annotate(format, /):
1607 if format == Format.FORWARDREF:
1608 return {"x": str}
1609 else:
1610 raise NotImplementedError(format)
1611
1612 with self.assertRaises(ValueError):
1613 annotationlib.call_annotate_function(annotate, Format.VALUE_WITH_FAKE_GLOBALS)
1614
1615 with self.assertRaises(RuntimeError):
1616 annotationlib.call_annotate_function(annotate, Format.VALUE)
1617
1618 with self.assertRaises(ValueError):
1619 # Some non-Format value
1620 annotationlib.call_annotate_function(annotate, 7)
1621
1622 def test_basic_non_function_annotate(self):
1623 class Annotate:
1624 def __call__(self, format, /, __Format=Format,
1625 __NotImplementedError=NotImplementedError):
1626 if format == __Format.VALUE:
1627 return {'x': str}
1628 elif format == __Format.VALUE_WITH_FAKE_GLOBALS:
1629 return {'x': int}
1630 elif format == __Format.STRING:
1631 return {'x': "float"}
1632 else:
1633 raise __NotImplementedError(format)
1634
1635 annotations = annotationlib.call_annotate_function(Annotate(), Format.VALUE)
1636 self.assertEqual(annotations, {"x": str})
1637
1638 annotations = annotationlib.call_annotate_function(Annotate(), Format.STRING)
1639 self.assertEqual(annotations, {"x": "float"})
1640
1641 with self.assertRaises(AttributeError) as cm:
1642 annotations = annotationlib.call_annotate_function(
1643 Annotate(), Format.FORWARDREF
1644 )
1645
1646 self.assertEqual(cm.exception.name, "__builtins__")
1647 self.assertIsInstance(cm.exception.obj, Annotate)
1648
1649 def test_full_non_function_annotate(self):
1650 def outer():
1651 local = str
1652
1653 class Annotate:
1654 called_formats = []
1655
1656 def __call__(self, format=None, *, _self=None):
1657 nonlocal local
1658 if _self is not None:
1659 self, format = _self, self
1660
1661 self.called_formats.append(format)
1662 if format == 1: # VALUE
1663 return {"x": MyClass, "y": int, "z": local}
1664 if format == 2: # VALUE_WITH_FAKE_GLOBALS
1665 return {"w": unknown, "x": MyClass, "y": int, "z": local}
1666 raise NotImplementedError
1667
1668 __globals__ = {"MyClass": MyClass}
1669 __builtins__ = {"int": int}
1670 __closure__ = (types.CellType(str),)
1671 __defaults__ = (None,)
1672
1673 __kwdefaults__ = property(lambda self: dict(_self=self))
1674 __code__ = property(lambda self: self.__call__.__code__)
1675
1676 return Annotate()
1677
1678 annotate = outer()
1679
1680 self.assertEqual(
1681 annotationlib.call_annotate_function(annotate, Format.VALUE),
1682 {"x": MyClass, "y": int, "z": str}
1683 )
1684 self.assertEqual(annotate.called_formats[-1], Format.VALUE)
1685
1686 self.assertEqual(
1687 annotationlib.call_annotate_function(annotate, Format.STRING),
1688 {"w": "unknown", "x": "MyClass", "y": "int", "z": "local"}
1689 )
1690 self.assertIn(Format.STRING, annotate.called_formats)
1691 self.assertEqual(annotate.called_formats[-1], Format.VALUE_WITH_FAKE_GLOBALS)
1692
1693 self.assertEqual(
1694 annotationlib.call_annotate_function(annotate, Format.FORWARDREF),
1695 {"w": support.EqualToForwardRef("unknown"), "x": MyClass, "y": int, "z": str}
1696 )
1697 self.assertIn(Format.FORWARDREF, annotate.called_formats)
1698 self.assertEqual(annotate.called_formats[-1], Format.VALUE_WITH_FAKE_GLOBALS)
1699
1700 def test_error_from_value_raised(self):
1701 # Test that the error from format.VALUE is raised
1702 # if all formats fail
1703
1704 class DemoException(Exception): ...
1705
1706 def annotate(format, /):
1707 if format == Format.VALUE:
1708 raise DemoException()
1709 else:
1710 raise NotImplementedError(format)
1711
1712 for fmt in [Format.VALUE, Format.FORWARDREF, Format.STRING]:
1713 with self.assertRaises(DemoException):
1714 annotationlib.call_annotate_function(annotate, format=fmt)
1715
1716
1717 class MetaclassTests(unittest.TestCase):
1718 def test_annotated_meta(self):
1719 class Meta(type):
1720 a: int
1721
1722 class X(metaclass=Meta):
1723 pass
1724
1725 class Y(metaclass=Meta):
1726 b: float
1727
1728 self.assertEqual(get_annotations(Meta), {"a": int})
1729 self.assertEqual(Meta.__annotate__(Format.VALUE), {"a": int})
1730
1731 self.assertEqual(get_annotations(X), {})
1732 self.assertIs(X.__annotate__, None)
1733
1734 self.assertEqual(get_annotations(Y), {"b": float})
1735 self.assertEqual(Y.__annotate__(Format.VALUE), {"b": float})
1736
1737 def test_unannotated_meta(self):
1738 class Meta(type):
1739 pass
1740
1741 class X(metaclass=Meta):
1742 a: str
1743
1744 class Y(X):
1745 pass
1746
1747 self.assertEqual(get_annotations(Meta), {})
1748 self.assertIs(Meta.__annotate__, None)
1749
1750 self.assertEqual(get_annotations(Y), {})
1751 self.assertIs(Y.__annotate__, None)
1752
1753 self.assertEqual(get_annotations(X), {"a": str})
1754 self.assertEqual(X.__annotate__(Format.VALUE), {"a": str})
1755
1756 def test_ordering(self):
1757 # Based on a sample by David Ellis
1758 # https://discuss.python.org/t/pep-749-implementing-pep-649/54974/38
1759
1760 def make_classes():
1761 class Meta(type):
1762 a: int
1763 expected_annotations = {"a": int}
1764
1765 class A(type, metaclass=Meta):
1766 b: float
1767 expected_annotations = {"b": float}
1768
1769 class B(metaclass=A):
1770 c: str
1771 expected_annotations = {"c": str}
1772
1773 class C(B):
1774 expected_annotations = {}
1775
1776 class D(metaclass=Meta):
1777 expected_annotations = {}
1778
1779 return Meta, A, B, C, D
1780
1781 classes = make_classes()
1782 class_count = len(classes)
1783 for order in itertools.permutations(range(class_count), class_count):
1784 names = ", ".join(classes[i].__name__ for i in order)
1785 with self.subTest(names=names):
1786 classes = make_classes() # Regenerate classes
1787 for i in order:
1788 get_annotations(classes[i])
1789 for c in classes:
1790 with self.subTest(c=c):
1791 self.assertEqual(get_annotations(c), c.expected_annotations)
1792 annotate_func = getattr(c, "__annotate__", None)
1793 if c.expected_annotations:
1794 self.assertEqual(
1795 annotate_func(Format.VALUE), c.expected_annotations
1796 )
1797 else:
1798 self.assertIs(annotate_func, None)
1799
1800
1801 class TestGetAnnotateFromClassNamespace(unittest.TestCase):
1802 def test_with_metaclass(self):
1803 class Meta(type):
1804 def __new__(mcls, name, bases, ns):
1805 annotate = annotationlib.get_annotate_from_class_namespace(ns)
1806 expected = ns["expected_annotate"]
1807 with self.subTest(name=name):
1808 if expected:
1809 self.assertIsNotNone(annotate)
1810 else:
1811 self.assertIsNone(annotate)
1812 return super().__new__(mcls, name, bases, ns)
1813
1814 class HasAnnotations(metaclass=Meta):
1815 expected_annotate = True
1816 a: int
1817
1818 class NoAnnotations(metaclass=Meta):
1819 expected_annotate = False
1820
1821 class CustomAnnotate(metaclass=Meta):
1822 expected_annotate = True
1823 def __annotate__(format):
1824 return {}
1825
1826 code = """
1827 from __future__ import annotations
1828
1829 class HasFutureAnnotations(metaclass=Meta):
1830 expected_annotate = False
1831 a: int
1832 """
1833 exec(textwrap.dedent(code), {"Meta": Meta})
1834
1835
1836 class TestTypeRepr(unittest.TestCase):
1837 def test_type_repr(self):
1838 class Nested:
1839 pass
1840
1841 def nested():
1842 pass
1843
1844 self.assertEqual(type_repr(int), "int")
1845 self.assertEqual(type_repr(MyClass), f"{__name__}.MyClass")
1846 self.assertEqual(
1847 type_repr(Nested), f"{__name__}.TestTypeRepr.test_type_repr.<locals>.Nested"
1848 )
1849 self.assertEqual(
1850 type_repr(nested), f"{__name__}.TestTypeRepr.test_type_repr.<locals>.nested"
1851 )
1852 self.assertEqual(type_repr(len), "len")
1853 self.assertEqual(type_repr(type_repr), "annotationlib.type_repr")
1854 self.assertEqual(type_repr(times_three), f"{__name__}.times_three")
1855 self.assertEqual(type_repr(...), "...")
1856 self.assertEqual(type_repr(None), "None")
1857 self.assertEqual(type_repr(1), "1")
1858 self.assertEqual(type_repr("1"), "'1'")
1859 self.assertEqual(type_repr(Format.VALUE), repr(Format.VALUE))
1860 self.assertEqual(type_repr(MyClass()), "my repr")
1861 # gh138558 tests
1862 self.assertEqual(type_repr(t'''{ 0
1863 & 1
1864 | 2
1865 }'''), 't"""{ 0\n & 1\n | 2}"""')
1866 self.assertEqual(
1867 type_repr(Template("hi", Interpolation(42, "42"))), "t'hi{42}'"
1868 )
1869 self.assertEqual(
1870 type_repr(Template("hi", Interpolation(42))),
1871 "Template('hi', Interpolation(42, '', None, ''))",
1872 )
1873 self.assertEqual(
1874 type_repr(Template("hi", Interpolation(42, " "))),
1875 "Template('hi', Interpolation(42, ' ', None, ''))",
1876 )
1877 # gh138558: perhaps in the future, we can improve this behavior:
1878 self.assertEqual(type_repr(Template(Interpolation(42, "99"))), "t'{99}'")
1879
1880
1881 class TestAnnotationsToString(unittest.TestCase):
1882 def test_annotations_to_string(self):
1883 self.assertEqual(annotations_to_string({}), {})
1884 self.assertEqual(annotations_to_string({"x": int}), {"x": "int"})
1885 self.assertEqual(annotations_to_string({"x": "int"}), {"x": "int"})
1886 self.assertEqual(
1887 annotations_to_string({"x": int, "y": str}), {"x": "int", "y": "str"}
1888 )
1889
1890
1891 class A:
1892 pass
1893
1894 TypeParamsAlias1 = int
1895
1896 class TypeParamsSample[TypeParamsAlias1, TypeParamsAlias2]:
1897 TypeParamsAlias2 = str
1898
1899
1900 class TestForwardRefClass(unittest.TestCase):
1901 def test_forwardref_instance_type_error(self):
1902 fr = ForwardRef("int")
1903 with self.assertRaises(TypeError):
1904 isinstance(42, fr)
1905
1906 def test_forwardref_subclass_type_error(self):
1907 fr = ForwardRef("int")
1908 with self.assertRaises(TypeError):
1909 issubclass(int, fr)
1910
1911 def test_forwardref_only_str_arg(self):
1912 with self.assertRaises(TypeError):
1913 ForwardRef(1) # only `str` type is allowed
1914
1915 def test_forward_equality(self):
1916 fr = ForwardRef("int")
1917 self.assertEqual(fr, ForwardRef("int"))
1918 self.assertNotEqual(List["int"], List[int])
1919 self.assertNotEqual(fr, ForwardRef("int", module=__name__))
1920 frm = ForwardRef("int", module=__name__)
1921 self.assertEqual(frm, ForwardRef("int", module=__name__))
1922 self.assertNotEqual(frm, ForwardRef("int", module="__other_name__"))
1923
1924 def test_forward_equality_get_type_hints(self):
1925 c1 = ForwardRef("C")
1926 c1_gth = ForwardRef("C")
1927 c2 = ForwardRef("C")
1928 c2_gth = ForwardRef("C")
1929
1930 class C:
1931 pass
1932
1933 def foo(a: c1_gth, b: c2_gth):
1934 pass
1935
1936 self.assertEqual(get_type_hints(foo, globals(), locals()), {"a": C, "b": C})
1937 self.assertEqual(c1, c2)
1938 self.assertEqual(c1, c1_gth)
1939 self.assertEqual(c1_gth, c2_gth)
1940 self.assertEqual(List[c1], List[c1_gth])
1941 self.assertNotEqual(List[c1], List[C])
1942 self.assertNotEqual(List[c1_gth], List[C])
1943 self.assertEqual(Union[c1, c1_gth], Union[c1])
1944 self.assertEqual(Union[c1, c1_gth, int], Union[c1, int])
1945
1946 def test_forward_equality_hash(self):
1947 c1 = ForwardRef("int")
1948 c1_gth = ForwardRef("int")
1949 c2 = ForwardRef("int")
1950 c2_gth = ForwardRef("int")
1951
1952 def foo(a: c1_gth, b: c2_gth):
1953 pass
1954
1955 get_type_hints(foo, globals(), locals())
1956
1957 self.assertEqual(hash(c1), hash(c2))
1958 self.assertEqual(hash(c1_gth), hash(c2_gth))
1959 self.assertEqual(hash(c1), hash(c1_gth))
1960
1961 c3 = ForwardRef("int", module=__name__)
1962 c4 = ForwardRef("int", module="__other_name__")
1963
1964 self.assertNotEqual(hash(c3), hash(c1))
1965 self.assertNotEqual(hash(c3), hash(c1_gth))
1966 self.assertNotEqual(hash(c3), hash(c4))
1967 self.assertEqual(hash(c3), hash(ForwardRef("int", module=__name__)))
1968
1969 def test_forward_equality_and_hash_with_cells(self):
1970 """Regression test for GH-143831."""
1971 class A:
1972 def one(_) -> C1:
1973 """One cell."""
1974
1975 one_f = ForwardRef("C1", owner=one)
1976 one_f_ga1 = get_annotations(one, format=Format.FORWARDREF)["return"]
1977 one_f_ga2 = get_annotations(one, format=Format.FORWARDREF)["return"]
1978 self.assertIsInstance(one_f_ga1.__cell__, types.CellType)
1979 self.assertIs(one_f_ga1.__cell__, one_f_ga2.__cell__)
1980
1981 def two(_) -> C1 | C2:
1982 """Two cells."""
1983
1984 two_f_ga1 = get_annotations(two, format=Format.FORWARDREF)["return"]
1985 two_f_ga2 = get_annotations(two, format=Format.FORWARDREF)["return"]
1986 self.assertIsNot(two_f_ga1.__cell__, two_f_ga2.__cell__)
1987 self.assertIsInstance(two_f_ga1.__cell__, dict)
1988 self.assertIsInstance(two_f_ga2.__cell__, dict)
1989
1990 type C1 = None
1991 type C2 = None
1992
1993 self.assertNotEqual(A.one_f, A.one_f_ga1)
1994 self.assertNotEqual(hash(A.one_f), hash(A.one_f_ga1))
1995
1996 self.assertEqual(A.one_f_ga1, A.one_f_ga2)
1997 self.assertEqual(hash(A.one_f_ga1), hash(A.one_f_ga2))
1998
1999 self.assertEqual(A.two_f_ga1, A.two_f_ga2)
2000 self.assertEqual(hash(A.two_f_ga1), hash(A.two_f_ga2))
2001
2002 def test_forward_equality_namespace(self):
2003 def namespace1():
2004 a = ForwardRef("A")
2005
2006 def fun(x: a):
2007 pass
2008
2009 get_type_hints(fun, globals(), locals())
2010 return a
2011
2012 def namespace2():
2013 a = ForwardRef("A")
2014
2015 class A:
2016 pass
2017
2018 def fun(x: a):
2019 pass
2020
2021 get_type_hints(fun, globals(), locals())
2022 return a
2023
2024 self.assertEqual(namespace1(), namespace1())
2025 self.assertEqual(namespace1(), namespace2())
2026
2027 def test_forward_repr(self):
2028 self.assertEqual(repr(List["int"]), "typing.List[ForwardRef('int')]")
2029 self.assertEqual(
2030 repr(List[ForwardRef("int", module="mod")]),
2031 "typing.List[ForwardRef('int', module='mod')]",
2032 )
2033 self.assertEqual(
2034 repr(List[ForwardRef("int", module="mod", is_class=True)]),
2035 "typing.List[ForwardRef('int', module='mod', is_class=True)]",
2036 )
2037 self.assertEqual(
2038 repr(List[ForwardRef("int", owner="class")]),
2039 "typing.List[ForwardRef('int', owner='class')]",
2040 )
2041
2042 def test_forward_repr_extra_names(self):
2043 def f(a: undefined | str): ...
2044
2045 annos = get_annotations(f, format=Format.FORWARDREF)
2046
2047 self.assertRegex(
2048 repr(annos['a']), r"ForwardRef\('undefined \| str'.*\)"
2049 )
2050
2051 def test_forward_recursion_actually(self):
2052 def namespace1():
2053 a = ForwardRef("A")
2054 A = a
2055
2056 def fun(x: a):
2057 pass
2058
2059 ret = get_type_hints(fun, globals(), locals())
2060 return a
2061
2062 def namespace2():
2063 a = ForwardRef("A")
2064 A = a
2065
2066 def fun(x: a):
2067 pass
2068
2069 ret = get_type_hints(fun, globals(), locals())
2070 return a
2071
2072 r1 = namespace1()
2073 r2 = namespace2()
2074 self.assertIsNot(r1, r2)
2075 self.assertEqual(r1, r2)
2076
2077 def test_syntax_error(self):
2078
2079 with self.assertRaises(SyntaxError):
2080 typing.Generic["/T"]
2081
2082 def test_delayed_syntax_error(self):
2083
2084 def foo(a: "Node[T"):
2085 pass
2086
2087 with self.assertRaises(SyntaxError):
2088 get_type_hints(foo)
2089
2090 def test_syntax_error_empty_string(self):
2091 for form in [typing.List, typing.Set, typing.Type, typing.Deque]:
2092 with self.subTest(form=form):
2093 with self.assertRaises(SyntaxError):
2094 form[""]
2095
2096 def test_or(self):
2097 X = ForwardRef("X")
2098 # __or__/__ror__ itself
2099 self.assertEqual(X | "x", Union[X, "x"])
2100 self.assertEqual("x" | X, Union["x", X])
2101
2102 def test_multiple_ways_to_create(self):
2103 X1 = Union["X"]
2104 self.assertIsInstance(X1, ForwardRef)
2105 X2 = ForwardRef("X")
2106 self.assertIsInstance(X2, ForwardRef)
2107 self.assertEqual(X1, X2)
2108
2109 def test_special_attrs(self):
2110 # Forward refs provide a different introspection API. __name__ and
2111 # __qualname__ make little sense for forward refs as they can store
2112 # complex typing expressions.
2113 fr = ForwardRef("set[Any]")
2114 self.assertNotHasAttr(fr, "__name__")
2115 self.assertNotHasAttr(fr, "__qualname__")
2116 self.assertEqual(fr.__module__, "annotationlib")
2117 # Forward refs are currently unpicklable once they contain a code object.
2118 fr.__forward_code__ # fill the cache
2119 for proto in range(pickle.HIGHEST_PROTOCOL + 1):
2120 with self.assertRaises(TypeError):
2121 pickle.dumps(fr, proto)
2122
2123 def test_evaluate_string_format(self):
2124 fr = ForwardRef("set[Any]")
2125 self.assertEqual(fr.evaluate(format=Format.STRING), "set[Any]")
2126
2127 def test_evaluate_string_format_extra_names(self):
2128 # Test that internal extra_names are replaced when evaluating as strings
2129 def f(a: unknown | str | int | list[str] | tuple[int, ...]): ...
2130
2131 fr = get_annotations(f, format=Format.FORWARDREF)['a']
2132 # Test the cache is not populated before access
2133 self.assertIsNone(fr.__resolved_str_cache__)
2134
2135 self.assertEqual(fr.evaluate(format=Format.STRING), "unknown | str | int | list[str] | tuple[int, ...]")
2136 self.assertEqual(fr.__resolved_str_cache__, "unknown | str | int | list[str] | tuple[int, ...]")
2137
2138 def test_evaluate_forwardref_format(self):
2139 fr = ForwardRef("undef")
2140 evaluated = fr.evaluate(format=Format.FORWARDREF)
2141 self.assertIs(fr, evaluated)
2142
2143 fr = ForwardRef("set[undefined]")
2144 evaluated = fr.evaluate(format=Format.FORWARDREF)
2145 self.assertEqual(
2146 evaluated,
2147 set[support.EqualToForwardRef("undefined")],
2148 )
2149
2150 fr = ForwardRef("a + b")
2151 self.assertEqual(
2152 fr.evaluate(format=Format.FORWARDREF),
2153 support.EqualToForwardRef("a + b"),
2154 )
2155 self.assertEqual(
2156 fr.evaluate(format=Format.FORWARDREF, locals={"a": 1, "b": 2}),
2157 3,
2158 )
2159
2160 fr = ForwardRef('"a" + 1')
2161 self.assertEqual(
2162 fr.evaluate(format=Format.FORWARDREF),
2163 support.EqualToForwardRef('"a" + 1'),
2164 )
2165
2166 def test_evaluate_notimplemented_format(self):
2167 class C:
2168 x: alias
2169
2170 fwdref = get_annotations(C, format=Format.FORWARDREF)["x"]
2171
2172 with self.assertRaises(NotImplementedError):
2173 fwdref.evaluate(format=Format.VALUE_WITH_FAKE_GLOBALS)
2174
2175 with self.assertRaises(NotImplementedError):
2176 # Some other unsupported value
2177 fwdref.evaluate(format=7)
2178
2179 def test_evaluate_with_type_params(self):
2180 class Gen[T]:
2181 alias = int
2182
2183 with self.assertRaises(NameError):
2184 ForwardRef("T").evaluate()
2185 with self.assertRaises(NameError):
2186 ForwardRef("T").evaluate(type_params=())
2187 with self.assertRaises(NameError):
2188 ForwardRef("T").evaluate(owner=int)
2189
2190 (T,) = Gen.__type_params__
2191 self.assertIs(ForwardRef("T").evaluate(type_params=Gen.__type_params__), T)
2192 self.assertIs(ForwardRef("T").evaluate(owner=Gen), T)
2193
2194 with self.assertRaises(NameError):
2195 ForwardRef("alias").evaluate(type_params=Gen.__type_params__)
2196 self.assertIs(ForwardRef("alias").evaluate(owner=Gen), int)
2197 # If you pass custom locals, we don't look at the owner's locals
2198 with self.assertRaises(NameError):
2199 ForwardRef("alias").evaluate(owner=Gen, locals={})
2200 # But if the name exists in the locals, it works
2201 self.assertIs(
2202 ForwardRef("alias").evaluate(owner=Gen, locals={"alias": str}), str
2203 )
2204
2205 def test_evaluate_with_type_params_and_scope_conflict(self):
2206 for is_class in (False, True):
2207 with self.subTest(is_class=is_class):
2208 fwdref1 = ForwardRef("TypeParamsAlias1", owner=TypeParamsSample, is_class=is_class)
2209 fwdref2 = ForwardRef("TypeParamsAlias2", owner=TypeParamsSample, is_class=is_class)
2210
2211 self.assertIs(
2212 fwdref1.evaluate(),
2213 TypeParamsSample.__type_params__[0],
2214 )
2215 self.assertIs(
2216 fwdref2.evaluate(),
2217 TypeParamsSample.TypeParamsAlias2,
2218 )
2219
2220 def test_fwdref_with_module(self):
2221 self.assertIs(ForwardRef("Format", module="annotationlib").evaluate(), Format)
2222 self.assertIs(
2223 ForwardRef("Counter", module="collections").evaluate(), collections.Counter
2224 )
2225 self.assertEqual(
2226 ForwardRef("Counter[int]", module="collections").evaluate(),
2227 collections.Counter[int],
2228 )
2229
2230 with self.assertRaises(NameError):
2231 # If globals are passed explicitly, we don't look at the module dict
2232 ForwardRef("Format", module="annotationlib").evaluate(globals={})
2233
2234 def test_fwdref_to_builtin(self):
2235 self.assertIs(ForwardRef("int").evaluate(), int)
2236 self.assertIs(ForwardRef("int", module="collections").evaluate(), int)
2237 self.assertIs(ForwardRef("int", owner=str).evaluate(), int)
2238
2239 # builtins are still searched with explicit globals
2240 self.assertIs(ForwardRef("int").evaluate(globals={}), int)
2241
2242 # explicit values in globals have precedence
2243 obj = object()
2244 self.assertIs(ForwardRef("int").evaluate(globals={"int": obj}), obj)
2245
2246 def test_fwdref_value_is_not_cached(self):
2247 fr = ForwardRef("hello")
2248 with self.assertRaises(NameError):
2249 fr.evaluate()
2250 self.assertIs(fr.evaluate(globals={"hello": str}), str)
2251 with self.assertRaises(NameError):
2252 fr.evaluate()
2253
2254 def test_fwdref_with_owner(self):
2255 self.assertEqual(
2256 ForwardRef("Counter[int]", owner=collections).evaluate(),
2257 collections.Counter[int],
2258 )
2259
2260 def test_name_lookup_without_eval(self):
2261 # test the codepath where we look up simple names directly in the
2262 # namespaces without going through eval()
2263 self.assertIs(ForwardRef("int").evaluate(), int)
2264 self.assertIs(ForwardRef("int").evaluate(locals={"int": str}), str)
2265 self.assertIs(
2266 ForwardRef("int").evaluate(locals={"int": float}, globals={"int": str}),
2267 float,
2268 )
2269 self.assertIs(ForwardRef("int").evaluate(globals={"int": str}), str)
2270 with support.swap_attr(builtins, "int", dict):
2271 self.assertIs(ForwardRef("int").evaluate(), dict)
2272
2273 with self.assertRaises(NameError, msg="name 'doesntexist' is not defined") as exc:
2274 ForwardRef("doesntexist").evaluate()
2275
2276 self.assertEqual(exc.exception.name, "doesntexist")
2277
2278 def test_evaluate_undefined_generic(self):
2279 # Test the codepath where have to eval() with undefined variables.
2280 class C:
2281 x: alias[int, undef]
2282
2283 generic = get_annotations(C, format=Format.FORWARDREF)["x"].evaluate(
2284 format=Format.FORWARDREF,
2285 globals={"alias": dict}
2286 )
2287 self.assertNotIsInstance(generic, ForwardRef)
2288 self.assertIs(generic.__origin__, dict)
2289 self.assertEqual(len(generic.__args__), 2)
2290 self.assertIs(generic.__args__[0], int)
2291 self.assertIsInstance(generic.__args__[1], ForwardRef)
2292
2293 generic = get_annotations(C, format=Format.FORWARDREF)["x"].evaluate(
2294 format=Format.FORWARDREF,
2295 globals={"alias": Union},
2296 locals={"alias": dict}
2297 )
2298 self.assertNotIsInstance(generic, ForwardRef)
2299 self.assertIs(generic.__origin__, dict)
2300 self.assertEqual(len(generic.__args__), 2)
2301 self.assertIs(generic.__args__[0], int)
2302 self.assertIsInstance(generic.__args__[1], ForwardRef)
2303
2304 def test_fwdref_invalid_syntax(self):
2305 fr = ForwardRef("if")
2306 with self.assertRaises(SyntaxError):
2307 fr.evaluate()
2308 fr = ForwardRef("1+")
2309 with self.assertRaises(SyntaxError):
2310 fr.evaluate()
2311
2312 def test_re_evaluate_generics(self):
2313 global global_alias
2314
2315 # If we've already run this test before,
2316 # ensure the variable is still undefined
2317 if "global_alias" in globals():
2318 del global_alias
2319
2320 class C:
2321 x: global_alias[int]
2322
2323 # Evaluate the ForwardRef once
2324 evaluated = get_annotations(C, format=Format.FORWARDREF)["x"].evaluate(
2325 format=Format.FORWARDREF
2326 )
2327
2328 # Now define the global and ensure that the ForwardRef evaluates
2329 global_alias = list
2330 self.assertEqual(evaluated.evaluate(), list[int])
2331
2332 def test_fwdref_evaluate_argument_mutation(self):
2333 class C[T]:
2334 nonlocal alias
2335 x: alias[T]
2336
2337 # Mutable arguments
2338 globals_ = globals()
2339 globals_copy = globals_.copy()
2340 locals_ = locals()
2341 locals_copy = locals_.copy()
2342
2343 # Evaluate the ForwardRef, ensuring we use __cell__ and type params
2344 get_annotations(C, format=Format.FORWARDREF)["x"].evaluate(
2345 globals=globals_,
2346 locals=locals_,
2347 type_params=C.__type_params__,
2348 format=Format.FORWARDREF,
2349 )
2350
2351 # Check if the passed in mutable arguments equal the originals
2352 self.assertEqual(globals_, globals_copy)
2353 self.assertEqual(locals_, locals_copy)
2354
2355 alias = list
2356
2357 def test_fwdref_final_class(self):
2358 with self.assertRaises(TypeError):
2359 class C(ForwardRef):
2360 pass
2361
2362
2363 class TestAnnotationLib(unittest.TestCase):
2364 def test__all__(self):
2365 support.check__all__(self, annotationlib)
2366
2367 @support.cpython_only
2368 def test_lazy_imports(self):
2369 import_helper.ensure_lazy_imports(
2370 "annotationlib",
2371 {
2372 "typing",
2373 "warnings",
2374 },
2375 )