Example Code

The example from the termios docs:

def getpass(prompt="Password: "):
    import termios, sys
    fd = sys.stdin.fileno()
    old = termios.tcgetattr(fd)
    new = termios.tcgetattr(fd)
    new[3] = new[3] & ~termios.ECHO          # lflags
    try:
        termios.tcsetattr(fd, termios.TCSADRAIN, new)
        passwd = input(prompt)
    finally:
        termios.tcsetattr(fd, termios.TCSADRAIN, old)
    return passwd

Actual Behavior

$ mypy --pretty --show-error-codes --check-untyped-defs example.py
example.py:6: error: Unsupported operand types for & ("List[bytes]" and "int")  [operator]
        new[3] = new[3] & ~termios.ECHO          # lflags
                 ^
example.py:6: note: Left operand is of type "Union[int, List[bytes]]"
Found 1 error in 1 file (checked 1 source file)

Expected Behavior

The code typechecks successfully, because it is correct. In the reality of runtime, I never have to worry that new[3] will be a list, because it won't.

The mypy error is caused by the definition of _Attr, which is the return type of tcgetattr:

Typeshed's own contribution guidelines, python/mypy#1693, and mypy's docs agree that union return types are bad news. I can get around this with an assert isinstance(new[3], int), but at runtime new[0] through new[5] will always be int, and new[6] will always be List[bytes] *, so the assertion is pointless.

It would be clearer if tcgetattr returned an object so the different values could have their own names and types, but that decision predates typeshed. It would be nice if we at least had an AnyOf type (python/typing#566) so we could write List[AnyOf[int, List[AnyOf[bytes, int]]]], but we don't. So we are left with List[Any], which is not very specific but is at least not incorrect.

* Except for new[6][termios.VTIME] and new[6][termios.VMIN], which are int in noncanonical mode (when new[3] & termios.ICANON is zero). The stubs currently ignore this possibility.