gh-85984: New additions and improvements to the tty library. (#101832)

New additions to the tty library. Functions added: cfmakeraw(), and cfmakecbreak(). The
functions setcbreak() and setraw() now return original termios to save an extra tcgetattr() call.

---------

Signed-off-by: Soumendra Ganguly <soumendraganguly@gmail.com>
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: Gregory P. Smith [Google LLC] <greg@krypto.org>

1 files changed, 54 insertions, 16 deletions

diff --git a/Lib/tty.py b/Lib/tty.py
index a72eb67..7d91602 100644
--- a/Lib/tty.py
+++ b/Lib/tty.py
@@ -4,9 +4,9 @@
 
 from termios import *
 
-__all__ = ["setraw", "setcbreak"]
+__all__ = ["cfmakeraw", "cfmakecbreak", "setraw", "setcbreak"]
 
-# Indexes for termios list.
+# Indices for termios list.
 IFLAG = 0
 OFLAG = 1
 CFLAG = 2
@@ -15,22 +15,60 @@ ISPEED = 4
 OSPEED = 5
 CC = 6
 
-def setraw(fd, when=TCSAFLUSH):
-    """Put terminal into a raw mode."""
-    mode = tcgetattr(fd)
-    mode[IFLAG] = mode[IFLAG] & ~(BRKINT | ICRNL | INPCK | ISTRIP | IXON)
-    mode[OFLAG] = mode[OFLAG] & ~(OPOST)
-    mode[CFLAG] = mode[CFLAG] & ~(CSIZE | PARENB)
-    mode[CFLAG] = mode[CFLAG] | CS8
-    mode[LFLAG] = mode[LFLAG] & ~(ECHO | ICANON | IEXTEN | ISIG)
+def cfmakeraw(mode):
+    """Make termios mode raw."""
+    # Clear all POSIX.1-2017 input mode flags.
+    # See chapter 11 "General Terminal Interface"
+    # of POSIX.1-2017 Base Definitions.
+    mode[IFLAG] &= ~(IGNBRK | BRKINT | IGNPAR | PARMRK | INPCK | ISTRIP |
+                     INLCR | IGNCR | ICRNL | IXON | IXANY | IXOFF)
+
+    # Do not post-process output.
+    mode[OFLAG] &= ~OPOST
+
+    # Disable parity generation and detection; clear character size mask;
+    # let character size be 8 bits.
+    mode[CFLAG] &= ~(PARENB | CSIZE)
+    mode[CFLAG] |= CS8
+
+    # Clear all POSIX.1-2017 local mode flags.
+    mode[LFLAG] &= ~(ECHO | ECHOE | ECHOK | ECHONL | ICANON |
+                     IEXTEN | ISIG | NOFLSH | TOSTOP)
+
+    # POSIX.1-2017, 11.1.7 Non-Canonical Mode Input Processing,
+    # Case B: MIN>0, TIME=0
+    # A pending read shall block until MIN (here 1) bytes are received,
+    # or a signal is received.
     mode[CC][VMIN] = 1
     mode[CC][VTIME] = 0
-    tcsetattr(fd, when, mode)
 
-def setcbreak(fd, when=TCSAFLUSH):
-    """Put terminal into a cbreak mode."""
-    mode = tcgetattr(fd)
-    mode[LFLAG] = mode[LFLAG] & ~(ECHO | ICANON)
+def cfmakecbreak(mode):
+    """Make termios mode cbreak."""
+    # Do not map CR to NL on input.
+    mode[IFLAG] &= ~(ICRNL)
+
+    # Do not echo characters; disable canonical input.
+    mode[LFLAG] &= ~(ECHO | ICANON)
+
+    # POSIX.1-2017, 11.1.7 Non-Canonical Mode Input Processing,
+    # Case B: MIN>0, TIME=0
+    # A pending read shall block until MIN (here 1) bytes are received,
+    # or a signal is received.
     mode[CC][VMIN] = 1
     mode[CC][VTIME] = 0
-    tcsetattr(fd, when, mode)
+
+def setraw(fd, when=TCSAFLUSH):
+    """Put terminal into raw mode."""
+    mode = tcgetattr(fd)
+    new = list(mode)
+    cfmakeraw(new)
+    tcsetattr(fd, when, new)
+    return mode
+
+def setcbreak(fd, when=TCSAFLUSH):
+    """Put terminal into cbreak mode."""
+    mode = tcgetattr(fd)
+    new = list(mode)
+    cfmakecbreak(new)
+    tcsetattr(fd, when, new)
+    return mode