From cdb2dbfe92b95dcd19ccab1a1e9b8c39263c54b0 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Tue, 21 May 2019 02:36:58 -0700 Subject: [PATCH] [3.7] bpo-22865: Expand on documentation for the pty.spawn function (GH-11980) (GH-13455) (cherry picked from commit 522ccef8690970fc4f78f51a3adb995f2547871a) Co-authored-by: Geoff Shannon --- Doc/library/pty.rst | 29 ++++++++++++++++--- Misc/ACKS | 1 + .../2019-02-21-18-13-50.bpo-22865.6hg6J8.rst | 1 + 3 files changed, 27 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index 0ab766065d6..12268437d07 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -43,11 +43,32 @@ The :mod:`pty` module defines the following functions: Spawn a process, and connect its controlling terminal with the current process's standard io. This is often used to baffle programs which insist on - reading from the controlling terminal. + reading from the controlling terminal. It is expected that the process + spawned behind the pty will eventually terminate, and when it does *spawn* + will return. + + The functions *master_read* and *stdin_read* are passed a file descriptor + which they should read from, and they should always return a byte string. In + order to force spawn to return before the child process exits an + :exc:`OSError` should be thrown. + + The default implementation for both functions will read and return up to 1024 + bytes each time the function is called. The *master_read* callback is passed + the pseudoterminal’s master file descriptor to read output from the child + process, and *stdin_read* is passed file descriptor 0, to read from the + parent process's standard input. + + Returning an empty byte string from either callback is interpreted as an + end-of-file (EOF) condition, and that callback will not be called after + that. If *stdin_read* signals EOF the controlling terminal can no longer + communicate with the parent process OR the child process. Unless the child + process will quit without any input, *spawn* will then loop forever. If + *master_read* signals EOF the same behavior results (on linux at least). + + If both callbacks signal EOF then *spawn* will probably never return, unless + *select* throws an error on your platform when passed three empty lists. This + is a bug, documented in `issue 26228 `_. - The functions *master_read* and *stdin_read* should be functions which read from - a file descriptor. The defaults try to read 1024 bytes each time they are - called. .. versionchanged:: 3.4 :func:`spawn` now returns the status value from :func:`os.waitpid` diff --git a/Misc/ACKS b/Misc/ACKS index 5ca2ccf0b25..8468d5ffd5b 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1829,3 +1829,4 @@ Gennadiy Zlobin Doug Zongker Peter Åstrand Zheao Li +Geoff Shannon diff --git a/Misc/NEWS.d/next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst b/Misc/NEWS.d/next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst new file mode 100644 index 00000000000..67a4ed26bed --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst @@ -0,0 +1 @@ +Add detail to the documentation on the `pty.spawn` function. \ No newline at end of file