TypeError: 'NoneType' object is not callable 表示代码试图调用值为 None 的变量，常见原因包括函数无返回值（默认返None）、变量覆盖内置函数（如 print = ...）、方法链中调用返回 None 的就地操作（如 list.append()），修复需确保调用对象确为可调用类型。
TypeError: 'NoneType' object is not callable 这类报错和类型提示本身无关，但常被误认为是 type hint 导致的错误——实际上，type hint 不会在运行时抛出任何异常。真正要修复的，是静态检查工具（如 mypy、pyright）报告的类型不匹配问题，或 IDE 因类型信息缺失/错误而给出的误报。
为什么 mypy 报 error: Argument 1 to "foo" has incompatible type "str"; expected "int"
这是 mypy 在告诉你：你调用了一个标注了 foo(x: int) 的函数，却传入了 "123" 这样的字符串。Python 解释器照常执行，但 mypy 认为这违背了你的类型契约。
常见原因和做法：
-
int("123")没做显式转换，直接传给foo—— 补上转换，或在调用前加类型断言（不推荐滥用） - 函数定义漏写了返回类型，导致 mypy 推断为
Any，后续调用链失去约束 —— 补全-> int或-> None - 使用了
Optional[int]却没做is not None检查就直接参与运算 —— 加判断，或用typing.cast(int, x)（仅限你 100% 确定） - 参数用了
Union[str, int]，但函数体里只按int处理 —— 改成if isinstance(x, int): ... else: ...，或拆成两个重载函数
VS Code 显示 Cannot assign to final variable "X" 但代码能跑
这是 Pylance（底层用 pyright）在执行严格检查，而你变量用了 Final 注解但后续又赋值了。例如：
立即学习“Python免费学习笔记（深入）”；
from typing import Final PORT: Final[int] = 8000 PORT = 8080 # ← 这里会触发 Pylance 报错
Final 是语义承诺，不是运行时锁。修复方式只有两种：
- 真的不再修改它，删掉那行赋值
- 如果必须动态改，就别用
Final，改用普通注解PORT: int
注意：Final 在 Python 3.8+ 才正式支持，3.7 需从 typing_extensions 导入。
用 list[str] 报 SyntaxError: invalid syntax
说明你 Python 版本低于 3.9。PEP 585 规定内置容器泛型（如 list、dict）直接支持方括号语法，但仅限 3.9+。
对应写法：
- Python 3.9+：
names: list[str] = ["a", "b"] - Python 3.5–3.8：
from typing import List，然后写names: List[str] = ["a", "b"]
混用会出问题：比如在 3.8 环境下写了 list[str]，mypy 可能不报错（取决于配置），但 CPython 解释器直接 SyntaxError。务必确认运行环境版本与语法兼容。
Optional[str] 和 Union[str, None] 哪个更安全？
两者等价，但 Optional[str] 更简洁、意图更明确。不过要注意一个易忽略点：
mypy 默认不检查 None 是否被安全解包。比如：
def get_name() -> Optional[str]:
return None
<p>name = get_name()
print(name.upper()) # ← mypy 默认不报错！
要让它报错，必须启用严格模式：
- 运行 mypy 时加
--strict，或 - 在
pyproject.toml中配[[tool.mypy.overrides]]启用disallow_untyped_calls = true和disallow_any_unimported = true
否则，Optional 只是“可为空”的声明，不自动带来空值防护 —— 这恰恰是很多人以为加了类型提示就万事大吉，结果线上 still crash with AttributeError: 'NoneType' object has no attribute 'upper' 的根源。
