| 1 |
:mod:`!pty` --- Pseudo-terminal utilities |
| 2 |
========================================= |
| 3 |
|
| 4 |
.. module:: pty |
| 5 |
:synopsis: Pseudo-Terminal Handling for Unix. |
| 6 |
|
| 7 |
.. moduleauthor:: Steen Lumholt |
| 8 |
.. sectionauthor:: Moshe Zadka <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/pty.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 14 |
The :mod:`!pty` module defines operations for handling the pseudo-terminal |
| 15 |
concept: starting another process and being able to write to and read from its |
| 16 |
controlling terminal programmatically. |
| 17 |
|
| 18 |
.. availability:: Unix. |
| 19 |
|
| 20 |
Pseudo-terminal handling is highly platform dependent. This code is mainly |
| 21 |
tested on Linux, FreeBSD, and macOS (it is supposed to work on other POSIX |
| 22 |
platforms but it's not been thoroughly tested). |
| 23 |
|
| 24 |
The :mod:`!pty` module defines the following functions: |
| 25 |
|
| 26 |
|
| 27 |
.. function:: fork() |
| 28 |
|
| 29 |
Fork. Connect the child's controlling terminal to a pseudo-terminal. Return |
| 30 |
value is ``(pid, fd)``. Note that the child gets *pid* 0, and the *fd* is |
| 31 |
*invalid*. The parent's return value is the *pid* of the child, and *fd* is a |
| 32 |
file descriptor connected to the child's controlling terminal (and also to the |
| 33 |
child's standard input and output). |
| 34 |
|
| 35 |
.. warning:: On macOS the use of this function is unsafe when mixed with using |
| 36 |
higher-level system APIs, and that includes using :mod:`urllib.request`. |
| 37 |
|
| 38 |
|
| 39 |
.. function:: openpty() |
| 40 |
|
| 41 |
Open a new pseudo-terminal pair, using :func:`os.openpty` if possible, or |
| 42 |
emulation code for generic Unix systems. Return a pair of file descriptors |
| 43 |
``(master, slave)``, for the master and the slave end, respectively. |
| 44 |
|
| 45 |
|
| 46 |
.. function:: spawn(argv[, master_read[, stdin_read]]) |
| 47 |
|
| 48 |
Spawn a process, and connect its controlling terminal with the current |
| 49 |
process's standard io. This is often used to baffle programs which insist on |
| 50 |
reading from the controlling terminal. It is expected that the process |
| 51 |
spawned behind the pty will eventually terminate, and when it does *spawn* |
| 52 |
will return. |
| 53 |
|
| 54 |
A loop copies STDIN of the current process to the child and data received |
| 55 |
from the child to STDOUT of the current process. It is not signaled to the |
| 56 |
child if STDIN of the current process closes down. |
| 57 |
|
| 58 |
The functions *master_read* and *stdin_read* are passed a file descriptor |
| 59 |
which they should read from, and they should always return a byte string. In |
| 60 |
order to force spawn to return before the child process exits an |
| 61 |
empty byte array should be returned to signal end of file. |
| 62 |
|
| 63 |
The default implementation for both functions will read and return up to 1024 |
| 64 |
bytes each time the function is called. The *master_read* callback is passed |
| 65 |
the pseudoterminal’s master file descriptor to read output from the child |
| 66 |
process, and *stdin_read* is passed file descriptor 0, to read from the |
| 67 |
parent process's standard input. |
| 68 |
|
| 69 |
Returning an empty byte string from either callback is interpreted as an |
| 70 |
end-of-file (EOF) condition, and that callback will not be called after |
| 71 |
that. If *stdin_read* signals EOF the controlling terminal can no longer |
| 72 |
communicate with the parent process OR the child process. Unless the child |
| 73 |
process will quit without any input, *spawn* will then loop forever. If |
| 74 |
*master_read* signals EOF the same behavior results (on linux at least). |
| 75 |
|
| 76 |
Return the exit status value from :func:`os.waitpid` on the child process. |
| 77 |
|
| 78 |
:func:`os.waitstatus_to_exitcode` can be used to convert the exit status into |
| 79 |
an exit code. |
| 80 |
|
| 81 |
.. audit-event:: pty.spawn argv pty.spawn |
| 82 |
|
| 83 |
.. versionchanged:: 3.4 |
| 84 |
:func:`spawn` now returns the status value from :func:`os.waitpid` |
| 85 |
on the child process. |
| 86 |
|
| 87 |
Example |
| 88 |
------- |
| 89 |
|
| 90 |
.. sectionauthor:: Steen Lumholt |
| 91 |
|
| 92 |
The following program acts like the Unix command :manpage:`script(1)`, using a |
| 93 |
pseudo-terminal to record all input and output of a terminal session in a |
| 94 |
"typescript". :: |
| 95 |
|
| 96 |
import argparse |
| 97 |
import os |
| 98 |
import pty |
| 99 |
import sys |
| 100 |
import time |
| 101 |
|
| 102 |
parser = argparse.ArgumentParser() |
| 103 |
parser.add_argument('-a', dest='append', action='store_true') |
| 104 |
parser.add_argument('-p', dest='use_python', action='store_true') |
| 105 |
parser.add_argument('filename', nargs='?', default='typescript') |
| 106 |
options = parser.parse_args() |
| 107 |
|
| 108 |
shell = sys.executable if options.use_python else os.environ.get('SHELL', 'sh') |
| 109 |
filename = options.filename |
| 110 |
mode = 'ab' if options.append else 'wb' |
| 111 |
|
| 112 |
with open(filename, mode) as script: |
| 113 |
def read(fd): |
| 114 |
data = os.read(fd, 1024) |
| 115 |
script.write(data) |
| 116 |
return data |
| 117 |
|
| 118 |
print('Script started, file is', filename) |
| 119 |
script.write(('Script started on %s\n' % time.asctime()).encode()) |
| 120 |
|
| 121 |
pty.spawn(shell, read) |
| 122 |
|
| 123 |
script.write(('Script done on %s\n' % time.asctime()).encode()) |
| 124 |
print('Script done, file is', filename) |