应直接标注具体类型（如str、Path）并设非None默认值，而非用Optional[T] = None；这样mypy等检查器能确保参数永不为None，同时支持不传参使用默认值。
用 Optional[T] 表示“可以是 T 或 None”，但你要的是“**不能是 None，但可以不传（即使用默认值）**”——这靠类型提示本身无法强制“不可为 None”，关键在于**组合使用类型标注 + 默认值 + 类型检查器的配合**。
核心写法：直接写具体类型 + 设非 None 默认值
最清晰、最被 mypy/pyright 等主流检查器正确识别的方式是：
- 参数类型标注为具体类型（如
str、int、Path），不加Optional - 给它一个明确的、非
None的默认值（如""、0、Path()、或...配合Union等进阶技巧）
例如：
from pathlib import Path
<p>def read_file(path: Path = Path("default.txt")) -> str:
return path.read_text()
mypy 会认为 path 永远是 Path 类型，调用 read_file() 或 read_file(Path("x")) 都合法；而 read_file(None) 会被直接报错。
立即学习“Python免费学习笔记（深入）”；
想允许“不传”，但又不想给具体默认值？用 Union[T, _Sentinel] + ... （进阶）
如果逻辑上你希望默认行为是“未提供”，而不是某个具体对象（比如想区分 arg=... 和 arg="something"），可以用私有哨兵值 + Union：
from typing import Union, TYPE_CHECKING
<p>if TYPE_CHECKING:
from typing import TypeAlias</p><p>_Sentinel = object() # 唯一占位符
SentinelType: TypeAlias = type(_Sentinel)</p><p>def process(data: Union[str, SentinelType] = _Sentinel) -> str:
if data is _Sentinel:
return "default logic"
return f"processed: {data}"
这样类型检查器知道 data 要么是 str，要么是那个哨兵（不是 None），且调用时不传参就走默认分支。注意：这不是标准做法，适合框架/库内部控制流。
别用 Optional[T] = None —— 它明确允许传 None
下面这种写法是反模式：
def bad_example(name: Optional[str] = None) -> str:
return name.upper() # ❌ mypy 不报错，但运行时崩
虽然你写了 = None，但类型提示 Optional[str] 告诉检查器“name 可以是 None”，所以 name.upper() 不会被警告。这不是你想要的“不能是 None”。
小结：推荐做法就一条
直接标注具体类型，配一个安全的非 None 默认值。既语义清晰，又让 mypy/pyright 能真正帮你挡住 None 入参。是否“缺省”由是否有默认值决定，是否“可为 None”由类型标注决定——两者正交，别混用 Optional 和 = None。
