@@ -3453,13 +3453,13 @@ Functions and decorators |
3453 | 3453 | Introspection helpers |
3454 | 3454 | --------------------- |
3455 | 3455 |
|
3456 | | -.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False) |
| 3456 | +.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False, *, format=Format.VALUE) |
3457 | 3457 |
|
3458 | 3458 | Return a dictionary containing type hints for a function, method, module, |
3459 | 3459 | class object, or other callable object. |
3460 | 3460 |
|
3461 | | - This is often the same as ``obj.__annotations__``, but this function makes |
3462 | | - the following changes to the annotations dictionary: |
| 3461 | + This is often the same as :func:`annotationlib.get_annotations`, but this |
| 3462 | + function makes the following changes to the annotations dictionary: |
3463 | 3463 |
|
3464 | 3464 | * Forward references encoded as string literals or :class:`ForwardRef` |
3465 | 3465 | objects are handled by evaluating them in *globalns*, *localns*, and |
@@ -3473,29 +3473,28 @@ Introspection helpers |
3473 | 3473 | annotations from ``C``'s base classes with those on ``C`` directly. This |
3474 | 3474 | is done by traversing :attr:`C.__mro__ <type.__mro__>` and iteratively |
3475 | 3475 | combining |
3476 | | - ``__annotations__`` dictionaries. Annotations on classes appearing |
3477 | | - earlier in the :term:`method resolution order` always take precedence over |
3478 | | - annotations on classes appearing later in the method resolution order. |
| 3476 | + :term:`annotations <variable annotation>` of each base class. Annotations |
| 3477 | + on classes appearing earlier in the :term:`method resolution order` always |
| 3478 | + take precedence over annotations on classes appearing later in the method |
| 3479 | + resolution order. |
3479 | 3480 | * The function recursively replaces all occurrences of |
3480 | 3481 | ``Annotated[T, ...]``, ``Required[T]``, ``NotRequired[T]``, and ``ReadOnly[T]`` |
3481 | 3482 | with ``T``, unless *include_extras* is set to ``True`` (see |
3482 | 3483 | :class:`Annotated` for more information). |
3483 | 3484 |
|
3484 | | - See also :func:`annotationlib.get_annotations`, a lower-level function that |
3485 | | - returns annotations more directly. |
3486 | | - |
3487 | 3485 | .. caution:: |
3488 | 3486 |
|
3489 | 3487 | This function may execute arbitrary code contained in annotations. |
3490 | 3488 | See :ref:`annotationlib-security` for more information. |
3491 | 3489 |
|
3492 | 3490 | .. note:: |
3493 | 3491 |
|
3494 | | - If any forward references in the annotations of *obj* are not resolvable |
3495 | | - or are not valid Python code, this function will raise an exception |
3496 | | - such as :exc:`NameError`. For example, this can happen with imported |
3497 | | - :ref:`type aliases <type-aliases>` that include forward references, |
3498 | | - or with names imported under :data:`if TYPE_CHECKING <TYPE_CHECKING>`. |
| 3492 | + If :attr:`Format.VALUE <annotationlib.Format.VALUE>` is used and any |
| 3493 | + forward references in the annotations of *obj* are not resolvable, a |
| 3494 | + :exc:`NameError` exception is raised. For example, this can happen |
| 3495 | + with names imported under :data:`if TYPE_CHECKING <TYPE_CHECKING>`. |
| 3496 | + More generally, any kind of exception can be raised if an annotation |
| 3497 | + contains invalid Python code. |
3499 | 3498 |
|
3500 | 3499 | .. note:: |
3501 | 3500 |
|
@@ -3513,6 +3512,10 @@ Introspection helpers |
3513 | 3512 | if a default value equal to ``None`` was set. |
3514 | 3513 | Now the annotation is returned unchanged. |
3515 | 3514 |
|
| 3515 | + .. versionchanged:: 3.14 |
| 3516 | + Added the ``format`` parameter. See the documentation on |
| 3517 | + :func:`annotationlib.get_annotations` for more information. |
| 3518 | + |
3516 | 3519 | .. versionchanged:: 3.14 |
3517 | 3520 | Calling :func:`get_type_hints` on instances is no longer supported. |
3518 | 3521 | Some instances were accepted in earlier versions as an undocumented |
|