tarfile.open(): Handle all modes (#12181)

Author: srittau

stdlib/tarfile.pyi

@@ -103,12 +103,10 @@ PAX_NAME_FIELDS: set[str]
 
 ENCODING: str
 
-_FileCreationModes: TypeAlias = Literal["a", "w", "x"]
-
 @overload
 def open(
     name: StrOrBytesPath | None = None,
-    mode: str = "r",
+    mode: Literal["r", "r:*", "r:", "r:gz", "r:bz2", "r:xz"] = "r",
     fileobj: IO[bytes] | None = None,
     bufsize: int = 10240,
     *,
@@ -121,16 +119,124 @@ def open(
     pax_headers: Mapping[str, str] | None = ...,
     debug: int | None = ...,
     errorlevel: int | None = ...,
-    compresslevel: int | None = ...,
+) -> TarFile: ...
+@overload
+def open(
+    name: StrOrBytesPath | None,
+    mode: Literal["x", "x:", "a", "a:", "w", "w:"],
+    fileobj: _Fileobj | None = None,
+    bufsize: int = 10240,
+    *,
+    format: int | None = ...,
+    tarinfo: type[TarInfo] | None = ...,
+    dereference: bool | None = ...,
+    ignore_zeros: bool | None = ...,
+    encoding: str | None = ...,
+    errors: str = ...,
+    pax_headers: Mapping[str, str] | None = ...,
+    debug: int | None = ...,
+    errorlevel: int | None = ...,
+) -> TarFile: ...
+@overload
+def open(
+    name: StrOrBytesPath | None = None,
+    *,
+    mode: Literal["x", "x:", "a", "a:", "w", "w:"],
+    fileobj: _Fileobj | None = None,
+    bufsize: int = 10240,
+    format: int | None = ...,
+    tarinfo: type[TarInfo] | None = ...,
+    dereference: bool | None = ...,
+    ignore_zeros: bool | None = ...,
+    encoding: str | None = ...,
+    errors: str = ...,
+    pax_headers: Mapping[str, str] | None = ...,
+    debug: int | None = ...,
+    errorlevel: int | None = ...,
+) -> TarFile: ...
+@overload
+def open(
+    name: StrOrBytesPath | None,
+    mode: Literal["x:gz", "x:bz2", "w:gz", "w:bz2"],
+    fileobj: _Fileobj | None = None,
+    bufsize: int = 10240,
+    *,
+    format: int | None = ...,
+    tarinfo: type[TarInfo] | None = ...,
+    dereference: bool | None = ...,
+    ignore_zeros: bool | None = ...,
+    encoding: str | None = ...,
+    errors: str = ...,
+    pax_headers: Mapping[str, str] | None = ...,
+    debug: int | None = ...,
+    errorlevel: int | None = ...,
+    compresslevel: int = 9,
+) -> TarFile: ...
+@overload
+def open(
+    name: StrOrBytesPath | None = None,
+    *,
+    mode: Literal["x:gz", "x:bz2", "w:gz", "w:bz2"],
+    fileobj: _Fileobj | None = None,
+    bufsize: int = 10240,
+    format: int | None = ...,
+    tarinfo: type[TarInfo] | None = ...,
+    dereference: bool | None = ...,
+    ignore_zeros: bool | None = ...,
+    encoding: str | None = ...,
+    errors: str = ...,
+    pax_headers: Mapping[str, str] | None = ...,
+    debug: int | None = ...,
+    errorlevel: int | None = ...,
+    compresslevel: int = 9,
+) -> TarFile: ...
+@overload
+def open(
+    name: StrOrBytesPath | None,
+    mode: Literal["x:xz", "w:xz"],
+    fileobj: _Fileobj | None = None,
+    bufsize: int = 10240,
+    *,
+    format: int | None = ...,
+    tarinfo: type[TarInfo] | None = ...,
+    dereference: bool | None = ...,
+    ignore_zeros: bool | None = ...,
+    encoding: str | None = ...,
+    errors: str = ...,
+    pax_headers: Mapping[str, str] | None = ...,
+    debug: int | None = ...,
+    errorlevel: int | None = ...,
     preset: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] | None = ...,
 ) -> TarFile: ...
 @overload
 def open(
     name: StrOrBytesPath | None = None,
-    mode: _FileCreationModes = ...,
+    *,
+    mode: Literal["x:xz", "w:xz"],
     fileobj: _Fileobj | None = None,
     bufsize: int = 10240,
+    format: int | None = ...,
+    tarinfo: type[TarInfo] | None = ...,
+    dereference: bool | None = ...,
+    ignore_zeros: bool | None = ...,
+    encoding: str | None = ...,
+    errors: str = ...,
+    pax_headers: Mapping[str, str] | None = ...,
+    debug: int | None = ...,
+    errorlevel: int | None = ...,
+    preset: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] | None = ...,
+) -> TarFile: ...
+
+# TODO: Temporary fallback for modes containing pipe characters. These don't
+# work with mypy 1.10, but this should be fixed with mypy 1.11.
+# https://github.com/python/typeshed/issues/12182
+@overload
+def open(
+    name: StrOrBytesPath | None = None,
     *,
+    mode: str,
+    fileobj: IO[bytes] | None = None,
+    bufsize: int = 10240,
     format: int | None = ...,
     tarinfo: type[TarInfo] | None = ...,
     dereference: bool | None = ...,
@@ -140,7 +246,6 @@ def open(
     pax_headers: Mapping[str, str] | None = ...,
     debug: int | None = ...,
     errorlevel: int | None = ...,
-    compresslevel: int | None = ...,
     preset: int | None = ...,
 ) -> TarFile: ...