https://github.com/python/cpython/commit/8bf99ae3a9f12d105a70d6fda93dddde4adeee8f
commit: 8bf99ae3a9f12d105a70d6fda93dddde4adeee8f
branch: main
author: Victorien <[email protected]>
committer: JelleZijlstra <[email protected]>
date: 2026-04-23T02:50:15Z
summary:
gh-119180: Document the `format` parameter in `typing.get_type_hints()`
(#143758)
Do not mention `__annotations__` dictionaries, as this is slightly
outdated since 3.14.
Rewrite the note about possible exceptions for clarity. Also do not
mention imported type aliases, as since 3.12 aliases with the `type`
statement do not suffer from this limitation anymore.
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 04acf2c16d15d2..1957cadcbb1592 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -3453,13 +3453,13 @@ Functions and decorators
Introspection helpers
---------------------
-.. function:: get_type_hints(obj, globalns=None, localns=None,
include_extras=False)
+.. function:: get_type_hints(obj, globalns=None, localns=None,
include_extras=False, *, format=Format.VALUE)
Return a dictionary containing type hints for a function, method, module,
class object, or other callable object.
- This is often the same as ``obj.__annotations__``, but this function makes
- the following changes to the annotations dictionary:
+ This is often the same as :func:`annotationlib.get_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
@@ -3473,17 +3473,15 @@ Introspection helpers
annotations from ``C``'s base classes with those on ``C`` directly. This
is done by traversing :attr:`C.__mro__ <type.__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.
+ :term:`annotations <variable annotation>` of each base class. 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, ...]``, ``Required[T]``, ``NotRequired[T]``, and
``ReadOnly[T]``
with ``T``, unless *include_extras* is set to ``True`` (see
:class:`Annotated` for more information).
- See also :func:`annotationlib.get_annotations`, a lower-level function that
- returns annotations more directly.
-
.. caution::
This function may execute arbitrary code contained in annotations.
@@ -3491,11 +3489,12 @@ Introspection helpers
.. note::
- 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>`.
+ If :attr:`Format.VALUE <annotationlib.Format.VALUE>` is used and any
+ forward references in the annotations of *obj* are not resolvable, a
+ :exc:`NameError` exception is raised. For example, this can happen
+ with names imported under :data:`if TYPE_CHECKING <TYPE_CHECKING>`.
+ More generally, any kind of exception can be raised if an annotation
+ contains invalid Python code.
.. note::
@@ -3513,6 +3512,10 @@ Introspection helpers
if a default value equal to ``None`` was set.
Now the annotation is returned unchanged.
+ .. versionchanged:: 3.14
+ Added the ``format`` parameter. See the documentation on
+ :func:`annotationlib.get_annotations` for more information.
+
.. versionchanged:: 3.14
Calling :func:`get_type_hints` on instances is no longer supported.
Some instances were accepted in earlier versions as an undocumented
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
