为何Python中Final类型注解在模块级与函数内表现不同？

当出现「TypeError: Cannot instantiate typing.*」错误时，通常和误用括号而非方括号有关，但Python的以下行为让人困惑：

from typing import Final

def f():
  h : Final[int] = 10 # Accepted
  i : Final(int) = 15 # Accepted

f() # Ran successfully
j : Final[int] = 1 # Accepted
k : Final(int) = 2 # ERROR

对应的错误信息：

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python3.9/typing.py", line 335, in __call__
    raise TypeError(f"Cannot instantiate {self!r}")
TypeError: Cannot instantiate typing.Final

核心问题解答 #

1. 模块级与函数内注解的求值时机差异 #

Python模块级的代码（包括类型注解）在模块被导入时就会立即执行求值；而函数内部的代码（包括类型注解）只有在函数被调用时才会执行，且Python运行时默认不会主动解析函数内的类型注解——除非你通过typing.get_type_hints()这类工具显式读取，否则这些注解只是作为未执行的表达式存在，不会触发实际调用。

2. 两种写法的合法性差异 #

• Final[int]：这是符合规范的正确写法。Final是类型构造器，使用方括号[]传入类型参数，会返回一个合法的类型注解对象，无论在模块级还是函数内都能被正确处理。
• Final(int)：这是错误写法。Final并非可实例化的类，它的__call__方法被特意设计为抛出TypeError，禁止直接调用。
  • 函数内部：因为运行时不会主动解析注解，Final(int)只是作为未执行的表达式存在，不会触发调用，所以不会报错。
  • 模块级：模块加载时会立即求值注解，Final(int)被实际调用，触发__call__里的错误逻辑，因此直接抛出异常。

内容的提问来源于stack exchange，提问作者Rui Miguel