MyPy infers descriptors are always ClassVars when testing assignability to protocols

[dchevell]

Bug Report

When defining a Protocol for objects containing descriptors, mypy appears to assume descriptors are always ClassVars. Annotating the protocol's descriptor attributes with ClassVar silences mypy, but raises errors in other type checkers (e.g. pyright). Given descriptors are allowed to be used as both instance and class variables (and __get__ / __set__ provide obj: object | None semantics to support this), I think this is a mypy bug.

A real-world example of this is defining a protocol for an SQLAlchemy model, e.g. a protocol might define id: orm.Mapped[int] to match models with an id integer attribute.

To Reproduce
Given the complexity of SQLAlchemy, here's an entirely self-contained example:

from typing import ClassVar, Protocol


class MyDescriptor:
    def __init__(self):
        self.value = "test"

    def __get__(self, obj: object | None, objtype: type[object]) -> str:
        return self.value

    def __set__(self, obj: object | None, value: str) -> None:
        self.value = value


class Foo:
    bar = MyDescriptor()


class HasBar(Protocol):
    bar: MyDescriptor


class HasBarWithClassVar(Protocol):
    bar: ClassVar[MyDescriptor]


instance1: HasBar = Foo()  # fails in mypy, passes in pyright
model1: type[HasBar] = Foo  # fails in mypy, passes in pyright

instance2: HasBarWithClassVar = Foo()  # fails in pyright, passes in mypy
model2: type[HasBarWithClassVar] = Foo  # fails in pyright, passes in mypy

Expected Behavior

Assigning Foo to HasBar should type check correctly, and assigning to HasBarWithClassVar should fail.

Actual Behavior

Assigning Foo to HasBar errors in mypy, but checks in pyright. Conversely, assigning to HasBarWithClassVar checks in mypy, but fails in pyright. They seem to fundamentally disagree.

$ mypy err_report.py
err_report.py:27: error: Incompatible types in assignment (expression has type "Foo", variable has type "HasBar")  [assignment]
err_report.py:27: note: Following member(s) of "Foo" have conflicts:
err_report.py:27: note:     bar: expected "MyDescriptor", got "str"
err_report.py:28: error: Incompatible types in assignment (expression has type "type[Foo]", variable has type "type[HasBar]")  [assignment]
Found 2 errors in 1 file (checked 1 source file)

$ pyright err_report.py
/path/to/my/err_report.py
  /path/to/my/err_report.py:30:33 - error: Type "Foo" is not assignable to declared type "HasBarWithClassVar"
    "Foo" is incompatible with protocol "HasBarWithClassVar"
      "bar" is defined as a ClassVar in protocol (reportAssignmentType)
  /path/to/my/err_report.py:31:36 - error: Type "type[Foo]" is not assignable to declared type "type[HasBarWithClassVar]"
    "Foo" is incompatible with protocol "HasBarWithClassVar"
    Type "type[Foo]" is not assignable to type "type[HasBarWithClassVar]"
      "bar" is defined as a ClassVar in protocol (reportAssignmentType)
2 errors, 0 warnings, 0 informations

If I were to annotate Foo.bar with ClassVar, then pyright accepts assigning Foo to HasBarWithClassVar (which is what I would expect), but now mypy won't:

class Foo:
    bar: ClassVar = MyDescriptor()

$ mypy err_report.py
err_report.py:27: error: Incompatible types in assignment (expression has type "Foo", variable has type "HasBar")  [assignment]
err_report.py:27: note: Protocol member HasBar.bar expected instance variable, got class variable
err_report.py:28: error: Incompatible types in assignment (expression has type "type[Foo]", variable has type "type[HasBar]")  [assignment]
err_report.py:30: error: Incompatible types in assignment (expression has type "Foo", variable has type "HasBarWithClassVar")  [assignment]
err_report.py:30: note: Protocol member HasBarWithClassVar.bar expected instance variable, got class variable
err_report.py:31: error: Incompatible types in assignment (expression has type "type[Foo]", variable has type "type[HasBarWithClassVar]")  [assignment]
Found 4 errors in 1 file (checked 1 source file)

Your Environment

• Mypy version used: 1.17.1
• Mypy command-line flags: none
• Mypy configuration options from mypy.ini (and other config files): n/a
• Python version used: 3.13.5

[dchevell]

For the sake of completeness, here's the SQLAlchemy example. It's more relevant, but I couldn't be sure it wasn't some unrelated edge case specific to SQLAlchemy, so the self-contained example seemed more appropriate … this example mostly illustrates the practical utility of the pattern being described:

from typing import ClassVar, Protocol
from sqlalchemy import orm


class Base(orm.DeclarativeBase):
    pass


class Foo(Base):
    __tablename__ = "foo"
    id: orm.Mapped[int] = orm.mapped_column(primary_key=True)


class HasIntId(Protocol):
    id: orm.Mapped[int]


class HasIntIdWithClassVar(Protocol):
    id: ClassVar[orm.Mapped[int]]


instance1: HasIntId = Foo()  # fails in mypy, passes in pyright
model1: type[HasIntId] = Foo  # fails in mypy, passes in pyright

instance2: HasIntIdWithClassVar = Foo()  # fails in pyright, passes in mypy
model2: type[HasIntIdWithClassVar] = Foo  # fails in pyright, passes in mypy

[sterliakov]

Yes, mypy and pyright fundamentally disagree here, and I personally consider mypy behavior correct. This:

class HasBar(Protocol):
    bar: MyDescriptor

means that

