Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-04-26 13:50:54 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-119180: Document the format parameter in typing.get_type_hints() (#143758)

Browse source 
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.
This commit is contained in:
Victorien 2026-04-23 04:50:15 +02:00 • committed by GitHub
parent 75ff1afcb6
commit 8bf99ae3a9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 17 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

31
Doc/library/typing.rst
View file

@ -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