From c80be7bae808d808174727af5721d67408d26da1 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Fri, 22 Feb 2019 02:39:09 -0800 Subject: [PATCH 1/7] Expand on documentation for the pty.spawn function --- Doc/library/pty.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index 0ab766065d6e81..4357778b933573 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -45,9 +45,12 @@ The :mod:`pty` module defines the following functions: process's standard io. This is often used to baffle programs which insist on reading from the controlling terminal. - 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. + The functions *master_read* and *stdin_read* are passed a file + descriptor which they should read from, and should return a byte + string. The default implementation for both functions will read up + to 1024 bytes each time the function is called. Returning an empty + byte string is interpreted as an end of file (EOF) condition, and + that *_read* function will no longer be called. .. versionchanged:: 3.4 :func:`spawn` now returns the status value from :func:`os.waitpid` From 8c9a632f03cf0f0ed47d77adc025f17e965b65dd Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" Date: Thu, 21 Feb 2019 18:13:51 +0000 Subject: [PATCH 2/7] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst 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 00000000000000..67a4ed26bede37 --- /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 From 81b1a2296561278f457b671095734ce6cd90f34b Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Mon, 25 Feb 2019 20:43:38 -0800 Subject: [PATCH 3/7] Rewrite pty.spawn docs again --- Doc/library/pty.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index 4357778b933573..bfa921cf10d714 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -43,14 +43,28 @@ 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. - - The functions *master_read* and *stdin_read* are passed a file - descriptor which they should read from, and should return a byte - string. The default implementation for both functions will read up - to 1024 bytes each time the function is called. Returning an empty - byte string is interpreted as an end of file (EOF) condition, and - that *_read* function will no longer be called. + 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. 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. + + In general, manually signaling EOF from one of the read callback will not + behave well. If *stdin_read* returns EOF the controlling terminal can no + longer communicate with. + + If both callbacks signal EOF then *spawn* will block indefinitely. This + is a bug, documented in `issue 26228 `_. + + The default implementation for both functions will read and return up to 1024 + bytes each time the function is called. *Master_read* 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. .. versionchanged:: 3.4 :func:`spawn` now returns the status value from :func:`os.waitpid` From eedc197361d0214e912ca6fad33dd5a80ce72437 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Mon, 25 Feb 2019 21:18:11 -0800 Subject: [PATCH 4/7] Add more detail about why and how return empty bytes is bad. --- Doc/library/pty.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index bfa921cf10d714..bceb89420701c8 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -51,13 +51,18 @@ The :mod:`pty` module defines the following functions: which they should read from, and they should always return a byte string. 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. - - In general, manually signaling EOF from one of the read callback will not - behave well. If *stdin_read* returns EOF the controlling terminal can no - longer communicate with. - - If both callbacks signal EOF then *spawn* will block indefinitely. This + that. This is not recommended. Instead, the graceful way to force the *spawn* + to return before the child process exits is to raise *OsError*. + + In general, manually signaling EOF without receiving it from the underlying + file descriptor from one or both of the read callbacks will not behave + well. 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 default implementation for both functions will read and return up to 1024 From fdcf2af5ed91b7d7e4d66e691d8a8f72ab86215f Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Tue, 26 Feb 2019 00:44:08 -0800 Subject: [PATCH 5/7] Remove value judgements --- Doc/library/pty.rst | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index bceb89420701c8..e9a2d45b70d29f 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -48,15 +48,19 @@ The :mod:`pty` module defines the following functions: 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. 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. This is not recommended. Instead, the graceful way to force the *spawn* - to return before the child process exits is to raise *OsError*. - - In general, manually signaling EOF without receiving it from the underlying - file descriptor from one or both of the read callbacks will not behave - well. If *stdin_read* signals EOF the controlling terminal can no longer + 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 *OsError* + should be thrown. + + The default implementation for both functions will read and return up to 1024 + bytes each time the function is called. *Master_read* 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). @@ -65,11 +69,6 @@ The :mod:`pty` module defines the following functions: *select* throws an error on your platform when passed three empty lists. This is a bug, documented in `issue 26228 `_. - The default implementation for both functions will read and return up to 1024 - bytes each time the function is called. *Master_read* 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. .. versionchanged:: 3.4 :func:`spawn` now returns the status value from :func:`os.waitpid` From 2e8cb2b7818ef24a8f273d6a94618453583cf487 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Tue, 26 Feb 2019 00:47:14 -0800 Subject: [PATCH 6/7] Add name to ACKS --- Misc/ACKS | 1 + 1 file changed, 1 insertion(+) diff --git a/Misc/ACKS b/Misc/ACKS index 8b3232551e1b09..c50d49dba342d5 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1858,3 +1858,4 @@ Zheao Li Carsten Klein Diego Rojas Edison Abahurire +Geoff Shannon From 3f67273b72e4dcb6b90247b276d7972c18a2d55f Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Tue, 26 Feb 2019 03:52:56 -0800 Subject: [PATCH 7/7] Fix markup/formatting feedback --- Doc/library/pty.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index e9a2d45b70d29f..12268437d07e98 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -49,12 +49,12 @@ The :mod:`pty` module defines the following functions: 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 *OsError* - should be thrown. + 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. *Master_read* is passed the - pseudoterminal’s master file descriptor to read output from the child + 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.