Use Literal overloads to give better types to subprocess

[msullivan]

This gives better types to subprocess.check_output and subprocess.run
by laboriously overloading using literals.

To support run, I turned CompletedProcess into _CompletedProcess[T]
with CompletedProcess = _CompletedProcess[Any]. I could pretty easily
be convinced that it would be better to just make CompletedProcess
generic, though.

I'd like to do the same for Popen but need to make mypy support
believing the type of __new__ in order for that to work.

[msullivan]

I tested this using:

import subprocess
import sys

reveal_type(subprocess.check_output('lol'))
reveal_type(subprocess.check_output('lol', universal_newlines=True))
if sys.version_info >= (3, 6):
    reveal_type(subprocess.check_output('lol', encoding='utf8'))
    reveal_type(subprocess.check_output('lol', errors='surrogateescape'))
    reveal_type(subprocess.check_output('lol', encoding='utf8', errors='surrogateescape'))
if sys.version_info >= (3, 7):
    reveal_type(subprocess.check_output('lol', text=True))

reveal_type(subprocess.check_output('lol', universal_newlines=1==1))


reveal_type(subprocess.run('lol'))
reveal_type(subprocess.run('lol', universal_newlines=True))
if sys.version_info >= (3, 6):
    reveal_type(subprocess.run('lol', encoding='utf8'))
    reveal_type(subprocess.run('lol', errors='surrogateescape'))
    reveal_type(subprocess.run('lol', encoding='utf8', errors='surrogateescape'))
if sys.version_info >= (3, 7):
    reveal_type(subprocess.run('lol', text=True))

reveal_type(subprocess.run('lol', universal_newlines=1==1))

[ilevkivskyi]

Thanks! Looks reasonable. I have few comments.

[ilevkivskyi]

I think you can already import it from typing

[msullivan]

Apparently not yet?

[ilevkivskyi]

OK, I see, it is defined in typing stub under if sys.version_info >= (3, 8): ...

[ilevkivskyi]

@msullivan

I'd like to do the same for Popen but need to make mypy support
believing the type of __new__ in order for that to work.

I would prefer to also support respecting annotations on self. This would allow several currently un-expressible patterns (and would lay foundation for support of higher order kinds). Examples:

Overloaded constructors:

T = TypeVar('bytes', 'Text')
class C(Generic[T]):
    @overload
    def __init__(self: C[Text], use_text: Literal[True]) -> None: ...
    @overload
    def __init__(self, use_text: bool) -> None: ...  # allow omitting annotation for fallback case

Methods that should be called only for some values of type argument:

class C(Generic[T]):
    def inc_value(self: C[int]) -> None: ...

x: C[int]
x.inc_value()  # OK
y: C[str]
y.inc_value()  # Error!

Methods that have different signature depending on value of type argument:

class C(Generic[T]):
    @overload
    def meth(self: C[int], inc_value: bool) -> None: ...
    @overload
    def meth(self) -> None: ...

Complex relationship between types in method and type arguments:

class C(Generic[T]):
    @overload
    def foo(self: C[int]) -> List[int]: ...
    @overload
    def foo(self: C[str]) -> str: ...

The first one is of course the most important but we also have few issues about other things.