继承pygame.sprite.Sprite时pyright报self.rect错误的原因与解决

pygame 官方类型存根中，pygame.sprite.Sprite 基类的 image、rect 属性被声明为 Optional 类型（即允许取值为 None）——这是因为基类本身不会在初始化方法中给这两个属性赋值，需要开发者在子类中自行完成初始化。
即使你已经在子类 __init__ 中给 self.rect 赋了 pygame.Rect 类型的实际值，Pyright 有时无法自动完成这个赋值带来的类型收窄，依然会沿用基类的可选类型声明，因此在你访问 self.rect 的属性/方法时，就会抛出「访问可选类型成员」的类型错误。
这类报错属于静态检查的误报，因为实际运行时 self.rect 已经在实例化阶段完成赋值，永远不会出现 None 的情况，所以代码可以正常运行。

方案1：类级显式类型注解（最推荐，零冗余） #

直接在子类中显式声明对应属性的非可选类型，覆盖基类的可选类型声明即可，不需要修改任何业务逻辑，也不需要加冗余的非空判断。修改后的代码示例：

import pygame

class Entity(pygame.sprite.Sprite):
    # 显式声明属性类型，告知类型检查器这两个属性不会为None
    image: pygame.Surface
    rect: pygame.Rect
    velocity: pygame.Vector2

    def __init__(
        self,
        pos: tuple[int, int],
        size: tuple[int, int],
        color: str,
        *groups: pygame.sprite.AbstractGroup,
    ) -> None:
        super().__init__(*groups)
        self.velocity = pygame.Vector2((0, 0))
        self.image = pygame.Surface(size)
        self.rect = self.image.get_rect(topleft=pos)
        self.image.fill(pygame.Color(color))

添加注解后，Pyright 会直接认定这两个属性的类型为对应非可选类型，后续所有相关操作都不会再触发这类报错。

方案2：调整Pyright检查规则 #

如果项目中存在大量Sprite子类，不想逐个添加类型注解，可以修改项目的Pyright配置，关闭可选成员访问的检查。在项目根目录新建pyrightconfig.json，添加如下配置：

{
  "reportOptionalMemberAccess": false
}

该方案的缺点是会全局关闭可选成员访问的检查，可能漏掉项目其他代码中真实存在的None访问风险。

方案3：赋值时做类型收窄 #

如果不想修改全局配置，也不想加类级注解，可以在属性赋值后加一行断言，强制让Pyright识别到类型已经收窄为非可选：

self.rect = self.image.get_rect(topleft=pos)
assert self.rect is not None

这种写法比每次使用属性前加非空判断简洁，但依然会增加无实际运行意义的冗余代码，只适合临时修复单个报错的场景。

不推荐在每次访问self.rect前都加非空判断的写法，这类判断在你的业务逻辑里永远不会触发，属于完全无效的冗余代码。

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