如何让使用X|Y类型注解的Python代码兼容Python 3.9？

开发者阿泽

2026-7-17

问题描述

自Python 3.10起，可使用X | Y等价于Union[X, Y]进行类型注解。现有一个基于Python 3.10+开发的大型Python包，大量使用该语法。因需适配树莓派OS bullseye（仅集成Python 3.9.2，不支持|类型注解语法），且仅需短期兼容（数月后将升级到含Python 3.11的Debian Bookworm版本树莓派OS）。已添加from __future__ import annotations，但使用pydantic解析类型注解时出现如下报错：

Traceback (most recent call last):
  File "/home/michael/margintest/./margin.py", line 6, in <module>
    from vtcontrol.apps.margintest.app import App
  File "/home/michael/margintest/vtcontrol/apps/margintest/app.py", line 16, in <module>
    from .widgets.steps import StepsDetailView, TestProgressbar
  File "/home/michael/margintest/vtcontrol/apps/margintest/widgets/steps.py", line 6, in <module>
    from ..runner import Runner
  File "/home/michael/margintest/vtcontrol/apps/margintest/runner.py", line 11, in <module>
    from .models.config import Config
  File "/home/michael/margintest/vtcontrol/apps/margintest/models/config.py", line 76, in <module>
    class StepConfig(BaseModel):
  File "/home/michael/margintest/venv/lib/python3.9/site-packages/pydantic/main.py", line 178, in __new__
    annotations = resolve_annotations(namespace.get('__annotations__', {}), namespace.get('__module__', None))
  File "/home/michael/margintest/venv/lib/python3.9/site-packages/pydantic/typing.py", line 400, in resolve_annotations
    value = _eval_type(value, base_globals, None)
  File "/usr/lib/python3.9/typing.py", line 283, in _eval_type
    return t._evaluate(globalns, localns, recursive_guard)
  File "/usr/lib/python3.9/typing.py", line 539, in _evaluate
    eval(self.__forward_code__, globalns, localns),
  File "<string>", line 1, in <module>
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

解决方案

报错核心原因：from __future__ import annotations仅将类型注解转为字符串存储，但pydantic在Python 3.9下解析时会尝试执行eval解析这些字符串，而Python 3.9本身不支持type | None这类|运算符的类型语法，最终触发报错。以下是几种短期兼容的可行方案：

批量代码替换（最直接可靠）：
用正则表达式全局替换项目中的|类型语法为Python 3.9支持的标准写法：
1. 将所有X | None替换为Optional[X]
2. 将所有A | B（多类型联合）替换为Union[A, B]，多类型如A | B | C则替换为Union[A, B, C]
  同时在所有用到这些类型的文件顶部导入：
```
from typing import Union, Optional
```
升级pydantic版本：
确保使用pydantic v1.10.0及以上版本（或pydantic v2.x），新版本对Python 3.9下的字符串类型注解兼容性优化明显，部分场景下无需修改代码即可解析|语法的字符串注解。
临时 monkey patch（应急用，不推荐长期）：
在项目入口文件添加以下代码，给Python 3.9的类型临时添加|运算符支持：
```
import typing

if hasattr(typing, "_GenericAlias"):
    def __or__(self, other):
        return typing.Union[self, other]

    typing._GenericAlias.__or__ = __or__
    type.__or__ = __or__
```
该方法可能存在未知兼容性风险，仅建议作为临时应急方案。

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