https://github.com/python/cpython/commit/aa9fe98e0649f0a151942914ef4e2810ca6126c2
commit: aa9fe98e0649f0a151942914ef4e2810ca6126c2
branch: main
author: Jelle Zijlstra <jelle.zijls...@gmail.com>
committer: JelleZijlstra <jelle.zijls...@gmail.com>
date: 2024-06-02T08:13:24-07:00
summary:
Improve documentation for typing.get_type_hints (#119928)
- 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.
Co-authored-by: Alex Waygood <alex.wayg...@gmail.com>
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index a8068609fcfbe7..94de64fcf835fc 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -3080,35 +3080,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`.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
