Soumendra Ganguly: new additions to the tty library. Functions added: cfmakeecho(), 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>

Doc/library/tty.rst

@@ -20,18 +20,39 @@ Because it requires the :mod:`termios` module, it will work only on Unix.
 The :mod:`tty` module defines the following functions:
 
 
+.. function:: cfmakeecho(mode, echo=True)
+
+   Set ECHO in the tty attribute list *mode*, which is a list like the one
+   returned by :func:`termios.tcgetattr`, if *echo* is :const:`True` or is
+   omitted. Unset ECHO if *echo* is :const:`False`.
+
+
+.. function:: cfmakeraw(mode)
+
+   Convert the tty attribute list *mode*, which is a list like the one returned
+   by :func:`termios.tcgetattr`, to that of a tty in raw mode.
+
+
+.. function:: cfmakecbreak(mode)
+
+   Convert the tty attribute list *mode*, which is a list like the one returned
+   by :func:`termios.tcgetattr`, to that of a tty in cbreak mode.
+
+
 .. function:: setraw(fd, when=termios.TCSAFLUSH)
 
    Change the mode of the file descriptor *fd* to raw. If *when* is omitted, it
    defaults to :const:`termios.TCSAFLUSH`, and is passed to
-   :func:`termios.tcsetattr`.
+   :func:`termios.tcsetattr`. The return value of :func:`termios.tcgetattr`
+   is saved before setting *fd* to raw mode; this value is returned.
 
 
 .. function:: setcbreak(fd, when=termios.TCSAFLUSH)
 
    Change the mode of file descriptor *fd* to cbreak. If *when* is omitted, it
    defaults to :const:`termios.TCSAFLUSH`, and is passed to
-   :func:`termios.tcsetattr`.
+   :func:`termios.tcsetattr`. The return value of :func:`termios.tcgetattr`
+   is saved before setting *fd* to cbreak mode; this value is returned.
 
 
 .. seealso::

Lib/tty.py

@@ -4,9 +4,9 @@
 
 from termios import *
 
-__all__ = ["setraw", "setcbreak"]
+__all__ = ["cfmakeecho", "cfmakeraw", "cfmakecbreak", "setraw", "setcbreak"]
 
-# Indexes for termios list.
+# Indices for termios list.
 IFLAG = 0
 OFLAG = 1
 CFLAG = 2
@@ -15,22 +15,70 @@ 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 cfmakeecho(mode, echo=True):
+    """Set/unset ECHO."""
+    if echo:
+        mode[LFLAG] |= ECHO
+    else:
+        mode[LFLAG] &= ~ECHO
+
+def cfmakeraw(mode):
+    """raw mode termios"""
+    # Clear all POSIX.1-2017 input mode flags.
+    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
+
+    # Do not echo characters (including NL); disable canonical input; disable
+    # the checking of characters against the special control characters INTR,
+    # QUIT, and SUSP (disable sending of signals using control characters);
+    # disable any implementation-defined special control characters not
+    # currently controlled by ICANON, ISIG, IXON, or IXOFF.
+    mode[LFLAG] &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN)
+
+    # 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 cfmakecbreak(mode):
+    """cbreak mode termios"""
+    # 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
+
+def setraw(fd, when=TCSAFLUSH):
+    """Put terminal into raw mode.
+    Returns original termios."""
+    mode = tcgetattr(fd)
+    new = list(mode)
+    cfmakeraw(new)
+    tcsetattr(fd, when, new)
+    return mode
 
 def setcbreak(fd, when=TCSAFLUSH):
-    """Put terminal into a cbreak mode."""
+    """Put terminal into cbreak mode.
+    Returns original termios."""
     mode = tcgetattr(fd)
-    mode[LFLAG] = mode[LFLAG] & ~(ECHO | ICANON)
-    mode[CC][VMIN] = 1
-    mode[CC][VTIME] = 0
-    tcsetattr(fd, when, mode)
+    new = list(mode)
+    cfmakecbreak(new)
+    tcsetattr(fd, when, new)
+    return mode

Misc/NEWS.d/next/Library/2020-12-07-03-04-11.bpo-41818.2f-iaW.rst

@@ -0,0 +1,2 @@
+Soumendra Ganguly: new additions to the tty library. Functions added: cfmakeecho(), cfmakeraw(), and cfmakecbreak().
+The functions setcbreak() and setraw() now return original termios to save an extra tcgetattr() call.