Python typing.IO 参数为什么变成仅位置参数

我在把一组文件处理代码切到 Python 3.15 的类型检查环境时，第一次看到 typing.IO 的方法签名带上斜杠，直觉上以为文件 API 发生了运行时变化。实际情况更窄：Python 调整的是 typing.IO 和 typing.BinaryIO 这两个抽象类型的方法定义，让它们与真实文件对象早已采用的仅位置参数约定保持一致。

官方变更记录：https://chromium.googlesource.com/external/github.com/python/cpython/+/f6ed7c0acbd9234226cab5cca12f9d312809103e

先记住结论：看到 read(size, /) 或 write(data, /) 时，调用处应使用 stream.read(1024)、stream.write(data) 这样的按位置传参方式，不要依赖 stream.read(size=1024) 这类关键字调用。这个改动主要影响静态接口的准确性和类型检查边界，不是把 open() 返回的文件对象换成了另一套运行时对象。

升级后先看清：变化发生在抽象签名

Python 官方文档把 typing.IO[AnyStr] 描述为文件流类型，TextIO 和 BinaryIO 分别对应文本和二进制流。CPython 的变更说明指出，真实文件对象的方法本来就采用仅位置参数，而旧的 typing.IO 抽象方法仍写成普通参数，因此抽象类型并不能准确表达对象真正实现的接口。

官方类型文档：https://docs.python.org/3/library/typing.html#typing.IO

这也是我排查时最先划出的边界：如果报错来自类型检查器或编辑器提示，先检查标注和调用签名；如果报错来自真实对象的执行，再检查调用是否真的把参数当成关键字传入。两者可能在同一行代码里出现，但修复范围不同。

斜杠到底限制了什么

Python 函数定义中，斜杠左边的参数是仅位置参数。也就是说，下面的 read(size, /) 允许传入一个位置值，但不允许把参数名 size 写在调用里。官方教程给出的规则是：斜杠用于分隔仅位置参数，斜杠之后的参数才可能是位置或关键字参数。

参数规则说明：https://docs.python.org/3/tutorial/controlflow.html#special-parameters

from typing import BinaryIO

def read_chunk(stream: BinaryIO, limit: int) -> bytes:
    # 传给文件流的方法时按真实签名传入位置参数。
    return stream.read(limit)

def write_chunk(stream: BinaryIO, payload: bytes) -> int:
    # write 的数据参数同样放在位置参数区域，不依赖关键字名。
    return stream.write(payload)

# 这些调用表达的是同一个抽象接口的有效用法。
chunk = read_chunk(stream, 4096)
written = write_chunk(stream, chunk)

这里的重点不是把所有参数都改成位置参数，而是遵循具体方法签名。比如函数自己的 read_chunk(stream, limit) 没有斜杠，调用者仍可以写成 read_chunk(stream=source, limit=4096)；真正受限制的是文件流方法那一层。

把旧调用改成与真实文件对象一致

最常见的触发信号是类型检查器开始提示类似“关键字参数不符合签名”，或者升级后某个泛型文件包装器的 stub 不再接受参数名。处理时我会先找出调用层，而不是修改 typing.IO 的定义或给检查器加全局忽略。

from typing import IO

def copy_prefix(source: IO[bytes], target: IO[bytes], limit: int) -> int:
    # 关键字 limit 只属于当前函数的参数，便于上层调用和阅读。
    data = source.read(limit)
    if not data:
        return 0

    # 对 IO 抽象方法按位置传递 bytes，避免依赖 data 这个参数名。
    return target.write(data)

# 外层业务函数可以继续使用关键字参数，因为它没有声明 /。
count = copy_prefix(source=input_stream, target=output_stream, limit=8192)

如果代码里出现 source.read(size=limit)、target.write(data=payload) 或类似的包装调用，可以把它们改为位置形式。改动后仍保留外层业务函数的关键字调用，这样既符合 I/O 方法的契约，也不会无谓扩大接口变化。

官方 I/O 文档也把具体流对象的方法写成带斜杠的形式，例如 read(size=-1, /)、write(b, /)。这说明仅位置约束不是 Python 3.15 才突然加入到文件对象上的规则，而是抽象类型在追赶已有实现。

官方 I/O 方法文档：https://docs.python.org/3/library/io.html

类型检查、运行时和回滚要分开判断

CPython 的变更说明把它称为技术上的破坏性变化，但同时指出两点缓冲因素：这些抽象方法本身通常不会在运行时被直接调用；typeshed 中相关参数已经是仅位置参数。因此，大多数项目遇到的是签名更准确后的检查结果，而不是生产服务突然因为 typing.IO 失去方法。

如果暂时不能升级全部工具链，我会把兼容策略放在项目边界：保留 typing.IO 标注，避免在内部依赖抽象方法的关键字参数，必要时把公共包装函数固定为位置传递。不要通过删除所有文件流类型标注来“回滚”，那会把真正的输入输出错误隐藏起来。

最后用一张清单确认修复范围

1. 先确认提示来自 typing.IO、BinaryIO 的抽象方法，而不是其它 typing API。
2. 看到签名中的 /，把斜杠左侧参数按位置传入。
3. 重点搜索 read(size=...)、write(data=...)、seek(offset=...) 这类底层方法调用。
4. 保留外层业务函数的关键字调用，不要把无关函数一起改成位置参数。
5. 分别运行类型检查和最小文件对象测试，区分抽象契约问题与真实对象问题。
6. 跨 Python 版本发布时，优先让公共包装函数遵循真实文件对象的调用方式。

这次变化最值得记住的不是某个版本号，而是抽象类型应该描述对象真正能接受的调用方式。对 typing.IO 来说，Python 3.15 只是把已经存在于文件对象上的规则写得更准确。若代码一直使用位置参数，通常不需要改动；若依赖 I/O 方法的关键字参数，尽早在调用边界调整，比对类型检查器做全局静音更稳妥。

相关问题

typing.IO 的变化会让 open() 返回不同的对象吗？

不会。变化针对 typing.IO 与 typing.BinaryIO 的抽象方法签名，重点是让类型契约与真实文件对象一致。

read(size, /) 能不能写成 read(size=1024)？

按照仅位置参数契约不应这样写，应使用 read(1024)。真实文件对象的方法也通常采用这种调用约定。

TextIO 和 BinaryIO 也受影响吗？

变更说明同时涉及 IO 和 BinaryIO 的参数定义；实际迁移时应以项目使用的具体方法签名和检查器提示为准。

必须把所有函数都改成位置参数吗？

不需要。只改受斜杠约束的文件流方法；项目自己的包装函数仍可按原有接口接受关键字参数。