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

[Yhg1s]

https://github.com/python/cpython/commit/f7e16d74adffb8bc890530caebf0a08a6ea89d36
commit: f7e16d74adffb8bc890530caebf0a08a6ea89d36
branch: 3.12
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Yhg1s <thomas at python.org>
date: 2023-08-02T01:52:28+02:00
summary:

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

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

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

files:
M Doc/library/typing.rst

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 60bf06e471cb2..d060066c0cdea 100644
--- a/Doc/library/typing.rst
+++ b/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::
-
-      class Foo:
-          def return_self(self) -> "Foo":
-              ...
-              return self
-
-   You should use :data:`Self` as calls to ``SubclassOfFoo.return_self`` would have
-   ``Foo`` as the return type and not ``SubclassOfFoo``.
+   In general, if something returns ``self``, as in the above examples, you
+   should use ``Self`` as the return annotation. If ``Foo.return_self`` was
+   annotated as returning ``"Foo"``, then the type checker would infer the
+   object returned from ``SubclassOfFoo.return_self`` as being of type ``Foo``
+   rather than ``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