python 类型检查器（如 pyright）不支持在 @overload 中直接声明实例属性类型，但可通过泛型 + 子类化 + __new__ 重载实现构造时精确推断 stdin 等属性的类型（如 io[str] 或 io[bytes]）。
在静态类型检查中，无法通过 @overload 为 __init__ 方法“声明”实例属性的类型——因为 @overload 仅用于描述函数调用签名（即输入参数与返回类型的对应关系），而 self.stdin: ... 这类语句在 __init__ 的 overload stub 中属于非法的语句式类型注解（Pyright 会报 reportRedeclaration），且运行时无效。
真正的解决方案是：将类型差异提升到类层级，利用 Python 的泛型（MyPopen[str] / MyPopen[bytes]）配合 __new__ 的重载，让类型检查器在实例创建时就确定其精确类型，从而自然继承对应泛型参数所约束的属性类型。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
✅ 正确实现方式（Pyright & mypy 兼容）
from typing import IO, Literal, Optional, TypeVar, Generic, overload, TYPE_CHECKING
if TYPE_CHECKING:
from typing import Any
T = TypeVar("T", str, bytes)
class MyPopen(Generic[T]):
stdin: Optional[IO[T]]
def __init__(self, text: bool = False) -> None:
self.stdin = None # 运行时统一初始化
# 关键：重载 __new__，根据 text 参数返回不同特化子类的实例
@overload
def __new__(cls, text: Literal[False] = ...) -> "MyPopen[bytes]": ...
@overload
def __new__(cls, text: Literal[True]) -> "MyPopen[str]": ...
def __new__(cls, text: bool = False) -> "MyPopen[str] | MyPopen[bytes]":
if text:
return super().__new__(_StrPopen)
else:
return super().__new__(_BytesPopen)
class _StrPopen(MyPopen[str]): pass
class _BytesPopen(MyPopen[bytes]): pass✅ 类型检查效果验证
# text=True → MyPopen[str]
pp1 = MyPopen(text=True)
assert pp1.stdin is not None
pp1.stdin.write("hello") # ✅ OK: str accepted
pp1.stdin.write(b"hello") # ❌ Error: bytes incompatible with str
# text=False → MyPopen[bytes]
pp2 = MyPopen(text=False)
assert pp2.stdin is not None
pp2.stdin.write("hello") # ❌ Error: str incompatible with bytes
pp2.stdin.write(b"hello") # ✅ OK: bytes accepted
# 默认 text=False → MyPopen[bytes]
pp3 = MyPopen()
pp3.stdin.write(b"ok") # ✅ OK? 为什么 subprocess.Popen 能做到？ CPython 的 subprocess 模块本身未在源码中写类型注解，其高精度类型支持来自 typeshed —— 即第三方存根文件（stdlib/subprocess.pyi），其中正是使用了类似上述 __new__ 重载 + 泛型子类的方式定义 text: Literal[True] 和 text: Literal[False] 的 overload 分支。
⚠️ 注意事项
- 不要尝试在 __init__ 的 overload stub 中写 self.xxx: ... —— 这是语法错误且被类型检查器禁止；
- __new__ 的 overload 必须覆盖所有可能调用路径（包括默认参数），否则会导致调用不匹配警告；
- 子类 _StrPopen / _BytesPopen 无需任何逻辑，仅作类型占位；所有运行时行为仍由 MyPopen 的 __init__ 和方法定义；
- 若需支持更多 I/O 属性（如 stdout, stderr），只需在泛型类中一并声明为 IO[T] | None，类型会自动传导；
- 在严格模式（--strict）下，super().__new__(...) 可能触发 error: Cannot instantiate abstract class 提示，此时可加 # type: ignore 或确保基类无 @abstractmethod。
该模式是目前 PEP 484 / PEP 695 生态下最健壮、工具链支持最完善的“构造时类型分支”方案，已被 pathlib, sqlite3, subprocess 等标准库存根广泛采用。
