[3.12] Clarify Self interaction with subclasses (GH-107511) (#107548)

Clarify `Self` interaction with subclasses (GH-107511)
(cherry picked from commit c8872f4285)

Co-authored-by: Alexandru Mărășteanu <alexei@users.noreply.github.com>

Doc/library/typing.rst

@@ -953,13 +953,17 @@ using ``[]``.
 
    For example::
 
-      from typing import Self
+      from typing import Self, reveal_type
 
       class Foo:
           def return_self(self) -> Self:
               ...
               return self
 
+      class SubclassOfFoo(Foo): pass
+
+      reveal_type(Foo().return_self())  # Revealed type is "Foo"
+      reveal_type(SubclassOfFoo().return_self())  # Revealed type is "SubclassOfFoo"
 
    This annotation is semantically equivalent to the following,
    albeit in a more succinct fashion::
@@ -973,15 +977,11 @@ using ``[]``.
               ...
               return self
 
-   In general if something currently follows the pattern of::
+   In general, if something returns ``self``, as in the above examples, you
-
+   should use ``Self`` as the return annotation. If ``Foo.return_self`` was
-      class Foo:
+   annotated as returning ``"Foo"``, then the type checker would infer the
-          def return_self(self) -> "Foo":
+   object returned from ``SubclassOfFoo.return_self`` as being of type ``Foo``
-              ...
+   rather than ``SubclassOfFoo``.
-              return self
-
-   You should use :data:`Self` as calls to ``SubclassOfFoo.return_self`` would have
-   ``Foo`` as the return type and not ``SubclassOfFoo``.
 
    Other common use cases include:
 
@@ -989,6 +989,17 @@ using ``[]``.
      of the ``cls`` parameter.
    - Annotating an :meth:`~object.__enter__` method which returns self.
 
+   You should not use ``Self`` as the return annotation if the method is not
+   guaranteed to return an instance of a subclass when the class is
+   subclassed::
+
+      class Eggs:
+          # Self would be an incorrect return annotation here,
+          # as the object returned is always an instance of Eggs,
+          # even in subclasses
+          def returns_eggs(self) -> "Eggs":
+              return Eggs()
+
    See :pep:`673` for more details.
 
    .. versionadded:: 3.11