x: HasBar
reveal_type(x.bar)  # N: revealed type is "__main__.MyDescriptor"

and Foo does dot exhibit such behavior.

Ant this:

class HasBarWithClassVar(Protocol):
    bar: ClassVar[MyDescriptor]

means that

X: type[HasBarWithClassVar]
reveal_type(X.bar)  # N: revealed type is "__main__.MyDescriptor"  # right, it is

x: HasBarWithClassVar
reveal_type(x.bar)  # N: revealed type is <whatever MyDescriptor.__get__ returns>  # OK again

See long discussion in #19274 (which is probably a duplicate).

[dchevell]

Doesn't it also mean that it should be an error to assign to an instance of Foo?

a variable annotation wrapped in ClassVar indicates that a given attribute is intended to be used as a class variable and should not be set on instances of that class.

If mypy is correct, wouldn't that mean that it's never valid to have a descriptor that supports being set on a class or an instance level?

@erictraut if this is more likely a pyright error I can raise it there, but wary of just being bounced back and forth (maybe it's something that needs to be standardised elsewhere)?

[sterliakov]

Sorry, missed this ping

Doesn't it also mean that it should be an error to assign to an instance of Foo?

This does somewhat contradict the definition of ClassVar as written, yes. However, I personally interpret that paragraph as "type checkers should ensure that class variables aren't mutated from instances", and this is consistent with allowing descriptor __get__. I can even argue that the variable itself is not set when you do instance.foo = ... because it's eventually handled by __set__ and not by __setattr__, but that's probably too much of a stretch.

And please note that all of this only applies to protocols.

If mypy is correct, wouldn't that mean that it's never valid to have a descriptor that supports being set on a class or an instance level?

Not sure what you mean by this. __set__ is not called when you assign to a class attribute.

class D:
    def __set__(*args): print('set', *args)

class A:
    d = D()

A.d = 0  # nothing should be printed

Metaclass would work here, but I'm not certain mypy handles combinations of custom metaclasses and descriptors correctly.

Note that mypy will correctly parse accessing such descriptor on the class object:

from typing import ClassVar, Protocol, TypeVar, overload

T = TypeVar("T")

class D:
    @overload
    def __get__(self, instance: None, typ: type) -> int: ...
    @overload
    def __get__(self, instance: T, typ: type[T]) -> str: ...
    def __get__(self, instance: T | None, typ: type[T]) -> int | str:
        raise NotImplementedError

class P(Protocol):
    d: ClassVar[D]

def check(obj: P) -> None:
    reveal_type(obj.d)  # N: Revealed type is "builtins.str"

def check_t(obj_t: type[P]) -> None:
    reveal_type(obj_t.d)  # N: Revealed type is "builtins.int"

[zzzeek]

This is coming to us now, so for completeness here's an example that illustrates the more practical elements of the mapped class, passing the class or instance of the class as an argument, and that aspect of it seems to work for both mypy and pyright. so at this point it looks like maybe pyright should be more flexible since it does seem to recognize the element as a descriptor when ClassVar is used

from __future__ import annotations

from typing import Any
from typing import ClassVar
from typing import Generic
from typing import Literal
from typing import overload
from typing import Protocol
from typing import TYPE_CHECKING
from typing import TypeVar
from typing import Union

_T_co = TypeVar("_T_co", bound=Any, covariant=True)


class ORMDescriptor(Generic[_T_co]):
    if TYPE_CHECKING:
        @overload
        def __get__(
            self, instance: Any, owner: Literal[None]
        ) -> ORMDescriptor[_T_co]: ...

        @overload
        def __get__(
            self, instance: Literal[None], owner: Any
        ) -> SQLOperationThing[_T_co]: ...

        @overload
        def __get__(self, instance: object, owner: Any) -> _T_co: ...

        def __get__(
            self, instance: object, owner: Any
        ) -> Union[ORMDescriptor[_T_co], SQLOperationThing[_T_co], _T_co]: ...


class SQLOperationThing(Generic[_T_co]):
    if TYPE_CHECKING:
        def some_sql_operation(self) -> SQLOperationThing[_T_co]:
            ...


class Foo:
    bar: ORMDescriptor[int]


class HasBar(Protocol):
    bar: ORMDescriptor[int]


class HasBarWithClassVar(Protocol):
    bar: ClassVar[ORMDescriptor[int]]

# these all seem to work in both type checkers
def sql_operation_one(cls: type[Foo]) -> SQLOperationThing[int]:
    return cls.bar.some_sql_operation()

def sql_operation_two(cls: type[HasBar]) -> SQLOperationThing[int]:
    return cls.bar.some_sql_operation()

def sql_operation_three(cls: type[HasBarWithClassVar]) -> SQLOperationThing[int]:
    return cls.bar.some_sql_operation()


# these all seem to work in both type checkers as well
# (pyright knows that HasBarWithClassVar.bar returns an int, so it is
# following descriptor logic w/ the classvar)
def instance_operation_one(obj: Foo) -> int:
    return obj.bar

def instance_operation_two(obj: HasBar) -> int:
    return obj.bar

def instance_operation_three(obj: HasBarWithClassVar) -> int:
    return obj.bar


# these observations still seem to hold true for current mypy/pyright
# (October 2025)

instance1: HasBar = Foo()  # fails in mypy, passes in pyright
model1: type[HasBar] = Foo  # fails in mypy, passes in pyright

# so likely, pyright should just make this work

instance2: HasBarWithClassVar = Foo()  # fails in pyright, passes in mypy
model2: type[HasBarWithClassVar] = Foo  # fails in pyright, passes in mypy