MyPy中双下划线参数生成存根文件时的特殊处理机制

在Python静态类型检查工具MyPy中，当使用stubgen命令生成存根文件(.pyi)时，对于以双下划线开头的参数名会进行特殊处理。这个机制涉及Python类型系统的深层约定，值得开发者特别注意。

现象描述

当函数参数名以双下划线开头时（如__unused_x），使用stubgen生成的存根文件中会出现一个特殊的/符号。例如：

def badUnderscores(__unused_x: int, /) -> None: ...

这个/符号实际上表示这是一个"仅限位置参数"(positional-only parameter)，这是Python类型系统的一个正式约定。

技术背景

Python类型系统规范中明确规定：所有以双下划线开头但不以双下划线结尾的参数名，都会被类型检查器假定为仅限位置参数。这个约定是为了：

1. 保持与旧版Python的兼容性
2. 提供一种标准方式来表示位置参数
3. 避免参数名冲突

仅限位置参数意味着这些参数不能通过关键字方式传递，只能通过位置传递。这是Python 3.8+通过PEP 570正式引入的语法特性。

实际影响

对于开发者而言，这个机制会导致：

1. 存根文件中自动添加/标记
2. 类型检查时会强制执行位置参数规则
3. 可能影响某些依赖参数名的工具

最佳实践

如果开发者只是想表示一个未使用的参数（常见于必须满足接口但实际不使用的参数），建议使用单下划线而非双下划线：

def betterUnderscores(_unused_x: int) -> None: ...

这样生成的存根文件将不会包含/标记，同时仍然能清晰表达参数的用途。

深入理解

Python中参数传递的几种形式：

1. 位置或关键字参数：常规参数形式
2. 仅限位置参数：/之前的参数
3. 仅限关键字参数：*之后的参数
4. 可变位置参数：*args
5. 可变关键字参数：**kwargs

MyPy通过双下划线参数名自动添加/的机制，实际上是为旧版Python代码提供了一种向后兼容的仅限位置参数表示方式。

总结

MyPy的这一行为不是bug，而是遵循Python类型系统规范的实现。开发者在使用双下划线参数名时应当了解其特殊含义，并根据实际需求选择合适的命名约定。对于大多数"未使用参数"的场景，单下划线是更合适的选择，既能表达意图又不会触发特殊类型规则。