bpo-41494: Adds window resizing support to pty.spawn [ SIGWINCH ]

[8vasu]

This was tested using Python 3.7 after commenting out the sys.audit lines.

https://docs.python.org/3/library/pty.html presents us with an example usage of pty.spawn. This example mimics script(1). However, the script(1) from util-linux has fantastic signal handing that pty.spawn does not directly provide. In fact, Lib/pty.py says "Bugs: No signal handling. Doesn't set slave termios and window size."

xterm(1) on Debian 10 GNU/Linux was used to test the pty.spawn example mentioned above; upon resizing the xterm(1) window, the output of programs such as ls(1) became scattered and hard to visually parse.

Currently, this patch does not modify any of the functions that are already present in Lib/pty.py. Instead, it exposes a new function called "wspawn" [ pty.wspawn ]. This is like pty.spawn + the following differences.

1. Window size is set at the beginning.
2. A SIGWINCH handler is registered. The old handler is saved and restored later.
3. If the above two steps fail, then cleanup is done, and an exception is raised, so that the programmer can catch the exception and use pty.spawn instead.
4. Unlike pty.spawn, this does not depend on OSError to break out of the parent mainloop. Instead, the main loop calls select with an adjustable timeout, so that waitpid with WNOHANG can be called periodically to check if the spawned child process has undergone an alteration of state. This might be a possible solution to https://bugs.python.org/issue26228, which is mentioned in the docs [ https://docs.python.org/3/library/pty.html ].
5. While the return value is same as that of pty.spawn, this accepts an extra optional "timeout" argument for the select call.

The aforementioned pty.spawn example now works well with window resizing if pty.wspawn is used in place of pty.spawn.

Signed-off-by: Soumendra Ganguly [email protected]

https://bugs.python.org/issue41494

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

CLA Missing

Our records indicate the following people have not signed the CLA:

@8vasu

For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

If you have recently signed the CLA, please wait at least one business day
before our records are updated.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

[8vasu]

The following are two [ very old ] stackoverflow threads that are relevant.

https://stackoverflow.com/questions/6418678/resize-the-terminal-with-python

https://stackoverflow.com/questions/16941885/want-to-resize-terminal-windows-in-python-working-but-not-quite-right

[8vasu]

C code equivalent to "_winresz" is

void _winresz(int pty_slave) {
        struct winsize w;
        if (ioctl(STDIN_FILENO, TIOCGWINSZ, &w) == 0)
                ioctl(pty_slave, TIOCSWINSZ, &w);
}

Notice that the above code checks if the TIOCGWINSZ call is a success before
making the TIOCSWINSZ call. Therefore, "_winresz" must always be called
in a try block.

References:

1. https://www.man7.org/linux/man-pages/man4/tty_ioctl.4.html / https://docs.python.org/3/library/fcntl.html?highlight=ioctl#fcntl.ioctl

[8vasu]

The SIGWINCH handler depends on the pty slave fd returned by openpty in the body of "wspawn" [ see below ]; while the handler could just have been a function nested inside wspawn, that would make wspawn less readable. That is the reason for writing "_create_hwinch", which simply takes the pty slave fd as an argument and returns the appropriate signal handler function [ for SIGWINCH ].

References:

1. https://man7.org/linux/man-pages/man3/openpty.3.html / https://docs.python.org/3/library/pty.html?highlight=openpty#pty.openpty

[8vasu]

Adding detailed comments for the reviewers. Most manpages referenced are from Linux. However, they should be similar on the BSDs.

Bugs:

1. Since signal.signal() is being called by wspawn(), we can only call wspawn from the main thread. Even if that was not the case, since wspawn is setting the SIGWINCH handler globally, we should only have one instance of wspawn() running across threads anyway.
2. wspawn() currently raises an exception if the initial attempt to set window size fails / if the attempt to register the SIGWINCH handler fails. Possible workaround: catch exception and try pty.spawn() instead.
3. Can calling select with very short timeout result in high CPU usage? Not tested.

[8vasu]

C code equivalent to "_cleanup" would use close(2), tcsetattr(3), and sigaction(2). This performs cleanup such as closing files, resetting tty attributes, and resetting the SIGWINCH signal handler. It is called right before wspawn returns/raises an exception.

References:

1. https://man7.org/linux/man-pages/man2/close.2.html / https://docs.python.org/3/library/os.html?highlight=os%20close#os.close
2. https://man7.org/linux/man-pages/man3/termios.3.html / https://docs.python.org/3/library/termios.html
3. https://man7.org/linux/man-pages/man2/sigaction.2.html / https://docs.python.org/3/library/signal.html#signal.signal

[8vasu]

This paragraph explains "_ekill". If the parent loop [ see "_wcopy" below ] terminates due to an exception, then that exception is caught by wspawn. Then, we call waitpid on spawned child process so that it does not become a zombie. However, right before calling waitpid, the child process is sent SIGTERM. A second (*) after that, the child process, if alive, receives SIGKILL to ensure that it is no longer running.

(*) Will an adjustable sleep be more useful?

References:

1. https://en.wikipedia.org/wiki/Zombie_process
2. https://man7.org/linux/man-pages/man2/wait.2.html / https://docs.python.org/3/library/os.html?highlight=waitpid#os.waitpid
3. https://man7.org/linux/man-pages/man2/kill.2.html / https://docs.python.org/3/library/os.html?highlight=kill#os.kill

[8vasu]

This is a modified version of "_copy". The differences are:

1. select is called with a finite, adjustable timeout value.
2. Calls waitpid [ with WNOHANG ] on the spawned child process periodically.
3. While _copy does not return anything, _wcopy cleanly exits and returns the output of os.waitpid.

References:

1. https://man7.org/linux/man-pages/man2/select.2.html / https://docs.python.org/3/library/select.html?highlight=select#select.select

[8vasu]

"wspawn" is spawn+the following differences.

1. It sets window size at the beginning.
2. It registers a SIGWINCH handler.
3. It does not depend on OSError to return. It does a clean return instead [ see "_wcopy" above ].

No. 3 above is related to

1. https://bugs.python.org/issue29070
2. https://bugs.python.org/issue26228

[8vasu]

Added detailed comments to the diff.

[8vasu]

References:

1. https://www.man7.org/linux/man-pages/man3/login_tty.3.html