Review findings

Author: sharkdp

conformance/results/mypy/protocols_generic.toml

@@ -18,7 +18,7 @@ protocols_generic.py:74: error: Incompatible types in assignment (expression has
 protocols_generic.py:75: error: Incompatible types in assignment (expression has type "AttrProto[float]", variable has type "AttrProto[int]")  [assignment]
 protocols_generic.py:133: error: Incompatible types in assignment (expression has type "InvalidParentProperty", variable has type "HasParentProperty")  [assignment]
 protocols_generic.py:133: note: Following member(s) of "InvalidParentProperty" have conflicts:
-protocols_generic.py:133: note:     parent: expected "InvalidParentProperty", got "int"
+protocols_generic.py:133: note:     parent: expected "InvalidParentProperty", got "HasParentProperty"
 protocols_generic.py:153: error: Incompatible types in assignment (expression has type "InvalidHasMethod", variable has type "HasMethod")  [assignment]
 protocols_generic.py:153: note: Following member(s) of "InvalidHasMethod" have conflicts:
 protocols_generic.py:153: note:     Expected:

conformance/results/pyright/protocols_generic.toml

@@ -28,10 +28,10 @@ protocols_generic.py:75:26 - error: Type "AttrProto[float]" is not assignable to
 protocols_generic.py:133:26 - error: Type "InvalidParentProperty" is not assignable to declared type "HasParentProperty"
   "InvalidParentProperty" is incompatible with protocol "HasParentProperty"
     "parent" is an incompatible type
-      Type "() -> int" is not assignable to type "() -> InvalidParentProperty"
+      Type "() -> HasParentProperty" is not assignable to type "() -> InvalidParentProperty"
         "HasParentProperty" is not assignable to "InvalidParentProperty"
-        Function return type "int" is incompatible with type "InvalidParentProperty"
-          "int" is not assignable to "InvalidParentProperty" (reportAssignmentType)
+        Function return type "HasParentProperty" is incompatible with type "InvalidParentProperty"
+          "HasParentProperty" is not assignable to "InvalidParentProperty" (reportAssignmentType)
 protocols_generic.py:153:18 - error: Type "InvalidHasMethod" is not assignable to declared type "HasMethod"
   "InvalidHasMethod" is incompatible with protocol "HasMethod"
     "m" is an incompatible type

conformance/results/zuban/protocols_generic.toml

@@ -19,7 +19,7 @@ protocols_generic.py:74: error: Incompatible types in assignment (expression has
 protocols_generic.py:75: error: Incompatible types in assignment (expression has type "AttrProto[float]", variable has type "AttrProto[int]")  [assignment]
 protocols_generic.py:133: error: Incompatible types in assignment (expression has type "InvalidParentProperty", variable has type "HasParentProperty")  [assignment]
 protocols_generic.py:133: note: Following member(s) of "InvalidParentProperty" have conflicts:
-protocols_generic.py:133: note:     parent: expected "InvalidParentProperty", got "int"
+protocols_generic.py:133: note:     parent: expected "InvalidParentProperty", got "HasParentProperty"
 protocols_generic.py:153: error: Incompatible types in assignment (expression has type "InvalidHasMethod", variable has type "HasMethod")  [assignment]
 protocols_generic.py:153: note: Following member(s) of "InvalidHasMethod" have conflicts:
 protocols_generic.py:153: note:     Expected:

conformance/tests/protocols_generic.py

@@ -125,8 +125,8 @@ def parent(self) -> Self:
 
 class InvalidParentProperty:
     @property
-    def parent(self) -> int:
-        return 0
+    def parent(self) -> HasParentProperty:
+        return ConcreteParentProperty()
 
 
 hp1: HasParentProperty = ConcreteParentProperty()  # OK

docs/guides/writing_stubs.rst

@@ -647,24 +647,23 @@ No::
     def foo(x: X = X()) -> None: ...
     def bar(y: str = None) -> None: ...
 
-Do not annotate ``self`` and ``cls`` in method definitions, except when
-referencing a type variable.
+Do not annotate ``self`` and ``cls`` in method definitions unless an explicit
+annotation is needed to constrain or relax the receiver type.
 
 Yes::
 
-    _T = TypeVar("_T", bound="Foo")
-
     class Foo:
         def bar(self) -> None: ...
         @classmethod
-        def create(cls: type[_T]) -> _T: ...
+        def create(cls) -> Self: ...
 
 No::
 
     class Foo:
-        def bar(self: Foo) -> None: ...
+        def bar1(self: Self) -> None: ...
+        def bar2(self: Foo) -> None: ...
         @classmethod
-        def baz(cls: type[Foo]) -> int: ...
+        def create(cls: type[Self]) -> Self: ...
 
 The bodies of functions and methods should consist of only the ellipsis
 literal ``...`` on the same line as the closing parenthesis and colon.