do typing tools give the Python @property decorator a magic pass on no-redef?

[zzzeek]

The Python @property decorator documents a form where we can define a function with @property, then refer to that function name again while calling upon modifier methods from the @property descriptor itself:

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """I'm the 'x' property."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

what a neat pattern! so neat that when I saw this, I obviously assumed it was a standard Python idiom and it's what you see in SQLAlchemy's hybrid documentation, it works great and everybody uses it.

However, when those of us outside of batteries included land try to use this pattern with tools like Mypy or Pyright, they give us the no-redef error or equivalent due to using the same name more than once. I can in fact copy the stub for @property verbatim, and the typing tools very much seem to be hardcoded to skipping the no-redef thing if the decorator is exactly builtins.property:

from typing import Any, Callable

# copied from builtins.pyi
class just_like_property:
    fget: Callable[[Any], Any] | None
    fset: Callable[[Any, Any], None] | None
    fdel: Callable[[Any], None] | None
    __isabstractmethod__: bool
    def __init__(
        self,
        fget: Callable[[Any], Any] | None = ...,
        fset: Callable[[Any, Any], None] | None = ...,
        fdel: Callable[[Any], None] | None = ...,
        doc: str | None = ...,
    ) -> None: ...
    def getter(self, __fget: Callable[[Any], Any]) -> property: ...
    def setter(self, __fset: Callable[[Any, Any], None]) -> property: ...
    def deleter(self, __fdel: Callable[[Any], None]) -> property: ...
    def __get__(self, __obj: Any, __type: type | None = ...) -> Any: ...
    def __set__(self, __obj: Any, __value: Any) -> None: ...
    def __delete__(self, __obj: Any) -> None: ...


class MyClass:
    @property
    def foo(self) -> int:
        ...

    @foo.setter
    def foo(self, value: int) -> None:
        ...

    @just_like_property
    def bar(self) -> int:
        ...

    @bar.setter
    def bar(self, value: int) -> None:
        ...

test3.py:37: error: Name "bar" already defined on line 33  [no-redef]

There's obviously several workarounds here, including type: ignore and using a different name for the interim functions, such as:

class MyClass:

    @just_like_property
    def _inst_bar(self) -> int:
        ...

    @_inst_bar.setter
    def bar(self, value: int) -> None:
        ...

This is sort of ugly, but if that's the state of things, it is what it is. If that's the best that can be done, I will proceed to be rewriting all my documentation examples to use a form more like the above that is type-checker friendly.

questions:

1. is this accurate, that @property is hardcoded in the typing tools to not produce a no-redef condition, or is there some API / pep / magical thing I'm not familiar with that can allow user-defined descriptors to do the same thing?
2. what's the recommended approach going forward, is it that simply what @property does is essentially a special, non-public Python syntax that the rest of us shouldn't use? (or if we should, then is this a bug in typing tools?)
3. does this seem like something that could be improved if there was interest or is this "correct by design" ?

thanks as always for all the great help I'm getting on these questions!

[Akuli]

1. Currently @property is hard-coded in the tools. It's unfortunate and creates several different kinds of issues for custom property classes and property-like classes. There have been attempts to reduce the special-casing, such as make property generic typeshed#5987.
2. It's perfectly fine to define your own property! It's well documented in Python docs and type checkers support it too. Apart from redefinition, only the built-in @property is problematic, and making your own to replace it is fine.
3. The no-redef warnings could be improved IMO. I think a better behavior would be to not complain when the second definition of a method bar is decorated with @bar.something, without checking whether the first definition has @property.

I will proceed to be rewriting all my documentation examples to use a form more like the above that is type-checker friendly.

I don't like this, because making a property read-only will no longer be simple as deleting the setter. It would be much better to get this fixed in mypy. But in my experience, mypy issues don't get fixed unless you're willing to fix things yourself :)

If mypy isn't getting fixed any time soon, I would probably use # type: ignore[no-redef] and explain it in the documentation.

[zzzeek]

very unfortunately, mypy and pylance disagree on where to put these ignores:

mypy:

    @hybrid_property
    def radius(self) -> float:
        return abs(self.length) / 2

    @radius.setter  # type: ignore[no-redef]
    def radius(self, value: float) -> None:
        self.length = value * 2

    @radius.expression  # type: ignore[no-redef]
    def radius(cls) -> ColumnElement[float]:
        return type_coerce(func.abs(cls.length) / 2, Float)

pylance:

    @hybrid_property
    def radius(self) -> float:  # type: ignore[no-redef]
        return abs(self.length) / 2

    @radius.setter
    def radius(self, value: float) -> None:  # type: ignore[no-redef]
        self.length = value * 2

    @radius.expression
    def radius(cls) -> ColumnElement[float]:  # type: ignore[no-redef]
        return type_coerce(func.abs(cls.length) / 2, Float)

the two styles are mutually exclusive, and mypy even reports an error for the ignores themselves above as they are unused:

$ mypy test4.py 
test4.py:40: error: Unused "type: ignore" comment
test4.py:43: error: Name "radius" already defined on line 39  [no-redef]
test4.py:44: error: Unused "type: ignore" comment
test4.py:47: error: Name "radius" already defined on line 39  [no-redef]
test4.py:48: error: Unused "type: ignore" comment
Found 5 errors in 1 file (checked 1 source file)

so there's no way to use accurately pointed ignores here.

[hauntsaninja]

If your property is very very similar to builtins.property, you can use the fun trick of lying to type checkers and telling them that your property is builtins.property, thereby piggy-backing on all type checker special-casing for builtins.property:

if TYPE_CHECKING:
    just_like_property = property
else:
    class just_like_property: ...

[zzzeek]

Even though the nature of @property is changing in that it will reject writes until setter is called, it's not changing its type from a typing perspective. I would gather the typing tools do in fact have more hardcoded logic in order to "predict" when a particular @property is going to be read-only or not, but that's not something that we who are writing descriptors are getting either; our descriptors have a __set__() method or they dont, and if __set__() is not present, or is present but doesn't return NoReturn, it's writeable. so this "the type changed from read only to read/write" is something outside of the scope of the immediate issue because I dont think (IIUC) it applies to userland descriptor classes.

From what I can see, "bar" is a "property" object at all times. It's the same idea for the descriptor decorators I have too. Methods like ".setter" are basically returning Self. The decorators I have are not switching from read-only to read/write or anything like that.

I see there's a lot of purity-oriented concerns about @property here but in a more pragmatic sense I'd be looking for some kind of hint to the type checker that "bar" is going to be reassigned a few times, but still to the same kind of object, so please just don't show any "no-redef" warnings. This hint could just be just a superclass that is placed in the bases of the descriptor class that indicates this is a "method-chained" descriptor, or something like that.

I guess that's not very satisfying because as mentioned above there's all kinds of other weird exceptions made by @property that the typing tools are trying to follow, and what's to stop us from asking for those too. But overall I think they are separate concerns.

I certainly don't have any appetite to single-handedly write a pep or anything on this end, just wanted to get a read on the general sentiment for this one.

[AlexWaygood]

Can you give us a link to the code for this descriptor? I'd be interested to take a look :)

[zzzeek]

took awhile to get the typed version merged, here it is: https://github.com/sqlalchemy/sqlalchemy/blob/3b520e758a715cf817075e4a90ae1b5813ffadd3/lib/sqlalchemy/ext/hybrid.py#L968

[jace]

Sorry for reviving an old thread, but there's another example of this with functools.singledispatch and singledispatchmethod.

Mypy issue: python/mypy#2904

@property's chained methods return a new object, but singledispatch mutates in place, while changing the type signature each time.

I think this is a useful pattern for registering multiple function bodies that are related (effectively if/else or match/case segments) but isolated from each other with their own args and return type.

Maybe a function's type definition should be considered finalised only when the parent scope (class or module) is closed?

[jace]

Also related, in the current releases of Pyright and Mypy, when a descriptor redefinition occurs (@property.setter pattern), Mypy ignores the new type post-redefinition, while Pyright recognises it.

Mypy bug report with sample code: python/mypy#16554