[Python-checkins] bpo-22865: Expand on documentation for the pty.spawn function (GH-11980)
Victor Stinner
webhook-mailer at python.org
Mon May 20 11:06:33 EDT 2019
https://github.com/python/cpython/commit/522ccef8690970fc4f78f51a3adb995f2547871a
commit: 522ccef8690970fc4f78f51a3adb995f2547871a
branch: master
author: Geoff Shannon <earthlingzephyr at gmail.com>
committer: Victor Stinner <vstinner at redhat.com>
date: 2019-05-20T17:06:16+02:00
summary:
bpo-22865: Expand on documentation for the pty.spawn function (GH-11980)
files:
A Misc/NEWS.d/next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst
M Doc/library/pty.rst
M Misc/ACKS
diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst
index 0ab766065d6e..12268437d07e 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 <https://bugs.python.org/issue26228>`_.
- 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 77f19909b300..f9d01d008679 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1859,3 +1859,4 @@ Zheao Li
Carsten Klein
Diego Rojas
Edison Abahurire
+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 000000000000..67a4ed26bede
--- /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
More information about the Python-checkins
mailing list