Asymmetric descriptor type apparently overriden when descriptor is set within the class body

[oddbury]

This could be a bug, or perhaps I don't understand how to correctly type my descriptors yet. The example below is a descriptor that is set with a float and get returns an int. If I only set the descriptor (with a float) outside the class body it works, and if I call the descriptor set method directly it also works, but if the descriptor is set within a method of the class body it adds this "| float" to the types we get from the descriptor.

Please could someone point me in the right direction?

from typing import (
    Any,
    assert_type,
    Optional,
    overload,
    Self,
)

class Descriptor:
   
    @overload
    def __get__(self, instance: None, owner: type) -> Self:
        ...

    @overload
    def __get__(self, instance: Any, owner: type) -> int:
        ...

    def __get__(self, instance: Optional[Any], owner: type) -> Self | int:
        if instance is None:
            return self
        return 1

    def __set__(self, instance: Any, value: float) -> None:
        pass

class Test:

    value1 = Descriptor()
    value2 = Descriptor()
    value3 = Descriptor()
    value4 = Descriptor()

    def __init__(self):
        self.value1 = 1.1
        self.set_value3()
        type(self).value4.__set__(self, 1.4)

    def set_value3(self):
        self.value3 = 1.3

test = Test()
test.value2 = 1.2

assert_type(Test.value1, Descriptor)
# pyright says "Descriptor | float"

assert_type(test.value1, int) 
# pyright says "int | float"

assert_type(test.value2, int)
# pyright says "int"

assert_type(test.value3, int)
# pyright says "int | float"

assert_type(test.value4, int)
# pyright says "int"

[Mohammad Rezwan Khan (mohammadrezwankhan)]

The behavior is reproducible, and the descriptor setter is being checked. The widening comes from a second static inference path: an unannotated assignment through self.value1 is also recorded as an instance-member declaration for value1.

Pyright then combines the class-body declaration value1 = Descriptor() with the inferred float declaration from self.value1 = 1.1. Its evaluator documents that explicit declarations take precedence, while inferred declarations are combined into a union (declared types take precedence; inferred declarations are combined). The member-assignment path still invokes the descriptor protocol and caches the setter assignment (assignment path), but the inferred instance declaration remains visible to later reads.

That explains all three results:

• Test.value1 sees Descriptor | float; class access applies __get__(None, Test) to the descriptor branch, leaving the inferred float branch.
• test.value1 and test.value3 see int | float; the descriptor branch returns int, while the self assignments contribute float.
• test.value2 and test.value4 stay int because the assignments are outside the class's inferred member declarations, and the explicit type(self).value4.__set__ call is not an attribute assignment.

The smallest fix is to make the class members explicitly typed descriptors:

class Test:
    value1: Descriptor = Descriptor()
    value2: Descriptor = Descriptor()
    value3: Descriptor = Descriptor()
    value4: Descriptor = Descriptor()

I verified the original reproducer with the current Pyright CLI: it reports the same three assert_type mismatches. With the four annotations above, the same file reports zero errors. This is also consistent with Pyright's descriptor tests, which distinguish a class-scoped descriptor from an ordinary instance variable (descriptor2 sample).

If you prefer not to add annotations, calling type(self).value1.__set__(self, 1.1) avoids creating the inferred self.value1 declaration, as your value4 case demonstrates. For normal descriptor syntax, though, the explicit class annotation is the robust workaround. If you believe unannotated data descriptors should suppress the inferred instance-member union, this is a useful focused bug report; the current behavior is a conservative inference limitation rather than a runtime descriptor override.

[oddbury]

Thank you, this is useful. At the very least I can fix my code by declaring the types of the class members.

If you believe unannotated data descriptors should suppress the inferred instance-member union, this is a useful focused bug report; the current behavior is a conservative inference limitation rather than a runtime descriptor override.

I genuinely don't know if I believe that. I stumbled into a problem because I implicitly assumed that the inferred types pyright reported were not treated differently from the types I had declared, but I am new to using type checking in python so I don't want to declare that everything that trips me up is a bug. I guess that's why I'm asking here rather than submitting an issue.

Thanks again!