Tighten tempfile() return types (#10232)

stdlib/tempfile.pyi

@@ -1,10 +1,21 @@
 import io
 import sys
-from _typeshed import BytesPath, GenericPath, ReadableBuffer, StrPath, WriteableBuffer
+from _typeshed import (
+    BytesPath,
+    GenericPath,
+    OpenBinaryMode,
+    OpenBinaryModeReading,
+    OpenBinaryModeUpdating,
+    OpenBinaryModeWriting,
+    OpenTextMode,
+    ReadableBuffer,
+    StrPath,
+    WriteableBuffer,
+)
 from collections.abc import Iterable, Iterator
 from types import TracebackType
 from typing import IO, Any, AnyStr, Generic, overload
-from typing_extensions import Literal, Self, TypeAlias
+from typing_extensions import Literal, Self
 
 if sys.version_info >= (3, 9):
     from types import GenericAlias
@@ -30,13 +41,10 @@ TMP_MAX: int
 tempdir: str | None
 template: str
 
-_StrMode: TypeAlias = Literal["r", "w", "a", "x", "r+", "w+", "a+", "x+", "rt", "wt", "at", "xt", "r+t", "w+t", "a+t", "x+t"]
-_BytesMode: TypeAlias = Literal["rb", "wb", "ab", "xb", "r+b", "w+b", "a+b", "x+b"]
-
 if sys.version_info >= (3, 12):
     @overload
     def NamedTemporaryFile(
-        mode: _StrMode,
+        mode: OpenTextMode,
         buffering: int = -1,
         encoding: str | None = None,
         newline: str | None = None,
@@ -50,7 +58,7 @@ if sys.version_info >= (3, 12):
     ) -> _TemporaryFileWrapper[str]: ...
     @overload
     def NamedTemporaryFile(
-        mode: _BytesMode = "w+b",
+        mode: OpenBinaryMode = "w+b",
         buffering: int = -1,
         encoding: str | None = None,
         newline: str | None = None,
@@ -80,7 +88,7 @@ if sys.version_info >= (3, 12):
 elif sys.version_info >= (3, 8):
     @overload
     def NamedTemporaryFile(
-        mode: _StrMode,
+        mode: OpenTextMode,
         buffering: int = -1,
         encoding: str | None = None,
         newline: str | None = None,
@@ -93,7 +101,7 @@ elif sys.version_info >= (3, 8):
     ) -> _TemporaryFileWrapper[str]: ...
     @overload
     def NamedTemporaryFile(
-        mode: _BytesMode = "w+b",
+        mode: OpenBinaryMode = "w+b",
         buffering: int = -1,
         encoding: str | None = None,
         newline: str | None = None,
@@ -121,7 +129,7 @@ elif sys.version_info >= (3, 8):
 else:
     @overload
     def NamedTemporaryFile(
-        mode: _StrMode,
+        mode: OpenTextMode,
         buffering: int = -1,
         encoding: str | None = None,
         newline: str | None = None,
@@ -132,7 +140,7 @@ else:
     ) -> _TemporaryFileWrapper[str]: ...
     @overload
     def NamedTemporaryFile(
-        mode: _BytesMode = "w+b",
+        mode: OpenBinaryMode = "w+b",
         buffering: int = -1,
         encoding: str | None = None,
         newline: str | None = None,
@@ -156,10 +164,11 @@ else:
 if sys.platform == "win32":
     TemporaryFile = NamedTemporaryFile
 else:
+    # See the comments for builtins.open() for an explanation of the overloads.
     if sys.version_info >= (3, 8):
         @overload
         def TemporaryFile(
-            mode: _StrMode,
+            mode: OpenTextMode,
             buffering: int = -1,
             encoding: str | None = None,
             newline: str | None = None,
@@ -168,11 +177,11 @@ else:
             dir: GenericPath[AnyStr] | None = None,
             *,
             errors: str | None = None,
-        ) -> IO[str]: ...
+        ) -> io.TextIOWrapper: ...
         @overload
         def TemporaryFile(
-            mode: _BytesMode = "w+b",
-            buffering: int = -1,
+            mode: OpenBinaryMode,
+            buffering: Literal[0],
             encoding: str | None = None,
             newline: str | None = None,
             suffix: AnyStr | None = None,
@@ -180,7 +189,43 @@ else:
             dir: GenericPath[AnyStr] | None = None,
             *,
             errors: str | None = None,
-        ) -> IO[bytes]: ...
+        ) -> io.FileIO: ...
+        @overload
+        def TemporaryFile(
+            mode: OpenBinaryModeWriting,
+            buffering: Literal[-1, 1] = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+            *,
+            errors: str | None = None,
+        ) -> io.BufferedWriter: ...
+        @overload
+        def TemporaryFile(
+            mode: OpenBinaryModeReading,
+            buffering: Literal[-1, 1] = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+            *,
+            errors: str | None = None,
+        ) -> io.BufferedReader: ...
+        @overload
+        def TemporaryFile(
+            mode: OpenBinaryModeUpdating = "w+b",
+            buffering: Literal[-1, 1] = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+            *,
+            errors: str | None = None,
+        ) -> io.BufferedRandom: ...
         @overload
         def TemporaryFile(
             mode: str = "w+b",
@@ -196,33 +241,63 @@ else:
     else:
         @overload
         def TemporaryFile(
-            mode: _StrMode,
-            buffering: int = ...,
-            encoding: str | None = ...,
-            newline: str | None = ...,
-            suffix: AnyStr | None = ...,
-            prefix: AnyStr | None = ...,
-            dir: GenericPath[AnyStr] | None = ...,
-        ) -> IO[str]: ...
+            mode: OpenTextMode,
+            buffering: int = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+        ) -> io.TextIOWrapper: ...
         @overload
         def TemporaryFile(
-            mode: _BytesMode = ...,
-            buffering: int = ...,
-            encoding: str | None = ...,
-            newline: str | None = ...,
-            suffix: AnyStr | None = ...,
-            prefix: AnyStr | None = ...,
-            dir: GenericPath[AnyStr] | None = ...,
-        ) -> IO[bytes]: ...
+            mode: OpenBinaryMode,
+            buffering: Literal[0],
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+        ) -> io.FileIO: ...
         @overload
         def TemporaryFile(
-            mode: str = ...,
-            buffering: int = ...,
-            encoding: str | None = ...,
-            newline: str | None = ...,
-            suffix: AnyStr | None = ...,
-            prefix: AnyStr | None = ...,
-            dir: GenericPath[AnyStr] | None = ...,
+            mode: OpenBinaryModeUpdating = "w+b",
+            buffering: Literal[-1, 1] = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+        ) -> io.BufferedRandom: ...
+        @overload
+        def TemporaryFile(
+            mode: OpenBinaryModeWriting,
+            buffering: Literal[-1, 1] = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+        ) -> io.BufferedWriter: ...
+        @overload
+        def TemporaryFile(
+            mode: OpenBinaryModeReading,
+            buffering: Literal[-1, 1] = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
+        ) -> io.BufferedReader: ...
+        @overload
+        def TemporaryFile(
+            mode: str = "w+b",
+            buffering: int = -1,
+            encoding: str | None = None,
+            newline: str | None = None,
+            suffix: AnyStr | None = None,
+            prefix: AnyStr | None = None,
+            dir: GenericPath[AnyStr] | None = None,
         ) -> IO[Any]: ...
 
 class _TemporaryFileWrapper(Generic[AnyStr], IO[AnyStr]):
@@ -294,7 +369,7 @@ class SpooledTemporaryFile(IO[AnyStr], _SpooledTemporaryFileBase):
         def __init__(
             self: SpooledTemporaryFile[bytes],
             max_size: int = 0,
-            mode: _BytesMode = "w+b",
+            mode: OpenBinaryMode = "w+b",
             buffering: int = -1,
             encoding: str | None = None,
             newline: str | None = None,
@@ -308,7 +383,7 @@ class SpooledTemporaryFile(IO[AnyStr], _SpooledTemporaryFileBase):
         def __init__(
             self: SpooledTemporaryFile[str],
             max_size: int,
-            mode: _StrMode,
+            mode: OpenTextMode,
             buffering: int = -1,
             encoding: str | None = None,
             newline: str | None = None,
@@ -323,7 +398,7 @@ class SpooledTemporaryFile(IO[AnyStr], _SpooledTemporaryFileBase):
             self: SpooledTemporaryFile[str],
             max_size: int = 0,
             *,
-            mode: _StrMode,
+            mode: OpenTextMode,
             buffering: int = -1,
             encoding: str | None = None,
             newline: str | None = None,
@@ -367,7 +442,7 @@ class SpooledTemporaryFile(IO[AnyStr], _SpooledTemporaryFileBase):
         def __init__(
             self: SpooledTemporaryFile[bytes],
             max_size: int = 0,
-            mode: _BytesMode = "w+b",
+            mode: OpenBinaryMode = "w+b",
             buffering: int = -1,
             encoding: str | None = None,
             newline: str | None = None,
@@ -379,7 +454,7 @@ class SpooledTemporaryFile(IO[AnyStr], _SpooledTemporaryFileBase):
         def __init__(
             self: SpooledTemporaryFile[str],
             max_size: int,
-            mode: _StrMode,
+            mode: OpenTextMode,
             buffering: int = -1,
             encoding: str | None = None,
             newline: str | None = None,
@@ -392,7 +467,7 @@ class SpooledTemporaryFile(IO[AnyStr], _SpooledTemporaryFileBase):
             self: SpooledTemporaryFile[str],
             max_size: int = 0,
             *,
-            mode: _StrMode,
+            mode: OpenTextMode,
             buffering: int = -1,
             encoding: str | None = None,
             newline: str | None = None,