非QObject类中QCoreApplication.translate的mypy报错与运行矛盾解决方法

问题背景 #

在非QObject子类中调用QCoreApplication.translate时，会出现mypy类型检查与实际运行逻辑的矛盾：

• 使用字符串参数调用：

self.translate("MyCustomClass", "This text should be translated", None)

mypy会抛出类型错误：Mypy: Argument 1 has incompatible type "str"; expected "bytes" [arg-type]，但实际翻译功能可正常运行。

• 按照mypy提示改用字节串参数：

self.translate(b"MyCustomClass", b"This text should be translated", None)

则触发运行时错误：

ValueError: 'PySide6.QtCore.QCoreApplication.translate' called with wrong argument values:
  PySide6.QtCore.QCoreApplication.translate(b'MyCustomClass', b'This text should be translated', None)
Found signature:
  PySide6.QtCore.QCoreApplication.translate(bytes, bytes, Optional[bytes] = None, int = -1)

问题根源在于PySide6提供的translate方法类型标注错误，其定义中参数类型被标注为bytes，但实际运行时仅接受字符串：

def translate(self, context, key, disambiguation, bytes=None, *args, **kwargs):
    """ translate(context: bytes, key: bytes, disambiguation: Optional[bytes] = None, n: int = -1) -> str """
    pass

可行解决办法 #

1. 单行忽略mypy报错 #

直接在报错代码行添加mypy忽略注释，保留正确的字符串参数写法：

self.translate("MyCustomClass", "This text should be translated", None)  # type: ignore[arg-type]

优点是快速简单，适合小范围场景使用。

2. 本地修正类型存根 #

创建自定义的类型存根文件（例如QtCore.pyi），修正translate方法的类型定义，同时支持字符串和字节串参数：

from typing import Optional, overload

class QCoreApplication:
    @overload
    def translate(self, context: str, key: str, disambiguation: Optional[str] = None, n: int = -1) -> str: ...
    @overload
    def translate(self, context: bytes, key: bytes, disambiguation: Optional[bytes] = None, n: int = -1) -> str: ...

随后在项目的mypy.ini或pyproject.toml中配置该存根文件的路径，让mypy优先加载修正后的类型信息。

3. 封装安全调用函数 #

编写一个封装函数，统一处理translate的调用逻辑，并通过正确的类型注解让mypy认可：

from PySide6.QtCore import QCoreApplication
from typing import Optional

def safe_translate(context: str, key: str, disambiguation: Optional[str] = None, n: int = -1) -> str:
    return QCoreApplication.translate(context, key, disambiguation, n)

后续代码中调用safe_translate即可同时满足类型检查和运行需求。

4. 上游提交修复 #

若有时间和精力，可向PySide6官方仓库提交类型标注修复的PR，从根源解决该类型定义错误问题。

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