diff options
author | Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> | 2024-06-02 17:21:47 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-06-02 15:21:47 +0000 |
commit | c8de0ec7b96d1c6d27f281c1ab7dc07e03283d22 (patch) | |
tree | e58c50ce164e9d6075649fc2a4aff7ae3ef12947 | |
parent | [3.12] gh-119016: Remove outdated sentences from the "classes" tutorial (GH-1... (diff) | |
download | cpython-c8de0ec7b96d1c6d27f281c1ab7dc07e03283d22.tar.gz cpython-c8de0ec7b96d1c6d27f281c1ab7dc07e03283d22.tar.bz2 cpython-c8de0ec7b96d1c6d27f281c1ab7dc07e03283d22.zip |
[3.12] Improve documentation for typing.get_type_hints (GH-119928) (#119944)
- Explicit list of what it does that is different from
"just return __annotations__"
- Remove reference to PEP 563; adding the future import doesn't
do anything to type aliases, and in general it will never make
get_type_hints() less likely to fail.
- Remove example, as the Annotated docs already have a similar
example, and it's unbalanced to have one example about this
one edge case but not about other behaviors of the function.
(cherry picked from commit aa9fe98e0649f0a151942914ef4e2810ca6126c2)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
-rw-r--r-- | Doc/library/typing.rst | 54 |
1 files changed, 28 insertions, 26 deletions
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index a39c2092e54..439e2bcd7dc 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2883,35 +2883,37 @@ Introspection helpers Return a dictionary containing type hints for a function, method, module or class object. - This is often the same as ``obj.__annotations__``. In addition, - forward references encoded as string literals are handled by evaluating - them in ``globals``, ``locals`` and (where applicable) - :ref:`type parameter <type-params>` namespaces. - For a class ``C``, return - a dictionary constructed by merging all the ``__annotations__`` along - ``C.__mro__`` in reverse order. - - The function recursively replaces all ``Annotated[T, ...]`` with ``T``, - unless ``include_extras`` is set to ``True`` (see :class:`Annotated` for - more information). For example: - - .. testcode:: - - class Student(NamedTuple): - name: Annotated[str, 'some marker'] - - assert get_type_hints(Student) == {'name': str} - assert get_type_hints(Student, include_extras=False) == {'name': str} - assert get_type_hints(Student, include_extras=True) == { - 'name': Annotated[str, 'some marker'] - } + This is often the same as ``obj.__annotations__``, but this function makes + the following changes to the annotations dictionary: + + * Forward references encoded as string literals or :class:`ForwardRef` + objects are handled by evaluating them in *globalns*, *localns*, and + (where applicable) *obj*'s :ref:`type parameter <type-params>` namespace. + If *globalns* or *localns* is not given, appropriate namespace + dictionaries are inferred from *obj*. + * ``None`` is replaced with :class:`types.NoneType`. + * If :func:`@no_type_check <no_type_check>` has been applied to *obj*, an + empty dictionary is returned. + * If *obj* is a class ``C``, the function returns a dictionary that merges + annotations from ``C``'s base classes with those on ``C`` directly. This + is done by traversing ``C.__mro__`` and iteratively combining + ``__annotations__`` dictionaries. Annotations on classes appearing + earlier in the :term:`method resolution order` always take precedence over + annotations on classes appearing later in the method resolution order. + * The function recursively replaces all occurrences of ``Annotated[T, ...]`` + with ``T``, unless *include_extras* is set to ``True`` (see + :class:`Annotated` for more information). + + See also :func:`inspect.get_annotations`, a lower-level function that + returns annotations more directly. .. note:: - :func:`get_type_hints` does not work with imported - :ref:`type aliases <type-aliases>` that include forward references. - Enabling postponed evaluation of annotations (:pep:`563`) may remove - the need for most forward references. + If any forward references in the annotations of *obj* are not resolvable + or are not valid Python code, this function will raise an exception + such as :exc:`NameError`. For example, this can happen with imported + :ref:`type aliases <type-aliases>` that include forward references, + or with names imported under :data:`if TYPE_CHECKING <TYPE_CHECKING>`. .. versionchanged:: 3.9 Added ``include_extras`` parameter as part of :pep:`593`. |