https://github.com/python/cpython/commit/032b1be5bb88f0988a13b056f1a09253acc0d838 commit: 032b1be5bb88f0988a13b056f1a09253acc0d838 branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: JelleZijlstra <[email protected]> date: 2026-04-22T19:59:18-07:00 summary:
[3.14] gh-119180: Document the `format` parameter in `typing.get_type_hints()` (GH-143758) (#148901) 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. (cherry picked from commit 8bf99ae3a9f12d105a70d6fda93dddde4adeee8f) Co-authored-by: Victorien <[email protected]> files: M Doc/library/typing.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 40f8c130d801db..7a76bc5545724b 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -3346,13 +3346,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 @@ -3366,17 +3366,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. @@ -3384,11 +3382,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:: @@ -3406,6 +3405,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]
