Fix type errors in Pyright

changelog.d/999.change.rst

@@ -0,0 +1,2 @@
+Made ``attrs.AttrsInstance`` stub available at runtime and fixed type errors
+related to the usage of ``attrs.AttrsInstance`` in Pyright.

src/attr/__init__.py

@@ -52,8 +52,14 @@
 ib = attr = attrib
 dataclass = partial(attrs, auto_attribs=True)  # happy Easter ;)
 
+
+class AttrsInstance:
+    pass
+
+
 __all__ = [
     "Attribute",
+    "AttrsInstance",
     "Factory",
     "NOTHING",
     "asdict",

src/attr/__init__.pyi

@@ -4,7 +4,6 @@ import sys
 from typing import (
     Any,
     Callable,
-    ClassVar,
     Dict,
     Generic,
     List,
@@ -26,6 +25,7 @@ from . import filters as filters
 from . import setters as setters
 from . import validators as validators
 from ._cmp import cmp_using as cmp_using
+from ._typing_compat import AttrsInstance_
 from ._version_info import VersionInfo
 
 if sys.version_info >= (3, 10):
@@ -65,9 +65,9 @@ _FieldTransformer = Callable[
 # _ValidatorType from working when passed in a list or tuple.
 _ValidatorArgType = Union[_ValidatorType[_T], Sequence[_ValidatorType[_T]]]
 
-# A protocol to be able to statically accept an attrs class.
-class AttrsInstance(Protocol):
-    __attrs_attrs__: ClassVar[Any]
+# We subclass this here to keep the protocol's qualified name clean.
+class AttrsInstance(AttrsInstance_, Protocol):
+    pass
 
 # _make --
 

src/attr/_typing_compat.pyi

@@ -0,0 +1,15 @@
+from typing import Any, ClassVar, Protocol
+
+# MYPY is a special constant in mypy which works the same way as `TYPE_CHECKING`.
+MYPY = False
+
+if MYPY:
+    # A protocol to be able to statically accept an attrs class.
+    class AttrsInstance_(Protocol):
+        __attrs_attrs__: ClassVar[Any]
+
+else:
+    # For type checkers without plug-in support use an empty protocol that
+    # will (hopefully) be combined into a union.
+    class AttrsInstance_(Protocol):
+        pass

src/attrs/__init__.py

@@ -3,6 +3,7 @@
 from attr import (
     NOTHING,
     Attribute,
+    AttrsInstance,
     Factory,
     __author__,
     __copyright__,
@@ -48,6 +49,7 @@
     "assoc",
     "astuple",
     "Attribute",
+    "AttrsInstance",
     "cmp_using",
     "converters",
     "define",

tests/test_pyright.py

@@ -78,3 +78,31 @@ def test_pyright_baseline():
     }
 
     assert diagnostics == expected_diagnostics
+
+
+def test_pyright_attrsinstance_compat(tmp_path):
+    """
+    Test that `AttrsInstance` is compatible with Pyright.
+    """
+    test_pyright_attrsinstance_compat_path = (
+        tmp_path / "test_pyright_attrsinstance_compat.py"
+    )
+    test_pyright_attrsinstance_compat_path.write_text(
+        """\
+import attrs
+
+# We can assign any old object to `AttrsInstance`.
+foo: attrs.AttrsInstance = object()
+
+reveal_type(attrs.AttrsInstance)
+"""
+    )
+
+    diagnostics = parse_pyright_output(test_pyright_attrsinstance_compat_path)
+    expected_diagnostics = {
+        PyrightDiagnostic(
+            severity="information",
+            message='Type of "attrs.AttrsInstance" is "Type[AttrsInstance]"',
+        ),
+    }
+    assert diagnostics == expected_diagnostics

tox.ini

@@ -92,7 +92,7 @@ commands = towncrier build --version UNRELEASED --draft
 [testenv:mypy]
 deps = mypy>=0.902
 commands =
-    mypy src/attrs/__init__.pyi src/attr/__init__.pyi src/attr/_version_info.pyi src/attr/converters.pyi src/attr/exceptions.pyi src/attr/filters.pyi src/attr/setters.pyi src/attr/validators.pyi
+    mypy src/attrs/__init__.pyi src/attr/__init__.pyi src/attr/_typing_compat.pyi src/attr/_version_info.pyi src/attr/converters.pyi src/attr/exceptions.pyi src/attr/filters.pyi src/attr/setters.pyi src/attr/validators.pyi
     mypy tests/typing_example.py