Type annotate the public API

[pradyunsg]

Closes #90

[takluyver]

Thanks @pradyunsg - it looks like @layday has already done a detailed review of the annotations, so I'll skip doing that.

My inclination is to be fairly conservative with Python version support, since this is meant to be a boring piece of low-level infrastructure that doesn't change often. I see pip hasn't dropped 3.7 support yet, so I'd suggest we don't here either. But I'm not going to argue about this if you really want to.

[layday]

https://github.com/pypa/build/pull/601

[pradyunsg]

The latest commit makes it possible to do...

if TYPE_CHECKING:
    from pyproject_hooks import SubprocessRunner

And then annotate subprocess runners using that type.

[pradyunsg]

Instead of leaving that as a comment, I've gone ahead and documented that.

[henryiii]

Wouldn’t it make sense to allow SubprocessRunner at runtime on Python 3.8+? So this interface oddity will go away once 3.7 is dropped? Another idea (if it’s not runtime checkable) is to just make it a dummy object at runtime, so downstream code isn’t forced into extra TYPE_CHECKING checks.

[layday]

That's what we do with the IsolatedEnv in build, it's a simple ABC at runtime on Python 3.7.

[pradyunsg]

On the basis of "this is better than status quo", I'm gonna go ahead and merge this.

There's a couple of potential follow ups to improve this further:

• Using the newer typing syntax and more granular "semantic" types, that @gotmax23 has suggested.
• Making the protocol available on Python 3.8+ at runtime (with an object on 3.7), as @henryiii suggested.

[pradyunsg]

(I'll fix the documentation build separately)