注解最佳实践

作者:

Larry Hastings

在 Python 3.10 及更高版本中访问对象的注解字典

Python 3.10 向标准库添加了一个新函数：inspect.get_annotations()。在 Python 3.10 及更高版本中，调用此函数是访问任何支持注解的对象的注解字典的最佳实践。此函数还可以为您“解字符串化”字符串化注解。

如果由于某种原因 inspect.get_annotations() 不适用于您的用例，您可以手动访问 __annotations__ 数据成员。Python 3.10 中此操作的最佳实践也发生了变化：从 Python 3.10 开始，保证 o.__annotations__ 始终适用于 Python 函数、类和模块。如果您确定您正在检查的对象是这三个特定对象之一，则可以直接使用 o.__annotations__ 来访问对象的注解字典。

但是，其他类型的可调用对象（例如，由 functools.partial() 创建的可调用对象）可能没有定义 __annotations__ 属性。在 Python 3.10 及更高版本中，当访问可能未知的对象的 __annotations__ 时，最佳实践是使用三个参数调用 getattr()，例如 getattr(o, '__annotations__', None)。

在 Python 3.10 之前，访问没有定义注解但具有带注解的父类的类将返回父类的 __annotations__。在 Python 3.10 及更高版本中，子类的注解将为空字典。

在 Python 3.9 及更低版本中访问对象的注解字典

在 Python 3.9 及更低版本中，访问对象的注解字典比在更高版本中复杂得多。问题在于这些旧版本 Python 中的设计缺陷，特别是与类注解有关。

访问其他对象（函数、其他可调用对象和模块）的注解字典的最佳实践与 3.10 的最佳实践相同，假设您没有调用 inspect.get_annotations()：您应该使用三参数的 getattr() 来访问对象的 __annotations__ 属性。

不幸的是，这并不是类的最佳实践。问题在于，由于 __annotations__ 在类上是可选的，并且由于类可以从其基类继承属性，因此访问类的 __annotations__ 属性可能会无意中返回基类的注解字典。例如

class Base:
    a: int = 3
    b: str = 'abc'

class Derived(Base):
    pass

print(Derived.__annotations__)

这将打印 Base 的注解字典，而不是 Derived 的。

如果您正在检查的对象是类 (isinstance(o, type))，您的代码将必须具有单独的代码路径。在这种情况下，最佳实践依赖于 Python 3.9 及更早版本的实现细节：如果一个类定义了注解，它们将存储在该类的 __dict__ 字典中。由于类可能定义了也可能没有定义注解，因此最佳实践是调用类字典的 get() 方法。

总而言之，以下是一些示例代码，可在 Python 3.9 及更早版本中安全地访问任意对象上的 __annotations__ 属性

if isinstance(o, type):
    ann = o.__dict__.get('__annotations__', None)
else:
    ann = getattr(o, '__annotations__', None)

运行此代码后，ann 应该是一个字典或 None。我们建议您在使用 isinstance() 进一步检查之前，仔细检查 ann 的类型。

请注意，某些特殊的或格式错误的类型对象可能没有 __dict__ 属性，因此为了更加安全，您可能还希望使用 getattr() 来访问 __dict__。

手动解字符串化字符串化注解

在某些注解可能是“字符串化”的情况下，并且您希望计算这些字符串以生成它们所代表的 Python 值，最好调用 inspect.get_annotations() 来为您完成这项工作。

如果您使用的是 Python 3.9 或更早版本，或者由于某种原因无法使用 inspect.get_annotations()，则需要复制其逻辑。我们建议您检查当前 Python 版本中 inspect.get_annotations() 的实现并遵循类似的方法。

简而言之，如果您希望计算任意对象 o 上的字符串化注解

  • 如果 o 是模块，则在调用 eval() 时使用 o.__dict__ 作为 globals。

  • 如果 o 是一个类，则在调用 eval() 时，使用 sys.modules[o.__module__].__dict__ 作为 globals，使用 dict(vars(o)) 作为 locals。

  • 如果 o 是使用 functools.update_wrapper()、functools.wraps() 或 functools.partial() 包装的可调用对象，则通过访问 o.__wrapped__ 或 o.func （视情况而定）迭代地解包它，直到找到根未包装的函数。

  • 如果 o 是可调用对象（但不是类），则在调用 eval() 时，使用 o.__globals__ 作为全局变量。

但是，并非所有用作注解的字符串值都可以通过 eval() 成功转换为 Python 值。理论上，字符串值可以包含任何有效的字符串，并且在实践中，存在有效的用例，即类型提示需要使用 无法 求值的字符串值进行注释。例如：

  • PEP 604 使用 | 的联合类型，在 Python 3.10 添加对此的支持之前。

  • 运行时不需要的定义，仅在 typing.TYPE_CHECKING 为真时导入。

如果 eval() 尝试求值此类值，则会失败并引发异常。因此，在设计使用注解的库 API 时，建议仅在调用方明确请求时才尝试求值字符串值。

所有 Python 版本中 __annotations__ 的最佳实践

  • 您应避免直接分配给对象的 __annotations__ 成员。让 Python 管理设置 __annotations__。

  • 如果您确实直接分配给对象的 __annotations__ 成员，则应始终将其设置为 dict 对象。

  • 如果您直接访问对象的 __annotations__ 成员，则应确保它是一个字典，然后再尝试检查其内容。

  • 您应避免修改 __annotations__ 字典。

  • 您应避免删除对象的 __annotations__ 属性。

__annotations__ 的怪癖

在所有 Python 3 版本中，如果该对象上未定义任何注解，则函数对象会延迟创建注解字典。您可以使用 del fn.__annotations__ 删除 __annotations__ 属性，但是如果您随后访问 fn.__annotations__，则该对象将创建一个新的空字典，并将其存储并作为其注解返回。在函数延迟创建其注解字典之前删除函数上的注解会抛出 AttributeError；连续两次使用 del fn.__annotations__ 保证始终抛出 AttributeError。

以上段落中的所有内容也适用于 Python 3.10 及更高版本中的类和模块对象。

在所有 Python 3 版本中，您可以将函数对象上的 __annotations__ 设置为 None。但是，随后使用 fn.__annotations__ 访问该对象上的注解将按照本节第一段的说明延迟创建一个空字典。这对于任何 Python 版本中的模块和类都不适用；这些对象允许将 __annotations__ 设置为任何 Python 值，并将保留设置的任何值。

如果 Python 为您字符串化注解（使用 from __future__ import annotations），并且您指定一个字符串作为注解，则该字符串本身将被引用。实际上，注解被引用了两次。例如：

from __future__ import annotations
def foo(a: "str"): pass

print(foo.__annotations__)

这将打印 {'a': "'str'"}。这不应真正被视为“怪癖”；在此提及只是因为它可能令人惊讶。