Use positional-only arguments for IO (#6851)

stdlib/bz2.pyi

@@ -88,7 +88,7 @@ def open(
     newline: str | None = ...,
 ) -> BZ2File | TextIO: ...
 
-class BZ2File(BaseStream, IO[bytes]):  # type: ignore # argument disparities between base classes
+class BZ2File(BaseStream, IO[bytes]):
     def __enter__(self: Self) -> Self: ...
     if sys.version_info >= (3, 9):
         @overload

stdlib/lzma.pyi

@@ -64,7 +64,7 @@ class LZMACompressor:
 
 class LZMAError(Exception): ...
 
-class LZMAFile(io.BufferedIOBase, IO[bytes]):  # type: ignore # argument disparities between base classes
+class LZMAFile(io.BufferedIOBase, IO[bytes]):
     def __init__(
         self,
         filename: _PathOrFile | None = ...,

stdlib/typing.pyi

@@ -499,6 +499,9 @@ Text = str
 
 TYPE_CHECKING = True
 
+# In stubs, the arguments of the IO class are marked as positional-only.
+# This differs from runtime, but better reflects the fact that in reality
+# classes deriving from IO use different names for the arguments.
 class IO(Iterator[AnyStr], Generic[AnyStr]):
     # TODO use abstract properties
     @property
@@ -516,27 +519,27 @@ class IO(Iterator[AnyStr], Generic[AnyStr]):
     @abstractmethod
     def isatty(self) -> bool: ...
     @abstractmethod
-    def read(self, n: int = ...) -> AnyStr: ...
+    def read(self, __n: int = ...) -> AnyStr: ...
     @abstractmethod
     def readable(self) -> bool: ...
     @abstractmethod
-    def readline(self, limit: int = ...) -> AnyStr: ...
+    def readline(self, __limit: int = ...) -> AnyStr: ...
     @abstractmethod
-    def readlines(self, hint: int = ...) -> list[AnyStr]: ...
+    def readlines(self, __hint: int = ...) -> list[AnyStr]: ...
     @abstractmethod
-    def seek(self, offset: int, whence: int = ...) -> int: ...
+    def seek(self, __offset: int, __whence: int = ...) -> int: ...
     @abstractmethod
     def seekable(self) -> bool: ...
     @abstractmethod
     def tell(self) -> int: ...
     @abstractmethod
-    def truncate(self, size: int | None = ...) -> int: ...
+    def truncate(self, __size: int | None = ...) -> int: ...
     @abstractmethod
     def writable(self) -> bool: ...
     @abstractmethod
-    def write(self, s: AnyStr) -> int: ...
+    def write(self, __s: AnyStr) -> int: ...
     @abstractmethod
-    def writelines(self, lines: Iterable[AnyStr]) -> None: ...
+    def writelines(self, __lines: Iterable[AnyStr]) -> None: ...
     @abstractmethod
     def __next__(self) -> AnyStr: ...
     @abstractmethod
@@ -545,7 +548,7 @@ class IO(Iterator[AnyStr], Generic[AnyStr]):
     def __enter__(self) -> IO[AnyStr]: ...
     @abstractmethod
     def __exit__(
-        self, t: Type[BaseException] | None, value: BaseException | None, traceback: TracebackType | None
+        self, __t: Type[BaseException] | None, __value: BaseException | None, __traceback: TracebackType | None
     ) -> bool | None: ...
 
 class BinaryIO(IO[bytes]):

tests/stubtest_allowlists/py310.txt

@@ -16,6 +16,18 @@ _collections_abc.MutableMapping.__setitem__
 _collections_abc.MutableMapping.pop
 _collections_abc.MutableMapping.setdefault
 
+# typing.IO uses positional-or-keyword arguments, but in the stubs we prefer
+# to mark these as positional-only for compatibility with existing sub-classes.
+typing.BinaryIO.write
+typing.IO.__exit__
+typing.IO.read
+typing.IO.readline
+typing.IO.readlines
+typing.IO.seek
+typing.IO.truncate
+typing.IO.write
+typing.IO.writelines
+
 ast.Bytes.__new__
 ast.Ellipsis.__new__
 ast.ExtSlice.__new__