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.

References:

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

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

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

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

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

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

"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