Document difference between typing.get_type_hints and inspect.get_annotations(eval_str=True)

[hauntsaninja]

The differences are subtle, it could be nice to explicitly document them somewhere.

[ericvsmith]

It might make sense to delay this until PEP 649 is accepted. Or at least expect to rework it.

But I agree it's a good idea.

[chongkong]

I'm still having difficulty understanding a diff. Before publishing the doc, can you explain the diffs briefly?

[Hnasar]

I came across a difference— it has to do with how stringified types (or from __future__ import annotations) are evaluated with TypedDicts. When using inspect.get_annotations the type is ForwardRef("str"), but with typing.get_type_hints the type is (a more typical) str. I'm not sure if this is a bug or an intended difference; but having two similar functions sure is confusing!

# test_ann.py
import dataclasses
import enum
import inspect
import typing
import pytest

class ATypedDict(typing.TypedDict):
    x: str

class ATypedDictWithStr(typing.TypedDict):
    x: "str"

class AnEnum(enum.Enum):
    x: str = 1

class AnEnumWithStr(enum.Enum):
    x: "str" = 1

@dataclasses.dataclass
class ADataClass:
    x: str

@dataclasses.dataclass
class ADataClassWithStr:
    x: "str"

@pytest.mark.parametrize(
    "cls",
    (
        ATypedDict,
        ATypedDictWithStr,
        AnEnum,
        AnEnumWithStr,
        ADataClass,
        ADataClassWithStr,
    ),
)
def test_equality(cls):
    assert inspect.get_annotations(cls, eval_str=True) == typing.get_type_hints(cls)

$ python3 -m pytest test_ann.py  -vvv
============================== test session starts ==============================
platform linux -- Python 3.11.9, pytest-7.4.0, pluggy-1.2.0
test_ann.py::test_equality[ATypedDict] PASSED                             [ 16%]
test_ann.py::test_equality[ATypedDictWithStr] FAILED                      [ 33%]
test_ann.py::test_equality[AnEnum] PASSED                                 [ 50%]
test_ann.py::test_equality[AnEnumWithStr] PASSED                          [ 66%]
test_ann.py::test_equality[ADataClass] PASSED                             [ 83%]
test_ann.py::test_equality[ADataClassWithStr] PASSED                      [100%]

=================================== FAILURES ====================================
_______________________ test_equality[ATypedDictWithStr] ________________________

cls = <class 'test_ann.ATypedDictWithStr'>

    @pytest.mark.parametrize(
        "cls", (…),
    )
    def test_equality(cls):
>       assert inspect.get_annotations(cls, eval_str=True) == typing.get_type_hints(cls)
E       AssertionError: assert {'x': ForwardRef('str', module='test_ann')} == {'x': <class 'str'>}
E         Differing items:
E         {'x': ForwardRef('str', module='test_ann')} != {'x': <class 'str'>}
E         Full diff:
E         - {'x': <class 'str'>}
E         + {'x': ForwardRef('str', module='test_ann')}

test_ann.py:47: AssertionError
========================== 1 failed, 5 passed in 0.04s ==========================

[Hnasar]

Another difference: only typing.get_type_hints returns the inherited members:

import inspect, typing

class A:
    age: int

class B(A):
    name: str

print(inspect.get_annotations(B))  # {'name': <class 'str'>}
print(typing.get_type_hints(B))  # {'age': <class 'int'>, 'name': <class 'str'>}

[emcd]

Another difference that is not very explicit in the documentation is that get_type_hints attempts to validate that the annotation is actually a type whereas get_annotations does not. (Mentioned by Jelle Zijlstra here.) If the validation fails, you will see an exception like:

TypeError: typing.ClassVar[int] is not valid as type argument

whereas get_annotations will happily return the annotation as-is.

[JelleZijlstra]

https://docs.python.org/3.14/library/typing.html#typing.get_type_hints now documents most of the differences, though we're missing the thing about raising errors on invalid types like ClassVar.

For what it's worth, I think most of what get_type_hints() does over get_annotations() is an attractive nuisance. The main useful things probably are that it's more thorough in evaluating forwardrefs and that it adds annotations from base classes.

[emcd]

Agreed. (The currently published Python 3.13 documentation has the same list, btw.) I mentioned the type validation here rather than opening a new issue since this issue is still open and seemingly collecting action items.

Earlier, I switched from get_annotations (with eval_str) to get_type_hints because of the automatic MRO traversal on classes for merging inherited annotations (as mentioned in the documentation). But, now, I am going to switch back and write my own merge for inherited annotations. Attractive nuisance, indeed.

[JelleZijlstra]

Oh it's worse, it raises on invalid types only if they are wrapped in a ForwardRef:

>>> import typing
>>> def f(x: typing.ClassVar[int]): pass
... 
>>> typing.get_type_hints(f)
{'x': typing.ClassVar[int]}
>>> def f(x: "typing.ClassVar[int]"): pass
... 
>>> typing.get_type_hints(f)
Traceback (most recent call last):
  File "<python-input-4>", line 1, in <module>
    typing.get_type_hints(f)
    ~~~~~~~~~~~~~~~~~~~~~^^^
  File "/Users/jelle/py/cpython/Lib/typing.py", line 2390, in get_type_hints
    hints[name] = _eval_type(value, globalns, localns, type_params, format=format, owner=obj)
                  ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jelle/py/cpython/Lib/typing.py", line 448, in _eval_type
    return evaluate_forward_ref(t, globals=globalns, locals=localns,
                                type_params=type_params, owner=owner,
                                _recursive_guard=recursive_guard, format=format)
  File "/Users/jelle/py/cpython/Lib/typing.py", line 993, in evaluate_forward_ref
    type_ = _type_check(
        value,
    ...<2 lines>...
        allow_special_forms=forward_ref.__forward_is_class__,
    )
  File "/Users/jelle/py/cpython/Lib/typing.py", line 204, in _type_check
    raise TypeError(f"{arg} is not valid as type argument")
TypeError: typing.ClassVar[int] is not valid as type argument

I'll open a new issue for that; I feel it's a bug.