Skip to content

Commit eedc197

Browse files
committed
Add more detail about why and how return empty bytes is bad.
1 parent 81b1a22 commit eedc197

File tree

1 file changed

+12
-7
lines changed

1 file changed

+12
-7
lines changed

Doc/library/pty.rst

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -51,13 +51,18 @@ The :mod:`pty` module defines the following functions:
5151
which they should read from, and they should always return a byte
5252
string. Returning an empty byte string from either callback is interpreted as
5353
an end-of-file (EOF) condition, and that callback will not be called after
54-
that.
55-
56-
In general, manually signaling EOF from one of the read callback will not
57-
behave well. If *stdin_read* returns EOF the controlling terminal can no
58-
longer communicate with.
59-
60-
If both callbacks signal EOF then *spawn* will block indefinitely. This
54+
that. This is not recommended. Instead, the graceful way to force the *spawn*
55+
to return before the child process exits is to raise *OsError*.
56+
57+
In general, manually signaling EOF without receiving it from the underlying
58+
file descriptor from one or both of the read callbacks will not behave
59+
well. If *stdin_read* signals EOF the controlling terminal can no longer
60+
communicate with the parent process OR the child process. Unless the child
61+
process will quit without any input, *spawn* will then loop forever. If
62+
*master_read* signals EOF the same behavior results (on linux at least).
63+
64+
If both callbacks signal EOF then *spawn* will probably never return, unless
65+
*select* throws an error on your platform when passed three empty lists. This
6166
is a bug, documented in `issue 26228 <https://bugs.python.org/issue26228>`_.
6267

6368
The default implementation for both functions will read and return up to 1024

0 commit comments

Comments
 (0)