[3.14] gh-144190: Clarify get_type_hints() instance behavior in docs (GH-144831)...

Co-authored-by: Rajhans Jadhao <rajhans.jadhao@gmail.com>

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index e7a6df156a27cdc69c3fba8a50aa4dd6c3a94990..a2625ab2a371663c40a6c3e475ff54c4656b0f99 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -3347,8 +3347,8 @@ Introspection helpers
 
 .. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False)
 
-   Return a dictionary containing type hints for a function, method, module
-   or class object.
+   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:
@@ -3389,6 +3389,13 @@ Introspection helpers
       :ref:`type aliases <type-aliases>` that include forward references,
       or with names imported under :data:`if TYPE_CHECKING <TYPE_CHECKING>`.
 
+   .. note::
+
+      Calling :func:`get_type_hints` on an instance is not supported.
+      To retrieve annotations for an instance, call
+      :func:`get_type_hints` on the instance's class instead
+      (for example, ``get_type_hints(type(obj))``).
+
    .. versionchanged:: 3.9
       Added ``include_extras`` parameter as part of :pep:`593`.
       See the documentation on :data:`Annotated` for more information.
@@ -3398,6 +3405,11 @@ Introspection helpers
       if a default value equal to ``None`` was set.
       Now the annotation is returned unchanged.
 
+   .. versionchanged:: 3.14
+      Calling :func:`get_type_hints` on instances is no longer supported.
+      Some instances were accepted in earlier versions as an undocumented
+      implementation detail.
+
 .. function:: get_origin(tp)
 
    Get the unsubscripted version of a type: for a typing object of the form