罕见返回None值的Python函数类型标注问题及最佳实践问询

场景描述 #

我定义了一个仅在特定输入下返回None、其余情况返回int的函数x，代码如下：

from typing import Union

def x(i: int) -> Union[int, None]:
    if i == 0:
        return
    return i

def test(i: int):
    a = x(i)
    # 类型警告：*= 不支持 int | None 和 int 类型
    a *= 25

该函数在代码库中被频繁调用，且多数场景下已确认传入的i不会触发None返回，但直接将返回值当作int使用会触发类型检查警告。

备选方案分析 #

我曾考虑过以下几种处理方式，但都存在问题：

• 添加if a is None: return检查：完全冗余，因为已确认不会出现该情况
• 加a *= 25 # type: ignore：会让变量a变为Unknown类型，丧失类型检查能力
• 加a = x(i) # type: int：消除原有警告但触发新的类型不匹配警告
• 使用cast(int, x(i))：尚未充分测试

我当前的做法是修改函数x的返回类型标注为仅int，在返回None的行添加# type: ignore，并在文档字符串中说明实际可能返回None，以此避免全库的类型警告：

def x(i: int) -> int:
    """可能也会返回 `None`"""
    if i == 0:
        return # type: ignore
    return i

请问这是否为最佳方案？

最佳实践建议 #

不推荐你当前的方案，因为这种做法会让类型标注与函数实际行为脱节，其他开发者（甚至未来的你）很可能忽略文档字符串的说明，误以为函数绝对不会返回None，最终埋下运行时错误的隐患。

针对该场景，更合理的处理方式分为两种情况：

1. 入参范围可明确约束 #

如果多数调用场景中，传入的i确实不可能为0，可以给函数x的入参添加更严格的类型标注，从根源上避免None返回的可能性：

from typing import Literal

# 示例：限定入参为非0整数（可根据实际业务范围调整）
def x(i: Literal[1,2,3,4,5]) -> int:
    if i == 0:
        return
    return i

也可以自定义NonZeroInt类型来复用约束，这种方式适合入参范围明确的场景，调用方也需要配合使用严格的类型标注。

2. 无法约束入参，但调用时可确认返回不为None #

这种情况下，使用cast(int, x(i))是更优的选择：

from typing import cast, Union

def x(i: int) -> Union[int, None]:
    if i == 0:
        return
    return i

def test(i: int):
    a = cast(int, x(i))
    a *= 25

cast的作用是告知类型检查器“我确认该值的类型为int”，不会改变代码的运行时行为，同时保留了函数x原本准确的类型标注，既避免了类型警告，又不会掩盖函数的实际行为。

如果觉得每个调用点写cast繁琐，可以封装一个带运行时断言的辅助函数，兼顾类型安全与运行时校验：

from typing import TypeVar, Optional

T = TypeVar('T')

def assert_not_none(value: Optional[T]) -> T:
    assert value is not None, "预期值不为None，但实际为None"
    return value

# 调用示例
def test(i: int):
    a = assert_not_none(x(i))
    a *= 25

这个辅助函数不仅能让类型检查器认可值的类型，还能在意外出现None时直接抛出错误，提前暴露问题，比单纯的cast更安全。

总结 #

• 不要修改函数本身的类型标注来掩盖实际行为，这会破坏类型系统的可信度
• 优先在调用点使用cast或带断言的辅助函数做类型确认
• 若入参范围明确，可通过严格的入参类型标注从根源解决问题

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