Skip to content

[3.7] bpo-22865: Expand on documentation for the pty.spawn function (GH-11980) #13455

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 21, 2019
Merged

[3.7] bpo-22865: Expand on documentation for the pty.spawn function (GH-11980) #13455

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 25 additions & 4 deletions Doc/library/pty.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
1 change: 1 addition & 0 deletions Misc/ACKS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1829,3 +1829,4 @@ Gennadiy Zlobin
Doug Zongker
Peter Åstrand
Zheao Li
Geoff Shannon
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/Documentation/2019-02-21-18-13-50.bpo-22865.6hg6J8.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add detail to the documentation on the `pty.spawn` function.