diff --git a/stubs/pexpect/@tests/test_cases/check_run.py b/stubs/pexpect/@tests/test_cases/check_run.py new file mode 100644 index 000000000000..5cadae74d09e --- /dev/null +++ b/stubs/pexpect/@tests/test_cases/check_run.py @@ -0,0 +1,31 @@ +from __future__ import annotations + +import sys +from typing_extensions import assert_type + +import pexpect + +if sys.platform != "win32": + # run() returns bytes unless an encoding is passed to it. + assert_type(pexpect.run("ls"), bytes) + assert_type(pexpect.run("ls", encoding="utf-8"), str) + assert_type(pexpect.run("ls", timeout=None, withexitstatus=False), bytes) + + # With withexitstatus, run() returns the exit status, which is None + # if the child was killed by a signal. + assert_type(pexpect.run("ls", withexitstatus=True), tuple[bytes, int | None]) + assert_type(pexpect.run("ls", withexitstatus=True, encoding="utf-8"), tuple[str, int | None]) + + flag: bool = bool(sys.argv) + assert_type(pexpect.run("ls", withexitstatus=flag), bytes | tuple[bytes, int | None]) + + # Responses may be strings, bytes or callbacks. + pexpect.run("ls", events={"Password:": "secret\n", rb"\?": b"y\n", "done": lambda _: True}) + pexpect.run("ls", events=[("Password:", "secret\n")]) + + assert_type(pexpect.runu("ls"), str) + assert_type(pexpect.runu("ls", withexitstatus=True), tuple[str, int | None]) + + # wait() returns None if the child was killed by a signal. + child: pexpect.spawn[bytes] = pexpect.spawn("ls") + assert_type(child.wait(), int | None) diff --git a/stubs/pexpect/pexpect/pty_spawn.pyi b/stubs/pexpect/pexpect/pty_spawn.pyi index 879915556e35..29af311c2270 100644 --- a/stubs/pexpect/pexpect/pty_spawn.pyi +++ b/stubs/pexpect/pexpect/pty_spawn.pyi @@ -65,7 +65,7 @@ class spawn(SpawnBase[AnyStr]): exitstatus: int | None signalstatus: int | None terminated: bool - def wait(self) -> int: ... + def wait(self) -> int | None: ... def isalive(self) -> bool: ... def kill(self, sig: int) -> None: ... def getwinsize(self) -> tuple[int, int]: ... diff --git a/stubs/pexpect/pexpect/run.pyi b/stubs/pexpect/pexpect/run.pyi index b3b0a0b546ad..c859fb6f2a26 100644 --- a/stubs/pexpect/pexpect/run.pyi +++ b/stubs/pexpect/pexpect/run.pyi @@ -1,28 +1,135 @@ from _typeshed import FileDescriptorOrPath -from collections.abc import Mapping -from typing import AnyStr +from collections.abc import Callable, Mapping +from typing import Any, Literal, TypeAlias, overload from .spawnbase import _InputRePattern, _Logfile +# Values are sent to the child if they are strings, and called with the +# caller's locals() otherwise. +_Response: TypeAlias = str | bytes | Callable[[dict[str, Any]], object] +_Events: TypeAlias = list[tuple[_InputRePattern, _Response]] | dict[_InputRePattern, _Response] + +# The output is bytes unless "encoding" (forwarded to pexpect.spawn) is given, in which case +# it is str. The exit status is None if the child was terminated by a signal. +@overload +def run( + command: str, + timeout: float | None = 30, + withexitstatus: Literal[False] = False, + events: _Events | None = None, + extra_args: None = None, + logfile: _Logfile | None = None, + cwd: FileDescriptorOrPath | None = None, + env: Mapping[str, str] | None = None, + *, + encoding: None = None, + **kwargs: Any, +) -> bytes: ... +@overload +def run( + command: str, + timeout: float | None = 30, + withexitstatus: Literal[True] = ..., + events: _Events | None = None, + extra_args: None = None, + logfile: _Logfile | None = None, + cwd: FileDescriptorOrPath | None = None, + env: Mapping[str, str] | None = None, + *, + encoding: None = None, + **kwargs: Any, +) -> tuple[bytes, int | None]: ... +@overload +def run( + command: str, + timeout: float | None = 30, + withexitstatus: Literal[False] = False, + events: _Events | None = None, + extra_args: None = None, + logfile: _Logfile | None = None, + cwd: FileDescriptorOrPath | None = None, + env: Mapping[str, str] | None = None, + *, + encoding: str, + **kwargs: Any, +) -> str: ... +@overload +def run( + command: str, + timeout: float | None = 30, + withexitstatus: Literal[True] = ..., + events: _Events | None = None, + extra_args: None = None, + logfile: _Logfile | None = None, + cwd: FileDescriptorOrPath | None = None, + env: Mapping[str, str] | None = None, + *, + encoding: str, + **kwargs: Any, +) -> tuple[str, int | None]: ... +@overload def run( command: str, timeout: float | None = 30, withexitstatus: bool = False, - events: list[tuple[_InputRePattern, AnyStr]] | dict[_InputRePattern, AnyStr] | None = None, + events: _Events | None = None, + extra_args: None = None, + logfile: _Logfile | None = None, + cwd: FileDescriptorOrPath | None = None, + env: Mapping[str, str] | None = None, + *, + encoding: None = None, + **kwargs: Any, +) -> bytes | tuple[bytes, int | None]: ... +@overload +def run( + command: str, + timeout: float | None = 30, + withexitstatus: bool = False, + events: _Events | None = None, + extra_args: None = None, + logfile: _Logfile | None = None, + cwd: FileDescriptorOrPath | None = None, + env: Mapping[str, str] | None = None, + *, + encoding: str, + **kwargs: Any, +) -> str | tuple[str, int | None]: ... + +# Deprecated: encoding defaults to "utf-8". +@overload +def runu( + command: str, + timeout: float | None = 30, + withexitstatus: Literal[False] = False, + events: _Events | None = None, + extra_args: None = None, + logfile: _Logfile | None = None, + cwd: FileDescriptorOrPath | None = None, + env: Mapping[str, str] | None = None, + **kwargs: Any, +) -> str: ... +@overload +def runu( + command: str, + timeout: float | None = 30, + withexitstatus: Literal[True] = ..., + events: _Events | None = None, extra_args: None = None, logfile: _Logfile | None = None, cwd: FileDescriptorOrPath | None = None, env: Mapping[str, str] | None = None, - **kwargs, -) -> AnyStr | tuple[AnyStr, int]: ... + **kwargs: Any, +) -> tuple[str, int | None]: ... +@overload def runu( command: str, timeout: float | None = 30, withexitstatus: bool = False, - events: list[tuple[_InputRePattern, AnyStr]] | dict[_InputRePattern, AnyStr] | None = None, + events: _Events | None = None, extra_args: None = None, logfile: _Logfile | None = None, cwd: FileDescriptorOrPath | None = None, env: Mapping[str, str] | None = None, - **kwargs, -) -> AnyStr | tuple[AnyStr, int]: ... + **kwargs: Any, +) -> str | tuple[str, int | None]: ...