python的类型注解（pep 484）主要针对函数参数和返回值，但直接为函数对象本身附加的属性（如`func.cache`）添加类型提示并不直接支持。本文将介绍一种利用可调用类（callable class）作为装饰器的方法，实现对函数属性的类型安全注解，从而提升代码的可读性和可维护性，并结合`mypy`等工具进行静态类型检查。
引言：函数属性与类型注解的挑战
在Python中，函数不仅是可调用对象，也可以像普通对象一样拥有属性，这在PEP 232中有所定义。例如，我们经常会看到将缓存字典直接附加到函数对象上的模式，如 foo.cache = {}。这种做法简洁高效，尤其适用于实现简单的备忘录模式或存储函数相关的状态。
然而，当引入类型注解（PEP 484）以提高代码可读性和可维护性时，我们面临一个挑战：如何为这些直接附加到函数对象上的属性添加类型提示？Python的类型提示系统主要关注函数签名（参数和返回值），对于函数对象本身的动态属性，并没有直接的语法或机制在函数定义内部进行类型注解。例如，在以下代码中，foo.cache的类型并未被明确声明，这使得静态类型分析工具（如mypy）无法对其进行有效检查：
def foo(s: str):
try:
print(foo.cache[s]) # mypy无法得知foo.cache的类型
except Exception:
print('NEW')
foo.cache[s] = 'CACHE'+s
foo.cache = {} # 运行时赋值，类型检查工具在此处也无法追溯到函数内部这种情况下，若不加以处理，mypy等工具将无法在编译时捕获因foo.cache类型不匹配而可能导致的潜在错误。
解决方案：利用可调用类实现类型安全
为了解决函数属性的类型注解问题，我们可以采用一种将函数包装在可调用类（Callable Class）中的模式。这种方法的核心思想是：创建一个类，它既可以作为装饰器接收原始函数，又可以定义带有类型注解的属性，并通过实现 __call__ 方法使其自身可像函数一样被调用。
立即学习“Python免费学习笔记（深入）”；
当一个函数被这样的可调用类装饰后，它实际上被替换成了该类的一个实例。这个实例承载了原始函数的功能，同时也拥有了在类定义中明确声明并类型注解的属性。
可调用类的设计
以下是一个名为 Cacheable 的可调用类示例，它旨在为函数提供一个类型安全的缓存属性：
import typing
class Cacheable:
# 明确声明缓存属性的类型
cache: dict[str, str]
# 存储原始函数，并声明其类型
_call: typing.Callable[[str], None]
def __init__(self, call: typing.Callable[[str], None]) -> None:
"""
初始化Cacheable实例。
Args:
call: 被装饰的原始函数。
"""
self.cache = {} # 初始化缓存字典
self._call = call # 保存原始函数
def __call__(self, s: str) -> None:
"""
使Cacheable实例可像函数一样被调用。
Args:
s: 传递给原始函数的参数。
"""
# 将调用委托给原始函数
return self._call(s)在这个 Cacheable 类中：
- cache: dict[str, str]：我们明确地声明了 cache 属性的类型为一个字符串到字符串的字典。
- _call: typing.Callable[[str], None]：我们声明了一个内部属性 _call 来存储被装饰的原始函数，并为其指定了类型签名。
- __init__ 方法在实例创建时初始化 cache 字典并保存原始函数。
- __call__ 方法使得 Cacheable 实例本身可以像函数一样被调用，它会将所有调用转发给内部存储的原始函数 _call。
作为装饰器使用
通过将 Cacheable 类作为装饰器使用，我们可以将上述类型安全的属性附加到函数上：
@Cacheable
def foo(s: str) -> None:
try:
# 此时 foo 已经是一个 Cacheable 实例，可以直接访问其类型安全的 cache 属性
print(foo.cache[s])
except KeyError: # 捕获KeyError而不是通用的Exception，更精确
print('new')
foo.cache[s] = f'cache{s}'
# 示例调用
foo('a') # 第一次调用，'new'，并缓存 'cachea'
foo('a') # 第二次调用，打印 'cachea'
foo('b') # 第一次调用，'new'，并缓存 'cacheb'当 foo 函数被 @Cacheable 装饰后，foo 变量不再指向原始函数，而是指向一个 Cacheable 类的实例。因此，对 foo.cache 的访问实际上是对 Cacheable 实例的 cache 属性的访问，这个属性在类定义时就已经有了明确的类型注解。
静态类型检查的优势
这种模式最大的优势在于其对静态类型检查工具（如 mypy）的友好性。现在，mypy 能够理解 foo 是一个 Cacheable 实例，并且知道 Cacheable 实例拥有一个类型为 dict[str, str] 的 cache 属性。
例如，如果尝试访问一个不存在的属性，mypy 将会立即发出警告：
# ... (接上面的Cacheable和foo定义)
# 尝试访问不存在的属性
# foo.someotherattribute = {}
# mypy会报告：error: "Cacheable" has no attribute "someotherattribute"
# 尝试访问Cacheable中未定义的属性
# print(foo.otherattribute[s])
# mypy会报告：error: "Cacheable" has no attribute "otherattribute"这极大地提升了代码的健壮性和可维护性，因为类型错误可以在运行时之前被发现。
注意事项与最佳实践
- 对象类型变更：使用此模式后，原始函数 foo 的类型不再是 typing.Callable，而是 Cacheable 类的实例。这意味着如果代码中存在依赖 foo 原始函数类型的地方，可能需要进行调整。
- 灵活性与复杂性：对于非常简单的函数属性，直接在函数外部赋值可能足够。但当属性数量增多、逻辑更复杂或需要更严格的类型检查时，可调用类装饰器模式的优势就显现出来。
- 通用性：Cacheable 模式可以推广到其他需要为函数附加类型化状态的场景，例如计数器、锁或其他资源管理。
- functools.wraps：虽然在这个特定的缓存例子中未直接使用，但当创建更通用的装饰器时，通常会使用 functools.wraps 来保留被装饰函数的元数据（如 __name__, __doc__ 等），以确保函数的行为更符合预期。对于这种将函数替换为类实例的模式，functools.wraps 的直接应用方式有所不同，因为我们改变了对象的类型。如果需要保留这些元数据，可能需要在 Cacheable 类的 __init__ 或 __call__ 中手动处理。
总结
为Python函数属性添加类型注解是一个不常见的需求，但通过利用可调用类作为装饰器，我们可以优雅地解决这一问题。这种方法不仅允许我们为函数附加的属性提供明确的类型提示，还使得静态类型检查工具能够对这些属性进行有效验证，从而显著提升代码的类型安全、可读性和可维护性。在需要为函数关联复杂状态或需要严格类型检查的场景中，这种模式是一个强大而灵活的解决方案。
