From 8896a25b6b3897af0fa9a41378841747b8e7f50b Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Mon, 12 Jan 2026 21:55:28 +0100 Subject: [PATCH 1/4] gh-119180: Document the `format` parameter in `typing.get_type_hints()` --- Doc/library/typing.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 73236413cbb80f..351f52e665f199 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3328,7 +3328,7 @@ 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 or class object. @@ -3381,6 +3381,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. + .. function:: get_origin(tp) Get the unsubscripted version of a type: for a typing object of the form From 9dd2b19d4c4c9e07e4d0fdb2964ec852eed428e8 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Mon, 12 Jan 2026 22:01:30 +0100 Subject: [PATCH 2/4] Rewrite some sections 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. --- Doc/library/typing.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 351f52e665f199..01521329863c8d 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3348,7 +3348,7 @@ Introspection helpers annotations from ``C``'s base classes with those on ``C`` directly. This is done by traversing :attr:`C.__mro__ ` and iteratively combining - ``__annotations__`` dictionaries. Annotations on classes appearing + :term:`annotations ` 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 @@ -3366,11 +3366,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 ` that include forward references, - or with names imported under :data:`if TYPE_CHECKING `. + If :attr:`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 `. + More generally, any kind of exception can be raised if an annotation + contains invalid Python code. .. versionchanged:: 3.9 Added ``include_extras`` parameter as part of :pep:`593`. From f5fc94332f26d5611bca8f32fac0ef32370047a4 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Tue, 13 Jan 2026 10:03:14 +0100 Subject: [PATCH 3/4] Wrap lines --- Doc/library/typing.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 01521329863c8d..72969feeb5330d 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3348,9 +3348,10 @@ Introspection helpers annotations from ``C``'s base classes with those on ``C`` directly. This is done by traversing :attr:`C.__mro__ ` and iteratively combining - :term:`annotations ` 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. + :term:`annotations ` 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 From 8cc9875d1ca15aed972b0805cea9adaace7b7126 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Tue, 13 Jan 2026 10:04:11 +0100 Subject: [PATCH 4/4] Mention `get_annotations()` early --- Doc/library/typing.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 72969feeb5330d..46062d27ada2f2 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3333,8 +3333,8 @@ Introspection helpers Return a dictionary containing type hints for a function, method, module or class 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 @@ -3357,9 +3357,6 @@ Introspection helpers 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.