Python类型注解问题：为何int无法传递给int子类PositiveInt？

问题场景 #

定义了继承自int的PositiveInt类用于限制正整数，但传入字面量1给Order的price参数时，Pylance抛出类型不兼容错误：

class PositiveInt(int):
    def __new__(cls, number: int):
        if number <= 0:
            raise ValueError("number must be positive")
        return super().__new__(cls, number)


class Order:
    def __init__(self, price: PositiveInt) -> None:
        self.price = price


Order(1) # Argument of type "Literal[1]" cannot be assigned to parameter "price" of type "PositiveInt" in function "__init__"
  # "Literal[1]" is incompatible with "PositiveInt"PylancereportGeneralTypeIssues

原因分析 #

1. 静态类型检查逻辑：虽然PositiveInt继承自int，但Literal[1]是int的子类型，却不是PositiveInt的子类型。类型检查器不会自动将int实例（包括字面量）向上转换为自定义子类，因为它无法推断传入的int会被构造为PositiveInt实例。
2. 参数传递逻辑：调用Order(1)时，直接传入的是int字面量，没有经过PositiveInt的构造过程，类型检查器认为参数类型不匹配。

修复方案 #

方案1：显式构造PositiveInt实例 #

直接在传入参数时转换为PositiveInt，让类型检查器明确识别参数类型：

Order(PositiveInt(1))

方案2：在Order内部处理类型转换 #

修改Order的参数注解为int，在__init__中完成转换和校验，对外隐藏类型细节：

class Order:
    def __init__(self, price: int) -> None:
        self.price = PositiveInt(price)

# 外部直接传入int即可
Order(1)

方案3：使用NewType（静态类型检查场景） #

如果仅需静态类型层面区分正整数，不需要运行时校验，用typing.NewType更轻量：

from typing import NewType

PositiveInt = NewType("PositiveInt", int)

class Order:
    def __init__(self, price: PositiveInt) -> None:
        self.price = price

# 传入时需显式转换
Order(PositiveInt(1))

方案4：兼容int和PositiveInt类型 #

使用Union[int, PositiveInt]作为参数类型，内部自动处理转换：

from typing import Union

class Order:
    def __init__(self, price: Union[int, PositiveInt]) -> None:
        if isinstance(price, int) and not isinstance(price, PositiveInt):
            self.price = PositiveInt(price)
        else:
            self.price = price

# 两种传入方式都支持
Order(1)
Order(PositiveInt(2))

优化建议 #

• 若需要运行时校验正整数，保留PositiveInt的__new__实现，同时选择显式构造或内部转换的方式，避免外部直接传入int给期望PositiveInt的参数。
• 若仅需静态类型检查，优先使用NewType，它不会带来额外的运行时开销。
• 避免依赖类型检查器的自动转换逻辑，显式处理类型转换能让代码逻辑更清晰，减少类型错误。

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