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'>}