解决MyPy报错：子类load_from_path方法签名与超类型不兼容

问题场景 #

父类BaseFileHandler定义了带默认参数的方法：

def load_from_path(self, filepath: IO[Any], mode: str = "r", **kwargs: Any) -> Any:
    with open(filepath, mode, encoding="utf-8") as f:
        return self.load_from_fileobj(f, **kwargs)

子类PickleHandler重写该方法时省略了mode参数：

def load_from_path(self, filepath: IO[Any], **kwargs: Any) -> Any:
    return super(PickleHandler, self).load_from_path(filepath, mode="rb", **kwargs)

运行MyPy时会触发Signature of "load_from_path" incompatible with supertype错误。

复现代码：

from typing import IO, Any

class BaseFileHandler:
    def load_from_fileobj(self, file: IO[Any], **kwargs: Any) -> Any:
        return "hi"
    def load_from_path(self, filepath: IO[Any], mode: str = "r", **kwargs: Any) -> Any:
            return self.load_from_fileobj(filepath, **kwargs)

class PickleHandler(BaseFileHandler):
    def load_from_path(self, filepath: IO[Any], **kwargs: Any) -> Any:
        return super(PickleHandler, self).load_from_path(filepath, mode="rb", **kwargs)

handler = PickleHandler()
obj = handler.load_from_path("fakefile.txt")
print(obj)

错误原因 #

子类重写方法时修改了父类的方法签名：父类显式声明了mode参数并带有默认值，而子类的签名中移除了该参数，仅通过**kwargs接收。这违反了里氏替换原则——调用父类方法的代码如果传入mode参数，子类的签名无法明确匹配，MyPy会判定为签名不兼容。

另外注意：父类中filepath的类型标注错误，open()接受字符串路径而非IO[Any]，正确类型应为str，否则调用时传入字符串会触发额外的类型错误。

解决方案 #

方案1：保留mode参数并强制关键字传递 #

显式声明mode参数，用*强制只能通过关键字传递，同时固定默认值为"rb"，既兼容父类签名，又限制子类的mode取值：

from typing import Literal, Any

class PickleHandler(BaseFileHandler):
    def load_from_path(self, filepath: str, *, mode: Literal["rb"] = "rb", **kwargs: Any) -> Any:
        return super().load_from_path(filepath, mode=mode, **kwargs)

• 用Literal["rb"]限制mode只能是"rb"，避免传入其他值；
• *确保mode只能作为关键字参数传递，和父类的参数顺序兼容；
• 修正filepath类型为str，符合实际使用场景。

方案2：保留父类完整签名，内部强制使用"rb" #

如果需要完全兼容父类的参数形式，但强制子类忽略传入的mode值，直接使用"rb"：

class PickleHandler(BaseFileHandler):
    def load_from_path(self, filepath: str, mode: str = "rb", **kwargs: Any) -> Any:
        # 忽略传入的mode，强制使用rb
        return super().load_from_path(filepath, mode="rb", **kwargs)

这种方式允许调用者传入mode参数，但子类内部会覆盖为"rb"，同时保持签名和父类完全一致。

方案3：用**kwargs兼容并添加类型注释（Python 3.12+） #

如果必须保留**kwargs的写法，可通过override装饰器让MyPy确认是刻意重写，同时内部强制覆盖mode值：

from typing import override, Any

class PickleHandler(BaseFileHandler):
    @override
    def load_from_path(self, filepath: str, **kwargs: Any) -> Any:
        kwargs["mode"] = "rb"
        return super().load_from_path(filepath, **kwargs)

注意：这种方式需要确保调用者不会依赖mode参数的自定义值，否则会被覆盖。

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