本文探讨了pycharm在处理继承自`functools.cached_property`的自定义描述符时的类型检查特异行为。尽管遵循标准类型提示，pycharm可能无法正确识别类型错误，而mypy则可以。研究表明，pycharm的类型检查逻辑似乎硬编码了对`cached_property`名称的依赖。文章提供了一个实用的解决方案：通过将自定义描述符类命名为`cached_property`，可以激活pycharm的预期类型检查行为。
PyCharm中自定义描述符的类型检查挑战
在Python开发中，我们经常会使用描述符（Descriptor）来定制属性的访问行为，而functools.cached_property是一个常见的例子，它提供了一种高效的缓存属性计算结果的方式。当我们需要基于cached_property创建自定义的描述符，并希望类型检查工具能够正确理解其行为时，可能会遇到一些意料之外的情况。
考虑以下一个自定义描述符result_property，它继承自functools.cached_property并进行了泛型化处理，旨在提供更精确的类型提示：
from functools import cached_property
from collections.abc import Callable
from typing import TypeVar, Generic, Any, overload, Union
T = TypeVar("T")
class result_property(cached_property, Generic[T]):
def __init__(self, func: Callable[[Any], T]) -> None:
super().__init__(func)
def __set_name__(self, owner: type[Any], name: str) -> None:
super().__set_name__(owner, name)
@overload
def __get__(self, instance: None, owner: Union[type[Any], None] = None) -> 'result_property[T]': ...
@overload
def __get__(self, instance: object, owner: Union[type[Any], None] = None) -> T: ...
def __get__(self, instance, owner=None):
# 实际的获取逻辑由 cached_property 基类处理
return super().__get__(instance, owner)
def func_str(s: str) -> None:
print(s)
class Foo:
@result_property
def prop_int(self) -> int:
return 1
foo = Foo()
# 尝试将一个整数类型的属性传递给一个期望字符串的函数
func_str(foo.prop_int)在这段代码中，foo.prop_int被明确地类型提示为int。当我们尝试将其传递给一个期望str类型参数的func_str函数时，理论上应该会触发类型错误。使用Mypy进行检查时，它会正确地报告错误：
tmp.py:38: error: Argument 1 to "func_str" has incompatible type "int"; expected "str" [arg-type] Found 1 error in 1 file (checked 1 source file)
然而，PyCharm（版本2023.2.3社区版或类似版本）的内置类型检查器在这种情况下却可能不会报告任何错误，将其视为合法的代码。这表明PyCharm在处理这种自定义描述符时，其类型推断机制可能存在一些特殊之处。
揭示PyCharm的硬编码逻辑
深入探究PyCharm的这种行为，我们发现其对cached_property的类型检查似乎是基于硬编码的名称匹配，而非完全的类型推断。这意味着，PyCharm可能不仅仅依赖于描述符的继承关系和__get__方法的类型签名，更可能依赖于描述符类的特定名称。
为了验证这一点，我们可以创建一个简化版、甚至可以说是一个“虚假”的cached_property描述符。即使这个描述符的内部实现可能不完整或不符合functools.cached_property的实际行为，只要它被命名为cached_property，PyCharm就可能应用其预设的类型检查逻辑。
# 这是一个简化的、可能不符合实际行为的 cached_property 描述符
def cached_property(func):
def foo(self):
# 这里的实现并不重要，关键在于名称
pass
return foo
def func_str(s: str) -> None:
print(s)
class Foo:
@cached_property
def prop_int(self) -> int:
return 1
foo = Foo()
# 即使是这个“虚假”的 cached_property，PyCharm 在此处会报告类型错误
func_str(foo.prop_int) # PyCharm 提示：Expected type 'str', got 'int' instead令人惊讶的是，即使是上述代码中一个如此简化的cached_property定义，PyCharm也能正确地识别出func_str(foo.prop_int)处的类型不匹配错误。这强有力地支持了PyCharm的类型检查器对cached_property这一名称存在特殊处理的推测。
解决方案：重命名自定义描述符
鉴于PyCharm的这种基于名称的特殊处理逻辑，一个直接且有效的解决方案就是将我们自定义的描述符类命名为cached_property。通过这种方式，我们可以“欺骗”PyCharm，使其将我们的自定义描述符视为其内置识别的cached_property，从而激活正确的类型检查行为。
以下是修改后的代码，将result_property重命名为cached_property：
import functools
from collections.abc import Callable
from typing import TypeVar, Generic, Any, overload, Union
T = TypeVar("T")
# 将自定义描述符类命名为 cached_property
class cached_property(functools.cached_property, Generic[T]):
def __init__(self, func: Callable[[Any], T]) -> None:
super().__init__(func)
def __set_name__(self, owner: type[Any], name: str) -> None:
super().__set_name__(owner, name)
@overload
def __get__(self, instance: None, owner: Union[type[Any], None] = None) -> 'cached_property[T]': ...
@overload
def __get__(self, instance: object, owner: Union[type[Any], None] = None) -> T: ...
def __get__(self, instance, owner=None):
return super().__get__(instance, owner)
def func_str(s: str) -> None:
print(s)
class Foo:
@cached_property # 使用重命名后的描述符
def prop_int(self) -> int:
return 1
foo = Foo()
# 现在 PyCharm 在此处会正确报告类型错误
func_str(foo.prop_int) # PyCharm 提示：Expected type 'str', got 'int' instead通过这个简单的重命名，PyCharm的类型检查器现在能够正确地识别出foo.prop_int的类型为int，并在将其传递给期望str的func_str时报告类型不匹配错误。
注意事项与总结
尽管这种重命名提供了一个实用的解决方案，但它本质上是一个利用PyCharm内部实现细节的变通方法，而非一个理想的、基于纯粹类型推断的解决方案。
注意事项：
- 命名冲突风险： 如果你的代码中已经有其他名为cached_property的自定义类或函数，这种重命名可能会导致命名冲突。需要确保你的自定义cached_property是在正确的作用域内定义，或者通过导入别名等方式避免冲突。
- 依赖IDE行为： 这种方法依赖于PyCharm当前版本（或类似版本）的特定行为。未来的PyCharm版本可能会改进其类型推断系统，从而使这种重命名不再必要，甚至可能导致新的问题。
- Mypy兼容性： 对于Mypy等其他类型检查器，它们通常会基于标准的PEP 484/526类型提示进行推断，因此即使不重命名，它们也能正确处理自定义描述符。这个解决方案主要针对PyCharm的特殊行为。
总结：
PyCharm在处理继承自functools.cached_property的自定义描述符时，其类型检查逻辑似乎优先依赖于描述符类的名称cached_property，而非完全基于其类型签名进行推断。当遇到PyCharm未能正确识别自定义cached_property类型错误的情况时，一个有效的临时解决方案是将自定义描述符类重命名为cached_property。虽然这不是一个完全符合类型系统最佳实践的方法，但在PyCharm改进其描述符类型推断机制之前，它提供了一个可行的途径来确保IDE的类型检查功能能够正常工作。
