Add new-in-3.9 parameters to subprocess.{run, call, check_call, check_output} (#8071)

2025-12-07 20:54:28 +08:00 · 2022-06-21 12:35:50 +01:00
parent 678c231e5b
commit f9e24680c3
1 changed files with 438 additions and 4 deletions
--- a/stdlib/subprocess.pyi
+++ b/stdlib/subprocess.pyi
@@ -101,7 +101,203 @@ class CompletedProcess(Generic[_T]):
    if sys.version_info >= (3, 9):
        def __class_getitem__(cls, item: Any) -> GenericAlias: ...

-if sys.version_info >= (3, 7):
+if sys.version_info >= (3, 9):
+    # 3.9 adds arguments "user", "group", "extra_groups" and "umask"
+    @overload
+    def run(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        capture_output: bool = ...,
+        check: bool = ...,
+        encoding: str | None = ...,
+        errors: str | None = ...,
+        input: str | None = ...,
+        text: Literal[True],
+        timeout: float | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> CompletedProcess[str]: ...
+    @overload
+    def run(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        capture_output: bool = ...,
+        check: bool = ...,
+        encoding: str,
+        errors: str | None = ...,
+        input: str | None = ...,
+        text: bool | None = ...,
+        timeout: float | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> CompletedProcess[str]: ...
+    @overload
+    def run(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        capture_output: bool = ...,
+        check: bool = ...,
+        encoding: str | None = ...,
+        errors: str,
+        input: str | None = ...,
+        text: bool | None = ...,
+        timeout: float | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> CompletedProcess[str]: ...
+    @overload
+    def run(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        *,
+        universal_newlines: Literal[True],
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        # where the *real* keyword only args start
+        capture_output: bool = ...,
+        check: bool = ...,
+        encoding: str | None = ...,
+        errors: str | None = ...,
+        input: str | None = ...,
+        text: bool | None = ...,
+        timeout: float | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> CompletedProcess[str]: ...
+    @overload
+    def run(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: Literal[False] = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        capture_output: bool = ...,
+        check: bool = ...,
+        encoding: None = ...,
+        errors: None = ...,
+        input: bytes | None = ...,
+        text: Literal[None, False] = ...,
+        timeout: float | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> CompletedProcess[bytes]: ...
+    @overload
+    def run(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        capture_output: bool = ...,
+        check: bool = ...,
+        encoding: str | None = ...,
+        errors: str | None = ...,
+        input: _TXT | None = ...,
+        text: bool | None = ...,
+        timeout: float | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> CompletedProcess[Any]: ...
+
+elif sys.version_info >= (3, 7):
    # Nearly the same args as for 3.6, except for capture_output and text
    @overload
    def run(
@@ -408,7 +604,37 @@ else:
    ) -> CompletedProcess[Any]: ...

 # Same args as Popen.__init__
-if sys.version_info >= (3, 7):
+if sys.version_info >= (3, 9):
+    # 3.9 adds arguments "user", "group", "extra_groups" and "umask"
+    def call(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        timeout: float | None = ...,
+        text: bool | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> int: ...
+
+elif sys.version_info >= (3, 7):
+    # 3.7 adds the "text" argument
    def call(
        args: _CMD,
        bufsize: int = ...,
@@ -456,7 +682,37 @@ else:
    ) -> int: ...

 # Same args as Popen.__init__
-if sys.version_info >= (3, 7):
+if sys.version_info >= (3, 9):
+    # 3.9 adds arguments "user", "group", "extra_groups" and "umask"
+    def check_call(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath = ...,
+        stdin: _FILE = ...,
+        stdout: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        timeout: float | None = ...,
+        *,
+        text: bool | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> int: ...
+
+elif sys.version_info >= (3, 7):
+    # 3.7 adds the "text" argument
    def check_call(
        args: _CMD,
        bufsize: int = ...,
@@ -502,7 +758,185 @@ else:
        timeout: float | None = ...,
    ) -> int: ...

-if sys.version_info >= (3, 7):
+if sys.version_info >= (3, 9):
+    # 3.9 adds arguments "user", "group", "extra_groups" and "umask"
+    @overload
+    def check_output(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        timeout: float | None = ...,
+        input: _TXT | None = ...,
+        encoding: str | None = ...,
+        errors: str | None = ...,
+        text: Literal[True],
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> str: ...
+    @overload
+    def check_output(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        timeout: float | None = ...,
+        input: _TXT | None = ...,
+        encoding: str,
+        errors: str | None = ...,
+        text: bool | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> str: ...
+    @overload
+    def check_output(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        timeout: float | None = ...,
+        input: _TXT | None = ...,
+        encoding: str | None = ...,
+        errors: str,
+        text: bool | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> str: ...
+    @overload
+    def check_output(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        *,
+        universal_newlines: Literal[True],
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        # where the real keyword only ones start
+        timeout: float | None = ...,
+        input: _TXT | None = ...,
+        encoding: str | None = ...,
+        errors: str | None = ...,
+        text: bool | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> str: ...
+    @overload
+    def check_output(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: Literal[False] = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        timeout: float | None = ...,
+        input: _TXT | None = ...,
+        encoding: None = ...,
+        errors: None = ...,
+        text: Literal[None, False] = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> bytes: ...
+    @overload
+    def check_output(
+        args: _CMD,
+        bufsize: int = ...,
+        executable: StrOrBytesPath | None = ...,
+        stdin: _FILE = ...,
+        stderr: _FILE = ...,
+        preexec_fn: Callable[[], Any] | None = ...,
+        close_fds: bool = ...,
+        shell: bool = ...,
+        cwd: StrOrBytesPath | None = ...,
+        env: _ENV | None = ...,
+        universal_newlines: bool = ...,
+        startupinfo: Any = ...,
+        creationflags: int = ...,
+        restore_signals: bool = ...,
+        start_new_session: bool = ...,
+        pass_fds: Any = ...,
+        *,
+        timeout: float | None = ...,
+        input: _TXT | None = ...,
+        encoding: str | None = ...,
+        errors: str | None = ...,
+        text: bool | None = ...,
+        user: str | int | None = ...,
+        group: str | int | None = ...,
+        extra_groups: Iterable[str | int] | None = ...,
+        umask: int = ...,
+    ) -> Any: ...  # morally: -> _TXT
+
+elif sys.version_info >= (3, 7):
    # 3.7 added text
    @overload
    def check_output(