Make return type of functools.cache_property covariant (#10053)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

stdlib/functools.pyi

@@ -28,6 +28,7 @@ if sys.version_info >= (3, 9):
     __all__ += ["cache"]
 
 _T = TypeVar("_T")
+_T_co = TypeVar("_T_co", covariant=True)
 _S = TypeVar("_S")
 _PWrapped = ParamSpec("_PWrapped")
 _RWrapped = TypeVar("_RWrapped")
@@ -183,17 +184,17 @@ class singledispatchmethod(Generic[_T]):
     def register(self, cls: type[Any], method: Callable[..., _T]) -> Callable[..., _T]: ...
     def __get__(self, obj: _S, cls: type[_S] | None = None) -> Callable[..., _T]: ...
 
-class cached_property(Generic[_T]):
-    func: Callable[[Any], _T]
+class cached_property(Generic[_T_co]):
+    func: Callable[[Any], _T_co]
     attrname: str | None
-    def __init__(self, func: Callable[[Any], _T]) -> None: ...
+    def __init__(self, func: Callable[[Any], _T_co]) -> None: ...
     @overload
     def __get__(self, instance: None, owner: type[Any] | None = None) -> Self: ...
     @overload
-    def __get__(self, instance: object, owner: type[Any] | None = None) -> _T: ...
+    def __get__(self, instance: object, owner: type[Any] | None = None) -> _T_co: ...
     def __set_name__(self, owner: type[Any], name: str) -> None: ...
     # __set__ is not defined at runtime, but @cached_property is designed to be settable
-    def __set__(self, instance: object, value: _T) -> None: ...
+    def __set__(self, instance: object, value: _T_co) -> None: ...  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues]
     if sys.version_info >= (3, 9):
         def __class_getitem__(cls, item: Any) -> GenericAlias: ...
 

test_cases/stdlib/check_functools.py

@@ -46,3 +46,22 @@ def check_cached_property_settable(x: int) -> None:
     assert_type(b.x, int)
     b.x = x
     assert_type(b.x, int)
+
+
+# https://github.com/python/typeshed/issues/10048
+class Parent: ...
+
+
+class Child(Parent): ...
+
+
+class X:
+    @cached_property
+    def some(self) -> Parent:
+        return Parent()
+
+
+class Y(X):
+    @cached_property
+    def some(self) -> Child:  # safe override
+        return Child()