Debian Codegraph @

Doc/library/pty.rst

raw
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)