Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`pty` --- Pseudo-terminal utilities |
| 2 | ======================================== |
| 3 | |
| 4 | .. module:: pty |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 5 | :platform: Linux |
| 6 | :synopsis: Pseudo-Terminal Handling for Linux. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. moduleauthor:: Steen Lumholt |
| 9 | .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| 10 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 11 | **Source code:** :source:`Lib/pty.py` |
| 12 | |
| 13 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | |
| 15 | The :mod:`pty` module defines operations for handling the pseudo-terminal |
| 16 | concept: starting another process and being able to write to and read from its |
| 17 | controlling terminal programmatically. |
| 18 | |
Mark Dickinson | 934896d | 2009-02-21 20:59:32 +0000 | [diff] [blame] | 19 | Because pseudo-terminal handling is highly platform dependent, there is code to |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 20 | do it only for Linux. (The Linux code is supposed to work on other platforms, |
| 21 | but hasn't been tested yet.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | |
| 23 | The :mod:`pty` module defines the following functions: |
| 24 | |
| 25 | |
| 26 | .. function:: fork() |
| 27 | |
| 28 | Fork. Connect the child's controlling terminal to a pseudo-terminal. Return |
| 29 | value is ``(pid, fd)``. Note that the child gets *pid* 0, and the *fd* is |
| 30 | *invalid*. The parent's return value is the *pid* of the child, and *fd* is a |
| 31 | file descriptor connected to the child's controlling terminal (and also to the |
| 32 | child's standard input and output). |
| 33 | |
| 34 | |
| 35 | .. function:: openpty() |
| 36 | |
| 37 | Open a new pseudo-terminal pair, using :func:`os.openpty` if possible, or |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 38 | emulation code for generic Unix systems. Return a pair of file descriptors |
| 39 | ``(master, slave)``, for the master and the slave end, respectively. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
| 41 | |
| 42 | .. function:: spawn(argv[, master_read[, stdin_read]]) |
| 43 | |
| 44 | Spawn a process, and connect its controlling terminal with the current |
| 45 | process's standard io. This is often used to baffle programs which insist on |
| 46 | reading from the controlling terminal. |
| 47 | |
| 48 | The functions *master_read* and *stdin_read* should be functions which read from |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 49 | a file descriptor. The defaults try to read 1024 bytes each time they are |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | called. |
| 51 | |
Gregory P. Smith | 0f21adf7 | 2012-09-29 12:41:03 -0700 | [diff] [blame] | 52 | .. versionchanged:: 3.4 |
| 53 | :func:`spawn` now returns the status value from :func:`os.waitpid` |
| 54 | on the child process. |
Georg Brandl | 4cf83f4 | 2010-12-30 17:22:33 +0000 | [diff] [blame] | 55 | |
| 56 | Example |
| 57 | ------- |
| 58 | |
| 59 | .. sectionauthor:: Steen Lumholt |
| 60 | |
| 61 | The following program acts like the Unix command :manpage:`script(1)`, using a |
| 62 | pseudo-terminal to record all input and output of a terminal session in a |
| 63 | "typescript". :: |
| 64 | |
Berker Peksag | c2dd680 | 2015-05-12 17:25:06 +0300 | [diff] [blame] | 65 | import argparse |
| 66 | import os |
| 67 | import pty |
| 68 | import sys |
| 69 | import time |
Georg Brandl | 4cf83f4 | 2010-12-30 17:22:33 +0000 | [diff] [blame] | 70 | |
Berker Peksag | c2dd680 | 2015-05-12 17:25:06 +0300 | [diff] [blame] | 71 | parser = argparse.ArgumentParser() |
| 72 | parser.add_argument('-a', dest='append', action='store_true') |
| 73 | parser.add_argument('-p', dest='use_python', action='store_true') |
| 74 | parser.add_argument('filename', nargs='?', default='typescript') |
| 75 | options = parser.parse_args() |
Georg Brandl | 4cf83f4 | 2010-12-30 17:22:33 +0000 | [diff] [blame] | 76 | |
Berker Peksag | c2dd680 | 2015-05-12 17:25:06 +0300 | [diff] [blame] | 77 | shell = sys.executable if options.use_python else os.environ.get('SHELL', 'sh') |
| 78 | filename = options.filename |
| 79 | mode = 'ab' if options.append else 'wb' |
Georg Brandl | 4cf83f4 | 2010-12-30 17:22:33 +0000 | [diff] [blame] | 80 | |
Berker Peksag | c2dd680 | 2015-05-12 17:25:06 +0300 | [diff] [blame] | 81 | with open(filename, mode) as script: |
| 82 | def read(fd): |
| 83 | data = os.read(fd, 1024) |
| 84 | script.write(data) |
| 85 | return data |
Georg Brandl | 4cf83f4 | 2010-12-30 17:22:33 +0000 | [diff] [blame] | 86 | |
Berker Peksag | c2dd680 | 2015-05-12 17:25:06 +0300 | [diff] [blame] | 87 | print('Script started, file is', filename) |
| 88 | script.write(('Script started on %s\n' % time.asctime()).encode()) |
Georg Brandl | 4cf83f4 | 2010-12-30 17:22:33 +0000 | [diff] [blame] | 89 | |
Berker Peksag | c2dd680 | 2015-05-12 17:25:06 +0300 | [diff] [blame] | 90 | pty.spawn(shell, read) |
Georg Brandl | 4cf83f4 | 2010-12-30 17:22:33 +0000 | [diff] [blame] | 91 | |
Berker Peksag | c2dd680 | 2015-05-12 17:25:06 +0300 | [diff] [blame] | 92 | script.write(('Script done on %s\n' % time.asctime()).encode()) |
| 93 | print('Script done, file is', filename) |