为何Mypy无法识别自定义Type Guard？类型守卫失效排查

1. 严格规范Type Guard的类型标注 #

• 必须使用typing.TypeGuard（Python 3.10+）或typing_extensions.TypeGuard，返回值标注要明确指定守卫确认的目标类型。比如你的邮箱配置是Optional[EmailSettings]，守卫函数应标注为：

  def is_email_config_complete(settings: EmailSettings | None) -> TypeGuard[EmailSettings]:
  

• 函数内部必须严格检查所有必填字段的非空性与类型匹配，不能遗漏任何SMTPHandler依赖的字段（如smtp_server、smtp_port、from_email等）。

2. 修正Pydantic Settings的类型定义 #

• 若邮箱配置类继承自BaseSettings，确保必填字段未被错误标记为Optional。如果字段是运行时必填但允许环境变量为空，用Field(...)而非Field(default=None)强制静态层面的必填性，减少守卫的校验压力。
• 检查字段类型是否与SMTPHandler的参数类型完全匹配，比如smtp_port必须是int而非str，避免类型不兼容错误。

3. 确保Type Guard的使用逻辑正确 #

• 在调用SMTPHandler前，必须用守卫做条件判断，且直接使用守卫校验后的变量，不要将变量赋值给其他标识符后再使用（类型检查器可能无法跟踪赋值后的类型）。示例：

  if is_email_config_complete(email_settings):
      # 此处email_settings会被类型检查器识别为非空的EmailSettings
      handler = SMTPHandler(
          mailhost=(email_settings.smtp_server, email_settings.smtp_port),
          fromaddr=email_settings.from_email,
          toaddrs=email_settings.to_emails,
          subject=email_settings.subject
      )
  

4. 调整类型检查器的配置 #

• Mypy：确保开启strict-optional（或strict模式），否则类型检查器不会区分None与非None类型。
• Pyright：在pyrightconfig.json中设置"strict": true或"typeCheckingMode": "strict"，确认useTypeGuardAnnotations为开启状态（默认开启）。
• 若守卫函数在其他模块，需明确导入（避免from .utils import *），确保类型检查器能识别函数的返回标注。

5. 用Pydantic内置验证替代Type Guard #

• 利用pydantic的model_validator在配置类内部完成完整性校验，实例化时若配置不全直接抛出错误，类型检查器会自动识别验证后的实例为有效非空类型：

  from pydantic import model_validator
  from pydantic_settings import BaseSettings
  
  class EmailSettings(BaseSettings):
      smtp_server: str | None = None
      smtp_port: int | None = None
      from_email: str | None = None
      to_emails: list[str] | None = None
  
      @model_validator(mode='after')
      def check_config_complete(self) -> 'EmailSettings':
          required_fields = [self.smtp_server, self.smtp_port, self.from_email, self.to_emails]
          if not all(field is not None for field in required_fields):
              raise ValueError("邮箱配置不完整")
          return self
  

• 实例化EmailSettings()后，类型检查器会认为所有必填字段均非空，直接传入SMTPHandler即可消除类型错误。

6. 校验SMTPHandler的参数类型匹配 #

• 确认SMTPHandler的参数类型要求，比如mailhost是否接受(str, int)组合，若你的smtp_port是从环境变量读取的字符串，需确保pydantic已自动转换为int，或在守卫中显式检查isinstance(settings.smtp_port, int)。

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