feat: add typing.Self

starpit · starpit · commit b41c207ce1e4 · 2025-04-17T10:36:42.000-04:00
Signed-off-by: Nick Mitchell &lt;nickm@us.ibm.com&gt;
diff --git a/Lib/typing.py b/Lib/typing.py
@@ -122,6 +122,7 @@
     'ParamSpecArgs',
     'ParamSpecKwargs',
     'runtime_checkable',
+    'Self',
     'Text',
     'TYPE_CHECKING',
     'TypeAlias',
@@ -164,7 +165,7 @@ def _type_check(arg, msg, is_argument=True, module=None, *, allow_special_forms=
     if (isinstance(arg, _GenericAlias) and
             arg.__origin__ in invalid_generic_forms):
         raise TypeError(f"{arg} is not valid as type argument")
-    if arg in (Any, NoReturn, Final, TypeAlias):
+    if arg in (Any, NoReturn, Final, Self, TypeAlias):
         return arg
     if isinstance(arg, _SpecialForm) or arg in (Generic, Protocol):
         raise TypeError(f"Plain {arg} is not valid as type argument")
@@ -438,6 +439,25 @@ def stop() -> NoReturn:
     """
     raise TypeError(f"{self} is not subscriptable")
 
+@_SpecialForm
+def Self(self, parameters):
+    """Used to spell the type of "self" in classes.
+
+    Example::
+
+        from typing import Self
+
+        class Foo:
+            def return_self(self) -> Self:
+                ...
+                return self
+
+    This is especially useful for:
+        - classmethods that are used as alternative constructors
+        - annotating an `__enter__` method which returns self
+    """
+    raise TypeError(f"{self} is not subscriptable")
+
 @_SpecialForm
 def ClassVar(self, parameters):
     """Special type construct to mark class variables.
