From a5d4657b46787716c73426820e73d7ad8fd61896 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Mon, 20 Apr 2026 12:23:41 +0200 Subject: [PATCH] [subprocess] Consistency between `text` and `universal_newlines` `text` can't be `False` if `universal_newlines` is `True`. Also document the overloads. --- stdlib/subprocess.pyi | 144 +++++++++++++++++++++--------------------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/stdlib/subprocess.pyi b/stdlib/subprocess.pyi index f6d7b88193ec..189da8d3aab6 100644 --- a/stdlib/subprocess.pyi +++ b/stdlib/subprocess.pyi @@ -88,7 +88,7 @@ class CompletedProcess(Generic[_T]): if sys.version_info >= (3, 11): # 3.11 adds "process_group" argument - @overload + @overload # text is True def run( args: _CMD, bufsize: int = -1, @@ -101,7 +101,7 @@ if sys.version_info >= (3, 11): shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any = None, creationflags: int = 0, restore_signals: bool = True, @@ -122,7 +122,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> CompletedProcess[str]: ... - @overload + @overload # encoding is str def run( args: _CMD, bufsize: int = -1, @@ -156,7 +156,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> CompletedProcess[str]: ... - @overload + @overload # errors is str def run( args: _CMD, bufsize: int = -1, @@ -190,7 +190,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> CompletedProcess[str]: ... - @overload + @overload # universal_newlines is True def run( args: _CMD, bufsize: int = -1, @@ -216,7 +216,7 @@ if sys.version_info >= (3, 11): encoding: str | None = None, errors: str | None = None, input: str | None = None, - text: bool | None = None, + text: Literal[True] | None = None, timeout: float | None = None, user: str | int | None = None, group: str | int | None = None, @@ -225,7 +225,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> CompletedProcess[str]: ... - @overload + @overload # universal_newlines and text are False, None, or missing def run( args: _CMD, bufsize: int = -1, @@ -259,7 +259,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> CompletedProcess[bytes]: ... - @overload + @overload # fallback def run( args: _CMD, bufsize: int = -1, @@ -296,7 +296,7 @@ if sys.version_info >= (3, 11): elif sys.version_info >= (3, 10): # 3.10 adds "pipesize" argument - @overload + @overload # text is True def run( args: _CMD, bufsize: int = -1, @@ -309,7 +309,7 @@ elif sys.version_info >= (3, 10): shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any = None, creationflags: int = 0, restore_signals: bool = True, @@ -329,7 +329,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # encoding is str def run( args: _CMD, bufsize: int = -1, @@ -362,7 +362,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # errors is str def run( args: _CMD, bufsize: int = -1, @@ -395,7 +395,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # universal_newlines is True def run( args: _CMD, bufsize: int = -1, @@ -421,7 +421,7 @@ elif sys.version_info >= (3, 10): encoding: str | None = None, errors: str | None = None, input: str | None = None, - text: bool | None = None, + text: Literal[True] | None = None, timeout: float | None = None, user: str | int | None = None, group: str | int | None = None, @@ -429,7 +429,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # universal_newlines and text are False, None, or missing def run( args: _CMD, bufsize: int = -1, @@ -462,7 +462,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> CompletedProcess[bytes]: ... - @overload + @overload # fallback def run( args: _CMD, bufsize: int = -1, @@ -497,7 +497,7 @@ elif sys.version_info >= (3, 10): ) -> CompletedProcess[Any]: ... else: - @overload + @overload # text is True def run( args: _CMD, bufsize: int = -1, @@ -510,7 +510,7 @@ else: shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any = None, creationflags: int = 0, restore_signals: bool = True, @@ -529,7 +529,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # encoding is str def run( args: _CMD, bufsize: int = -1, @@ -561,7 +561,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # errors is str def run( args: _CMD, bufsize: int = -1, @@ -593,7 +593,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # universal_newlines is True def run( args: _CMD, bufsize: int = -1, @@ -619,14 +619,14 @@ else: encoding: str | None = None, errors: str | None = None, input: str | None = None, - text: bool | None = None, + text: Literal[True] | None = None, timeout: float | None = None, user: str | int | None = None, group: str | int | None = None, extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> CompletedProcess[str]: ... - @overload + @overload # universal_newlines and text are False, None, or missing def run( args: _CMD, bufsize: int = -1, @@ -658,7 +658,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> CompletedProcess[bytes]: ... - @overload + @overload # fallback def run( args: _CMD, bufsize: int = -1, @@ -879,7 +879,7 @@ else: if sys.version_info >= (3, 11): # 3.11 adds "process_group" argument - @overload + @overload # text is True def check_output( args: _CMD, bufsize: int = -1, @@ -891,7 +891,7 @@ if sys.version_info >= (3, 11): shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any = None, creationflags: int = 0, restore_signals: bool = True, @@ -910,7 +910,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> str: ... - @overload + @overload # encoding is str def check_output( args: _CMD, bufsize: int = -1, @@ -941,7 +941,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> str: ... - @overload + @overload # errors is str def check_output( args: _CMD, bufsize: int = -1, @@ -972,7 +972,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> str: ... - @overload + @overload # universal_newlines is True def check_output( args: _CMD, bufsize: int = -1, @@ -996,7 +996,7 @@ if sys.version_info >= (3, 11): input: _InputString | None = None, encoding: str | None = None, errors: str | None = None, - text: bool | None = None, + text: Literal[True] | None = None, user: str | int | None = None, group: str | int | None = None, extra_groups: Iterable[str | int] | None = None, @@ -1004,7 +1004,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> str: ... - @overload + @overload # universal_newlines and text are False, None, or missing def check_output( args: _CMD, bufsize: int = -1, @@ -1035,7 +1035,7 @@ if sys.version_info >= (3, 11): pipesize: int = -1, process_group: int | None = None, ) -> bytes: ... - @overload + @overload # fallback def check_output( args: _CMD, bufsize: int = -1, @@ -1069,7 +1069,7 @@ if sys.version_info >= (3, 11): elif sys.version_info >= (3, 10): # 3.10 adds "pipesize" argument - @overload + @overload # text is True def check_output( args: _CMD, bufsize: int = -1, @@ -1081,7 +1081,7 @@ elif sys.version_info >= (3, 10): shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any = None, creationflags: int = 0, restore_signals: bool = True, @@ -1099,7 +1099,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> str: ... - @overload + @overload # encoding is str def check_output( args: _CMD, bufsize: int = -1, @@ -1129,7 +1129,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> str: ... - @overload + @overload # errors is str def check_output( args: _CMD, bufsize: int = -1, @@ -1159,7 +1159,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> str: ... - @overload + @overload # universal_newlines is True def check_output( args: _CMD, bufsize: int = -1, @@ -1183,14 +1183,14 @@ elif sys.version_info >= (3, 10): input: _InputString | None = None, encoding: str | None = None, errors: str | None = None, - text: bool | None = None, + text: Literal[True] | None = None, user: str | int | None = None, group: str | int | None = None, extra_groups: Iterable[str | int] | None = None, umask: int = -1, pipesize: int = -1, ) -> str: ... - @overload + @overload # universal_newlines and text are False, None, or missing def check_output( args: _CMD, bufsize: int = -1, @@ -1220,7 +1220,7 @@ elif sys.version_info >= (3, 10): umask: int = -1, pipesize: int = -1, ) -> bytes: ... - @overload + @overload # fallback def check_output( args: _CMD, bufsize: int = -1, @@ -1252,7 +1252,7 @@ elif sys.version_info >= (3, 10): ) -> Any: ... # morally: -> str | bytes else: - @overload + @overload # text is True def check_output( args: _CMD, bufsize: int = -1, @@ -1264,7 +1264,7 @@ else: shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any = None, creationflags: int = 0, restore_signals: bool = True, @@ -1281,7 +1281,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> str: ... - @overload + @overload # encoding is str def check_output( args: _CMD, bufsize: int = -1, @@ -1310,7 +1310,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> str: ... - @overload + @overload # errors is str def check_output( args: _CMD, bufsize: int = -1, @@ -1339,7 +1339,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> str: ... - @overload + @overload # universal_newlines is True def check_output( args: _CMD, bufsize: int = -1, @@ -1363,13 +1363,13 @@ else: input: _InputString | None = None, encoding: str | None = None, errors: str | None = None, - text: bool | None = None, + text: Literal[True] | None = None, user: str | int | None = None, group: str | int | None = None, extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> str: ... - @overload + @overload # universal_newlines and text are False, None, or missing def check_output( args: _CMD, bufsize: int = -1, @@ -1398,7 +1398,7 @@ else: extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> bytes: ... - @overload + @overload # fallback def check_output( args: _CMD, bufsize: int = -1, @@ -1462,16 +1462,16 @@ class CalledProcessError(SubprocessError): class Popen(Generic[AnyStr]): args: _CMD - stdin: IO[AnyStr] | None - stdout: IO[AnyStr] | None - stderr: IO[AnyStr] | None + stdin: IO[Any] | None + stdout: IO[Any] | None + stderr: IO[Any] | None pid: int returncode: int | MaybeNone universal_newlines: bool if sys.version_info >= (3, 11): # process_group is added in 3.11 - @overload + @overload # encoding is str def __init__( self: Popen[str], args: _CMD, @@ -1502,7 +1502,7 @@ class Popen(Generic[AnyStr]): pipesize: int = -1, process_group: int | None = None, ) -> None: ... - @overload + @overload # errors is str def __init__( self: Popen[str], args: _CMD, @@ -1533,7 +1533,7 @@ class Popen(Generic[AnyStr]): pipesize: int = -1, process_group: int | None = None, ) -> None: ... - @overload + @overload # universal_newlines is True def __init__( self: Popen[str], args: _CMD, @@ -1565,7 +1565,7 @@ class Popen(Generic[AnyStr]): pipesize: int = -1, process_group: int | None = None, ) -> None: ... - @overload + @overload # text is True def __init__( self: Popen[str], args: _CMD, @@ -1579,7 +1579,7 @@ class Popen(Generic[AnyStr]): shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any | None = None, creationflags: int = 0, restore_signals: bool = True, @@ -1596,7 +1596,7 @@ class Popen(Generic[AnyStr]): pipesize: int = -1, process_group: int | None = None, ) -> None: ... - @overload + @overload # universal_newlines and text are False, None, or missing def __init__( self: Popen[bytes], args: _CMD, @@ -1627,7 +1627,7 @@ class Popen(Generic[AnyStr]): pipesize: int = -1, process_group: int | None = None, ) -> None: ... - @overload + @overload # fallback def __init__( self: Popen[Any], args: _CMD, @@ -1660,7 +1660,7 @@ class Popen(Generic[AnyStr]): ) -> None: ... elif sys.version_info >= (3, 10): # pipesize is added in 3.10 - @overload + @overload # encoding is str def __init__( self: Popen[str], args: _CMD, @@ -1690,7 +1690,7 @@ class Popen(Generic[AnyStr]): umask: int = -1, pipesize: int = -1, ) -> None: ... - @overload + @overload # errors is str def __init__( self: Popen[str], args: _CMD, @@ -1720,7 +1720,7 @@ class Popen(Generic[AnyStr]): umask: int = -1, pipesize: int = -1, ) -> None: ... - @overload + @overload # universal_newlines is True def __init__( self: Popen[str], args: _CMD, @@ -1751,7 +1751,7 @@ class Popen(Generic[AnyStr]): umask: int = -1, pipesize: int = -1, ) -> None: ... - @overload + @overload # text is True def __init__( self: Popen[str], args: _CMD, @@ -1765,7 +1765,7 @@ class Popen(Generic[AnyStr]): shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any | None = None, creationflags: int = 0, restore_signals: bool = True, @@ -1781,7 +1781,7 @@ class Popen(Generic[AnyStr]): umask: int = -1, pipesize: int = -1, ) -> None: ... - @overload + @overload # universal_newlines and text are False, None, or missing def __init__( self: Popen[bytes], args: _CMD, @@ -1811,7 +1811,7 @@ class Popen(Generic[AnyStr]): umask: int = -1, pipesize: int = -1, ) -> None: ... - @overload + @overload # fallback def __init__( self: Popen[Any], args: _CMD, @@ -1842,7 +1842,7 @@ class Popen(Generic[AnyStr]): pipesize: int = -1, ) -> None: ... else: - @overload + @overload # encoding is str def __init__( self: Popen[str], args: _CMD, @@ -1871,7 +1871,7 @@ class Popen(Generic[AnyStr]): extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> None: ... - @overload + @overload # errors is str def __init__( self: Popen[str], args: _CMD, @@ -1900,7 +1900,7 @@ class Popen(Generic[AnyStr]): extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> None: ... - @overload + @overload # universal_newlines is True def __init__( self: Popen[str], args: _CMD, @@ -1930,7 +1930,7 @@ class Popen(Generic[AnyStr]): extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> None: ... - @overload + @overload # text is True def __init__( self: Popen[str], args: _CMD, @@ -1944,7 +1944,7 @@ class Popen(Generic[AnyStr]): shell: bool = False, cwd: StrOrBytesPath | None = None, env: _ENV | None = None, - universal_newlines: bool | None = None, + universal_newlines: Literal[True] | None = None, startupinfo: Any | None = None, creationflags: int = 0, restore_signals: bool = True, @@ -1959,7 +1959,7 @@ class Popen(Generic[AnyStr]): extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> None: ... - @overload + @overload # universal_newlines and text are False, None, or missing def __init__( self: Popen[bytes], args: _CMD, @@ -1988,7 +1988,7 @@ class Popen(Generic[AnyStr]): extra_groups: Iterable[str | int] | None = None, umask: int = -1, ) -> None: ... - @overload + @overload # fallback def __init__( self: Popen[Any], args: _CMD,